net-kingdom/docs/security-bootstrap-use-cases.md

Security Bootstrap Use Cases

Status: draft product/security model Date: 2026-05-24

Purpose

This document defines the operator-facing use cases for bootstrapping NetKingdom security infrastructure and Railiance OpenBao custody. The goal is a guided experience that makes the secure path the easy path.

Early infrastructure may be assembled by an anonymous or low-assurance setup operator. That operator can deploy, observe, and prepare the system, but must not become the permanent root of trust by accident. The dedicated king credential accepts custody later, then the platform is reset, rotated, checked, and reopened under explicit oversight.

Design Principles

• No secret value is stored in Git, State Hub, chat, tickets, screenshots, or email.
• Email may notify; it must not carry root secrets or recovery material.
• Day-to-day accounts can operate setup tooling but should not hold master custody.
• Every dangerous step has plain language, a checklist, a confirmation, and a rollback or recovery explanation.
• The UI should show trust stage, current gates, and next safe action.
• The system should be useful before all future security components exist.
• Two-of-three custody should be an upgrade path, not a redesign.

Trust Stages

Stage	Name	UX posture
S0	MVP/prototype	Warn that state is not clean enough for live secrets.
S1	Low-trust assembly	Allow setup by a low-assurance operator; block live custody actions.
S2	King credential preparation	Guide creation/import, second factor, and offline recovery.
S3	OpenBao bootstrap	Guide init/unseal/configure without exposing secret output.
S4	Cleanup and hardening	Reset/rotate bootstrap-era state and run checks.
S5	Reopen under custody	Enable delegated admin/user operations under king oversight.
S6	Multi-custodian upgrade	Add independent custody and rekey/recovery drills.

Use Cases

A. Set Up King Credential

Goal: create or import the dedicated platform-root credential independently of day-to-day accounts.

UX requirements:

• explain why the king credential is separate from Gitea/email;
• guide password-safe or offline storage choice;
• guide OTP or hardware-backed second factor setup through the verifying authority, without generating or storing seed material in the bootstrap UI;
• verify recovery codes exist without collecting them;
• record only non-secret metadata: credential label, creation date, custody posture, and notification contact; and
• require a deliberate confirmation before OpenBao bootstrap can proceed.

B. Onboard New User

Goal: add a user with scoped day-to-day access.

UX requirements:

• identify whether the user is a setup operator, platform admin, tenant admin, reviewer, or workload/service principal;
• map requested access to IAM groups and OpenBao/flex-auth scopes;
• require MFA where role sensitivity demands it;
• avoid granting platform-root authority through ordinary onboarding; and
• produce an audit record and review date.

C. Temporarily Lock User

Goal: suspend access without deleting identity history.

UX requirements:

• disable login/session/token issuance;
• revoke active sessions and temporary tokens where supported;
• preserve audit identity and ownership records;
• make unlock path explicit; and
• show dependent service accounts or keys that may be affected.

D. Permanently Lock And Offboard User

Goal: remove a user from operational access while preserving audit evidence.

UX requirements:

• revoke sessions, tokens, app passwords, SSH keys, and OpenBao tokens;
• transfer owned resources or service principals;
• remove groups/roles and tenant memberships;
• keep immutable audit records;
• schedule credential rotation for any shared material the user may have seen; and
• require a second confirmation for platform/admin users.

E. Review And Change User Credentials

Goal: inspect credential posture and rotate or reset safely.

UX requirements:

• show MFA state, recovery-code freshness, active tokens, SSH keys, and role memberships;
• separate "rotate credential" from "change authorization";
• offer a safe emergency reset flow;
• record non-secret evidence of completion; and
• never reveal credential values.

F. Set Up New Fabric With Its Own Admin

Goal: create a new fabric or deployment with delegated admin control.

UX requirements:

• create fabric identity and admin boundary;
• bind admin claims to that fabric without granting platform-root;
• create OpenBao path prefixes and policies;
• create audit routing and backup expectations;
• document handover to the fabric admin; and
• make transfer/revocation path clear.

G. Bootstrap OpenBao

Goal: initialize OpenBao after the king credential is prepared.

UX requirements:

• verify OpenBao pod, PVCs, initialization state, and backup posture;
• show the exact trust stage and why live init is or is not allowed;
• guide key-share/threshold choice;
• avoid printing or storing secret output where possible;
• prompt for manual custody actions out-of-band;
• configure audit, initial mounts, and non-root admin path; and
• require root-token revoke or offline escrow disposition.

H. Transfer Custody To King Credential

Goal: move from low-trust setup to explicit platform-root control.

UX requirements:

• verify king credential login and second factor;
• verify root-token disposition and OpenBao admin path;
• rotate bootstrap credentials and admin passwords;
• reset databases or service credentials created during MVP/prototype mode;
• run host/workload checks and vulnerability scans where available;
• complete backup/restore drill; and
• only then mark the platform reopened under custody.

I. Add Multi-Custodian Control

Goal: upgrade from single king custody to two-of-three or equivalent.

UX requirements:

• guide custodian invitation without sending secrets by email;
• explain share/threshold consequences in plain language;
• perform OpenBao rekey or recovery-key update when appropriate;
• record escrow holders without recording secret shares;
• run a recovery drill; and
• keep single-custodian fallback only as an explicit exception.

First Interface Shape

The first version can be a local operator console rather than a full web app. It should be command-driven but humane:

Security Bootstrap Console

Trust stage: S1 - Low-trust assembly
Next safe action: Create or import king credential

Blocked:
- OpenBao init: king credential not prepared
- Live secrets: OpenBao not initialized and restore drill not complete

Available:
- Review setup operator
- Generate king credential checklist
- Run OpenBao preflight
- Print offline custody packet template

As the flow matures, it can become a local web UI that ties together NetKingdom identity, OpenBao status, user lifecycle, custody posture, audit events, and fabric onboarding.

The visual language should follow whynot-design: quiet document surfaces, sentence-case labels, mostly black and white, one yellow highlighter accent, 1px hairlines, no gradients, no card shadows, and no marketing copy. Security state should be legible through labels and structure, not decorative color.

Non-Goals For The First Version

• no secret manager UI that displays secret values;
• no automated email delivery of credentials;
• no unattended OpenBao initialization;
• no permanent trust in MVP bootstrap accounts;
• no tenant-admin path to platform-root authority; and
• no dependency on full Keycloak/federation before the bootstrap console is useful.