feat: close WP-0009/WP-0013 production integration stewardship strand

Ship flex-auth policy gate registry and smoke evidence, archive WP-0009 through WP-0013, and add integration docs: ops-bridge cert_command migration playbook, operator OpenBao token hygiene, principals drift check script, and 2026-06-24 INTENT/SCOPE gap analysis.
2026-06-24 12:44:32 +02:00
parent 1778b169da
commit 90007c2cda
24 changed files with 2192 additions and 121 deletions
--- a/wiki/playbooks/operator-openbao-token-hygiene.md
+++ b/wiki/playbooks/operator-openbao-token-hygiene.md
@@ -0,0 +1,105 @@
+# Operator OpenBao Token Hygiene
+
+Date: 2026-06-24  
+Workplan: WARDEN-WP-0013 T4
+
+Daily `warden sign` against production OpenBao requires a **scoped** API token in
+`VAULT_TOKEN` — not the cluster root token.
+
+---
+
+## Rules
+
+| Rule | Rationale |
+| --- | --- |
+| Never commit `VAULT_TOKEN` | Tokens are secrets |
+| Never paste tokens in chat, State Hub, or workplans | Same |
+| Do not use root token for daily `warden sign` | Break-glass only |
+| Prefer short-lived tokens | Limit blast radius |
+| Refresh on HTTP 403 | Token expired or policy mismatch |
+
+---
+
+## Scoped token for warden
+
+Production signing needs permission to call the SSH engine sign endpoint for the
+roles mapped in `warden.yaml` (`adm-role`, `agt-role`, `atm-role`).
+
+Illustrative policy shape (create in OpenBao policy admin — adjust names to match
+your cluster):
+
+```hcl
+# warden-sign — least privilege for ops-warden CLI
+path "ssh/sign/agt-role" {
+  capabilities = ["create", "update"]
+}
+path "ssh/sign/adm-role" {
+  capabilities = ["create", "update"]
+}
+path "ssh/sign/atm-role" {
+  capabilities = ["create", "update"]
+}
+```
+
+Issue a token bound to `warden-sign` (operator procedure in `railiance-platform` /
+OpenBao admin runbooks).
+
+---
+
+## Session pattern
+
+```bash
+# Set for current shell only — do not add to ~/.bashrc with a literal token
+export VAULT_TOKEN="<scoped-token>"
+
+warden status agt-state-hub-bridge
+warden sign agt-state-hub-bridge --pubkey ~/.ssh/agt-state-hub-bridge_ed25519.pub
+```
+
+`warden` reads the env var named in `vault.token_env` (default `VAULT_TOKEN`).
+
+---
+
+## OIDC / interactive login
+
+For human operators, prefer platform OIDC login that yields a short-lived OpenBao
+token instead of copying long-lived secrets.
+
+| Need | Route to |
+| --- | --- |
+| Interactive login, OIDC, MFA | key-cape / Keycloak — `warden route show key-cape-oidc-login` |
+
+ops-warden does not implement login; it documents the route only.
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause | Action |
+| --- | --- | --- |
+| `Vault token not found` | `VAULT_TOKEN` unset | Export scoped token |
+| `HTTP 403` / `permission denied` | Expired token or insufficient policy | Re-issue `warden-sign` token |
+| `Signing failed` + connection error | Wrong `vault.addr` or network | Check `warden.yaml`, tunnel/VPN |
+| Suggest `--backend local` | OpenBao unreachable | Fix connectivity; local is lab-only |
+
+After fixing token issues, re-run:
+
+```bash
+warden sign <actor> --pubkey <path>
+```
+
+---
+
+## Root token (break-glass only)
+
+Cluster root tokens bypass all policy. Use only for one-time engine setup
+(`wiki/OpenBaoSshEngineChecklist.md` § One-time SSH engine setup), then revoke
+from daily shell profile.
+
+---
+
+## See also
+
+- `wiki/OpenBaoSshEngineChecklist.md`
+- `wiki/OpsWardenConfig.md` — Authentication section
+- `examples/warden.production.example.yaml`