railiance-platform/docs/credential-lane-designs/secrets-engine-task-execution-entitlement.md

# Secrets Engine task execution entitlement — Platform owner design

Prepared under RPF-WP-0035-T11; implementation belongs to RPF-WP-0035-T12.
This is a proposed source design, not an installed endpoint, approved CCR,
founder disposition or native acceptance. CCR-2026-0038 stays login-self-only.
No service default changes and no standing service administrative ACL.

## Existing machinery and exact first action

Platform INTENT §§ Stable Interfaces, Secure Custody and Operable/Observable
require a stable constrained backend interface. Platform owns OpenBao enforcement
and credential lifecycle; KeyCape owns identity, access-engine decides, approval-engine
consumes, and Secrets Engine owns the lifecycle PEP. Platform is Staff with declared
Tooling gaps, not a replacement identity or authorization engine.

Current `cli._require_lane_approval` consumes before `_open_backend`, which gives
`apply_plan` the login-self token. That token cannot read/write target ACLs or
AppRole roles. Login proof cannot complete functional Lifecycle adoption.

First action: a new explicit **execute-ccr** interface applying exactly one reviewed
`workload-kv-read` CCR's two structure objects: its generated reader ACL and one
OIDC/Kubernetes role on an existing mount. Refuse mount enable/config, AppRole,
KV data/metadata operations, SecretID issuance, token delivery, arbitrary argv,
free-form policy bodies, broader typed CCR dispatch and generic `apply_plan`.
Generic Secrets Engine apply supports mount/AppRole work; silently translating
that action to this owner interface would change its meaning.

Reuse `credential-change.py`'s workload-kv-read validator, generated policy,
`auth_payload`, readiness/binding checks and metadata applier structure. Existing
`service-jwt-login` remains identity only; existing `custody-generate-grant` supplies
patterns for exact generated policy/issuer/token-role TTL/no-default/cleanup, but
its `platform/workloads/keycape/+` create grant cannot perform structure writes.
A new separately reviewed request type **task-execution-grant** is necessary;
it is not yet in `LANE_MODULES`, so presenting it today must be refused.

## Bound request and interface

Proposed version `platform-task-execution/v1`, initially a founder-attended owner
primitive, not an unattended HTTP service. Input is a bounded private pipe containing
a non-secret request envelope; service authentication is a separate memory-only
credential channel. No credential enters command argv, environment, receipt or Git.
The owner launches the exact reviewed primitive through the existing attended
platform-admin envelope only after the scoped founder go is recorded.

Envelope fields: unique `operation_id`; `action=execute-ccr`; platform realm and
stage; service principal `service:secrets-engine` of type service; consumer catalogue
revision/hash; exact CCR id/content SHA256; all authoritative generated source/body
SHA256s; ordered endpoint/method/payload digests; exact canonical CheckRequest and
its digest; served approval id/claim binding; PDP DecisionEnvelope id/package/version,
not-before/expiry; successful consume binding; owner admission/source revision.
The canonical request includes operation id, CCR digest, catalogue digest and the
whole target/body plan, not merely a friendly lane name. Local owner files are the
source; supplied payloads, file paths or HCL are never applied. Secret-bearing
request fields and unknown fields are refused.

Action/PDP spelling is a new consumer contract to publish with access-engine.
Reuse its canonical digest/claim validation, do not invent an interchangeable
`apply` decision. Service identity and caller subject are independently matched;
a caller assertion of `service:secrets-engine`, a decoded JWT or a successful
human OIDC login is insufficient. Authenticate against CCR38's exact native role
and independently verify lookup creation path, role, effective token/identity
policies and service entity provenance. If the existing metadata does not bind
subject adequately, use KeyCape signature/issuer/audience/expiry validation plus
owner-correlated native role login; do not label role-only metadata a trusted subject.

## Admission, consume and execution ordering

1. Secrets Engine and Platform perform only local/static checks and public
   unauthenticated discovery before consume: envelope/schema, owner CCR readiness,
   exact source hashes, generated policy/role equality, full target/body plan,
   owner primitive revision, journal availability and available bounded lifetime.
   The founder's independently approved owner envelope is separate bootstrap
   authority; it grants no consumer lifecycle action by itself.
2. Platform durably reserves `(approval_id, request_digest, operation_id)` with a
   unique constraint and confirms the exact plan. Journal write must be fsynced
   and atomic before acknowledgement. No database content is copied to evidence.
3. Secrets Engine obtains validated claim/PDP correspondence and performs the
   existing approval-engine CAS consume for that same request. No protected consumer
   login, client-secret read or backend write precedes this step. Platform accepts
   neither a caller boolean nor an unsigned copy as proof: it independently validates
   the served claim/PDP and verifies consume with approval-engine's authenticated
   replay/verification contract. If this is unavailable, it refuses execution.
