Area: docs — discoverability (DX) · found via WaveHouse-Stats dogfooding
Expected: build a correct auth/ingest integration from the docs alone.
Actual: access-control.md is already strong on the authorization model (fail-closed, roles, default_role/admin_role, eval flow), but several load-bearing behaviors are still source-only — each shaped the Stats integration and required a code dive:
- HMAC-vs-JWKS is either/or with alg pinning; no static asymmetric key, and JWKS is a fatal boot dependency.
exp is not required (never-expiring tokens validate).- No token revocation.
- Policy evaluation order: schema-validate runs before check-injection (validate → column ACL → check → dedupe).
- The dedupe contract (body-field id only, permanent/local, no per-table key).
Impact (Stats): fine for us (we read the code); a real barrier for external adopters.
Scope: audit access-control.md / api.md#authentication / configuration.md and fill the gaps above — verifier modes + alg pinning, the exp/revocation stance, policy evaluation order, and the dedupe contract. (PR #193's docs pass doesn't touch these pages.)
Related: the auth-hardening epic #228, policy seed-vs-SoT #229, and async-ingest #230 are the behaviors to document.
From WAVEHOUSE-FEEDBACK.md (WaveHouse-Stats dogfooding); validated by code-read against 0f8826c on 2026-06-04.
Area: docs — discoverability (DX) · found via WaveHouse-Stats dogfooding
Expected: build a correct auth/ingest integration from the docs alone.
Actual:
access-control.mdis already strong on the authorization model (fail-closed, roles, default_role/admin_role, eval flow), but several load-bearing behaviors are still source-only — each shaped the Stats integration and required a code dive:expis not required (never-expiring tokens validate).Impact (Stats): fine for us (we read the code); a real barrier for external adopters.
Scope: audit
access-control.md/api.md#authentication/configuration.mdand fill the gaps above — verifier modes + alg pinning, theexp/revocation stance, policy evaluation order, and the dedupe contract. (PR #193's docs pass doesn't touch these pages.)Related: the auth-hardening epic #228, policy seed-vs-SoT #229, and async-ingest #230 are the behaviors to document.
From
WAVEHOUSE-FEEDBACK.md(WaveHouse-Stats dogfooding); validated by code-read against0f8826con 2026-06-04.