net-kingdom/workplans/NET-WP-0016-guided-security-bootstrap-experience.md

id, type, title, domain, repo, status, owner, topic_slug, created, updated, depends_on, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	created	updated	depends_on	state_hub_workstream_id
NET-WP-0016	workplan	Guided Security Bootstrap Experience	netkingdom	net-kingdom	finished	codex	netkingdom	2026-05-24	2026-05-24	NET-WP-0015 NK-WP-0012	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

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

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

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

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

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

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

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

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.