secrets-engine/docs/task-scoped-openbao-execution-contract.md

# Task-scoped protected OpenBao execution — owner design

Design ID: `SECRETS-EXEC-20261011-v1`. Status: proposed, source preparation only.
Owning draft: `SECRETS-WP-0013`; adoption remains `SECRETS-WP-0008-T06`.
No native entitlement, owner assent or founder go is established here.

## The concrete gap and immediate correction

`cli._require_lane_approval` consumes the approved action before `_open_backend`.
`engine_auth.select_engine_auth` selects service-jwt for auto whenever its login
contract is configured. CCR-2026-0038 grants a 300-second, eight-use token with
exactly `secrets-engine-login-self`. It explicitly denies custody data/metadata,
policy/auth writes and child-token creation. Thus a valid approval can be
consumed before an ordinary apply/provision/exec fails for lack of backend power.

The staged correction checks **local execution readiness before claim/PDP/CAS**
for every caller about to access protected OpenBao work. Until a real reviewed
execution backend ships, service-jwt is rejected for those callers. Explicit
bootstrap/env providers retain their existing approval/stance gates; no fallback
or default changes. Service-auth login/self probes remain available. Local-only
compromise/reactivate records retain their existing path. A file/boolean claiming
entitlement cannot make the guard pass. Tests exercise the actual apply handler,
asserting zero claim/PDP/consume/login/apply calls for configured auto and missing
explicit service-jwt entitlement. This correction fixes early consumption; it
does **not** implement task-scoped protected work or complete T06.

## One initial execution surface

Implement `secrets-engine execute-ccr --catalog <id> --stage prod --request <file>`
as an explicit, metadata-only action. It admits one owner-reviewed Platform
`workload-kv-read` CCR with already-existing KV and auth mounts, exact generated
policy and exact Kubernetes or existing netkingdom OIDC role. It does not call
generic `apply_plan`: that function can manage AppRoles/mounts, which differs
from Platform's typed CCR applier. Provision, exec delivery, rotation, KV reads,
SecretIDs, token creation by the caller, mounting and arbitrary CLI commands
remain outside this first entitlement. Their backend obligations require their
own later exact action contracts, not reuse of this metadata allowance.

CCR38 and its role/policy stay byte-for-byte unchanged. The engine identifies
itself through that login-only service session; authentication does not create
authority for the metadata action. A new separately reviewed Platform
`task-execution-grant` CCR admits the founder-owned execution mediator and its
temporary exact two-path task token. Existing applied CCRs, including CCR38,
cannot be replayed to manufacture new native work. A real unexecuted, separately
approved metadata CCR and native success/negative/cleanup receipts are needed
for the first proof; none is selected or approved by this design.

## Exact request binding

Use `authorization.build_action_request(entry, 'execute-ccr', ...)` with the
existing canonical digest rules. `apply` is a distinct legacy action: its v2
policy ignores this metadata contract and must never stand in for execute-ccr.
Add a reviewed `context.execution_contract` object
before observing the claim or calling Check. Its fields are:

| Field | Binding |
| --- | --- |
| contract_version | `SECRETS-EXEC-20261011-v1` |
| operation_id | Owner-issued UUID, part of the request digest |
| operation | `metadata-apply-ccr`, closed enum |
| execution_actor | Verified `service:secrets-engine`, separate from initiating subject |
| ccr_id / ccr_immutable_sha256 | Exact unapplied owner CCR ID and immutable content digest |
| execution_grant_ccr_id / grant_immutable_sha256 | Exact reviewed task-token materialization and cleanup contract |
| catalog_sha256 | Exact non-secret approved catalog target specification |
| source_bundle | Absolute owner-resolved files and immutable SHA256 hashes for engine dispatcher, Platform mediator, typed CCR module and policy/auth source |
| backend_origin / cluster_uid | Exact reviewed estate OpenBao origin and railiance01 identity |
| operations | Ordered exact HTTP method, normalized path and canonical JSON/text payload hash for each read/write/readback; no user supplied body |
| operation_deadline | Upper bound no later than approval, PDP, caller and original/fresh source validity; task-token expiry may be earlier |
| backend_budget | TTL at most 120s, at most twelve uses, no renew/child/wrap/unlimited uses |
| expected_before / expected_after | Owner-authenticated revision/state digests, never secret contents |

