headquarter/openspec/changes/archive/2026-05-17-auth-oauth/tasks.md

1. Configuration and schema foundation

• 1.1 Add auth/OIDC/JWT/cookie settings to backend config with environment-aware defaults.
• 1.2 Add refresh token SQLAlchemy model and relationships to user model.
• 1.3 Add Alembic migration for refresh token table and indexes.
• 1.4 Add/adjust tests that fail first for config and refresh-token model metadata.

2. Auth provider and token services

• 2.1 Implement Authentik OIDC client helpers for login URL build and callback token exchange.
• 2.2 Implement JWKS-based token verification helper for provider tokens.
• 2.3 Implement internal JWT mint/verify helper with configured TTL.
• 2.4 Implement refresh token store service (hashing, create, rotate, revoke, reuse detection).
• 2.5 Add unit tests for provider verification, JWT helpers, cookie options, and refresh lifecycle.

3. Auth HTTP endpoints

• 3.1 Implement GET /auth/login redirect endpoint.
• 3.2 Implement GET /auth/callback with state validation, token exchange, user upsert, and cookie set.
• 3.3 Implement POST /auth/refresh with DB validation and rotation.
• 3.4 Implement POST /auth/logout to revoke refresh state and clear cookies.
• 3.5 Implement GET /auth/me returning authenticated user payload via internal JWT.
• 3.6 Add integration tests for callback, refresh rotation, logout, and unauthorized cases.

4. Verification and OpenSpec tracking

• 4.1 Run auth-focused and full backend checks (pytest, ruff check, mypy) and fix findings.
• 4.2 Run migration verification against local Postgres and confirm current revision.
• 4.3 Update this task list with completed checkboxes and note any blockers/follow-ups.

Blockers / Follow-ups

• No blocking items remain for this change.

Runtime verification

• DATABASE_URL=postgresql+asyncpg://headquarter:headquarter@localhost:5432/headquarter .venv/bin/alembic -c alembic.ini upgrade head succeeded.
• DATABASE_URL=postgresql+asyncpg://headquarter:headquarter@localhost:5432/headquarter .venv/bin/alembic -c alembic.ini current returned 0002_refresh_tokens (head).