ops-mason/workplans/MASON-WP-0010-security-case-materialization.md

id	type	title	domain	repo	status	flavor	owner	topic_slug	created	updated	depends_on	related_repos	state_hub_workstream_id
MASON-WP-0010	workplan	Materialize SecurityCases from their type, with acceptance as the only gate	infotech	ops-mason	blocked	implementation	claude-code	netkingdom	2026-10-08	2026-10-31		net-kingdom ops-warden railiance-platform	eabf2c39-94bd-5a11-8f2e-76d7a95d1583

MASON-WP-0010 — Materialize SecurityCases from their type, with acceptance as the only gate

Why

NetKingdom is introducing SecurityCaseTypes (net-kingdom NK-WP-0048, canon security-case-types_v0.1, proposed). A type is designed once, with documentation, tests and an informed-decision. Each case of an implemented type is then light: it is accepted, ops-mason arranges it, and ops-warden follows through.

ops-mason's four phases (construction plan, review, executive summary, build) stay exactly as they are for new types and for structure that no type covers. For a KnownSecurityCase, the construction plan is rendered from the type's materialization templates, and the executive-summary gate collapses to the case acceptance, because the shape was decided when the type was acknowledged.

MASON-WP-0009 (a hand-built placement of a key-cape client secret) is the kind of work this replaces. It becomes a reference instance for the first type.

Tasks

id: MASON-WP-0010-T01
status: done
depends_on: [NK-WP-0048-T03]
priority: high
state_hub_task_id: "3382ea7b-65ca-59a9-97ae-273455af44c2"

T01 — Define the type's materialization section

Propose the materialization part of the SecurityCaseType schema together with net-kingdom: policy, role, KV path structure and catalog-entry templates over case parameters, with naming rules. These must respect ops-mason's existing "respect, extend or compact before adding" review, so that a type cannot template sprawl. Write it for the first type, oidc-browser-relying-party, from MASON-WP-0009 and the existing key-cape client custody paths.

Review (2026-10-08) of net-kingdom security-case-types/oidc-browser-relying-party/type.yaml 1.0. The structure (four items, all but the catalog entry conditional on confidential) is right. The names add three new families where existing ones cover the need, so they fail "respect, extend or compact before adding". Requested refinements, each from the live CCR-2026-0033 placement (plans/keycape-secrets-engine-openbao-client-custody.md):

1. Fix the path in the type. secret_ref should not be case-settable; a free pattern under platform/workloads/ lets every case pick its own layout. Derive it: platform/workloads/keycape/{client_id} (field CLIENT_SECRET), as for secrets-engine-openbao.
2. Reuse the policy family. Existing readers are workload-kv-read-keycape-<client>-<reader>. Rename keycape-client-{client_id}-read to workload-kv-read-keycape-{client_id}-eso (KeyCape reads its client secret only through ESO), and {consuming_service}-oidc-client-{client_id}-read to workload-kv-read-keycape-{client_id}-{consuming_service}. Update verification custody-allowed-to-consumer and rollback to match.
3. Template the policy body, not just its name. An openbao_policy item needs its rules (read on platform/data/workloads/keycape/{client_id}, nothing else: no metadata, list, parent or sibling), or the review cannot check invariant (ii) and a rendered plan is not buildable.
4. Add the missing ESO role. deliver-secret needs a Kubernetes-auth role external-secrets-keycape-{client_id} (kind openbao_role, bound to the ESO service account, policy from item 2, 15m TTL, no default policy), as the reference placement has.
5. Catalog naming. The one existing entry is rapp-qonto-keycape-client; prefer {consuming_service}-keycape-client over oidc-client-{client_id}.
6. Rollback order. mint-secret "destroy" and client-secret-path "remove" act on the same KV path; collapse to one step (metadata delete after the ExternalSecret is gone) so rollback cannot fail on a missing path.

With 1-4 applied, the section is acceptable to ops-mason for NK-WP-0048-T05.

