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:

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.