openbao king credential bootstrapping

docs/security-bootstrap-openbao-ceremony-ux.md

@@ -0,0 +1,117 @@
+# OpenBao Ceremony UX
+
+Status: draft UX contract
+Date: 2026-05-24
+
+## Purpose
+
+This document translates the Railiance OpenBao ceremony into a guided UX. It is
+the product contract for `NET-WP-0016-T05`.
+
+The UI must make unsafe live initialization difficult to do accidentally. The
+first prototype should not execute `bao operator init`; it should show
+readiness, blocked gates, and the manual ceremony steps.
+
+## Ceremony States
+
+| State | Meaning |
+| --- | --- |
+| `not-ready` | Required gates are missing |
+| `preflight-ready` | Safe checks pass, but human ceremony still required |
+| `human-ceremony` | Operator is running the live init/unseal outside automation |
+| `post-unseal-config` | Audit, mounts, auth, and policies are being configured |
+| `root-disposition` | Root token is revoked or sealed offline |
+| `restore-required` | Snapshot/restore drill still blocks live secrets |
+| `ready-for-handover` | OpenBao is ready for cleanup and custody handover |
+
+## Readiness Gates
+
+Live initialization is blocked unless:
+
+- king credential kit is complete;
+- custody mode is selected;
+- offline custody packet is prepared;
+- OpenBao pod and PVC preflight passes;
+- OpenBao reports `Initialized: false` and `Sealed: true`;
+- operator has acknowledged no secret output enters unsafe channels;
+- maintenance window is deliberate; and
+- human ceremony mode is selected.
+
+## Preflight Panel
+
+The OpenBao panel should show:
+
+| Check | Source |
+| --- | --- |
+| Pod status | `make openbao-status` |
+| PVC status | `make openbao-status` |
+| Initialized/sealed state | `bao status` through Railiance target |
+| Helper script readiness | `make openbao-verify` |
+| Custody gates | NetKingdom bootstrap metadata |
+| Restore gate | State Hub task/progress evidence |
+
+The UI should show command output as plain text and mark any unknown result as
+unknown, not success.
+
+## Human Ceremony Guide
+
+When ready, the UI prints a guide:
+
+1. Confirm no screen recording or shared terminal logging is active.
+2. Confirm the offline custody packet is physically ready.
+3. Run the Railiance command manually in the approved shell.
+4. Route each unseal share directly to its approved custody location.
+5. Unseal by prompt, not by command-line argument.
+6. Use the root token only for first configuration.
+7. Run initial configuration helper.
+8. Create non-root admin path.
+9. Revoke or offline-seal the root token.
+10. Record only non-secret evidence.
+
+The UI must not ask the operator to paste unseal shares or root tokens.
+
+## Post-Unseal Configuration
+
+The UI may guide these safe commands:
+
+```bash
+make openbao-configure-initial
+make openbao-verify-post-unseal
+```
+
+Token entry must remain prompt-based or local-file based as implemented by
+Railiance helpers. The UI should not store or echo the token.
+
+## Evidence Record
+
+The UI may record:
+
+- ceremony date;
+- custody mode;
+- OpenBao initialized status;
+- audit enabled status;
+- initial mounts/policies loaded;
+- root-token disposition category: `revoked`, `offline-sealed`, or `deferred`;
+- snapshot taken status;
+- restore drill status; and
+- operator/contact.
+
+It must not record secret values.
+
+## Failure Handling
+
+If init output is accidentally exposed:
+
+1. Stop the ceremony.
+2. Mark the ceremony as compromised.
+3. Do not migrate live secrets.
+4. Rotate/rekey according to OpenBao procedure before proceeding.
+5. Record non-secret incident evidence.
+
+If post-unseal configuration fails:
+
+1. Keep root token handling in human custody.
+2. Do not create live secrets.
+3. Fix the configuration issue.
+4. Rerun the helper or manual command.
+5. Record the failed step without secret output.