net-kingdom/workplans/NK-WP-0045-root-grant-custody-record.md

id	type	title	domain	repo	status	flavor	owner	topic_slug	created	updated	related	state_hub_workstream_id
NK-WP-0045	workplan	Make the platform-root custody record readable as a non-secret root-grant fact	infotech	net-kingdom	finished	implementation	claude-code	netkingdom	2026-09-29	2026-10-03	NK-ADR-0017 NK-WP-0042	43fbb1aa-b711-5792-b72b-07cd93ca8f45

Accepted NK-ADR-0017 makes the platform-root custody record the authority for the root grant. The non-secret schema/validator and OpenBao delivery design are complete and approved; live delivery, consumer acceptance and independent retained-history recovery are verified. The published empty record returns no root grant. This work does not assign a custodian from directory or claim projections, and no secret material enters the record.

Accept ADR-0017

id: NK-WP-0045-T01
status: done
needs_human: false
decision_id: c2cff929-91b9-4018-bfd6-fa04f7da8280
priority: high
state_hub_task_id: "25489680-c611-59f9-a0c4-291c4e2a7356"

Resolve the open points (15-minute cache bound, envelope mapping) and move the ADR to accepted.

2026-10-03: human gate routed to hub decision cef97ccd-4ee7-40fe-859e-1df9c9360ecb (D10: Identity record and MFA: accept NK-ADR-0017, choose the record read surface, agree the MFA user experience) by CUST-WP-0075; resolving that decision raises C-40 here.

Define the custody-record schema

id: NK-WP-0045-T02
status: done
depends_on: [NK-WP-0045-T01]
priority: high
state_hub_task_id: "49d8dd25-b555-55e9-a481-037d2b98fcc5"

Add canon/schemas/custody-record_v0.1.schema.json: record id and revision, (issuer, subject), relation platform-root-custodian, tenant:platform, granted-at, superseded-by, revoked-at with actor and reason. Non-secret only; the schema rejects token, key, share and recovery-code fields.

Done 2026-10-03 (CUST-WP-0075, build mode; ADR-0017 stays proposed, acceptance remains T01 under decision cef97ccd). Added canon/schemas/custody-record_v0.1.schema.json: record_id + monotonic per-record revision, owner_system: net-kingdom-custody, and entries keyed by exact (issuer, subject) (no username/email/group key), each with the fixed grant {scope_type: tenant, scope_id: platform, relation: platform-root-custodian, owner_system: net-kingdom-custody}, ceremony evidence (basis: custody-ceremony only, so projections cannot ground an entry), granted, optional superseded_by (entry id + revision) or revoked (at, actor, reason, revision), never both. A freshness block caps consumer cache at 900 s with on_unreadable: no-grant. Field names matching token, key, secret, share, recovery, password, reset, seed, private, otp or credential are rejected at every level. Incorporates user-engine's 2026-10-03 confirmation (message 60acf176): exact (issuer, subject) keying, monotonic revision, 15-minute cache bound, fail closed. If T01 amends the ADR, revise this schema to match.

Add a validator and fixtures

id: NK-WP-0045-T03
status: done
depends_on: [NK-WP-0045-T02]
priority: medium
state_hub_task_id: "6372f282-a12b-54b4-b2ea-327b20e58c8f"

Validator with grant, revocation and supersession fixtures, plus negative cases: projection-only grants, tenant-admin implication, secret-bearing fields. Follow the existing tool layout under tools/.

Done 2026-10-03 (CUST-WP-0075). tools/custody-record/validate.py (schema plus semantics: one active grant per (issuer, subject), revision ordering, supersession links, secret-looking values; successor_errors for append-only, strictly newer revisions so a stale read is distinguishable from a revocation; observe_root_grant for the ADR-0017 section 3 fail-closed read rule). Fixtures under tools/custody-record/fixtures/: valid grant, revocation, supersession; invalid projection-only grant, tenant-admin implication, other tenant, root-token / recovery-code / unseal-share fields, secret-looking value, username key, cache over 900 s, duplicate active grant, revoked-and-superseded. Tests tools/custody-record/tests/test_custody_record.py (13 passed; make custody-record-test); full pytest tests tools: 131 passed.

