From de4c4f84f5043b97a205f1a72a26e77f8750d628 Mon Sep 17 00:00:00 2001 From: tegwick Date: Sat, 3 Oct 2026 19:01:13 +0200 Subject: [PATCH] Accept root grant ADR and approved OpenBao delivery design Assistant: codex Assistant-Model: gpt-6.1-sol Assistant-Session: 01a1029d-2c93-7500-a0e0-e3e089668b29 --- canon/schemas/custody-record_v0.1.schema.json | 2 +- ...oot-grant-custody-and-account-authority.md | 45 +++++++++++----- .../root-grant-read-contract_v0.1.md | 36 ++++++------- tools/custody-record/README.md | 4 +- .../NK-WP-0045-root-grant-custody-record.md | 51 +++++++++++++++---- 5 files changed, 93 insertions(+), 45 deletions(-) diff --git a/canon/schemas/custody-record_v0.1.schema.json b/canon/schemas/custody-record_v0.1.schema.json index 5467043..3a29ced 100644 --- a/canon/schemas/custody-record_v0.1.schema.json +++ b/canon/schemas/custody-record_v0.1.schema.json @@ -2,7 +2,7 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://policy.coulomb.social/schemas/custody-record/v0.1", "title": "NetKingdom platform-root custody record v0.1", - "description": "Machine-readable, non-secret form of the platform-root custody record (NK-ADR-0017, status proposed; NK-WP-0045-T02). The record is the single authority for the root grant. Entries are keyed by exact (issuer, subject), never by username. The root grant is relation platform-root-custodian in tenant:platform only; directory membership and IAM claims are projections and cannot ground an entry. Revocation and supersession are recorded custody actions that add a record revision; entries are never deleted. No secret material: token, key, share, recovery-code, password and reset-link fields are rejected everywhere.", + "description": "Machine-readable, non-secret form of the platform-root custody record (NK-ADR-0017, status accepted; NK-WP-0045-T02). The record is the single authority for the root grant. Entries are keyed by exact (issuer, subject), never by username. The root grant is relation platform-root-custodian in tenant:platform only; directory membership and IAM claims are projections and cannot ground an entry. Revocation and supersession are recorded custody actions that add a record revision; entries are never deleted. No secret material: token, key, share, recovery-code, password and reset-link fields are rejected everywhere.", "type": "object", "additionalProperties": false, "required": [ diff --git a/docs/adr/ADR-0017-root-grant-custody-and-account-authority.md b/docs/adr/ADR-0017-root-grant-custody-and-account-authority.md index 0d62e64..feaeb4a 100644 --- a/docs/adr/ADR-0017-root-grant-custody-and-account-authority.md +++ b/docs/adr/ADR-0017-root-grant-custody-and-account-authority.md @@ -2,19 +2,19 @@ id: NK-ADR-0017 type: architecture-decision-record title: "The Root Grant Is Derived From the Custody Record, Scoped to tenant:platform, and Observed as Non-Secret Evidence" -status: proposed +status: accepted owner: net-kingdom -revision: "1" -decided: "2026-09-29" -last_reviewed: "2026-09-29" +revision: "2" +decided: "2026-10-03" +last_reviewed: "2026-10-03" review_interval: 12m --- # ADR-0017 - Root-Grant Custody and Account Authority -**Status:** Proposed (drafted on the defaults agreed with the operator; accept after user-engine review) -**Date:** 2026-09-29 -**Deciders:** Bernd Worsch, Claude +**Status:** Accepted by Bernd Worsch on 2026-10-03; user-engine mapping confirmed. +**Date:** 2026-10-03 (drafted 2026-09-29) +**Decider:** Bernd Worsch ## Context @@ -78,14 +78,31 @@ contains tokens, keys, unseal shares, recovery codes, or reset links. - user-engine can represent `AccountAuthority.root-grant` deterministically from the custody record id and revision, and unblocks USER-WP-0037-T02. - The custody record needs a machine-readable, non-secret form that a workload - can read. Its shape and location are an open follow-up (below); until it - exists, user-engine returns "no root grant" rather than inferring one. + can read. Its schema and OpenBao delivery design are approved; until the owner + delivers the live read path, user-engine returns "no root grant" rather than inferring one. - The 15-minute bound and the projection-versus-record rule are decisions of this ADR and may be tightened at review. -## Open follow-ups +## Delivery design and approval receipt -- Define the machine-readable custody-record schema and read surface (owner: - net-kingdom; delivery of the read path may involve railiance-platform). -- Confirm with user-engine that the membership-envelope mapping above is - sufficient for `AccountAuthority`. +Bernd explicitly approved: “Accept ADR-0017 and approve the proposed OpenBao +delivery design.” Scoped State Hub decision: `c2cff929-91b9-4018-bfd6-fa04f7da8280`. +The separate MFA journey in bundled D10 remains pending. + +- Delivery owner: railiance-platform, RPF-WP-0049. +- OpenBao KV v2 mount `platform`; API path + `/v1/platform/data/custody/net-kingdom/platform-root`. +- Record `nk-custody:platform-root`, owner `net-kingdom-custody`; + complete document at response `data.data.document`. KV metadata version is + concurrency state, distinct from custody revision. +- user-engine is the authenticated exact-path read-only consumer. Custody + writes use a separate attended human lane. The actual workload identity and + writer binding must be established through their owner routing procedures. +- [Read contract](../contracts/root-grant-read-contract_v0.1.md) and + `canon/schemas/custody-record_v0.1.schema.json` define the document and checks. + user-engine confirmed the membership-envelope mapping (message `60acf176`). + +Design approval does not establish live admission or a real custody entry. +Remaining delivery work: real reader identity, reviewed attended executor, +recovery/audit configuration, bounded live provisioning approval and genuine +ceremony provenance, followed by producer and consumer acceptance receipts. diff --git a/docs/contracts/root-grant-read-contract_v0.1.md b/docs/contracts/root-grant-read-contract_v0.1.md index 069af9a..7e441e5 100644 --- a/docs/contracts/root-grant-read-contract_v0.1.md +++ b/docs/contracts/root-grant-read-contract_v0.1.md @@ -1,31 +1,33 @@ # Root-grant read contract v0.1 -Owner: net-kingdom. Status: proposed implementation contract, 2026-10-03. -Tracks NK-WP-0045 and proposed [ADR-0017](../adr/ADR-0017-root-grant-custody-and-account-authority.md). +Owner: net-kingdom. Status: approved delivery design, 2026-10-03. +Tracks NK-WP-0045 and accepted [ADR-0017](../adr/ADR-0017-root-grant-custody-and-account-authority.md). Schema: [custody-record v0.1](../../canon/schemas/custody-record_v0.1.schema.json). Reference implementation and fixtures: [validator](../../tools/custody-record/README.md). -This contract prepares delivery; it does not accept the ADR, choose a live -endpoint, assign a custodian, or establish a real root grant. Fixtures are +The founder accepted ADR-0017 and selected the OpenBao design below. Delivery +and identity admission are pending; design acceptance does not assign a +custodian or establish a real root grant. Fixtures are synthetic and must never seed the authoritative record. ## Read-surface decision (T04) -The founder's open decision `cef97ccd-4ee7-40fe-859e-1df9c9360ecb` -must accept/amend ADR-0017 and select one delivery surface and accountable repo. -user-engine has already confirmed the exact subject and envelope mapping -(message `60acf176`, recorded in USER-WP-0037-T02). +The founder explicitly accepted ADR-0017 and approved the proposed OpenBao +design. Scoped receipt: `c2cff929-91b9-4018-bfd6-fa04f7da8280`. +T01/T04 are done; bundled D10 `cef97ccd-4ee7-40fe-859e-1df9c9360ecb` +stays open for its separate MFA journey. -| Option | Delivering repo | Requirements and tradeoff | -| --- | --- | --- | -| OpenBao-held non-secret document | railiance-platform | Governed exact-path workload read, separate custody write lane, atomic revision updates; uses existing custody infrastructure but needs consumer identity admission. Recommended for review, subject to owner confirmation. | -| Private platform service | Named platform runtime owner | Authenticated bounded read, atomic document, custody write/audit lane, availability and recovery; adds a runtime to operate. NetKingdom supplies canon, not a new runtime by default. | -| Repository artifact delivered to workloads | Named artifact/distribution owner | Authenticated provenance, atomic publication, revision rollback protection and a refresh route for sensitive writes; an indefinitely cached checkout is insufficient. | +Selected delivery owner: **railiance-platform**, RPF-WP-0049. OpenBao KV v2 +mount `platform`, API path `/v1/platform/data/custody/net-kingdom/platform-root`, +record ID `nk-custody:platform-root`, owner `net-kingdom-custody`. The complete +schema document is at response `data.data.document`; KV metadata version is +transport concurrency state, not the custody revision. -Decision receipt must name the surface, delivering repo, trusted record ID, -consumer identity mechanism, writer/custody approval lane and bootstrap -provenance. No endpoint, OpenBao path or access grant is invented here. If the -ADR changes, schema, validator and this contract must be reconciled before use. +user-engine reads through an authenticated exact-path read-only identity; +separate attended human custody writes publish whole-document CAS updates. +The actual user-engine runtime identity/auth binding, writer custody binding, +bootstrap provenance and live acceptance are still owner delivery requirements. +The producer packet is `railiance-platform/openbao/root-grant/README.md`. ## Producer requirements (T05) diff --git a/tools/custody-record/README.md b/tools/custody-record/README.md index 0d557d0..716c787 100644 --- a/tools/custody-record/README.md +++ b/tools/custody-record/README.md @@ -2,7 +2,7 @@ Validates the non-secret platform-root custody record defined by `canon/schemas/custody-record_v0.1.schema.json` (NK-ADR-0017, status -proposed; NK-WP-0045-T02/T03). Offline and read-only. +accepted; NK-WP-0045-T02/T03). Offline and read-only. ```bash uv run tools/custody-record/validate.py tools/custody-record/fixtures/valid/*.json @@ -27,7 +27,7 @@ be logged against untrusted inputs. Runtime owners must also authenticate the source, bind the expected record ID, retain the revision baseline, and re-read for sensitive writes. See the -[proposed read contract](../../docs/contracts/root-grant-read-contract_v0.1.md) +[approved read contract](../../docs/contracts/root-grant-read-contract_v0.1.md) for delivery requirements and cross-repo acceptance receipts. Fixtures: `valid/` covers grant, revocation and supersession; `invalid/` diff --git a/workplans/NK-WP-0045-root-grant-custody-record.md b/workplans/NK-WP-0045-root-grant-custody-record.md index 8d48d18..77811ac 100644 --- a/workplans/NK-WP-0045-root-grant-custody-record.md +++ b/workplans/NK-WP-0045-root-grant-custody-record.md @@ -24,10 +24,9 @@ not change custody itself, and no secret material enters the record. ```task id: NK-WP-0045-T01 -status: wait -needs_human: true -decision_id: cef97ccd-4ee7-40fe-859e-1df9c9360ecb -blocking_reason: "Bernd accepts or amends NK-ADR-0017 (proposed) after user-engine confirms the AccountAuthority mapping." +status: done +needs_human: false +decision_id: c2cff929-91b9-4018-bfd6-fa04f7da8280 priority: high state_hub_task_id: "25489680-c611-59f9-a0c4-291c4e2a7356" ``` @@ -98,11 +97,10 @@ Tests `tools/custody-record/tests/test_custody_record.py` (13 passed; ```task id: NK-WP-0045-T04 -status: wait +status: done depends_on: [NK-WP-0045-T02] -needs_human: true -decision_id: cef97ccd-4ee7-40fe-859e-1df9c9360ecb -blocking_reason: "Needs a decision on where a workload reads the record (OpenBao-held, platform service, or repository artifact) and which owner delivers it." +needs_human: false +decision_id: c2cff929-91b9-4018-bfd6-fa04f7da8280 priority: high state_hub_task_id: "472e191f-8b7a-5d0e-84ef-2717f92bc83c" ``` @@ -117,9 +115,10 @@ answer fixes T05. ```task id: NK-WP-0045-T05 status: wait -depends_on: [NK-WP-0045-T04] -wait_kind: both -blocking_reason: "Open decision cef97ccd must name the read surface and delivering repo; that owner must supply authenticated atomic publication, custody provenance and delivery receipts under docs/contracts/root-grant-read-contract_v0.1.md." +depends_on: [NK-WP-0045-T04, RPF-WP-0049-T05] +wait_kind: dependency +blocked_on: message-from:railiance-platform +blocking_reason: "Approved OpenBao design; RPF-WP-0049-T05 must provide the real authenticated read path, custody provenance and producer receipts. Reader identity, executor/recovery and separate live provisioning approval remain pending." priority: medium state_hub_task_id: "628e8a3b-17a4-5f97-a484-c564a87d650d" ``` @@ -186,3 +185,33 @@ ADR acceptance or runtime delivery is claimed. 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.