generated from coulomb/repo-seed
120 lines
3.7 KiB
Markdown
120 lines
3.7 KiB
Markdown
# 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;
|
|
- recovery material is prepared for the selected custody mode;
|
|
- offline custody packet is prepared for the selected custody mode;
|
|
- selected custody mode is explicitly approved;
|
|
- 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.
|