Platform secret setup

docs/openbao.md

@@ -88,6 +88,22 @@ That state is intentional until the bootstrap ceremony is completed.
 Do not initialize OpenBao in a casual shell session. Initialization emits the
 unseal keys and initial root token. Treat this as a break-glass event.
 
+Pre-flight checks:
+
+```bash
+make openbao-status
+make openbao-verify
+```
+
+Proceed only when:
+
+- `openbao-0` is Running.
+- data and audit PVCs are Bound.
+- `bao status` reports `Initialized: false` and `Sealed: true`.
+- Railiance01 host/cluster backup posture is understood for this maintenance
+  window.
+- three human escrow recipients are named before the command is run.
+
 Recommended ceremony:
 
 1. Confirm the Railiance01 backup posture first.
@@ -110,6 +126,12 @@ Recommended ceremony:
    auth, enable audit, and prepare policies.
 7. Revoke or tightly escrow the initial root token.
 
+Do not paste unseal keys, root tokens, screenshots, or command output into Git,
+State Hub, chat, shell history, or issue trackers. Each unseal share goes to one
+escrow owner through an out-of-band channel. The initial root token is either
+revoked after a non-root platform-admin token exists or stored as offline
+break-glass material with the same handling as unseal shares.
+
 ## Initial Configuration After Unseal
 
 Enable file audit:
@@ -130,6 +152,107 @@ Kubernetes auth, database dynamic credentials, PKI, CSI, and External Secrets
 integration are follow-up tasks in `RAIL-PL-WP-0002`. Do not migrate live
 application secrets until those policies and restore drills are documented.
 
+The repo now includes a non-secret helper for the first post-unseal
+configuration:
+
+```bash
+make openbao-configure-initial
+```
+
+The target prompts for a token, enables file audit, enables the `platform/` KV
+v2 mount, enables Kubernetes auth, configures Kubernetes auth from the in-pod
+service account, and loads:
+
+- `openbao/policies/platform-admin.hcl`
+- `openbao/policies/platform-readonly.hcl`
+
+It does not print or store the token. You may also set
+`OPENBAO_TOKEN_FILE=/path/to/token-file` for an operator-local, uncommitted
+token file.
+
+After the helper succeeds, create a non-root admin token:
+
+```bash
+kubectl exec -n openbao openbao-0 -- \
+  bao token create -policy=platform-admin -period=24h -orphan
+```
+
+Store that token through the approved operator secret path, then revoke or
+tightly escrow the initial root token. The root token should not become the
+normal operator credential.
+
+## Auth And Workload Integration
+
+Initial auth model:
+
+| Actor | Method | Notes |
+|-------|--------|-------|
+| Bootstrap operator | one-time root token | only for initial audit, mounts, auth, policies, and non-root token creation |
+| Platform operator | token with `platform-admin` | temporary until NetKingdom OIDC/admin integration is ready |
+| Read-only reviewer | token with `platform-readonly` | metadata and health visibility, no secret reads |
+| Kubernetes workload | Kubernetes auth role | namespace/service-account bound, policy per workload |
+| Human identity | NetKingdom IAM Profile/OIDC | target model; OpenBao is not the identity provider |
+| Automation | Kubernetes auth or short-lived operator token | no root tokens in automation |
+
+Workload delivery choice:
+
+- Prefer External Secrets Operator for values that should become Kubernetes
+  Secrets consumed by ordinary Helm charts.
+- Use CSI-mounted files for workloads that need file references, sharper
+  mount-level boundaries, or secret refresh without rewriting application
+  manifests.
+- Do not use the OpenBao injector in the current deployment; the Helm values
+  leave it disabled.
+- Application repositories request paths and policies; `railiance-platform`
+  owns platform mounts, policy shape, and delivery mechanisms.
+
+Path convention:
+
+```text
+platform/workloads/<namespace>/<service-account>/<secret-name>
+platform/object-storage/<consumer>
+platform/databases/<consumer>
+platform/operators/<purpose>
+```
+
+The template policy for workload KV reads is
+`openbao/policies/workload-kv-read-template.hcl`.
+
+## Backup, Restore, Audit, And Monitoring
+
+Before any live application secrets move into OpenBao:
+
+1. Enable file audit and confirm an audit file is written under
+   `/openbao/audit/openbao-audit.log`.
+2. Create an OpenBao Raft snapshot from the unsealed pod:
+
+   ```bash
+   kubectl exec -n openbao openbao-0 -- \
+     bao operator raft snapshot save /tmp/openbao-raft.snap
+   kubectl cp openbao/openbao-0:/tmp/openbao-raft.snap ./openbao-raft.snap
+   ```
+
+3. Encrypt the snapshot with age/SOPS-compatible custody before it leaves the
+   operator machine.
+4. Run an isolated restore drill before treating OpenBao as live secret
+   custody. The drill must prove that a fresh OpenBao instance can restore the
+   snapshot, unseal, and read a test secret.
+5. Decide where audit logs are shipped durably. The audit PVC alone is not a
+   durable audit sink.
+6. Run:
+
+   ```bash
+   make openbao-verify-post-unseal
+   ```
+
+Monitoring baseline:
+
+- pod readiness and liveness from Kubernetes probes
+- `bao status` seal/init state
+- PVC capacity for data and audit storage
+- audit log write success
+- future Prometheus scraping once the cluster monitoring stack exists
+
 ## Artifact-Store Object Storage Handoff
 
 `artifact-store` is the consumer-facing artifact preservation service for