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. The operator-workstation state is already off-host and independent of railiance01/OpenBao. Documenting backup and readback of that receipt holder remains an explicit acceptance dependency; no new service is required merely to duplicate it. 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 and workstation receipt-holder backup/readback proof remain owner acceptance requirements, alongside isolated OpenBao recovery evidence.

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.

Attended execution outcome — 2026-10-03

The founder executed admission and empty publication. Fresh receipts, initial revision 1/KV1/no-grant digest and exact residual recovery/reader evidence are recorded in delivery evidence. This completes RPF-WP-0049-T04. T05 remains evidence-blocked; generic approval is not pending. Old operator role configuration is not an execution receipt.

Remaining bounded attended finish

Native isolated Raft recovery and local receipt-holder scratch restoration now pass. The operator-owned directory has no discovered workstation backup job. The non-authoritative recovery copy in docs/evidence/root-custody-history enters the existing owner Forgejo source backup scope; that does not imply a fresh provider archive has included this new commit. One attended command completes current live baseline check plus direct protected history provider readback:

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-custody-finish-attended.sh \
  --state /home/worsch/.local/state/net-kingdom-root-custody/baseline.json \
  --net-kingdom /home/worsch/net-kingdom \
  --receipt /tmp/platform-root-finish-UNIQUE-RUN.json

The silent child uses the current governed OpenBao backup account/lane only, requires the known Backup owner and create-only share shape, checks quota, encrypts history with current escrow, creates one uniquely named artifact under the existing forgejo/ backup folder, downloads through operator authority and verifies ciphertext and decrypted history equality. It deletes nothing and changes no credential or policy. Read the fresh receipt; old receipts are refused.

A local historical rclone configuration was found during backup discovery and its credential-bearing coordinates may have appeared in tool output. It is never reused. The helper compares that share with the current lane in memory and records only booleans. If it is the current lane, the helper stops before upload and requires coordinated existing credential incident/cutover recovery, preserving consumers; it never rotates an uninformed predecessor. If different, the historical owner's revocation status remains unverified separately from root-grant authority. No credential-bearing coordinates are copied to evidence.

Finish failure receipts

The first finish attempt failed after successful authenticated owner reads but before a receipt. Its exact provider cause was lost by the old catch-all; it is not evidence of missing IAM. The corrected wrapper reserves a fresh receipt before helper imports and always records safe stage/error codes. Inspect that receipt after execution even if the child returns nonzero. Failed upload or readback includes safe numeric HTTP status and generated artifact name when available; do not rerun with the same receipt path or weaken expected provider contract/status checks blindly. No token, share coordinates, private key, raw response or exception message is written. helper_import means startup failed; backup_operator_read means current owner credential retrieval failed; provider_contract, crypto, quota, upload/download or ciphertext/decrypt stages identify the remaining provider proof boundary. Login cleanup and task success remain separate, and only a verified fresh success receipt completes T05.

The finish helper also uses the established independent operator escrow at /home/worsch/.config/age/railiance-backup.key. It derives that key's public recipient in a captured subprocess, compares it with the current governed lane and decrypts the downloaded artifact with the independent key file. Only match and decryption booleans are recorded; the private key is never read into logs or replaced. A missing/different escrow is an explicit fixed-code recovery failure, not a request to create or reset a key implicitly.

The 2026-10-03 finish receipt returned HTTP401 at public upload after current baseline and independent escrow verification passed. Corrected clients include Nextcloud's required X-Requested-With: XMLHttpRequest header for public DAV non-GET operations. See official DAV documentation and stable31 public handler. Live causality is unproved until a fresh attended finish run succeeds. This changes request protocol only; preserve lane/token/permissions and do not rotate credentials or fall back to wider account uploads. Failure receipts now retain current lane KV version. The historical exposed share differs from current lane; separate historical owner/revocation evidence remains unverified.

The corrected-header retry still returned401 against lane KVversion3. Before another upload use the same attended wrapper with --inspect-share and a fresh receipt path. This performs only owner-scoped existing-share OCS inspection and Depth0 public DAV route probes; successful diagnostic receipt explicitly sets backup_roundtrip_proved=false. Current route uses reviewed lane coordinates; documented /public.php/dav/files/{token} is probed read-only, with and without Basic auth. Protected shares require their password per official documentation; no password is inferred or changed. A later repair must follow diagnosed owner procedure; inspection cannot change lane, shares or provider files.

Actual read-only inventory found neither token nor label in exact folder at lane KV3. This is not proof of deletion or absence in subfolders. Repair mode checks all Backup account-owned shares for label ambiguity, verifies exact folder and account before creating only the reviewed create-only public link. It requires explicit --repair-share --expected-lane-version 3 --confirm-repair "RESTORE Backup CREATE ONLY". Existing or new candidate must have exact owner/path/label/public type/permissions4, known absent password and expiry. Known share re-read must match. Then actual retained history is encrypted, uploaded through documented public files route with required header, downloaded as Backup, independently escrow-decrypted and compared BEFORE CAS. Only token and URL are changed; every other lane field and all old shares/files preserved. Fresh receipt keeps share ID and provider proof if subsequent CAS/readback fails. On retry matching reviewed candidate is reused; stale expected version refuses. PROPFIND denial alone does not prove grant invalid: create-only policy can deny read properties. Backup consumers need normal governed credential refresh after cutover; this is separate from custody history proof and no live rollout occurs.

Producer recovery completed2026-10-03: fresh founder repair receipt proves current empty revision1/KV1 matches retained baseline, actual encrypted upload201, Backup readback200, independently escrow-decrypted history match before CAS3->4. See safe provider receipt. Producer plan RPF-WP-0049 finished. Backup runtime consumer refresh remains activity-core-owned; historical share revocation is separately unverified. No real custody grant was added.