Decide the read surface

id: NK-WP-0045-T04
status: done
depends_on: [NK-WP-0045-T02]
needs_human: false
decision_id: c2cff929-91b9-4018-bfd6-fa04f7da8280
priority: high
state_hub_task_id: "472e191f-8b7a-5d0e-84ef-2717f92bc83c"

Options and the owner (net-kingdom versus railiance-platform) go to Bernd; the answer fixes T05.

2026-10-03: human gate routed to hub decision cef97ccd-4ee7-40fe-859e-1df9c9360ecb (D10: Identity record and MFA: accept NK-ADR-0017, choose the record read surface, agree the MFA user experience) by CUST-WP-0075; resolving that decision raises C-40 here.

Deliver the read path with the owner

id: NK-WP-0045-T05
status: done
depends_on: [NK-WP-0045-T04, RPF-WP-0049-T05]
wait_kind: null
blocked_on: null
needs_human: false
intervention_note: null
blocking_reason: null
priority: medium
state_hub_task_id: "628e8a3b-17a4-5f97-a484-c564a87d650d"

Hand off the schema and read contract to the owner; NetKingdom does not absorb the runtime. Include the fail-closed and staleness rules from ADR-0017.

Close the loop with user-engine

id: NK-WP-0045-T06
status: done
depends_on: [NK-WP-0045-T01, RPF-WP-0049-T04, USER-WP-0037-T02, RAPP-USER-ENGINE-WP-0003-T03]
priority: medium
state_hub_task_id: "eb71faf7-d6c7-5a3a-bdb6-17281cc5a01a"

Tell user-engine the read path is live so USER-WP-0037-T02 can derive AccountAuthority.root-grant from it, and record the evidence.

2026-10-03: live admitted reader and empty source accepted; controlled baseline initialization, fresh read and real post-initialization pod restart persistence verified. Reader LIST/sibling GET/exact-path write denied HTTP 403; wrong-audience JWT denied; no-grant mapping verified. Internal fixture service serialization uses the actual live source but does not claim external Hub-route acceptance. Consumer milestone depends on the completed producer admission/publication milestone RPF-WP-0049-T04; the broader T05 producer recovery gate remains separate. No actual root grant or ceremony is needed for this empty-source acceptance.

Acceptance Criteria

• The custody-record schema and validator exist and reject secret-bearing and projection-only inputs.
• A workload can read the root-grant fact from an owner-delivered surface.
• user-engine derives the root grant without inferring it from claims.

Initial implementation review, before founder approval — 2026-10-03

Local implementation is complete for the current draft. Workplan moved to blocked: T01/T04 require the founder's open decision; T05 needs the selected runtime owner; T06 needs user-engine integration. Task status wait expresses these blockers under the repository convention. No live source, custody entry, ADR acceptance or runtime delivery is claimed.

• Added read contract with three concrete surface options, a review recommendation, producer and consumer requirements, and owner-specific acceptance receipts. T04's choice remains human-owned. T05's delivery repo cannot be bound until that choice.
• Hardened T03 implementation: reject retroactive actions in revision transitions, invalid comparison documents and backwards update times; observations can check a previous document and fail closed on rollback, future timestamps and timezone-naive clocks. CLI diagnostics suppress raw validation errors and malformed input so rejected secrets cannot be echoed.
• Required external work: selected delivery owner creates its implementation workplan and supplies the T05 receipts; user-engine implements its adapter in USER-WP-0037-T02 and supplies T06 receipts. The contract is the handoff artifact; runtime work remains in owner repos. Handoffs sent via State Hub: railiance-platform bc0c620c-6520-4d42-b5d1-df082042ed03 (conditional delivery requirements) and user-engine d6efcf93-9f51-4763-b7d7-a2f43ea4fbf9 (adapter/acceptance requirements).
• Validation: make custody-record-test — 18 passed, including regression tests for the newly found transition, clock and diagnostic gaps. Full regression python3 -m pytest tests tools — 136 passed.
• Security knowledge: Emergent package 0.2.3, start and root, source status verified-files, orientation-only; digest 60f8811c6b94b30d357a0d9e5022f2a8ea52e69b47138d3a536755f3295310b5. Local source/test/contract work only; no control relaxation or live mutation.

