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:

```bash
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):

```bash
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):
   ```bash
   bao kv metadata get platform/workloads/reuse/reuse-surface/runtime-secrets
   ```

2. **Export hub write token for a shell session** (streams to your terminal):
   ```bash
   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):
   ```bash
   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):
   ```bash
   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:
   ```bash
   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:
   ```bash
   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).