feat(authz): add Cedar-based authorization tier with deferred API-key authn

[jmgilman]

Summary

Adds an authorization tier to the template: a deny-by-default authorization decision expressed as middleware between endpoints, with authentication deliberately deferred to the integrator. The goal is a sensible, loosely-coupled starting point that morphs into whatever a consumer needs — not a bundled identity provider.

• Engine: AWS Cedar via cedar-go, committed as the engine (no vendor-neutral portability layer) — we expose Cedar's real types (Request/Decision/Diagnostic/PolicySet) behind a thin internal/authz package.
• Modular, per-resource authz slices: each domain contributes its policies, action identifiers, and a fact resolver from internal/<domain>/authz, merged into one PolicySet + composite entity getter at the composition root — the same vertical-slice pattern as the HTTP registrar.
• One global Huma middleware, deny-by-default: every operation must declare authz.Require(...) or authz.Public(); undeclared → 403. Require also stamps the OpenAPI security requirement so protection is visible in the generated docs.
• URL-fed resource identity: by-id routes bind the path param to Resource = Todo::"<id>" with no DB load; attribute/relationship policies load entities lazily through a request-scoped, fail-closed getter.
• Authentication is deferred: the shipped Authenticator is a replaceable API-key adapter (X-API-Key / Bearer) backed by a PostgreSQL api_keys table. Integrators swap it for real JWT/OIDC/session authn — see DELETE_ME.md.

The domain core (internal/todo) stays Cedar-free.

How it was built (four gated phases)

Each phase ran implement → 3-lens adversarial review (correctness · doc-adherence · conventions) → fix → validate, with a human gate between phases:

• A — base internal/authz package + API-key authn + api_keys migration + config flags + mockery doubles (wired inert; --authz-enabled off until routes were tagged).
• B — the todo/authz slice, route tagging, URL-id binding, the composite-getter precedence guard, and flipping --authz-enabled to true. Caught and fixed a latent enforcement bug (Huma freezes per-operation middleware at register time, so authz had to be installed before huma.Register and the OpenAPI security stamped after).
• C — container-backed integration tests: the real PostgreSQL APIKeyStore adapter and an end-to-end functional authz suite (no key → 401, wrong role → 403, user/admin → allowed) in internal/integration.
• D — the dev-only hack/sql mock-keys seed, README/DELETE_ME/docs, and a live docker compose up functional check of the day-one demo.

Day-one demo

docker compose up --build brings up postgres → migrate → seed → api and seeds two dev-only mock keys. The seed lives in hack/sql/ (applied only to the ephemeral compose DB), never in a migration, so the mock credentials can never reach a real deployment.

curl -sS localhost:8080/todos                              # => 401 (deny-by-default)
curl -sS -H 'X-API-Key: dev-user-key' localhost:8080/todos # => 200

Config

• --authz-enabled (default true) — master switch / escape hatch.
• --authz-policy-dir — load .cedar files from a directory instead of the embedded set (fails fast on a missing/empty/invalid dir).
• API keys live in the api_keys table (--database-url is already required).

Testing

• moon run root:check green (build, lint, unit tests, openapi-check, sqlc-check, mockery-check, docs).
• moon run test-integration green against a real postgres:17-alpine container (the postgres APIKeyStore adapter + the full e2e authz matrix). Default go test ./... stays hermetic (integration tests are build-tagged).
• The compose day-one demo verified live end-to-end (401 without a key; 200/201 with the seeded keys; admin override; Bearer credential; by-id routes).

Removal

DELETE_ME.md documents removing the tier surgically: replace the API-key authenticator (#1), then delete internal/authz (incl. apikey), internal/todo/authz, the 00002 migration + 0002 seed, untag the routes, and drop the --authz-* config. No sqlc regeneration is needed (omit_unused_structs keeps the todo sqlc package free of the api_keys model).

Follow-up (pre-existing, unchanged)

test-integration is still not wired into CI — the GitHub workflows remain .disabled pending a Docker-capable runner.

🤖 Generated with Claude Code