The action subject/type/purpose/tenant are the actual initiating principal's
verified identity and existing catalog purpose, not inferred from engine service
identity or arbitrary environment fields. Founder-attended invocation names that
principal and the representation explicitly. The mediator refuses absent owner
identity correspondence; a caller-authored subject string is not evidence.

The signed/served approval must bind the same approval-free execution context;
the PDP must return the exact canonical request and matching approval digest.
Publish and pin the updated access-engine policy package/version that evaluates
this context; an older package accepting only a catalog ID cannot authorize it.
No package default or implicit semantic acceptance is assumed. Approval identity,
decision ID and canonical request digest travel together in a non-secret request
descriptor. They are provenance until freshly validated and CAS-consumed.

CCR immutable digests exclude only explicitly owner-defined append-only review/
evidence fields; policy bytes, role bytes, typed mutation body, target coordinates,
grant/deadline and source revisions are included. Approval IDs added after
issuance do not change their own binding. The mediator independently reconstructs
all operation bodies from owner sources and compares the resulting digest list.
It accepts no caller ACL template, path override, shell argv or raw JSON body.

## Execution mediation and consume ordering

Use the existing attended Platform front door, invoked by the founder, to run a
new fixed Platform owner mediator. No daemon, broad new service or new bearer
delivery to agents is required. The caller engine prepares a non-secret request
and receives a non-secret receipt. The founder-held admin credential exists only
inside the reviewed Platform child, through the existing attended route. It is
never exported to the caller. Neither local receipt files nor user-authored
`approved` labels authorize the child.

The Platform child runs the reviewed Secrets Engine authorization/consume code
at the last responsible execution boundary; the CLI preparation path does not
consume early and then hand an untrusted receipt to a more privileged process.
The backend mediation contract must preserve engine ownership of lifecycle
validation while Platform owns its OpenBao credential and typed native primitive.

1. Load pinned sources and exact non-secret request; check typed CCR/grant owner
   approval, catalog/subject/operation correspondence, source/state expectations,
   owner-only execution state directory, supported method/body allowlist and
   local clock/deadline. No protected OpenBao call occurs yet.
2. Atomically reserve the operation in a dedicated engine execution ledger,
   uniquely keyed by `approval_id + request_digest`; the operation UUID is inside
   the digest. Bind the authenticated caller, sources and deadline. This is
   execution state, not the audit outbox or a local evidence-presence gate.
   Multiworker locking uses SQLite `BEGIN IMMEDIATE` and uniqueness constraints;
   only the reservation creator may proceed.
3. Use `authorize_action` / approval-claim validation / `check_decision` / exact
   envelope validation, with pinned policy package and trusted application time.
   Recheck freshness after network calls. Require served human control for the
   production grant; missing claims, unreachable PDP or mismatched binding refuse.
4. Call `require_production_consume` once for that exact binding. Require
   confirmed matching consumption. Persist `consume-confirmed` before any
   protected OpenBao login, custody read, capability check or mutation. A consume
   timeout is `unknown`; never treat it as absence or automatically retry.
   A consumed/idempotent response without the same live local admission is not
   permission to execute again. Retrying a completed operation returns only its
   existing receipt; an incomplete/unknown operation requires owner reconciliation
   and a fresh exact approval for any additional backend action.
5. After consume, perform the existing attended in-memory client-secret source
   and CCR38 service login without provider fallback. Verify its exact login-self
   policy/TTL/uses and service identity; keep this session self-only. Failure
   consumes the trial without metadata effects; no implicit re-login or retry.
6. In the Platform child, use the separately authorized founder-held identity
   only to materialize the reviewed exact ephemeral task policy/token. OpenBao's
   token parent remains platform-owned; the CCR38 token cannot mint it. The grant
   binds every policy/token create/revoke/delete step to this operation and its
   cleanup. Do not give a standing `sys/policies/acl/*`, `auth/*/role/*` or
   `auth/token/create` grant to the engine service.
7. Recheck decision, approval and operation deadlines before **each** protected
   request. The task token is nonrenewable, no default/identity policies and
   grants only read/create/update on the one approved ACL policy path and the
   one approved workload auth-role path, plus revoke-self. No child token, mount
   administration, KV data/metadata, SecretID or sibling role is admitted.
   OpenBao ACL narrows endpoint access; it cannot restrict the HCL/role payload.
   Only the mediator's independently reconstructed body equality enforces that.
