From 3b951e81393d8d66bd0cc5ffabc18dd49b1398b4 Mon Sep 17 00:00:00 2001 From: tegwick Date: Wed, 17 Jun 2026 00:18:01 +0200 Subject: [PATCH] docs: add interhub bootstrap access lane --- SCOPE.md | 3 + wiki/InterHubBootstrapAccessLane.md | 126 ++++++++++++++++++++++++++++ 2 files changed, 129 insertions(+) create mode 100644 wiki/InterHubBootstrapAccessLane.md diff --git a/SCOPE.md b/SCOPE.md index 60928ad..9b6dfbe 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -57,6 +57,8 @@ backend is in use. - `ops-bridge` needs a `cert_command` to be defined for a tunnel - Adding a new actor to the principals inventory - Bootstrapping the CA for a new environment +- Reaching a trusted execution host for attended Inter-Hub bootstrap work with + a short-lived agent certificate --- @@ -123,6 +125,7 @@ keywords: [ssh, certificate, ca, credential, warden, ops-warden, pki, vault] - Start with: `SCOPE.md` (this file), then `wiki/AccessManagementDirective.md` - Config reference: `wiki/OpsWardenConfig.md` - cert_command contract: `wiki/CertCommandInterface.md` +- Inter-Hub bootstrap access lane: `wiki/InterHubBootstrapAccessLane.md` - Config files: `~/.config/warden/warden.yaml`, `~/.config/warden/inventory.yaml` - State: `~/.local/state/warden/` (certs, generated keypairs) - Entry point: `warden --help` diff --git a/wiki/InterHubBootstrapAccessLane.md b/wiki/InterHubBootstrapAccessLane.md new file mode 100644 index 0000000..67a720e --- /dev/null +++ b/wiki/InterHubBootstrapAccessLane.md @@ -0,0 +1,126 @@ +# Inter-Hub Bootstrap Access Lane + +Date: 2026-06-17 + +## Purpose + +This runbook describes how ops-warden participates in authenticated Inter-Hub +bootstrap tasks, especially the ops-hub production activation lane tracked by +`CUST-WP-0049`. + +ops-warden does not store Inter-Hub API keys. Its role is to issue short-lived +SSH certificates for a narrow actor so an operator or agent can reach a trusted +execution host without introducing static SSH keys into the workflow. + +## Boundary + +ops-warden owns: + +- actor registration +- short-lived certificate issuance +- TTL and principal policy +- `ops-ssh-wrapper` usage + +ops-warden does not own: + +- Inter-Hub operator key storage +- OpenBao policy or secret paths +- host-side `/etc/ssh/auth_principals/` deployment +- force-command wrappers +- database migrations or Kubernetes access + +Those host-side controls belong to `railiance-infra` or the relevant +deployment repo. Long-lived secret custody belongs in OpenBao or the approved +operator secret store. + +## Actor Pattern + +Use a dedicated `agt` actor for Codex-assisted bootstrap work: + +```bash +warden inventory add agt-codex-interhub-bootstrap \ + --type agt \ + --principal agt-interhub-bootstrap \ + --ttl 2 \ + --description "Short-lived agent access for attended Inter-Hub bootstrap execution" +``` + +Guidance: + +- Prefer a 1-2 hour TTL for attended bootstrap. +- Keep the principal narrower than general ops access. +- Do not reuse human `adm` actors for agent-assisted bootstrap runs. +- Remove or disable the actor after the bootstrap lane is no longer needed. + +## Execution Shape + +The intended flow is: + +1. Operator approves the production bootstrap run. +2. ops-warden signs a short-lived cert for `agt-codex-interhub-bootstrap`. +3. The target host accepts only the narrow `agt-interhub-bootstrap` principal. +4. Host-side policy maps that principal to a force-command or wrapper that can + run only the Inter-Hub bootstrap routine. +5. The wrapper reads the Inter-Hub operator key from OpenBao or an attended + `0600` temp file. +6. The wrapper runs the repo-owned bootstrap command, for example + `make interhub-bootstrap` in `ops-hub`. +7. Any generated runtime key is stored back into OpenBao immediately. +8. The wrapper prints non-secret evidence only: ids, status, timestamps, and + key prefixes. + +Example client-side wrapper use: + +```bash +WARDEN_ACTOR=agt-codex-interhub-bootstrap \ +SSH_PUBKEY="$HOME/.ssh/id_ed25519.pub" \ +ops-ssh-wrapper ssh ops-bootstrap@ run-ops-hub-interhub-bootstrap +``` + +The exact remote command and host account are environment-specific and should +be provisioned by the deployment repo. + +## Host-Side Requirements + +Before this lane can be used in production, railiance-infra or the deployment +owner should provide: + +- an auth principals entry for `agt-interhub-bootstrap` +- password auth disabled for the target account +- a force-command or restricted wrapper for the bootstrap path +- OpenBao read access for the Inter-Hub operator key, if unattended material + access is approved +- OpenBao write access for the generated ops-hub runtime key +- non-secret execution logging + +Without those controls, use only an attended local `IHUB_OPERATOR_KEY_FILE` +run. + +## Non-Secret Evidence + +Safe evidence to copy into State Hub: + +- workplan id and task id +- Inter-Hub base URL +- hub id and slug +- manifest id and status +- API consumer id +- runtime key prefix +- widget counts +- event id and event type + +Never log: + +- full operator keys +- full runtime API keys +- OpenBao tokens +- kubeconfig contents +- raw SQL output that could include secrets + +## Related Work + +- `the-custodian/workplans/CUST-WP-0049-interhub-bootstrap-access-lane.md` +- `ops-hub/docs/bootstrap-runbook.md` +- `wiki/AccessManagementDirective.md` +- `wiki/OpsWardenConfig.md` +- `wiki/CertCommandInterface.md`