tegwick
c3f1dfbc07
Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a05e2e-805b-7042-a750-71f473bceea2
43 lines
1.5 KiB
Markdown
43 lines
1.5 KiB
Markdown
# Approval consumption API
|
|
|
|
Status: implemented under Gate House decision `GH-DEC-2026-003`.
|
|
|
|
The normative protocol is
|
|
`gate-house/docs/contracts/approval-consumption.md`. This document records the
|
|
approval-engine implementation surface; it does not redefine the protocol.
|
|
|
|
## Endpoint
|
|
|
|
```text
|
|
POST /v1/approvals/{id}/consume
|
|
```
|
|
|
|
```json
|
|
{
|
|
"request_digest": "sha256:<64 lowercase hex>",
|
|
"decision_id": "decision:optional-provenance"
|
|
}
|
|
```
|
|
|
|
The caller is the PEP that is about to perform the protected side effect. It
|
|
calls consume after an ALLOW and before that side effect. `request_digest` is
|
|
the canonical digest from the PDP decision binding, not a newly serialized
|
|
request and not approval-engine's native binding digest.
|
|
|
|
## Results
|
|
|
|
- First valid consume: atomically stores the digest, changes `approved` to
|
|
`consumed`, and inserts one `approval.use` outbox row in the same transaction.
|
|
- Same digest after consumption: `200` idempotent success and no second outbox
|
|
row.
|
|
- Different digest after consumption: `409 conflict`; the PEP must not act.
|
|
- Revoked, superseded, expired, outside-window, requested, or unknown object:
|
|
conflict or not-found; the PEP must not act.
|
|
- Outbox insert/store failure: `503`; the transaction rolls back and the PEP
|
|
must not act.
|
|
|
|
There is no unconsume, release, or reserve. If the protected side effect fails
|
|
after consumption, the approval remains spent and a retry needs a new approval.
|
|
|
|
The response is mutation evidence, not a permission decision. It contains no
|
|
`effect`, `allow`, `deny`, or decision result.
|