tegwick
f62d3fe789
Implements step 2 (access-engine POST /v1/check) and wires the whole GH-DEC-2026-003 sequence together, then proves it against a live throwaway OpenBao rather than only unit-level fakes. - decision_check.check_decision performs the PDP call; an unreachable or non-200 PDP raises, since silence is never permission. - approval_consume.authorize_action coordinates steps 1 and 2 and returns an AuthorizedAction. Both steps build the same CheckRequest via a shared _expected_request, since two descriptions of the action cannot produce corresponding digests. - apply_unreachable_engine_stance takes authorized=. The published map defines fail_closed as no side effect WITHOUT a durable decision record, so holding a validated one means the residue does not apply. Not a bypass: both steps must have succeeded and CAS consume still precedes OpenBao. Unconfigured still returns None and fails closed. The end-to-end test caught one more instance of the cross-vocabulary bug: a leftover comparison of the claim's binding.action against ours. The claim says secrets.kv.destroy where we say destroy, so it would have failed against every real claim. Removed; the tie is pdp_digest. Integration coverage asserts PIP-then-PDP ordering, that consume is the last step before the backend, and that an unreachable PDP, denied decision, invalid claim, missing pdp_digest, consume conflict and action mismatch each stop before OpenBao. 284 tests pass; production still fails closed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01M65ovP3eiiPHubibvWs9mD Assistant: claude-code Assistant-Model: opus Assistant-Process: 393550@bnt-lap001 Assistant-Session: 4bb359f9-1f12-4410-9e76-079cf23c82e4
139 lines
6.8 KiB
Markdown
139 lines
6.8 KiB
Markdown
# 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 today, 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>`), and no mapping between them is published. flex-auth makes no
|
|
cross-check either and states the correspondence is ours. Computing a native
|
|
digest from our own vocabulary would compare two different languages and never
|
|
match, so this engine does not compute one. Closing that gap needs a published
|
|
mapping co-authored by approval-engine and flex-auth; it is a prerequisite for
|
|
`SECRETS-WP-0007-T04` making `destroy` reachable.
|
|
|
|
### 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.
|