railiance-platform/openbao/root-grant

Approved platform-root producer design

Prepared for NK-WP-0045-T05 / RPF-WP-0049, 2026-10-03. Founder approved: "Accept ADR-0017 and approve the proposed OpenBao delivery design." Scoped made decision receipt: c2cff929-91b9-4018-bfd6-fa04f7da8280. This selects railiance-platform and the exact source below. Identity admission, attended live provisioning, custody provenance and live readiness remain pending. NetKingdom canon remains authoritative; reviewed baseline is net-kingdom commit db319335b27b61b855382ee5af5d690f06eeb010. Deployments must pin the validator and its schema together, and reconcile amendments before publication.

Approved source and transport

• KV v2 mount: platform (existing owner convention; live suitability unverified).
• Exact API path: /v1/platform/data/custody/net-kingdom/platform-root.
• record_id: nk-custody:platform-root; owner_system: net-kingdom-custody.
• API response unwrap: data.data.document is the complete canon document. data.metadata.version is KV concurrency state, distinct from canon revision.
• Reader: owner manifests identify namespace user-engine, ServiceAccount user-engine. Role user-engine-root-custody-reader on auth/kubernetes binds exactly those values and audience openbao. Tokens last at most 60s, with no default policy. Dedicated projected JWT is owned by rapp-user-engine; the existing flex-auth JWT and ESO AppRole are not reused. Live admission remains unexecuted. Reader policy is exact-path read; no list, sibling read or write. Never distribute an attended writer token.
• Writer: separate human custody lane, bounded attended MFA operator login, reviewed exact-path policy. This packet does not grant a credential or role.
• Reader timeout 5 seconds, maximum document 256 KiB. A successful authenticated owner read, not document time or a cache read, sets observed_at. Failure means no grant. No raw server response/error logging.

Offline implementation

scripts/root_grant_publish.py creates a single KV v2 CAS payload from a candidate, previous document, exact previous KV version and the pinned NetKingdom validator module. No network or publication is implemented here. It validates both documents, exact source identity and successor semantics; refuses missing existing baselines, same-revision changes and rollback. CAS=0 is bootstrap-only, CAS=current-version updates; a CAS conflict requires a fresh owner read and revalidation, never blind retry. It never prints documents.

The attended executor is implemented in scripts/root_grant_attended.py:

• provision checks existing Kubernetes auth and active audit, admits only the exact reviewed reader policy/role, enables CAS on this key and verifies all readbacks. Differing existing policies/roles are refused without overwrite.
• publish reads current document and KV version together, validates pinned canon and the persisted high-water baseline, fsyncs a pending journal before CAS write, verifies exact readback, retains immutable local history and atomically advances state. Exact replay creates no new version. Ambiguous writes recover only after exact matching owner readback and durable history.
• restore-check requires the independently retained publisher baseline to match the restored source exactly. Missing/different baseline never resets authority or permits rollback. Off-host history backup is still an execution dependency; local files alone cannot prove safe disaster restoration.
• The silent child requires the existing warden attended-login envelope and exact loopback OpenBao tunnel. No raw process response/error is emitted. Every invocation requires a new receipt path: old success receipts are refused.

Authorized attended execution packet

Founder approval to "go forward" authorizes continued implementation and bounded provisioning of the approved design. No additional generic design approval is requested. Attended OIDC/MFA must still run in the founder's own terminal:

BAO_ADDR=http://127.0.0.1:18200 VAULT_ADDR=http://127.0.0.1:18200 \
  warden access openbao-platform-admin-login --exec -- \
  /home/worsch/railiance-platform/scripts/root-grant-attended.sh provision \
  --receipt /tmp/platform-root-admission-UNIQUE-RUN.json

Replace UNIQUE-RUN with a fresh run identifier. The child is silent. Inspect the new JSON receipt and warden's printed result; a shell exit code or previous receipt cannot establish success. Provisioning does not create a custody grant. Existing operator platform-admin identity provides the human writer lane; this packet does not create another privileged identity or reuse its token in user-engine. Deployment/network policy/consumer activation belongs to rapp-user-engine and follows source image publication and admission receipts.