4. Bind the authenticated service identity after successful consume. Authenticate
   once; refusal or timeout burns this admission. Platform atomically transitions
   the same reservation to `consume-confirmed`, then `applying` before any effect.
   A racing second call cannot acquire the state. Consume idempotency is not permission
   to execute twice. Repeated calls return the recorded terminal receipt only.
5. Inside the founder owner envelope, mint an **owner-held ephemeral task token**
   with only exact target paths. Apply exactly the pinned typed plan, compare
   value-free native readback, revoke the task token, remove only this operation's
   temporary grant role/policy after revoke, and finalize the durable receipt.

New approval-engine verification/replay semantics and owner journal are required
implementation gates. They are not supplied by current `ConsumedApproval` dataclasses
or caller receipts. If approval-engine offers only idempotent consume, Platform may
make the authenticated same-digest consume call itself after the client call, but
must verify exact original correspondence and keep the independent execution
journal; never interpret idempotent success as a fresh admission.

Journal states: `reserved → consume-confirmed → applying → verified|failed|unknown`.
Consume/auth failures become `failed`; uncertain consume, lost post-write response,
crash after `applying`, or cleanup failure become `unknown`. None automatically
re-executes. A retry requires owner reconciliation, native readback and a fresh
approval/operation id if another effect is needed. No rollback reuses the consumed
approval; retain partial state and prepare a separately approved exact recovery.

## Backend policy, payload and time enforcement

Ephemeral role/policy names derive from the operation hash and are owner-controlled.
Proposed token: service, orphan, nonrenewable, no default/identity policies, TTL and
explicit maximum at most **120s**, and **12 uses maximum** including cleanup.
Actual expiry is the earliest approval/PDP expiry, founder window expiry, authenticated
identity/session expiry and now+120s; refuse insufficient remaining time. Budget
is a reviewed fixed operation plan, never an arbitrary caller num_uses. Reserve
at least one self-revoke use and refuse exhausted/expired executions.

Grant endpoints are exactly `sys/policies/acl/<CCR reader policy>` and
`auth/<CCR existing mount>/role/<CCR role>` with only required read/create/update;
self lookup/capabilities/revoke have explicit minimal grants. Explicit deny applies
to guarded client-secret data/metadata, token create/renew, secret-id and all
unrelated structure targets. Do not publish blanket deny on all ACL paths if it
would also override the two intended target grants. The target-set allowlist and
native denied sibling/admin/data probes define this exact scope.

The founder-held issuer may mint only the unique task role; the service role
never receives issuer/token-create authority. Existing platform-admin bootstrap
remains founder-attended; no persistent administrative credential is introduced
for Secrets Engine. No task token is returned to the caller or reused by generic
`_open_backend`. Returning one would allow direct OpenBao bypass of lifecycle checks.

OpenBao ACL limits endpoint paths/capabilities, but **cannot constrain the HCL or
role JSON body or bind an approval digest by itself**. Independent Platform mediation
validates the exact body hashes against locally generated owner-approved source
immediately before each call; this is part of backend enforcement. A policy-write
token exported to a caller would let it replace the target ACL with broad powers,
and an auth-role-write token could bind a privileged policy. Therefore raw exact-path
ACL is not sufficient execution authority. Native ACL probes prove endpoint scope;
independent mediator counterexamples must prove body/action/approval scope.

## Evidence, acceptance and rollback

Value-free receipt: proposal/source/CCR/request/decision/consume/journal digests,
principal fingerprint and role, reserved/executed timestamps, fixed endpoint/payload
hashes, native request ids or safe hashes, readback equality, task/session accessor
fingerprints, exact granted TTL/uses, revoke and temporary-object cleanup booleans,
terminal state. No raw tokens, JWTs, full accessors, errors, KV responses or secrets.
Receipt return is separate from protected-action success: unknown cleanup never
reports verified. Retain outcome after client disconnect for safe read-only recovery.

Required implementation and native proofs: intended disposable metadata-only action
passes once; wrong identity/type/issuer/audience/claims, altered CCR/catalogue/body,
wrong action/target, stale revision, TTL/use exhaustion, invalid/expired/mismatched
PDP or consume, missing journal, racing/replayed request, direct raw-token sibling
write, policy-body escalation and role-policy substitution all refuse. Crash/timeout
at reserve/consume/mint/write/readback/revoke/temporary cleanup must preserve unknown
and prevent retry. Native ACL denials and mediator refusals must be distinguished
from transport failure. Restore/delete only the disposable objects by their owning
reviewed recovery action; never broaden the service policy to discover gaps.

The initial pilot does not cover provision/rotate/handoff/wrap/exec/deactivate,
KV destruction or the existing generic AppRole apply. Each needs its own typed
operation/body contract and owner evidence. Full steady-state adoption additionally
needs dispatcher integration, real intended result and accounting/reservation
reconciliation, credential-free caller execution and reviewed default migration.
RPF35-T02 and Secrets T06 cannot close from the login verifier or this design.