8. Use an injected restricted backend adapter for the exact ordered native
   calls. Compare current expected state; write only the approved generated body,
   read it back, and compare it. No `OpenBaoClient._run_ok` raw failure reaches
   receipts: capture/discard backend output and use closed reason codes. A generic
   403/timeout or “already exists” is not successful verification.
9. Finally self-revoke the task token and login-self token, then retire only the
   exact per-operation grant policy under founder-owned cleanup authority.
   Record confirmed revocation/absence separately from native apply status.
   Policy retirement alone does not prove issued-token revocation.

Task-token use budget is declared before issuance: two before-state reads, two
writes, two readbacks and one self-revoke (seven uses), plus at most four explicit
metadata capability checks and one reserved cleanup use (twelve total). Failed
backend calls count; never retry to evade limits. The immutable
`backend_budget.ttl_seconds` declares the requested task-token TTL (30–120s).
The native adapter does not dynamically recompute or shorten that declaration.
Before issuance, conservatively require at least the declared TTL plus the 5s
cleanup reserve within the remaining operation/approval/PDP authority, including
clock uncertainty. The requested and explicit maximum native token TTL equal
the declared budget; returned native TTL must be positive and at most that budget.
The token can expire before the operation deadline; failure or expiry stops work
without remint. The signed operation deadline remains no later than approval,
PDP, authenticated caller and both original/fresh source validity. Access's
trusted source path independently requires the same TTL-plus-5s fit after source
I/O and an operation interval no longer than 120s. Therefore a structural 120s
backend budget cannot fit inside a 120s authority interval with the reserve and
refuses. No renewal or remint extends the operation. CCR38 keeps its
own 300s/eight-use limit; login-self checks and revoke fit its separate budget.

## Failure, replay and recovery

Ledger states: `reserved → consume-confirmed → authenticating → grant-issued →
applying → verified`, followed by a separate `cleanup-confirmed` or
`cleanup-unconfirmed` result. Every external call is durably recorded as about
to execute before the call, then recorded complete afterward. Crash between
those steps is `unknown` rather than presumed failure. Concurrent duplicate
requests never both reach consume or OpenBao.

An operation can end refused before consumption, consumed-without-backend-work,
partially-applied, backend-outcome-unknown, verified-cleanup-unconfirmed or
verified-cleanup-confirmed. No incomplete state permits blind reapplication.
Cleanup continues when an action deadline expires, under the original explicit
cleanup obligation, without new business writes. Read/repair of changed target
state requires a fresh exact owner-reviewed recovery approval; no old snapshot
overwrites concurrent owner edits. Hard interruption uses the Platform owner's
bounded revocation/cleanup procedure with protected accessor custody. Ledger
and evidence carry only fingerprints/metadata; the raw accessor/token never
leaves owner memory or the separately admitted owner-private recovery channel.

Revocation failure blocks owner acceptance and T06 closure, even if TTL will
eventually expire. Emit non-secret atomic local lifecycle events/outbox records
at the ledger boundaries; audit-core outage does not suppress cleanup. Do not
claim an empty archive proves no effects, or that local ledger state is founder
approval. Owner acceptance requires native before/after equality, denied sibling
actions and verified cleanup under the same exact trial.

## Implementation hooks and closure tests

- `engine_auth.py`: staged readiness guard now. Later separate identity-session
  and execution-adapter objects; generic service-jwt client remains self-only.
- `cli.py`: staged guard passed through backend-action approval callers now.
  New explicit execute-ccr preparation/mediated dispatch later; ordinary apply
  does not acquire new rights merely because the login contract is configured.
- `authorization.py`, `approval_consume.py`: execution context participates in
  both approval-free binding and full PDP digest; owner child returns the actual
  `ConsumedApproval`, not only an `AuthorizedAction` ID.
- New `execution_contract.py`, `execution_ledger.py`, `mediated_backend.py`:
  strict closed schema, deterministic compiler, separate admission state,
  pinned owner-native adapter and non-secret outcome types. Ordinary subprocess
  command execution is not an implementation of this adapter.
- Platform owns task-execution-grant CCR/typed validator/token materializer/
  fixed execution child/recovery hooks. Approval Engine/PDP owners acknowledge
  the request+claim/package correspondence; secrets-engine cannot assent for them.