Resume when decision cef97ccd-4ee7-40fe-859e-1df9c9360ecb is answered: reconcile any amendments, name the delivering repo/task on T05, verify its receipts, then obtain user-engine acceptance before closing T06 and the plan.

Founder approval and owner progress — 2026-10-03

Bernd explicitly accepted ADR-0017 and approved the proposed OpenBao delivery design. Scoped made decision c2cff929-91b9-4018-bfd6-fa04f7da8280; T01/T04 are done. ADR is accepted and the read contract names railiance-platform's KV v2 source platform/data/custody/net-kingdom/platform-root, record nk-custody:platform-root, read-only user-engine consumer and separate attended human custody writer. The bundled D10 stays open for separate MFA work.

Owner preparation progressed: railiance-platform RPF-WP-0049 has a CAS payload helper, exact-path policy drafts and five passing offline tests (source baseline 663135c, pushed and exact-commit primary sync applied). user-engine has prepared a transport-neutral observation adapter and seven fixture checks; full suite 284 tests passed with eight optional skips. Neither source packet is a live read path or real custody grant.

Plan stays blocked on T05 producer delivery (RPF-WP-0049-T05), then T06 consumer integration (USER-WP-0037-T02). Remaining concrete gates are actual runtime reader identity/auth route, reviewed executor and durable recovery/audit baseline, separate bounded live provisioning/custody bootstrap approval and real positive/negative acceptance receipts. Source choice/ADR acceptance are resolved and must not be requested again.

Knowledge reload: package 0.2.3 digest 60f8811c6b94b30d357a0d9e5022f2a8ea52e69b47138d3a536755f3295310b5; start/decisions cards withheld due to changed informed-decision source. Reviewed current informed-decision README and owner guidance directly. This approval is recorded from the human instruction, not inferred from situational knowledge.

Go-forward implementation — 2026-10-03

Bernd subsequently approved: “Good, i approve go forward please.” Continuing implementation and the bounded approved delivery design is authorized; do not request ADR, surface or generic go-forward approval again. Plan temporarily active while owner implementation progresses; T05 in progress. Missing facts and an attended OIDC/MFA handoff remain execution conditions, not a request to repeat the approval.

Delegated source ownership: railiance-platform producer/executor and admission; user-engine authenticated transport, durable baseline and runtime mapping; rapp-user-engine deployment packaging and dedicated projected JWT. Confirmed consumer owner declarations in rapp-user-engine/manifests/runtime.yaml name namespace/Deployment/ServiceAccount user-engine, automount disabled and an existing flex-auth-only projection. OpenBao requires its separate audience.

Custody evidence review: local bootstrap metadata records a temporary-single- king approval in May 2026 and a directory reference. The signed local escrow roster is planned, with planned identity references. Neither binds a current exact OIDC issuer/subject as a real root-grant ceremony record. Asked the founder for only the non-secret ceremony reference and exact issuer/subject; no grant will be inferred from directory/JWT projections or these historical records.

Source completion and operational handoff — 2026-10-03

Completed all presently implementable source work across three owner repos. Current state returns to blocked, with T05/T06 wait: attended OpenBao execution, image promotion and actual delivery/consumer acceptance remain. Design/go-forward approvals are resolved; do not ask them again. The attended session is required by the existing owner route and cannot be simulated by an agent process.

