Skip to content

docs: audit & fill the consumer-facing Security & Auth Model #231

Description

@EricAndrechek

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.

Activity

  1. added
    documentationImprovements or additions to documentation
    area/docsDocumentation, site/, README
    securitySecurity-sensitive issue or fix
    on Jun 4, 2026
  2. coderabbitai commented on Jun 4, 2026

    @coderabbitai
    🔗 Related PRs

    #123 - fix(api): drop CORS credentials + skip same-origin decoration [merged]
    #172 - feat(rbac)!: fail-closed authorization + default_role public access [merged]
    #187 - docs: prep docs for publishing [merged]


    📝 Issue Planner

    Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.

    • Create Plan

    🧪 Issue enrichment is currently in open beta.

    You can configure auto-planning by selecting labels in the issue_enrichment configuration.

    To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

    issue_enrichment:
      auto_enrich:
        enabled: false

    💬 Have feedback or questions? Drop into our discord!

  3. moved this from Backlog to Ready in WaveHouse Task Boardon Jun 9, 2026
  4. moved this from Ready to Backlog in WaveHouse Task Boardon Jun 9, 2026
  5. added
    area/authAuthentication: tokens, JWT/JWKS, keys, token expiry/revocation
    on Aug 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area/authAuthentication: tokens, JWT/JWKS, keys, token expiry/revocationarea/docsDocumentation, site/, READMEdocumentationImprovements or additions to documentationsecuritySecurity-sensitive issue or fix

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions