approval-engine/README.md

approval-engine

The approval as a durable, authenticated, consumable object — issued before an action, verified at the moment of use, and provably not replayable.

An Engine, role PIP, in the NetKingdom security layer model (statute v0.7, accepted; operative form net-kingdom/SECURITY-COMPANION.md). It answers one question, totally and decidably:

Is this approval valid right now — for this exact action, target, actor, and purpose — and has it already been used?

It does not decide whether the action is permitted. That is access-engine, which stays NetKingdom's only policy decision point. An approval is one input to that decision.

Deliberately small, boring, and strict: atomic supersession and single consumption are what make Canon test T-06 — Approval Replay passable. Flexibility here would be a defect. Graded, evidence-based progression belongs to maturity-engine; the two engines are deliberate opposites.

See INTENT.md and SCOPE.md. Declaration: layer.yaml. Claim: docs/approval-claim.md. Consume: docs/approval-consumption.md. Origin: flex-auth FLEX-DEC-2026-001, raised while assenting to the security layer model.

make test
approval-engine migrate --db approvals.sqlite
approval-engine verify --db approvals.sqlite
approval-engine serve --db approvals.sqlite \
  --jwt-issuer https://auth.netkingdom.local \
  --jwt-audience approval-engine \
  --jwks-url http://key-cape.sso.svc.cluster.local:8080/jwks

POST /v1/approvals/{id}/consume implements GH-DEC-2026-003: the PEP atomically spends the approval before the protected side effect. Same-digest retries are idempotent; a different digest conflicts.

Production operations, caller scopes, audit delivery, and PEP sequencing are documented in docs/storage-operations.md, docs/caller-authentication.md, docs/outbox-contract.md, and docs/pep-integration.md. The checked-in StatefulSet deliberately refuses production startup without a migrated persistent store, KeyCape JWT verification, and authenticated audit delivery.