The founder answered the ceremony question: “i dont think there is one”. Prepared and validated the initial empty candidate with entries: [], grounded by non-secret disposition/evidence. It assigns no root custodian and introduces no synthetic identity. Publication must refuse any existing unexpected record/baseline rather than overwrite it. A later real grant needs a genuine ceremony and a strictly newer revision.

• NetKingdom: emitted expires_at from the record's actual cache bound; 18 focused tests pass. Canon pin db319335b27b61b855382ee5af5d690f06eeb010.
• railiance-platform: attended publisher/admission/recovery with crash-safe receipts, replay refusal and source pinning; 14 tests pass, implementation fa958cc, empty-publication handoff 35d326f, exact-commit primary sync applied.
• user-engine: bounded authenticated transport, pinned policy/schema package, atomic durable PostgreSQL baseline, receipt-bound initial bootstrap and AccountAuthority mapping; source 0d0751d. Final suite ran 296 tests with eight skips; layer and packaged-resource checks passed. Isolated PostgreSQL CAS/conflict/reconnect persistence verified. Image publication verified: sha256:030fe90232e20bb02b372e3d16b8ff659a5407d54f6405eb85754262b9ad7dc6; registry manifest and disposable container import/resource checks passed. Owner final sync f85c968. Actual promotion remains pending producer attendance.
• rapp-user-engine: separate projected openbao JWT and scoped egress, explicit immutable-image renderer and release/rollback packet; 7 packaging tests pass, 576f5e7, pushed/clean. Owner plan RAPP-USER-ENGINE-WP-0003.

Operator steps are concrete in railiance-platform/openbao/root-grant/README.md: attended read-role/CAS admission, then publication of the reviewed empty candidate, with independent retained state and fresh non-secret receipts. After delivery and image publication, follow rapp-user-engine/docs/root-custody-release.md to render, dry-run/diff/deploy and initialize the PostgreSQL baseline using the publisher canonical document digest. Retain authenticated no-grant/read-deny/outage and restart evidence; positive grant/revocation remains isolated synthetic evidence until a real ceremony introduces a grant.

Safe live preflight only: OpenBao initialized/unsealed; anonymous exact-path read denied 403, response body discarded. No live admission, publication, consumer rollout or actual grant occurred in this session.

Published-image release preflight is also complete: staged manifest rendered to /tmp/user-engine-custody-release.yaml (SHA256 5e21548fc2d23926d167f17795f098f8db5fffafe9bcd3bee43875f7bb51a50e, rapp-user-engine packet commit 13a9c0b, committed and synced), correct Ready node/headroom verified, eight-object server dry-run passed and expected Deployment/NetworkPolicy diff inspected with raw output suppressed. Existing live factor-recovery setting, mounts, volumes and egress semantics preserved in the final artifact. No apply. Actual runtime promotion still follows attended reader/source delivery and controlled baseline initialization. No further image publication or generic approval gate remains.

Attended producer execution verified — 2026-10-03

Founder reported successful execution. Fresh non-secret receipts independently read from /tmp/platform-root-admission-20261003T181954Z-333977.json and /tmp/platform-root-publish-20261003T181954Z-333977.json both contain ok: true. Admission verifies the exact user-engine reader role, namespace/ServiceAccount, audience openbao, required CAS and active audit. Publication verifies canonical revision 1, KV version 1 and digest 33a2ae086385028db1b654aa5646b7a98bcde1c5878c804e19315dadc3f87248. The durable publisher baseline matches that revision/version/digest. The record has no entries and grants no root authority. The older operator OIDC role JSON is configuration, not this execution evidence.

Plan resumed to active while owner agents reconcile producer receipts and independent recovery evidence, deploy the prepared runtime, initialize its durable baseline through the authenticated reader and exercise live acceptance. The attended-login intervention is resolved; do not request it again. Knowledge reloaded: Emergent 0.2.4, start/root verified-files, orientation-only, digest 025aab4f38246219c924bc94954e70ea0e6e7f72bcaf8d4344cd599602d345c3.

Live consumer delivery accepted — 2026-10-03