Counterexamples required before shipping: login-only auto provider consumes
nothing; stale/forged grant file changes nothing; same name with changed HCL or
role body refuses; wrong method/sibling policy/role/KV/SecretID/child-token/mount
write refuses; changed source/caller/tenant/catalog/deadline alters the bound
request and refuses; consume conflict/unavailability/timeout produces zero
backend calls; idempotent approval consumption never causes a second execution;
concurrent calls admit one worker; postconsume login failure never falls back;
expiry during a multi-call operation stops new mutations but permits scoped
cleanup; readback mismatch/transport failure is incomplete; revoke failure
never passes; partial apply and crash after write require explicit recovery.

Current staged readiness regression suite: eight new checks plus 28 existing
auth, consume and privileged-evidence checks pass (36 total). No native action
was performed. Full entitlement implementation, policy-package publication,
independent Platform/Secrets Engine/identity/approval/PDP acknowledgement and
exact founder-scoped native proof remain required. A successful metadata trial
alone would not cover value provision or exec delivery.

## Existing commands and the next contract they actually need

| Existing operation | Current login-only outcome | Contract required after the metadata pilot |
| --- | --- | --- |
| apply / apply_plan | Readiness refusal before consume; no backend | A separate exact policy/AppRole/mount structure compiler and grant for each admitted PlanAction. The workload-kv-read execute-ccr pilot does not implement these generic AppRole/mount calls. |
| provision / rotate | Readiness refusal before consume; no KV writes | Exact KV v2 data path, declared field set, expected CAS version, no sibling changes, owner-held opaque input handle, confirmed new version and separately admitted revoke/cleanup. Never expose secret plaintext or guessable secret-value hashes in request/evidence. |
| verify positive/negative | Readiness refusal before consume; no custody reads | Metadata capability probe plus, only when required, exact declared field-presence read through a restricted owner adapter. Return booleans; malformed/denied/transport error is inconclusive, not absence. Independent negative identity and exact deny paths are separate bindings. |
| exec / wrap | Readiness refusal before consume; no read/injection/wrap | Exact custody path/field, signed executable/cwd/destination/exec-owner binding and duration, no user arbitrary shell, owner-mediated read and approved process-local delivery, or exact one-use wrap creation/unwrap/expiry; self revoke and injected material cleanup. |
| handoff | Readiness refusal before consume; no role-id/SecretID mint | Exact existing AppRole and single-use SecretID creation, bounded TTL/uses and owner-admitted delivery; native role-id lookup/SecretID mint/login/revoke budget and no caller standing credential. |
| revoke / native suspend/deactivate | Readiness refusal before consume; no backend revocation/deletion | Exact policy/role/lease/accessor target and expected state, admitted lifecycle effect, rollback/custody preservation and denial readback. Token/lease handles remain owner-private; receipt fingerprints cannot authorize another handle. |
| session revoke | Readiness refusal before its backend; legacy stance remains | Exact already-held protected handle, typed token/lease revocation and independent subject/authority binding; no arbitrary accessor or lease-prefix wildcard. |
| destroy | Existing live destroy refusal remains | Exact destructive dual-control contract and custody/backup/version proof; metadata pilot supplies neither. |
| compromise / reactivate local state | Existing local state gate remains | No new OpenBao entitlement; these local records do not establish actual native revocation/reactivation. |
| service-auth probe-openbao | Existing explicit self-only identity trial | CCR38 positive/negative/lifetime/revoke proof, with no implied entitlement to any catalog lane. |

Each subsequent contract needs its own owner-reviewed compiler, request/PDP
package binding, method/body enforcement, consume admission, TTL/use budget,
failure/recovery rules and native counterexamples. No success in the initial
metadata pilot unblocks these rows by default. Full T06 adoption requires the
actual selected engine production workflow to run through the corresponding
reviewed entitlement, with native effect, denial/no-fallback and cleanup proof.

## Source preparation: typed request propagation (2026-10-11)

The staged ExecutionContract descriptor is deliberately a closed, immutable
non-secret value. `parse` validates shape and captures JSON; every `as_dict`
revalidates even directly constructed instances and returns a detached copy.
It is not an owner approval, source authenticity attestation, principal
representation or proof that the requested origin is admitted. Compiler and
mediator must independently reconstruct and authenticate sources and bodies.

The exact proposed descriptor serialization refines the table above:

- Digests use `sha256:` plus 64 lowercase hexadecimal characters. UUIDs use
  canonical lowercase hyphenated form. CCR and grant IDs must be distinct.
