openbao king credential bootstrapping

docs/security-bootstrap-handover-cleanup.md

@@ -0,0 +1,103 @@
+# Security Bootstrap Handover And Cleanup
+
+Status: draft UX contract
+Date: 2026-05-24
+
+## Purpose
+
+This document defines the post-king handover cleanup and reopen gates. It is
+the product contract for `NET-WP-0016-T07`.
+
+The platform can be assembled in MVP/prototype mode, but it should not be
+treated as clean until bootstrap-era credentials, databases, tokens, and access
+paths have been reviewed and reset or rotated.
+
+## Handover Goal
+
+The handover proves that:
+
+- the king credential controls platform-root recovery;
+- day-to-day setup access is scoped and revocable;
+- OpenBao root-token disposition is known;
+- bootstrap-era material has been reset or rotated;
+- backups and restore work; and
+- the platform can reopen under explicit custody.
+
+## Cleanup Checklist
+
+| Area | Required action |
+| --- | --- |
+| Gitea/admin accounts | Review admins, remove stale accounts, require MFA where available |
+| IAM users | Review setup users, platform admins, tenant admins, and reviewers |
+| Databases | Reset bootstrap passwords and rotate app credentials |
+| OpenBao | Revoke or seal root token, verify non-root admin path, review policies |
+| Kubernetes | Review service accounts, tokens, namespaces, and privileged bindings |
+| SSH/access | Review keys, remove unknown keys, rotate setup access where needed |
+| SOPS/age | Review recipients and emergency bundle handling |
+| State Hub | Record non-secret decisions, progress, and remaining gates |
+| Backups | Take snapshot and run restore drill before live secrets |
+| Audit | Confirm durable audit routing or documented interim custody |
+| Scans | Run host/workload checks available for the current environment |
+
+## Reopen Gates
+
+The platform may be marked reopened only when:
+
+- king credential kit is complete;
+- OpenBao is initialized and unsealed or approved for the next seal posture;
+- root token is revoked or offline-sealed;
+- non-root platform admin path exists;
+- bootstrap databases and admin credentials are reset or rotated;
+- no unknown platform admins remain;
+- backup snapshot exists;
+- restore drill has passed;
+- audit handling is known;
+- user lifecycle paths are documented; and
+- remaining risk exceptions are listed with owners and dates.
+
+## UX Shape
+
+The handover screen should be a checklist with evidence rows:
+
+```text
+HANDOVER
+
+Stage
+S4 - Cleanup and hardening
+
+Blocked
+- Reopen platform: restore drill missing
+- Live secrets: root-token disposition deferred
+
+Evidence
+- King credential kit: complete
+- OpenBao preflight: passed
+- Non-root admin path: pending
+```
+
+The UI should avoid a celebratory "complete" state. It should say "reopened
+under custody" and list any remaining exceptions.
+
+## Related Workplan Review
+
+When `NET-WP-0016` closes, review related security and bootstrap workplans for
+stale assumptions:
+
+- `NET-WP-0015` for king credential and custody status;
+- `NK-WP-0001` for older Vault and admin bootstrap language;
+- `NK-WP-0004` for credential-management foundation alignment;
+- `NK-WP-0005` for agent-driven bootstrap boundaries;
+- `NK-WP-0006` for platform-root architecture language;
+- `NK-WP-0007` for OpenBao and STS responsibility split;
+- `NK-WP-0011` for future expanded-mode identity;
+- `RAIL-PL-WP-0002` for OpenBao live ceremony gates; and
+- any SSO/MFA bootstrap scripts that still assume MVP credentials are final.
+
+Each review should result in one of:
+
+- keep as-is;
+- update stale language;
+- add follow-up task;
+- mark superseded; or
+- archive/retire if the workplan is now represented by the guided bootstrap
+  experience.