secrets-engine/docs/approval-consumption.md

Approval consumption (PEP)

Status: engine consumer and the PIP claim/validate join are implemented; live production remains fail-closed until approval-engine and access-engine actually serve the durable objects.

Normative protocol: gate-house/docs/contracts/approval-consumption.md (GH-DEC-2026-003). Implementation surface: approval-engine/docs/approval-consumption.md. This document records how secrets-engine, as the PEP for OpenBao writes, consumes that protocol. It does not redefine it.

Sequence

1. PIP  GET  /v1/approvals/{id}/claim
2. PDP  access-engine Check / decide          → ALLOW
3. PEP  POST /v1/approvals/{id}/consume       → CAS
4. PEP  OpenBao call                          → only after consume succeeds

Step 1 is resolve_consume_binding (approval_consume.py): it reproduces the exact CheckRequest with build_action_request, fetches the durable ActionAuthorization from GET /v1/approvals/{id}/claim, and validates it with validate_action_authorization before returning a consume binding. Until 2026-09-06 that function was a return None stub and the validator was unreachable from src/; the join now exists.

The approval-engine object id is never inferred from a State Hub decision UUID. It comes from catalog approval.authorization_id or a served decision.authorization_id. The Check request id is an opaque correlator the PEP cannot regenerate, so the served one is adopted; every security-relevant field is still compared exactly and the binding digest is recomputed against the served request.

Every live privileged production handler passes _require_lane_approval, which calls require_production_consume before OpenBaoClient.resolve. Dry-run and plan do not consume. Build/test remain fail-open relative to approval-engine. The three-factor unsafe-demo exception is not a consume path.

Fail closed

Condition	Result
No served consume binding	refuse; no OpenBao
URL/token/authorization id all unset	binding is None → refuse; no OpenBao
Partially configured join (missing subject or policy pin)	raise; never degrade to "unconfigured"
Claim digest, action, or field set mismatch	refuse; no OpenBao
Missing SECRETS_ENGINE_APPROVAL_URL or token file	refuse; no OpenBao
HTTP 409 / different digest	refuse; no OpenBao
Same digest after consume	idempotent success; OpenBao may proceed
401/403/404/503/unreachable	refuse; no OpenBao
Side effect fails after consume	approval is spent; no unconsume

The consume response is mutation evidence (status=consumed plus the presented digest). It is not a permission. Evidence records approval id, digest, idempotence, and consumed-at only. No token, secret, or accessor.

Required configuration

The join is absent by default, so an unconfigured engine behaves exactly as it did before. Production additionally needs:

Variable	Meaning
SECRETS_ENGINE_APPROVAL_URL	approval-engine base URL (claim + consume)
SECRETS_ENGINE_APPROVAL_TOKEN_FILE	mode-0600 credential, outside Git
SECRETS_ENGINE_AUTHORIZATION_SUBJECT_ID / _SUBJECT_TYPE	the acting principal
SECRETS_ENGINE_AUTHORIZATION_POLICY_PACKAGE / _VERSION	the live pin
SECRETS_ENGINE_AUTHORIZATION_MIN_APPROVALS	distinct-approver threshold

There is deliberately no default policy pin. flex-auth stated that the published secrets-engine.lifecycle / v1 names are example vocabulary on the envelope, not a live package, so treating them as a default would pin production to a package nobody publishes.

What this does not do

• It does not enable live production. Unreachable-engine stance still fail-closes production until an access-engine decision record is served (SECRETS-WP-0007-T04 / SECRETS-WP-0008-T02).
• It does not render or cache an authorization decision.
• It does not infer consumption from a decision record or from local evidence.