2026-10-08: net-kingdom folded in all six (net-kingdom 074b3a0, message 508e2a12); its schema/validator now require a body on policy and role items. NK-WP-0048-T05 still waits on WARDEN-WP-0044-T01 and a founder answer.

2026-10-09: the founder accepted memo r4; hub decision e418263e resolved and the type is acknowledged (net-kingdom 0e86f95). T02 is unblocked.

Review (2026-10-31) of net-kingdom security-case-types/oidc-service-client/type.yaml 0.1 (proposed, net-kingdom 5d5f15d, memo nk-wp-0056-t14-oidc-service-client-r1, hub decision f8044f81, request message f61cc81e). Checked against the browser type 1.1, the live CCR-2026-0041/0042 placement and the bounded executor's native lanes CCR-2026-0058/0059, and by a trial render of examples/nk-bind-executor-approval.yaml through case_plan.render and case_build on a scratch copy marked acknowledged (no live survey, no OpenBao). All six items render; names come out as workload-kv-read-keycape-nk-bind-executor-approval-{eso,bounded-executor}, external-secrets-keycape-nk-bind-executor-approval and catalog entry bounded-executor-keycape-nk-bind-executor-approval.

Verdict: acceptable with changes. The structure is right and reuses the browser type's custody, ESO and policy families. R3, R4, R6, R7 and R8 change the type (so memo r2 replaces r1); R10 is ops-mason's own builder work and does not block acknowledgment, but must land before the first case is built.

• R1 — client-secret-path: ok. Derived, not case-settable, same platform/workloads/keycape/{client_id} / CLIENT_SECRET as the browser type and CCR-2026-0033. Unconditional (the type is always confidential), so no when. client_id is unique in KeyCape, so browser and service clients cannot collide in the one keycape/ subtree.
• R2 — keycape-reader-policy and naming family: ok. Unchanged from the browser type; workload-kv-read-keycape-<client>-<reader> is respected for both readers. Longest rendered name is 68 characters, within OpenBao limits.
• R3 — eso-role: change needed (small). Bound to external-secrets/external-secrets, one policy, 15m, no default policy: right. But the body omits audience: openbao and token_explicit_max_ttl: 15m, which the consumer role states and the live external-secrets-keycape-forgejo role has; ops-mason's builder fills them in silently today. Add both so the template is what gets built, and the two roles read the same.
• R4 — consumer-reader-policy self-lifecycle stanzas: change needed. The auth/token/lookup-self (read) and auth/token/revoke-self (update) stanzas are correct and needed (a native per-call reader should revoke its token after the read, and the platform applier refuses a token_self_lifecycle: true policy without them, see T04 2026-10-10). But only the consumer policy declares them, while the ESO policy needs them equally. Declare them in both policy bodies, so each body is the complete policy the review checks (item 3 of the 1.0 review). ops-mason then stops appending them (R10).
• R5 — consumer-reader-role (native Kubernetes auth): ok. One ServiceAccount, one namespace, audience openbao, 15m ttl/max/explicit max, one policy, no default policy: this is exactly the CCR-2026-0058/0059 shape that is live and verified for sso/nk-bind-executor, and "policies are never combined in one role" holds (the executor gets a third separate role). Role name equal to the policy name matches the native-lane convention. Dropping ESO delivery to the consumer removes a Secret copy and a SecretStore per case; ops-mason prefers it.
• R6 — consumer binding parameters: change needed. The patterns admit consumer_service_account: default and namespaces such as external-secrets, openbao or kube-system. Refuse default (any pod in the namespace would read the client secret; CCR-2026-0059 verifies the default SA is denied), and refuse the external-secrets and openbao namespaces, in the type's constraints or the validator.
• R7 — shared namespace with KeyCape's copy: change needed. The first case binds sso/nk-bind-executor, and sso is where deliver-secret writes keycape-{client_id}-client. So "no Secret copy in the consumer's namespace" (README, purpose) is false for this case; isolation rests on the consumer SA having no Secret read in its namespace (true today: rapp-bounded-executor manifests/rbac.yaml grants no Secret access). Add a verification: {consumer_namespace}/{consumer_service_account} cannot get Secrets in its namespace (in particular sso/keycape-{client_id}-client), can-i denial as proof; and reword the README claim to "the type creates no Secret copy for the consumer".
• R8 — verification wording: change needed (small). custody-allowed-to-consumer says the policy grants read on the path "and nothing else"; with R4 it also grants token self-lookup/revoke. Say "and no other path under platform/, apart from token self-lifecycle". Optionally add the same allow check for the ESO policy.
• R9 — catalog-entry: ok, one question. {consuming_service}-keycape-{client_id} instead of the browser type's {consuming_service}-keycape-client is right: a service holds one client per audience, so the browser form would collide. Question: consuming_service: bounded-executor differs from the workload name the platform already uses for this executor (net-kingdom-bind-executor in CCR-2026-0058/0059 and their catalog ids). The case should use the established name, or the type README should say which one workload_ref carries.
• R10 — ops-mason builder (ours, not a type change). The trial build shows four defects to fix before the first service-client case is built: (a) _policy_hcl always appends the self-lifecycle stanzas, so the consumer policy gets them twice; append only when absent. (b) A policy with a role is treated as ESO: the consumer CCR gets access_frontdoor.type: external-secrets; for a native role it must be platform-owner (as CCR-2026-0059) with a delivery: {surface: native-workload-login, namespace, service_account} block. (c) catalog_id is hard-coded to {consuming_service}-keycape-client; take it from the catalog item. (d) audience and token_explicit_max_ttl are hard-coded / copied from token_max_ttl; take them from the role body (with R3). The consumer CCR is no longer in_flight: with the role in the type it is complete proposed, bound_claims_confirmed: false until the platform owner confirms the SA.
• R11 — rollback order: ok, with one addition. Consumer configuration, registration, env binding, delivery, then custody (one metadata delete, after the ExternalSecret is gone, per item 6 of the 1.0 review), roles before their policies, catalog last: consistent with the browser type. Addition: deleting the consumer role does not revoke issued tokens; state that rollback is complete only after the consumer's last token has expired (at most 15m after the role is deleted) or was revoked, as the T03 deactivate note does. Suggested, not required: remove consumer-reader-role directly after hand-over is reversed, so consumer access ends first. (ops-mason's own rollback.yaml lists removes_exactly in plain reverse order, which differs from the type's steps; fixed with R10.)

