ops-warden/wiki/playbooks/reuse-surface-hub-write-token.md

reuse-surface Hub Write Token — OpenBao Custody

Date: 2026-07-07 (promoted active 2026-07-07)
Workplan: RAILIANCE-WP-0011-T03 · CCR-2026-0005
Catalog: reuse-surface-hub-write-token (active — path live, ESO delivering)

Bearer token for authenticated writes to the production federation hub at https://reuse.coulomb.social (POST /v1/repos, reuse-surface hub register). ops-warden does not vend this token — custody belongs to railiance-platform (OpenBao) and the reuse-surface workload via External Secrets.

---

Owner-confirmed lane (no placeholders)

Field	Value
OpenBao server	https://bao.coulomb.social (railiance01, 92.205.62.239)
KV path	platform/workloads/reuse/reuse-surface/runtime-secrets
Hub write field	REUSE_SURFACE_TOKEN
Webhook HMAC field	REUSE_SURFACE_FORGEJO_WEBHOOK_SECRET
Read policy	workload-kv-read-reuse-surface-runtime
ESO delivery	ExternalSecret reuse/reuse-surface-runtime → reuse-surface-env (Railiance01)
Deploy runbook	railiance-apps/docs/reuse-surface-on-railiance01.md
Hub API spec	reuse-surface/specs/FederationHubAPI.md

Promotion gate (met 2026-07-07): path seeded, ExternalSecret reuse/reuse-surface-runtime SecretSynced, positive hub + webhook verification and negative default-policy denial recorded in CCR-2026-0005.

Which identity this route evaluates

warden access does not pick a principal. Two identities are involved, and they are not the same:

Plane	Identity
OpenBao data read	The ambient token: BAO_TOKEN, else VAULT_TOKEN, else ~/.vault-token. warden access prints the entity, OIDC role, and policies before a proxy.
flex-auth gate	policy.caller_auth in warden.yaml. On this workstation that mints a short-lived token for ServiceAccount ops-warden/ops-warden. An allow here does not mean OpenBao allowed the read.

A capabilities check on one shell and a proxy in another can disagree. The OpenBao CLI in the proxy uses that process's ambient token. An attended platform-admin login (entity 4a1f663c-0621-0483-edd0-f852274f4b6b, policies default, operator-custody, platform-admin) can show read on both exact paths while auth/netkingdom/role/coding-agent is denied: that role's agent-high-risk-boundary policy denies data read on this path. The 2026-10-14 hub registration attempt was that shape. PDP decision f730e3da14beebdd allowed the fetch; OpenBao then returned HTTP 403 and the helper did not run.

Do not attach workload-kv-read-reuse-surface-runtime to the platform-admin entity 4a1f663c-0621-0483-edd0-f852274f4b6b. CCR-2026-0005 remains the KV and ESO authority. ESO still uses Kubernetes role auth/kubernetes/role/reuse-surface-runtime-eso with policy workload-kv-read-reuse-surface-runtime-eso.

The attended caller is OIDC role reuse-surface-hub-writer-workload-kv-read on auth/netkingdom, group reuse-surface-hub-writers, assurance aal2, policy workload-kv-read-reuse-surface-runtime only. railiance-platform CCR-2026-0044 is applied. Log in with:

bao login -method=oidc -path=netkingdom role=reuse-surface-hub-writer-workload-kv-read

warden access does not perform that login. It reads the ambient token. Use this role's token for the proxy.

ops-mason verified both modes on 2026-10-14. The member receipt (docs/evidence/2026-10-14-reuse-surface-hub-writer-member.txt) logged in as entity c204099b-cb94-363f-e207-5ff4d4aa6e94 with only workload-kv-read-reuse-surface-runtime: read on the exact data and metadata paths, deny on the parent and on issue-core-runtime, then revoked. The non-member receipt refused the login. The CCR approval comment names member entity f94b7c34-e151-30bb-b473-df3ccdbb9bf1; the passing receipt's entity is the one above.

Break-glass (cluster read)

If OpenBao is unreachable, operators with Railiance01 kubeconfig may read the materialized Secret (ESO cache):

kubectl --kubeconfig ~/.kube/config-hosteurope get secret reuse-surface-env -n reuse \
  -o jsonpath='{.data.REUSE_SURFACE_TOKEN}' | base64 -d

Never paste values into chat, State Hub, workplans, or Git.

---

Worker checklist

1. Confirm OpenBao reachability (you act as yourself; ops-warden adds no credential):

   bao kv metadata get platform/workloads/reuse/reuse-surface/runtime-secrets
   

2. Export hub write token for a shell session (streams to your terminal):

   export REUSE_SURFACE_URL=https://reuse.coulomb.social
   export REUSE_SURFACE_TOKEN=$(
     bao kv get -field=REUSE_SURFACE_TOKEN \
       platform/workloads/reuse/reuse-surface/runtime-secrets
   )
   

3. Or proxy via warden access (same bao kv get, audited metadata only):

   warden route show reuse-surface-hub-write-token --json
   warden access reuse-surface-hub-write-token --fetch
   

4. Webhook HMAC (same path, second field — must match Forgejo org webhook):

   bao kv get -field=REUSE_SURFACE_FORGEJO_WEBHOOK_SECRET \
     platform/workloads/reuse/reuse-surface/runtime-secrets
   

   After rotation: railiance-apps make reuse-forgejo-webhook.

5. Register a repo after publish-check passes:

   reuse-surface hub status
   reuse-surface hub register --repo <slug> \
     --url <forgejo-raw-capabilities-yaml-url> \
     --domain <domain>
   

6. Verify federated index picked up the new source:

   curl -fsS "$REUSE_SURFACE_URL/v1/federated" | jq '.sources | map(.repo) | index("<slug>")'
   

Rotation: railiance-platform/docs/reuse-surface-runtime-secrets-rotation-runbook.md (OpenBao patch → ESO force-sync → hub rollout → make reuse-forgejo-webhook when the webhook HMAC changes → make reuse-webhook-smoke). Lifecycle: railiance-platform/docs/credential-lane-lifecycle-runbook.md (CCR-2026-0005).