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](INTENT.md) and [SCOPE.md](SCOPE.md). Declaration: [layer.yaml](layer.yaml).
Claim: [docs/approval-claim.md](docs/approval-claim.md).
Consume: [docs/approval-consumption.md](docs/approval-consumption.md).
Origin: `flex-auth` `FLEX-DEC-2026-001`, raised while assenting to the security
layer model.

```bash
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.