T04 is unchanged by this type: secrets-engine-openbao's second reader is an attended OIDC operator, not a ServiceAccount, so it fits neither type.

id: MASON-WP-0010-T02
status: done
depends_on: [MASON-WP-0010-T01, NK-WP-0048-T05]
priority: high
state_hub_task_id: "fd385537-7378-5539-8a6e-f45851296f42"

T02 — Render a construction plan from a case

mason plan --case <case.yaml> validates the case against its implemented type, renders the construction plan from the type's templates, and runs the existing consistency review against current OpenBao structure (read-only, no values). The output is the usual plan, marked derived-from-type, plus the case-acceptance reference in place of a fresh executive summary.

Tests: render the reference case; refuse a case whose type is not implemented; refuse parameter values outside the type's validation; flag a collision with existing structure.

2026-10-09 done: ops-mason plan --case <case.yaml> [--out F] [--no-live] (src/ops_mason/case_plan.py). Validation and rendering are net-kingdom's own security_case_validator.py (imported, not copied), with provider declarations loaded through its composer. ops-mason adds the review against existing structure: a read-only live survey (policy list, role lists, KV metadata, ops-warden catalog ids) that fails loudly instead of returning an empty structure, and flags each collision as a finding. Output is a construction plan with derived_from_type and render_digest, and section 5 is the case acceptance; status reviewed only when accepted and collision-free. Exit 0 clean, 1 collisions, 2 refused. tests/test_case_plan.py (8, on a copy of the type marked implemented); suite 167 passed. The live Forgejo case is refused today, correctly: the type is acknowledged, not yet implemented.