Runtime owner completed RAPP-USER-ENGINE-WP-0003 (synced HEAD f108c65); reviewed Deployment/NetworkPolicy applied, verified custody image running, Ready 1/1 and HTTP 200 health/readiness. USER-WP-0037-T02 accepted the delivered empty source, with fresh authenticated receipt-bound baseline initialization and actual pod restart persistence. Exact reader denied list/sibling/write, and wrong-audience login denied. Evidence is retained in the final consumer receipt. T06 is done; T05 remains in progress for independent recovery/provider/audit evidence. Isolated actual OpenBao Raft snapshot restore refused an older missing record and accepted the latest matching record; no production rollback occurred. Startup limitation: each newly created pod initially hit one PostgreSQL connection-refused exit, then recovered to stable Ready. Source owner records this separately; it is not concealed as a zero-restart acceptance.

Final recovery execution handoff — 2026-10-03

Live read/login audit correlation independently verified: matching request and response events for both exact consumer IDs, with no errors. Only the final 64 MiB of the 6.68 GB owner audit file was searched; raw records were captured and suppressed. Sanitized receipt retained in delivery evidence.

Producer prepared scripts/root-custody-finish-attended.sh: it checks the current live source against retained high-water state, uses the current governed Nextcloud Backup account/lane, enforces quota, encrypts baseline/history with age, creates one uniquely named object and verifies provider readback/decryption. It does not overwrite/delete backups or rotate credentials. Nineteen producer/ finish tests passed, including real age crypto with a disposable in-memory provider. It also checks whether the historical local backup-share URL inadvertently surfaced during inspection matches the current lane, using booleans only; a current match stops before upload for the owner incident flow. No raw credentials are retained in evidence.

T06 is complete, with user-engine synced d955cd7 and runtime owner f108c65. T05 and the workplan return to blocked solely on the prepared attended recovery execution and its owner receipt. The founder's own OIDC/MFA terminal is required by the owner execution contract; no approval decision is reopened.

Producer final owner sync: b8f8a7ada65f0a86b90a54812365757838102991, exact expected/derived commit applied on primary/railiance01, clean and ahead/behind 0. Non-authoritative recovery copy of the non-secret baseline/history was retained in owner source commit a252447058105eed0931d34f1a906f39ce7c2e5e and retrieved through a fresh remote clone with exact byte matching. That proves remote source retrieval, not a provider archive generation. The attended direct history backup roundtrip is the remaining evidence gate.

Attended finish attempt 20261003T185421Z-333977 failed before receipt creation; session was revoked. Audit verifies its custody and both backup bundle reads were successful; exact subsequent roundtrip failure remains unproven. Producer is repairing safe diagnostics and full-command test coverage before retry. T05 remains wait and the plan blocked; no provider success is claimed and no new credential admission or generic approval is inferred from this failure.

Producer repair 33ff822 now reserves a private fresh receipt before dependency imports, emits only fixed stage/error codes and safe HTTP/artifact metadata, and checks the existing independent escrow key for recovery. Thirty-two tests passed, including full command startup/success/failure under private attended HOME with real validator/age crypto and disposable backend/provider fixtures. Parent installed-wrapper smoke confirmed non-attended execution is refused with safe failure receipt. The same attended command is ready with a newly generated run ID; actual provider failure/success is not inferable until that receipt exists.

Second actual finish attempt 20261003T191229Z-333977 produced a safe failure receipt: current baseline and independent escrow checks pass; historical share differs from current lane; provider upload returned HTTP 401. Review identified a missing required public DAV X-Requested-With: XMLHttpRequest request header, whose omission Nextcloud documents as a cause of 401. Producer is fixing the client request without rotating credentials or expanding authority. T05 remains blocked pending authenticated upload/readback/decryption after that correction; the client defect alone does not establish an invalid provider credential.

