net-kingdom/docs/security-bootstrap-operator-journey.md

# 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.