ops-warden/docs/security-case-execution-proposal.md

SecurityCase execution contract proposal — 2026-10-10

Status: proposed owner review; not an accepted runtime protocol or authority. Owner: ops-warden. Related: WARDEN-WP-0044-T03, NK-WP-0048, MASON-WP-0010.

warden case plan now gives a valid descriptive run, but the type's entry_point, auth, verification check and rollback action fields are prose. No warden case run or rollback implementation exists. A case becoming materialized cannot turn those descriptions into executable commands.

The proposal preserves caller authority and routes by owner. It introduces no new credential, policy grant, shell command inferred from prose, or authority for Warden to configure a consumer. Architectural contract acceptance belongs to net-kingdom and adapter interfaces to their owners. Founder review is needed only if the acknowledged type's authorization/session boundary changes; the current absence of a machine contract is not an excuse to fabricate one.

Proposed machine seam

Keep human descriptions. Add a separately validated execution reference to steps and checks, resolving to owner-provided closed adapters. An adapter has:

• immutable reference (owner repo, interface id, version, source digest);
• closed parameter schema (no secret-sensitivity fields; no free shell text);
• declared actor mode and catalog lane, which must agree with the case plan;
• explicit side-effect class and target identifier deriving from case parameters;
• idempotency/reconciliation contract and metadata-only receipt schema;
• supported rollback reference or explicit owner-only undo.

Warden does not invent an argv contract for ExternalSecrets, group membership, KeyCape registration or Forgejo configuration. Owner adapters may internally call their reviewed tools. Warden invokes only the fixed entry point provided by that adapter, with validated separate argv fields, and refuses unknown adapters or templates. entry_point prose never goes to shell=True or sh -c.

An owner may initially supply a receipt-only adapter: the run sheet records that step as pending until the owner performs it and provides independent evidence. This gives useful resumable orchestration before every live adapter exists, without implying native completion or transferring ownership.

Run sheet and receipts

The run sheet pins exact case bytes (case-ref), accepted type bytes/version, owner adapter digests, catalog revision, acceptance reference and ordered step identities. Changed pins require a newly reviewed sheet; never inherit previous success into a different exact revision without explicit reconciliation.

Each attempt yields an immutable metadata receipt containing these pins, step id, owner, target, attempt id, result enum and evidence-reference fingerprints. Allowed results: pending-owner, not-started, running, verified-success, verified-no-change, failed-before-change, failed-after-change, uncertain. Neither subprocess output nor arbitrary owner payload is copied into receipts. Adapter error strings are not evidence and must not be logged verbatim.

Stop on failure or uncertainty. A thrown exception or lost process receipt is uncertain, not failed-before-change. Uncertain/failed-after-change blocks retry until the owner reconciles target state. verified-success and verified-no-change are not repeated. Retry after failed-before-change requires the same pins and adapter's explicit retry-safe classification; a replay-safe CAS0 receipt is reconciled, not retried into secret generation. State persistence must write running before dispatch and result afterwards; interruption between those writes leaves uncertain on resume. Outbox failures remain visible and do not get rewritten as verified audit delivery.

Owner receipt ingestion must authenticate provenance or be explicitly manual attended evidence, never a bare trusted JSON argument. Source/local receipts are attributive preparation until their owner contract defines independent native verification. Overall native completion requires every applicable step and verification plus confirmed session revocation; pending-owner is never success.

Sessions, values and rollback

Reuse proxy_attended_login_exec containment/output suppression/revocation rather than add a second login helper. A key-cape login lane and the OpenBao broker issuer role are distinct grants; the executor must represent both and never silently share/inherit a token. Grouping is permitted only within the same declared identity/lane and preserves follow-through order. An agent principal cannot dispatch generated-in-custody mint-secret. The broker continues to rederive the exact case-ref independently.

Rollback traverses successful step receipts in reverse order and only invokes an owner's reviewed undo for target changes that receipt proves were created by this case. Existing shared groups, membership and policies cannot be deleted by interpreting a type rollback sentence literally. 'No change' yields no undo; failed/uncertain states require reconciliation first. Do not restore a prior secret value by extracting it into Warden; custody rollback is owner-native.

Owner acceptance requests to prepare

1. net-kingdom: accept the closed machine seam separately from descriptive type fields, document materialized = structural acceptance, and avoid gating that state on mint-secret which is itself a follow-through step. Pin the revised schema/type and keep type acceptance provenance explicit.
2. railiance-platform: provide a generate adapter over existing credential.py exact --grant, --client-id, --case-file, --case-ref and receipt result codes; clarify reconcile semantics for already-present CAS0 and grant/session revocation evidence. No new credential is required by this proposal.
3. key-cape/net-kingdom: provide registration/group/env adapters and verify/undo contracts in the existing attended boundary; do not hand Warden a user-engine runtime token or a new broad Kubernetes credential.
4. railiance-apps/Forgejo: provide consumer OIDC + groups enforcement adapter or receipt-only step, exact auth binding for CCR-2026-0042, and source/native group-denial verification. This stays consumer ownership.
5. ops-mason: give a hash-pinned materialization receipt and list of objects created vs pre-existing, sufficient for collision checks and scoped rollback.

No coordination messages have been sent by preparation of this proposal.

Implementation and verification after owner seam acceptance

Implement case_run.py with injected typed adapters and receipt storage, then CLI run-sheet/receipt import/resume/rollback commands. Keep case_plan read-only. Add type machine-seam validation without turning valid descriptive planning into an unreviewed source-breaking schema migration.

Required tests: rejected changed pins; unaccepted/unmaterialized cases; unsupported adapter/argv refusal; agent mint refusal; pending owner keeps native gate open; verified success never replayed; lost receipt resumes as uncertain; crash after running persistence prevents duplicate side effect; failed-before-change retries only with declared retry-safe adapter; failed-after-change needs owner reconcile; malicious/secret output excluded; inability to revoke remains unverified; rollback visits created successful objects only, preserves shared memberships, and stops on uncertain undo. Inject runners; no live login or target required.

WARDEN-WP-0044-T03 remains open. This packet resolves the precise source contract deficit; it is not case materialization, a native run, or a type decision.

Local reducer prototype

src/warden/case_receipt_state.py is proposed local source preparation, not an accepted wire format. Its pure immutable transitions can be tested without any owner adapter or shell dispatch. Persist the returned running intent before an external side effect; on a lost result, recover marks uncertainty and blocks replay. No receipt provenance, durable storage, CLI dispatch or live action is implemented. tests/test_case_receipt_state.py covers the failure boundaries.