Protocol repair 50da37c is implemented: exact public-DAV header added to custody upload and shared platform clients, real HTTP wire test verifies the emitted header and conditional-create request, failure receipt retains lane KV version. Forty-one relevant tests pass; no credentials/endpoints/policies or account fallback changed. Source-only refresh requirements for vendored backup workloads are tracked by the platform owner and are not represented as deployed. T05 awaits a fresh attended live finish receipt from the corrected source.

Header-corrected actual retry 20261003T192330Z-290055 still failed HTTP 401 at provider upload, lane KV version 3; current baseline and independent escrow match. Header correction did not prove the actual cause or resolve provider delivery. Owner is preparing bounded read-only provider share/endpoint inspection before any credential or transport repair. T05/plan remain blocked; unchanged repeated finish commands are not an actionable next step until diagnosis is available.

Producer diagnostic 4dd9646ec21b63a7743dae0ad3273da2f73adefe implements --inspect-share in the existing bounded wrapper. It reads owner-scoped OCS share bindings and compares current/documented public routes with depth-zero PROPFIND, emitting safe metadata/statuses. Full-main tests prevent uploads. Final review fee1d339f98d0fd7ec2336d946eea2340d557f8a preserves unknown password and expiry-clock information and skips redundant auth probes on clearly protected/expired shares; 25 finish tests pass, exact remote sync applied, clean. The next human execution is read-only inspection with a fresh receipt, not another unchanged backup attempt. Approval remains recorded.

The actual read-only inspection completed at 19:36 UTC; receipt is docs/evidence/2026-10-03-root-custody-share-inspection.json. The current KV3 token and expected labelled share were absent from the Backup owner's reviewed folder inventory. This does not establish global deletion. No provider mutations or backup roundtrip occurred; diagnostic ok: true is not recovery acceptance.

Railiance-platform is preparing a bounded attended repair: verify the replacement create-only share against the exact owner/folder, prove encrypted retained-history upload/download/decryption, then CAS only the upload token and URL at the expected lane version. Preserve the recovery key, other lane fields, existing backups and unknown shares, and return safe receipts for partial operations.

Activity-core owns the downstream delivery dependency: ExternalSecret refresh does not refresh environment values in running workers; Forgejo's backup client uses a frozen ConfigMap, and CNPG uses the projected platform checkout. Those consumers need reviewed refresh and loaded-client evidence after a repaired lane receipt. They do not substitute for NK's independent retained-history proof.

Prepared repair source: railiance-platform f1a780d, 33 finish tests passed (55 relevant producer/backup tests total). Includes actual HTTP wire contract, real crypto roundtrip, stale expected-version refusal before provider mutation, and safe partial-success receipts. Next attended execution uses --repair-share --expected-lane-version 3 --confirm-repair 'RESTORE Backup CREATE ONLY' with fresh receipt; actual success remains unproved until that receipt is verified. Downstream requirement is owned by ACTIVITY-WP-0042-T08 (020d19be-0576-5052-ad35-14b1d5a48fe1), waiting on repaired-lane proof then reviewed source/environment refresh. T07 supplies read-only stale-client evidence.

Completion — 2026-10-03 19:56 UTC

Actual founder-attended repair succeeded; verified receipt retained at docs/evidence/2026-10-03-root-custody-recovery-verified.json. Current source KV1/revision1 and canonical digest match the independent baseline. Encrypted retained history uploaded with HTTP201, downloaded with HTTP200 and decrypted using the independent escrow key, matching the retained history. This proof preceded the coordinates-only backup lane CAS from version3 to4; escrow and unrelated fields, unknown shares and old backups were preserved.

T05 is done and the plan is finished, six of six tasks complete. The empty record certifies no root custodian. This completion covers custody-record source, consumer, audit and recovery acceptance; it does not certify broader scheduled backup readiness. ACTIVITY-WP-0042-T08 retains the source/environment consumer refresh requirement (receipt explicitly says runtime consumers not refreshed). Historical credential ownership/revocation remains unverified in its existing platform incident; no historical credential was used by this recovery.