2026-10-09: net-kingdom accepted the Forgejo case (net-kingdom/security-cases/forgejo-netkingdom-oidc.yaml, message d1bbcb44). As the reference case it renders with --allow-unimplemented, mirroring the validator's flag: allowed only for an acknowledged type, marked reference_case: true; and reviewed now requires a live survey. Rendered live into plans/case-forgejo-netkingdom-oidc.md: status reviewed, no collision, digest sha256:fb8b114d….

id: MASON-WP-0010-T03
status: progress
depends_on: [MASON-WP-0010-T02]
blocked_on: message-from:railiance-platform
blocking_reason: "Typed exact structural evidence request is prepared. Native materialization waits on independently authenticated policy/role/layout/catalog observations and CCR42 consumer binding/application. Mint, delivery and first live verification are follow-through, not structural prerequisites."
priority: high
state_hub_task_id: "56cea6be-c613-586c-80cd-125340b374da"

T03 — Build from an accepted case

mason build --case <case.yaml> builds a rendered plan when the case's acceptance record is present, with no separate executive-summary approval. Its audit trail names the case, the type version and the acceptance. It proposes the pointer-only ops-warden catalog entries the type defines, as today. Rollback removes exactly what this case created.

Acceptance: the Forgejo reference case (NK-WP-0048-T06) materializes through this path.

2026-10-09: implemented. ops-mason build --case <case> --plan <plan> [--out] [--allow-unimplemented] (src/ops_mason/case_build.py) refuses unless the case is accepted, the plan is reviewed and its render digest equals a fresh render. It writes a bundle and never touches OpenBao: one workload-kv-read CCR draft per policy (ESO policy + Kubernetes role, mirroring CCR-2026-0033; the consumer policy in_flight with openbao.auth missing until the consumer owner binds it), the policy HCL, an ops-warden catalog proposal, rollback.yaml (exactly what the case creates, reverse order) and a manifest with file hashes. Every file names the case, type version, render digest and acceptance record; the audit log gets a case-build-prepared record with the case acceptance as approver. The drafts are checked with railiance-platform's own credential-change.py validate. tests/test_case_build.py (6); suite 175 passed. Forgejo bundle built into builds/case-forgejo-netkingdom-oidc/, platform validation pass; handed to railiance-platform (message 2c409503).

id: MASON-WP-0010-T04
status: wait
depends_on: [MASON-WP-0010-T03]
blocking_reason: "After T03, and only once a type fits: secrets-engine-openbao is a service (JWT) client, which oidc-browser-relying-party does not cover."
priority: medium
state_hub_task_id: "f6ad0d3c-8f47-5fdf-8115-6ca9d8a1fead"

T04 — Adopt MASON-WP-0009 as a case

Once oidc-browser-relying-party (or the confidential service client type) is implemented, express MASON-WP-0009's placement as a case of that type without changing the live structure, and close the hand-built path.

2026-10-10 (T03): railiance-platform filed the drafts as CCR-2026-0041 (ESO reader) and CCR-2026-0042 (consumer reader, in_flight until railiance-apps binds it), messages 83465dcd/be3a762d; the founder applied CCR-2026-0041 at 2026-10-09T18:09Z. Its review found a render defect: the CCRs declare token_self_lifecycle: true but the policies lacked the lookup-self/revoke-self stanzas, so the applier refused them. Fixed in case_build.py (test asserts the three stanzas; output now equals the platform-generated policy apart from comments) and in the committed bundle. Two follow-ups for the next render: net-kingdom changed the type to KEYCAPE_{client_id:env}_CLIENT_SECRET (ops-warden 23ba584), so the render digest will change; and a live re-render of a partly applied case will report its own objects as collisions. The KV value waits on mint-secret (RPF-WP-0054).

2026-10-10 (T03 follow-up): plan --case now recognises objects listed in the case's own committed bundle (builds/case-<id>/rollback.yaml, same case id) as "already present from this case's own build", not collisions; anything else existing still collides (2 tests, suite 177 passed). The committed Forgejo plan is stale: net-kingdom's {client_id:env} change moves the render digest from fb8b114d… to 5e97931e…. Re-render it live under the next survey grant.

