Files
headquarter/openspec/changes/archive/2026-05-17-auth-oauth/proposal.md
T

1.4 KiB

Why

The project has database foundations in place but still lacks production-ready user authentication. We need a secure OAuth2/OIDC integration with Authentik that issues internal session credentials and supports reliable logout and token revocation.

What Changes

  • Implement backend OAuth2/OIDC login and callback flow against Authentik.
  • Verify Authentik-issued tokens via JWKS before minting local credentials.
  • Mint short-lived internal JWT access tokens and store refresh tokens server-side.
  • Add refresh-token rotation, revocation, and explicit logout semantics.
  • Apply environment-aware secure cookie policy (strict in production, relaxed for localhost development).
  • Add auth endpoints, supporting services, and test coverage for auth flows.

Capabilities

New Capabilities

  • auth-session-tokens: Internal JWT access-token issuance, opaque refresh-token storage, rotation, and revocation.

Modified Capabilities

  • auth-oauth: Extend OAuth/OIDC behavior to require JWKS validation, internal JWT minting, cookie policy by environment, and DB-backed refresh lifecycle.

Impact

  • Affected backend modules in apps/api/src (config, models, auth services, API routes).
  • New database schema object for refresh-token persistence and an accompanying migration.
  • New environment variables for OIDC/JWT/cookie settings.
  • Frontend auth integration points for login/logout/me/refresh behavior.