generated from coulomb/repo-seed
openbao king credential bootstrapping
This commit is contained in:
192
docs/security-bootstrap-operator-journey.md
Normal file
192
docs/security-bootstrap-operator-journey.md
Normal file
@@ -0,0 +1,192 @@
|
||||
# Security Bootstrap Operator Journey
|
||||
|
||||
Status: draft UX contract
|
||||
Date: 2026-05-24
|
||||
|
||||
## Purpose
|
||||
|
||||
This document defines the first operator journey for the guided security
|
||||
bootstrap experience. It is the product contract for `NET-WP-0016-T02`.
|
||||
|
||||
The first interface may be a CLI or local web console, but the interaction
|
||||
model should already be UI-shaped: clear state, blocked gates, next safe
|
||||
action, and quiet instructions that do not assume the operator is an OpenBao or
|
||||
IAM expert.
|
||||
|
||||
## Design System
|
||||
|
||||
The UI should use `whynot-design` where a visual surface is built.
|
||||
|
||||
Required visual posture:
|
||||
|
||||
- mostly black and white, using `--hi` only as a highlighter or signal marker;
|
||||
- 1px hairlines, document-like panels, generous whitespace;
|
||||
- sentence case for labels, headings, and buttons;
|
||||
- uppercase mono only for short stage/status eyebrows;
|
||||
- no gradients, decorative imagery, card shadows, scale transforms, or hype
|
||||
copy;
|
||||
- square or lightly rounded panels; pills only for labels; and
|
||||
- Lucide-style icons only when they speed recognition.
|
||||
|
||||
The console should feel like a field notebook and control surface, not a SaaS
|
||||
dashboard. The security work is serious, but the interface should stay calm.
|
||||
|
||||
## Shell
|
||||
|
||||
The first screen always answers four questions:
|
||||
|
||||
| Area | Content |
|
||||
| --- | --- |
|
||||
| Trust stage | Current stage, e.g. `S1 - Low-trust assembly` |
|
||||
| Next safe action | One primary action that can be done now |
|
||||
| Blocked gates | Actions that are blocked and why |
|
||||
| Evidence | Non-secret records already present |
|
||||
|
||||
Suggested first screen:
|
||||
|
||||
```text
|
||||
SECURITY BOOTSTRAP
|
||||
|
||||
Stage
|
||||
S1 - Low-trust assembly
|
||||
|
||||
Next safe action
|
||||
Define king credential kit
|
||||
|
||||
Blocked gates
|
||||
- OpenBao init: king credential is not prepared
|
||||
- Live secrets: restore drill is not complete
|
||||
- Reopen platform: bootstrap credentials have not been rotated
|
||||
|
||||
Available actions
|
||||
1. Review setup operator
|
||||
2. Define king credential kit
|
||||
3. Run OpenBao preflight
|
||||
4. Print custody packet template
|
||||
5. Show handover checklist
|
||||
```
|
||||
|
||||
Only one action should be visually primary. Everything else is secondary,
|
||||
status-only, or explicitly blocked.
|
||||
|
||||
## Navigation
|
||||
|
||||
Top-level areas:
|
||||
|
||||
| Area | Purpose |
|
||||
| --- | --- |
|
||||
| Overview | Trust stage, next action, blocked gates |
|
||||
| King credential | Dedicated root credential kit and custody posture |
|
||||
| Users | Onboard, lock, offboard, review credentials |
|
||||
| OpenBao | Preflight, ceremony readiness, post-unseal checks |
|
||||
| Fabrics | New fabric setup and admin handover |
|
||||
| Handover | Reset, rotate, scan, restore, reopen |
|
||||
| Audit | Non-secret evidence and progress records |
|
||||
|
||||
The first prototype has CLI sections plus a localhost custody-approval UI. A
|
||||
larger web UI should use a left rail with short labels and a sticky top
|
||||
hairline header.
|
||||
|
||||
## Action Model
|
||||
|
||||
Each action has a typed shape:
|
||||
|
||||
| Field | Meaning |
|
||||
| --- | --- |
|
||||
| Name | Short sentence-case label |
|
||||
| Stage | Earliest trust stage where action is valid |
|
||||
| Preconditions | Required non-secret facts |
|
||||
| Warnings | Plain-language risk note |
|
||||
| Inputs | Non-secret inputs only |
|
||||
| Secret handling | Where the secret is created, displayed, or explicitly not handled |
|
||||
| Result | Non-secret evidence recorded |
|
||||
| Undo/recovery | What to do if the action was wrong or incomplete |
|
||||
|
||||
Actions that would handle root material must default to blocked until the UI can
|
||||
prove the prerequisites. The first prototype should not run live `bao operator
|
||||
init`; it should only report readiness and print the manual ceremony guide.
|
||||
|
||||
## Gate Model
|
||||
|
||||
Gate status values:
|
||||
|
||||
| Value | Meaning |
|
||||
| --- | --- |
|
||||
| `ready` | Safe to perform now |
|
||||
| `blocked` | Required facts are missing |
|
||||
| `human` | Requires deliberate human ceremony or approval |
|
||||
| `done` | Completed and recorded |
|
||||
| `deferred` | Intentionally postponed |
|
||||
|
||||
Avoid red/green severity colors. Use labels, ordering, and text. If color is
|
||||
used, stay in the whynot grey ramp; reserve yellow for a selected or
|
||||
human-required marker.
|
||||
|
||||
## Required Gates
|
||||
|
||||
OpenBao live initialization is blocked until:
|
||||
|
||||
- king credential kit is defined;
|
||||
- custody mode is selected;
|
||||
- offline recovery storage is prepared;
|
||||
- OpenBao preflight passes;
|
||||
- setup operator understands no secret output may enter Git, State Hub, chat,
|
||||
tickets, email, screenshots, or shell history; and
|
||||
- the run is human-attended.
|
||||
|
||||
Platform reopen is blocked until:
|
||||
|
||||
- OpenBao root token is revoked or sealed offline;
|
||||
- non-root admin path exists;
|
||||
- bootstrap-era credentials are reset or rotated;
|
||||
- host/workload checks are complete or explicitly deferred;
|
||||
- backup and restore drill are complete; and
|
||||
- audit sinks are known.
|
||||
|
||||
## Data Sources
|
||||
|
||||
The first console can read:
|
||||
|
||||
| Source | Use |
|
||||
| --- | --- |
|
||||
| State Hub REST | workstream/task status, decisions, progress events |
|
||||
| `net-kingdom` docs | custody model and use-case definitions |
|
||||
| `railiance-platform` make targets | OpenBao preflight and post-unseal checks |
|
||||
| local operator metadata | non-secret answers such as custody mode and kit label |
|
||||
|
||||
Local metadata should be non-secret and should live outside Git by default. If
|
||||
a repo file is needed, it must be a template or example only.
|
||||
|
||||
## Content Rules
|
||||
|
||||
The UI should use short declarative text:
|
||||
|
||||
- "King credential is not prepared."
|
||||
- "OpenBao init is blocked."
|
||||
- "Run preflight from `railiance-platform`."
|
||||
- "Do not paste secret output anywhere."
|
||||
|
||||
Avoid moralizing or dramatic language. Good security here should feel like a
|
||||
clear checklist with good defaults.
|
||||
|
||||
## First Prototype Boundary
|
||||
|
||||
The first prototype should:
|
||||
|
||||
- show trust stage and gates;
|
||||
- print the king credential kit checklist;
|
||||
- run safe OpenBao preflight commands or explain why they cannot run;
|
||||
- generate a non-secret custody packet template;
|
||||
- list user lifecycle actions as guided flows;
|
||||
- list handover cleanup gates; and
|
||||
- refuse live OpenBao init.
|
||||
|
||||
The first prototype should not:
|
||||
|
||||
- store passwords, root tokens, unseal shares, OTP seeds, recovery codes, or
|
||||
private keys;
|
||||
- call `bao operator init`;
|
||||
- send email;
|
||||
- alter IAM users;
|
||||
- rotate live databases automatically; or
|
||||
- hide uncertainty behind a green check.
|
||||
Reference in New Issue
Block a user