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

```text
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
```

**Each artifact is validated by the layer that owns its data**
(`GH-DEC-2026-005`). There is no single bundled object:

| Step | Artifact | Owner | Validated by |
| --- | --- | --- | --- |
| 1 | approval-claim | approval-engine | `approval_claim.validate_approval_claim` |
| 2 | DecisionEnvelope | flex-auth | `authorization.validate_decision_envelope` |

The claim carries the *approval fact*: issuer, `valid_now`, consumption state,
binding digest, freshness, `reason_code`. The envelope carries the *decision*:
effect, exact CheckRequest binding, canonical request digest, lifetime, and the
policy package/version pin. Neither republishes the other's data.

`ActionAuthorization` is **deferred and was never ratified**
(`FLEX-DEC-2026-006`). It cannot be served from a step-1 call, and nothing here
validates it. A ratified post-decision form remains a deferred option.

There are **two different digests** over the same proposed action, and they are
never compared to each other:

- `claim.binding.digest` — approval-engine native, `sha256` over canonical JSON
  of `{action, actor, principal, purpose, target}`.
- `decision.binding.request_digest` — flex-auth canonical CheckRequest digest.

`claim.binding.pdp_digest` is the **only** comparison usable, and its absence
fails the action closed. The claim's `binding.action` and `binding.target` speak
approval-engine's vocabulary (`secrets.kv.destroy`, `{"id": ..., "stage": ...}`)
while ours speaks the catalog's (`destroy`, `catalog:<id>`). No mapping between
them exists and none is coming: gate-house rejected one outright in
`GH-DEC-2026-008`, because a translation can be confidently wrong and fails
**open** by silently accepting a claim approved for a different action. An
identity check cannot. So this engine computes no native digest.

### The two gates on the pdp path

**1. `binding.pdp_path` must be `true`.** This is approval-engine's declaration
(schema v3) that the approval was requested against a bound CheckRequest. Their
`create()` refuses `pdp_path` true without a `pdp_digest`, so the declaration
*guarantees* the digest. The converse does not hold, and we must not infer it: a
digest recorded for some other reason is no declaration anybody made, and every
approval issued before schema v3 carries `pdp_path` false regardless of any
digest it holds.

The cost is real and is ours to carry — an approval requested without a bound
CheckRequest is not usable here and never becomes usable later. `GH-DEC-2026-008`
holds that correct: an approval granted against an unspecified action does not
become an approval for a specific one because a consumer later found a use for
it. If a real destroy workflow cannot bind at issue, that is the falsifier
gate-house wrote into the reversal, and it should be **raised**, not worked
around.

**2. The digest identity, against the right comparand.**

```text
claim.binding.pdp_digest == decision.binding.approval_binding_digest   correct
claim.binding.pdp_digest == decision.binding.request_digest            can never pass
```

`pdp_digest` is recorded at *issue* time, and issue precedes the decision. A
request that carries the claim inside its hashed `context` therefore has a
different `request_digest` by construction — the claim is part of the material
being hashed. This engine found that circularity against the T03 replay fixture;
flex-auth fixed it in `FLEX-DEC-2026-007` by publishing
`binding.approval_binding_digest`, the same canonical digest with
`context.approval` removed, which is stable across attaching the claim.

`approval_binding_digest` is **not** a replay identity. `request_digest` still
covers the claim and still moves when it changes, because two requests differing
only in which approval was presented must not share a replay identity — one
allows, the other denies `dual_control_required`. Collapsing them would let an
allow obtained with a valid claim be replayed against a request carrying none.

Our own CheckRequest is claim-free today (`context` is `{"purpose": ...}`), so
flex-auth emits no `approval_binding_digest` for it and the identity holds
transitively: step 1 compares the claim's `pdp_digest` to the canonical digest of
the exact claim-free request we are about to send, and step 2 confirms the
decision's `request_digest` is that same value. `approval_binding_digest(request)`
implements the published exclusion rule so that the check is already correct if
we ever carry the claim in context; when the field is present it is recomputed
and never taken on faith.

### What is hashed in the flex-auth digest

`tenant`, `subject`, `action`, `resource`, `context` — and nothing else.
`id` is correlation only, `policy_version` lives in provenance, and
`caring_context` is hashed separately. Including any of them yields a digest
that matches no issued decision. `digest_material` enforces the exclusion and
`tests/test_decision_replay.py` pins it against two real envelopes.

A consumer re-hashing the *original unenriched* request will not match a
decision that turned on registry attributes: the binding is the evaluator's
statement of what it hashed, so recompute from the binding tuple.

The approval-engine object id is never inferred from a State Hub decision UUID.
It comes from catalog `approval.authorization_id`, and is the value in the
`{id}` path segment echoed back as `approval_id`.

**There is no authority constant.** The engine previously required
`provenance.authority == "state-hub"`, which contradicted its own source: State
Hub is a read model and holds no runtime approval authority, so that check
failed closed against every correctly issued record. The approval fact's
authority is approval-engine (checked as `issuer`); the decision's is flex-auth.

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 (step 2) |
| `SECRETS_ENGINE_PDP_URL` / `_PDP_TOKEN_FILE` | the per-consumer access-engine pin |

The distinct-approver threshold is no longer a consumer-side check. The claim
does not expose approver entries; approval-engine folds that requirement into
`valid_now`, which is true only when enough distinct authenticated approvers
have been recorded and the object is not consumed, superseded, revoked, or
expired.

There is deliberately no default policy pin. The reserved coordinate is
`secrets-engine.catalog-lane.lifecycle` / `v1`, but that is a *reservation, not
a publication* (`FLEX-DEC-2026-005`) and must not be configured until
`FLEX-WP-0021-T02` publishes the package. `docs/gated-actions.md` supplies the
action vocabulary that package is built from.

Step 2 additionally needs the `flex-auth-secrets-engine` Service DNS. No
estate-wide PDP exists by design — flex-auth runs per-consumer cluster-local
pins — and that pin has not been created, so the PDP call is not wired yet.

## 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.