headquarter/docs/superpowers/plans/2026-05-17-auth-oauth.md

Auth OAuth Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Implement Authentik-backed OIDC login that issues internal JWT access tokens, rotates DB-backed refresh tokens, and supports secure logout.

Architecture: FastAPI route handlers delegate to focused auth services: OIDC provider client, token verifier/minting service, and refresh token store. Session state is carried in httpOnly cookies while refresh-token validity is enforced from PostgreSQL. Token trust boundary is explicit: provider token is JWKS-verified before local token minting.

Tech Stack: FastAPI, SQLAlchemy (async), Alembic, python-jose, httpx, pytest/pytest-asyncio, ruff, mypy

---

Task 1: Config and DB schema

Files:

• Modify: apps/api/src/config.py

• Modify: apps/api/src/models/user.py

• Create: apps/api/src/models/refresh_token.py

• Modify: apps/api/src/models/__init__.py

• Create: apps/api/alembic/versions/0002_refresh_tokens.py

• Test: apps/api/tests/test_config.py

• Test: apps/api/tests/test_models.py

• Step 1: Write failing tests for OIDC/JWT config and refresh-token metadata

• Step 2: Run focused tests to verify red state

• Step 3: Implement minimal config and model changes

• Step 4: Add migration and migration metadata test updates

• Step 5: Re-run focused tests to verify green state

Task 2: Auth services

Files:

• Create: apps/api/src/auth/__init__.py

• Create: apps/api/src/auth/cookies.py

• Create: apps/api/src/auth/oidc.py

• Create: apps/api/src/auth/jwt_service.py

• Create: apps/api/src/auth/refresh_store.py

• Test: apps/api/tests/test_auth_services.py

• Step 1: Write failing tests for cookie policy, JWT mint/verify, and refresh lifecycle

• Step 2: Run targeted tests to verify failures are expected

• Step 3: Implement minimal auth service modules to satisfy tests

• Step 4: Re-run tests and iterate until green

Task 3: Auth API routes

Files:

• Create: apps/api/src/main.py

• Create: apps/api/src/api/__init__.py

• Create: apps/api/src/api/auth.py

• Test: apps/api/tests/test_auth_api.py

• Step 1: Write failing API tests for /auth/login, /auth/callback, /auth/refresh, /auth/logout, /auth/me

• Step 2: Run targeted API tests to confirm red state

• Step 3: Implement minimal route handlers and dependency wiring

• Step 4: Re-run API tests until green

Task 4: Verification and OpenSpec updates

Files:

• Modify: openspec/changes/auth-oauth/tasks.md

• Step 1: Run full checks: pytest, ruff check src tests, mypy src

• Step 2: Run migration against local Postgres and verify current revision

• Step 3: Mark completed checkboxes and capture any blockers in OpenSpec tasks