# Tenant secret onboarding

Date: 2026-07-17  
Workplan: WARDEN-WP-0028

How to add a **client/tenant** commercial secret to NetKingdom OpenBao so
ops-warden can route it and consumers can use it without pasting values into
Git, State Hub, or chat.

---

## Path convention

```text
mount:  tenants                 # dedicated KV v2 mount (not platform/)
path:   tenants/<tenant>/<workload>/<bundle>
```

| Segment | Meaning | Example |
| --- | --- | --- |
| `tenant` | Stable client slug | `binky` |
| `workload` | Capability / system | `company-email` |
| `bundle` | One purpose / one CCR | `imap` |

**Do not** put new client secrets under `platform/workloads/…` (fleet/platform
services) or invent `secret/prod/…` as the production home.

First worked lane: `tenants/binky/company-email/imap` (CCR-2026-0007).

---

## Ownership

| Step | Owner |
| --- | --- |
| Business need, non-secret host facts, consumer config | Tenant control repo (e.g. `binky-control`) |
| CCR, policy HCL, OIDC role, mount hygiene | `railiance-platform` |
| Catalog front door + playbook + rotation guide | `ops-warden` |
| Value provision (Red) | Human founder/operator |
| Optional exec wrapper | `secrets-engine` (same path only) |

---

## Checklist

1. **Slug + fields** — pick `tenant`/`workload`/`bundle` and field names (no values).
2. **CCR** — `railiance-platform/credential-change-requests/CCR-YYYY-NNNN-….yaml`
   - `openbao.mount: tenants`
   - `openbao.kv_path: tenants/<tenant>/<workload>/<bundle>`
   - `policy_name` starts with `workload-kv-read-`
   - OIDC role ends with `-workload-kv-read`
   - `risk` high for mailbox/admin/recovery-class secrets
3. **Policy file** — exact `tenants/data/…` + `tenants/metadata/…` read only.
4. **Applier dry-run** — `scripts/credential-change.py applier-dry-run <CCR>`
5. **Approve + apply metadata** — policy + OIDC role; **no** secret write in apply.
6. **ops-warden catalog** — draft entry with `risk: high`, rotation block, concrete
   `fetch_command` for primary field; playbook under `wiki/playbooks/`.
7. **Founder provision** — `bao kv put tenants/… FIELD=@file` (mode 0600 file) or
   secrets-engine provision; never chat/Git.
8. **Verify capabilities-safe** — `bao token capabilities` allow/deny; never
   `kv get` for deny tests (WP-0026).
9. **Promote** catalog `draft` → `active` when resolvable; update CCR readiness.
10. **Agent boundary** — add exact data `deny` + metadata `read` to
    `agent-high-risk-boundary` for high-risk lanes.

---

## Worker fetch (after active)

```bash
bao login -method=oidc -path=netkingdom role=<lane>-workload-kv-read
warden access <catalog-id> --out /tmp/secret.file   # mode 0600
# agents: never raw --fetch stream; WARDEN_AGENT_ID + risk=high → exit 7
```

## See also

- `wiki/playbooks/binky-company-email-imap.md`
- `wiki/playbooks/catalog-lane-promotion.md`
- `wiki/playbooks/agent-read-boundary.md`
- `railiance-platform/docs/credential-change-approval.md`