- `source_bundle` has exactly engine_dispatcher, platform_mediator, typed_ccr and
  policy_auth; each has exactly an absolute normalized `path` and `sha256`.
  This parses paths without reading files; pin verification remains unimplemented.
- `operations` is an ordered list of exactly method/path/payload_sha256 objects.
  It accepts only GET/PUT metadata policy and auth-role endpoint shapes, with
  normalized relative paths. This schema does not reconstruct bodies or prove
  that all before/write/readback operations occur or target exactly two paths.
  A later owner compiler must enforce those semantics before any execution.
- `backend_origin` is an explicit-port HTTP(S) origin without credentials, path,
  query or fragment. Syntactic acceptance creates no approved route or network
  call. Estate pinning and server authentication remain mediator obligations.
- `backend_budget` has exactly ttl_seconds (integer 30–120) and uses (integer
  1–12); booleans fail. Listed calls must leave at least one cleanup use.
  Renewal, remint and live per-call accounting remain outside this descriptor.
- expected_before/expected_after are non-secret state digests; operation_deadline
  is timezone-aware. Before claim, refuse expired deadlines using the existing
  trusted-time window. After claim and Check, refuse a deadline later than either
  served approval or decision expiry. A future mediator must recheck before every
  effect and provide separately authorized cleanup after business expiry.
- catalog_sha256 is a descriptor-local sorted compact JSON fingerprint of the
  complete existing context.catalog_target, distinct from canonical PDP digests.
  Resource catalog ID/stage, subject, tenant and purpose remain bound separately
  through the unchanged canonical request hashing implementation.

The same typed descriptor passes through build_action_request, _expected_request,
resolve_approval_observation and authorize_action. Any contract on apply or another
legacy action refuses. execute-ccr without a typed valid contract, prod stage or
platform tenant refuses. execute-ccr always binds human_control=true, even on a
legacy bootstrap catalog, and cannot use an unserved/demo fallback. Invalid or
catalog-mismatched descriptors refuse before claim/PDP/CAS. Returned requests are
independent copies; later caller mutation cannot change the stored descriptor.

99 focused source tests pass across context propagation, the existing approval
join, decision validation, readiness, consume and engine auth. New tests exercise
all four actual builders, actual consume request formatting and claim-free/full
joins; mutation of operation, CCR/grant/source/body/method/path/budget/deadline/
estate/state/principal/purpose/catalog/tenant/stage refuses the original approval.
Transport/PDP stand-ins deliberately supply hypothetical human control and an
ALLOW: they prove propagation, not a shipped policy or real principal admission.

No execute-ccr CLI, identity-owner verified initiating-principal interface,
new access policy package, typed owner compiler, task-grant materializer,
independent authenticated consume-confirmation integration, durable admission
journal, restricted backend, per-call deadline checks or native entitlement is
supplied by this stage. Existing cfg subject strings remain legacy provenance;
this change does not make them verified human representation. Existing generic
consume receipt validation limitations remain explicitly separate. service-jwt
readiness guard/default and ordinary actions remain unchanged. T01 stays in
progress, T03 stays wait, WP13 stays proposed, and WP8-T06 stays open.

## D3 wrapped-delivery primitive and its separate entitlement

D3 P3=b chooses response-wrapped issuer delivery with one-time unwrap. The
existing wrapped-handoff primitive now verifies native TTL/accessor/creation-path
metadata and reserves a private immutable recipient file before minting. Native
KV-v2 creation paths include the `data/` endpoint; caller-requested CLI paths
cannot substitute for returned metadata. Failed mint/write or an altered
reservation retains an uncertain attempt and never silently overwrites/remints.

A disposable local OpenBao integration proves the exact source path,60-second
TTL, successful first unwrap and specific HTTP400 consumed-token replay denial.
This proves backend semantics, not the estate's first delivered lane, audited
initiating principal, consumer identity, independent owner acceptance or cleanup
under crash/revocation. Production CLI wrapping remains fail-closed. Existing
metadata execute-ccr contracts expressly exclude wrap/KV value delivery and cannot
be borrowed for this purpose. A separate exact owner-admitted delivery operation
must bind actor,path,audience,deadline,authorization/consume state,destination,
audit,replay/crash recovery and rollback before native adoption. The prepared
D2 repository-issuer lane remains attended until its own reviewed execution and
independent destination/adoption proofs pass.