---
id: NET-WP-0016
type: workplan
title: "Guided Security Bootstrap Experience"
domain: netkingdom
repo: net-kingdom
status: finished
owner: codex
topic_slug: netkingdom
created: "2026-05-24"
updated: "2026-05-24"
depends_on:
  - NET-WP-0015
  - NK-WP-0012
state_hub_workstream_id: "16069174-6698-4855-ad9e-5092c8571f38"
---

# NET-WP-0016 - Guided Security Bootstrap Experience

## Goal

Create the operator-facing bootstrap experience that makes NetKingdom and
OpenBao security setup understandable, repeatable, and safe for non-experts.

The platform should be possible to assemble with a low-trust setup operator,
then hand over to a dedicated king credential, reset and harden the bootstrap
state, and reopen under explicit custody.

## Context

Railiance and NetKingdom have reached a point where raw runbooks are not enough.
The infrastructure is still early and evolving, and the human operator does not
need to be an OpenBao/Keycloak/flex-auth expert to take the next safe step.

Good security here should feel like guided operations: visible trust stage,
clear blocked actions, plain-language explanations, and no accidental secret
exposure.

## Scope

In scope:

- define bootstrap use cases for king credential setup, user lifecycle,
  OpenBao bootstrap, fabric setup, break-glass, and multi-custodian upgrade;
- design the first local operator console/checklist flow;
- define safety gates for live OpenBao initialization;
- define non-secret status records and audit/progress events;
- define where the UI reads status from NetKingdom, Railiance, and State Hub;
  and
- implement a first minimal CLI or local UI if the design stabilizes.

Out of scope:

- storing or displaying secret values;
- implementing the full web UI before the workflow is validated;
- replacing OpenBao, key-cape, Keycloak, or flex-auth administrative UIs;
- unattended OpenBao initialization; and
- sending root material or recovery secrets by email.

## Tasks

### T01 - Define Bootstrap Use Cases

```task
id: NET-WP-0016-T01
status: done
priority: high
state_hub_task_id: "67af8a29-7ca1-4a9d-be3e-bdc48dd2d1fd"
```

Document the canonical bootstrap use cases and trust stages.

**2026-05-24:** Added `docs/security-bootstrap-use-cases.md` covering king
credential setup, onboarding, temporary lockout, permanent lockout/offboarding,
credential review/rotation, new fabric admin setup, OpenBao bootstrap, custody
handover, and later multi-custodian upgrade.

### T02 - Design The First Operator Journey

```task
id: NET-WP-0016-T02
status: done
priority: high
state_hub_task_id: "662e439b-5fba-4e17-bc62-0ace97ba8788"
```

Design the first command-driven or local-web operator journey: trust stage,
next safe action, blocked gates, preflight checks, custody packet template, and
clear plain-language instructions.

**2026-05-24:** Added `docs/security-bootstrap-operator-journey.md`. The first
journey uses a quiet `whynot-design` control surface: trust stage, one next
safe action, blocked gates, evidence rows, and a refusal boundary around live
OpenBao initialization.

### T03 - Define King Credential Kit Output

```task
id: NET-WP-0016-T03
status: done
priority: high
state_hub_task_id: "98aba75f-a7c1-4486-be7f-e8d1148d5303"
```

Define the non-secret artifacts the bootstrap experience can generate for the
king credential: checklist, custody packet template, OTP setup instructions,
password-safe guidance, and verification prompts.

**2026-05-24:** Added `docs/security-bootstrap-king-credential-kit.md`.

### T04 - Define User Lifecycle Flows

```task
id: NET-WP-0016-T04
status: done
priority: high
state_hub_task_id: "44766b45-21b8-45cd-8c0a-0ca8281ae8e9"
```

Define guided flows for onboarding, temporary lockout, permanent lockout,
offboarding, credential review, credential rotation, and delegated fabric admin
setup.

**2026-05-24:** Added `docs/security-bootstrap-user-lifecycle.md`.

### T05 - Define OpenBao Ceremony UX

```task
id: NET-WP-0016-T05
status: done
priority: high
state_hub_task_id: "53f55c99-8403-4b58-9ed4-b03e68c1ef3c"
```

Translate the Railiance OpenBao ceremony into a guided sequence that can show
status, block unsafe live init, guide offline custody, and record non-secret
completion evidence.

**2026-05-24:** Added `docs/security-bootstrap-openbao-ceremony-ux.md`.

### T06 - Prototype Local Bootstrap Console

```task
id: NET-WP-0016-T06
status: done
priority: medium
state_hub_task_id: "ef1c8ee4-250c-479a-b0fb-0b5cf4249bd9"
```

Implement the first minimal local operator console or CLI once the journey is
clear. It should read status, print checklists, run safe preflight commands,
and refuse live bootstrap when gates are missing.

**2026-05-24:** Added
`tools/security-bootstrap-console/security_bootstrap_console.py`, a read-only
local console with status, king-kit, custody-packet, handover-checklist,
metadata-template, and OpenBao preflight commands. Added Make targets for the
safe entry points. The console refuses live OpenBao init.

### T07 - Define Handover And Cleanup Gates

```task
id: NET-WP-0016-T07
status: done
priority: medium
state_hub_task_id: "46c7e3dc-e824-46ef-833d-9a83189735e0"
```

Define the post-king handover cleanup flow: reset databases, rotate tokens,
review admin accounts, run scan/check steps, verify backups, and mark the
platform reopened under king oversight.

**2026-05-24:** Added `docs/security-bootstrap-handover-cleanup.md`.

### T08 - Review Related Workplans On Closeout

```task
id: NET-WP-0016-T08
status: done
priority: medium
state_hub_task_id: "7665f6ac-6b0e-4a09-8a9b-9d2150310114"
```

When this workplan closes, review related NetKingdom and Railiance security
workplans to update stale bootstrap assumptions, retire superseded tasks, and
add follow-ups where the guided bootstrap experience becomes the canonical
operator path.

**2026-05-24:** Added
`docs/security-bootstrap-related-workplan-review.md`, kept `NK-WP-0004` and
`NK-WP-0005` as substrate workplans with closeout notes, left historical
`NK-WP-0001` archived, and updated stale Railiance OpenBao custody wording.

## Acceptance Criteria

- The setup operator can see the current trust stage and next safe action.
- Live OpenBao init remains blocked until king credential and custody gates are
  satisfied.
- User lifecycle operations are described in plain, auditable flows.
- New fabrics can receive delegated admins without granting platform root.
- Secret values are never stored or displayed by the bootstrap experience.
- The path to two-of-three custody is explicit and low-friction.