The machine surface cortex's UpstreamEntitlementProvider (#57) consumes,
mirroring the EntitlementProvider trait 1:1 over the B1 ledger.
- `authz.rs`: POST /authz/v1/{resolve,reserve,settle,release,snapshot}.
resolve → {principal, snapshot} | 401 invalid_api_key (a deactivated
account resolves as the SAME 401 — the silent-abuse no-clue property).
reserve returns 200 whether granted ({reservation_id}) or budget-refused
({rejected:{kind,...}}) — a refusal is an authoritative answer, not a
transport failure; non-2xx means "fail closed" to the client. settle/
release → 204 (idempotent). snapshot → {hard_cap,spent,reserved} | 404.
Rejections use the shared #63 OpenAiError envelope (cortex-core dep).
- Client auth: shared-bearer middleware (constant-time compare via subtle)
maps a token → operator_id (stamped into request extensions for #58
served-usage); empty config = open dev surface (logged). mTLS deferred.
- ledger gains resolve_key (sha256 lookup, account-active-gated), snapshot,
and sweep_stale (one data-modifying-CTE statement releasing aged-out open
reservations and folding their reserved tokens back into accounts+keys).
- Sweeper task spawned in run(); [authz] ttl/interval + [client_auth]
config; crypto::sha256 helper.
Validated against a throwaway Postgres 16 (fresh schema): resolve→reserve→
settle→snapshot round-trip, over-cap → 200 insufficient_quota rejection
(not retried away), deactivated account → 401 (no clue), missing/wrong
client bearer → 401 before any DB hit. 5 unit + 8 gated integration tests;
all skip cleanly without UPSTREAM_TEST_DATABASE_URL so CI stays green.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01F6o3ddqmYNh9kzdwq6eowh
