# 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**