approval-engine/docs/pep-integration.md

PEP integration sequence

approval_engine.pep implements the fail-closed ordering from GH-DEC-2026-003 without becoming a PDP:

1. fetch a fresh approval claim;
2. pass that claim to the consumer's authorization decision function;
3. require ALLOW, decision id, and the exact canonical request digest;
4. CAS-consume the approval;
5. only after confirmed consumption invoke the protected callback.

Claim or consume unavailability, invalid/consumed claims, DENY, digest mismatch, and consume conflicts all prevent the callback. A same-digest retry receives the engine's idempotent success. If the callback fails after consume, the approval stays spent; there is no unconsume.

The module rereads the mounted bearer-token file on each HTTP request. Its unit harness uses a dry-run callback and demonstrates the ordering, but live closure requires the secrets-engine-owned handler to prove that no OpenBao request is made in every failure case.