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:

```text
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.