2026-10-10: Forgejo plan re-rendered live: reviewed, no collision, digest af1f4f81…; policy workload-kv-read-keycape-forgejo-eso shown as already present from this case's own bundle. The ESO role did not appear as present; check on the next grant.

2026-10-10: checked. auth/kubernetes/role/external-secrets-keycape-forgejo exists as applied (external-secrets/external-secrets, audience openbao, 15m, policy workload-kv-read-keycape-forgejo-eso, no default policy). Why the plan's "already present" list omitted it is not yet confirmed (the survey should list auth/kubernetes/role); reproduce under the next grant. The collision review is unaffected: it never flagged the role.

2026-10-10: type 1.1 (net-kingdom e2174ce, message af66538c) adds the consumer-enforces-groups verification and tightens redirect URIs; the case is re-pinned to @1.1. The live re-render above was already 1.1. Bundle rebuilt from it (builds/case-forgejo-netkingdom-oidc/, platform validation pass); the ESO policy is unchanged against the applied CCR-2026-0041, so 1.1 changes no OpenBao object.

2026-10-11 accepted-architecture source implementation: materialization is structure only under the already accepted canon; the stale mint-before- materialization blocker is removed, not replaced by a fake status label. src/ops_mason/case_structure.py and read-only ops-mason structure-request validate a separate current structural projection against the hashed bundle and prepare typed per-owner observations. Full execution drift remains visible: 35880bb adds --check-config to register-client, changing full render af1f4f81 → e64b56e4 while materialization/composition/verification/rollback remain equal. No prior execution approval is carried forward. Candidate receipt verification requires independent owner/manual provenance and derives undo only from verified creation receipts; planned rollback identities are not ownership. Thirty-three relevant tests and ruff pass. Status-only raw-hash binding previews accepted→materialized only after independent observations, preserving every parameter/acceptance field; it writes and signs nothing. Details and exact native owner seams: docs/forgejo-structural-materialization-source-v1.md. T03 remains progress; case remains accepted@1.1, not materialized/live. CCR42 consumer auth remains in_flight, and native owner evidence is not manufactured by source preparation.

2026-10-16 (T03 source compatibility): plan, build and structure-request now expose explicit --types-root, passing it to the existing exact-version NetKingdom API. Actual acknowledged 1.2 source renders the proposed Forgejo case into a six-object draft, preserving its absent acceptance. Six actual-source integration checks prove the root selection, dedicated consumer namespace/SA, ordinary unimplemented refusal, proposed build refusal, historical 1.1 bundle refusal and malformed namespace refusal. Existing 44 plan/build/ structure tests pass. No live survey, execution, case/type status, acceptance, native owner evidence or CCR was changed. T03 remains progress; actual accepted 1.2 case/reviewed source and authenticated native owner evidence remain required.

2026-10-17 (T03 source review): ops-mason source is complete for T03. structure-request prepares the typed request; case_structure.verify and bind_status_transition take an owner-supplied authenticating verifier by design, so no CLI that trusts observation JSON is added. Every remaining step is an owner observation or an attended native run.

Attended checklist (in order; none may be simulated):

1. net-kingdom: accept the Forgejo case at type 1.2 (acceptance record in the case); ops-mason then re-renders plan --case ... --types-root <1.2> to reviewed and rebuilds the bundle (source-only, worker may run).
2. railiance-platform: supply independently authenticated metadata-only observations for ESO policy, external-secrets-keycape-forgejo role and KV layout, each marked created (with change receipt) or preexisting-matched, against the structure-request digest. No values.
3. railiance-apps + railiance-platform: bind CCR-2026-0042 consumer openbao.auth (namespace/SA), reconcile it from @1.0 to the current type, review and apply; supply its receipt.
4. ops-warden: authenticate the pointer-only catalog entry observation.
5. Owner (railiance-platform) supplies the authenticating verifier seam and, with founder go, runs bind_status_transition to preview accepted -> materialized; Warden accepts the new raw case digest.
6. Follow-through after materialization, not prerequisites: mint in custody, ESO delivery, first live verification (NK-WP-0048-T06).