The founder reported that no actual custody ceremony is known. NetKingdom has therefore prepared examples/custody-record/initial-empty-record.json, a schema-valid first publication candidate with entries: []. It establishes no root grant. The non-secret provenance is net-kingdom/docs/evidence/2026-10-03-root-grant-delivery-progress.md. Continued go-forward approval covers preparing and publishing this no-grant baseline through the attended owner lane; no new generic approval is needed. A future real grant still requires a genuine signed human ceremony with exact issuer and subject; planned roster/LLDAP membership cannot supply it.

After successful admission, run this second attended step in the founder's terminal. Create the operator-owned state directory first; it must persist outside the checkout and outside warden's temporary attended-login home.

install -d -m 700 /home/worsch/.local/state/net-kingdom-root-custody
BAO_ADDR=http://127.0.0.1:18200 VAULT_ADDR=http://127.0.0.1:18200 \
  warden access openbao-platform-admin-login --exec -- \
  /home/worsch/railiance-platform/scripts/root-grant-attended.sh publish \
  --candidate /home/worsch/net-kingdom/examples/custody-record/initial-empty-record.json \
  --state /home/worsch/.local/state/net-kingdom-root-custody/baseline.json \
  --provenance-ref net-kingdom/docs/evidence/2026-10-03-root-grant-delivery-progress.md \
  --net-kingdom /home/worsch/net-kingdom \
  --validator-digest 9156e399c8d92a45b817bfc3738c89843487ce57e1718ed747f804f95cc719bb \
  --schema-digest bb6cd6da5dc48eddcf118ae78c2cacfafd5f860098fd8a8368fe6bc845776d07 \
  --receipt /tmp/platform-root-publish-UNIQUE-RUN.json

Inspect the new receipt. Existing source without independently retained state is refused rather than overwritten; a failed/ambiguous write requires owner readback and journal recovery. Bootstrap uses CAS=0. The publisher retains baseline.json and immutable history/ receipts. Restore baseline.json, history/ and any pending journal from independently retained latest evidence before a recovery check; restoring only an older OpenBao snapshot cannot establish current authority. Off-host history backup destination, owner and readback receipt remain an explicit acceptance dependency. Local state enables safe publication but does not satisfy that independent recovery proof.

restore-check takes the same source pins and state but no candidate or provenance argument, plus a fresh receipt path, via the same attended wrapper. Source digests enforce the reviewed NetKingdom validator and schema without importing an unreviewed path. Neither command should print document contents, privileged tokens or raw backend errors.

Acceptance also needs revocation/supersession exercise and rollback/restore receipts. Exercise real grant changes only under their own custody ceremony approval. Use isolated synthetic paths for non-live algorithm exercises.

History, recovery and audit

OpenBao audit is owned by railiance-platform; the custody fact and ceremony are owned by net-kingdom-custody. Confirm mount backup owner and restoration before calling this source live. Retain KV history and independent publication digest / revision high-water receipts. Readers persist their own trusted baseline across restart. A restored snapshot must not reactivate an older grant: suspend reads, compare restored record with independently retained latest baseline, reconcile all later custody actions, and re-enable only after owner receipts. Do not reset baselines, destroy versions or recreate an old record under the same ID. KV CAS prevents races, but is not proof against snapshot rollback. Retention settings and independent backup location remain an owner implementation gate.

No control was relaxed and no live action was taken. Emergent knowledge 0.2.3 start was withheld/orientation-only (digest 60f8811c6b94b30d357a0d9e5022f2a8ea52e69b47138d3a536755f3295310b5); source review read the-custodian agent-environment-orientation section 0 and informed-decision README, plus the source NetKingdom contract/schema/validator.

Producer delivery receipts complete RPF-WP-0049-T05 / NK-WP-0045-T05. Consumer integration and runtime acceptance follow in USER-WP-0037-T02 / NK-WP-0045-T06; they do not block initial producer delivery.