feat: implement auth, projects, and frontend foundation

2026-05-17 20:21:55 +00:00
parent e7819bfc82
commit 71d9fe6406
88 changed files with 10936 additions and 47 deletions
@@ -0,0 +1,170 @@
+# Auth OAuth Design
+
+## Goal
+
+Implement OAuth2/OIDC authentication via Authentik with internal JWT access tokens, DB-backed refresh token rotation, secure cookie handling, and explicit logout revocation.
+
+## Scope
+
+In scope:
+- Authentik code flow callback handling
+- Authentik token verification via JWKS
+- Internal JWT minting and validation
+- Refresh token persistence and rotation
+- Logout revocation and cookie clearing
+- Cookie policy split for dev vs production
+
+Out of scope:
+- RBAC policy engine
+- Multi-device session management UI
+- Social providers beyond existing Authentik setup
+
+## Chosen Approach
+
+Use full OIDC callback exchange with JWKS verification, then mint an internal short-lived JWT and store opaque refresh tokens server-side.
+
+Why this approach:
+- Keeps trust boundary explicit (no blind trust of exchange payload)
+- Allows immediate refresh-token revocation on logout
+- Decouples internal auth contract from external provider claim shape
+
+## Defaults
+
+- Access token TTL: 15 minutes
+- Refresh token TTL: 7 days
+- Cookie mode:
+  - Production: `Secure=true`, `SameSite=strict`, `httpOnly=true`
+  - Local development: `Secure=false`, `SameSite=lax`, `httpOnly=true`
+
+## Architecture
+
+1. Frontend calls `GET /auth/login`.
+2. Backend redirects to Authentik authorize endpoint.
+3. Authentik redirects to backend callback with `code`.
+4. Backend exchanges `code` for Authentik tokens.
+5. Backend validates Authentik access token using Authentik JWKS (`iss`, `aud`, `exp`, signature).
+6. Backend maps claims to local user record (create/update by `authentik_id`).
+7. Backend mints internal access JWT and opaque refresh token.
+8. Backend stores hashed refresh token in database and sets cookies.
+9. Protected endpoints validate internal access JWT.
+10. `POST /auth/refresh` rotates refresh token and issues new access JWT.
+11. `POST /auth/logout` revokes refresh token and clears cookies.
+
+## Data Model
+
+Add a `refresh_tokens` table:
+
+- `id`: UUID primary key
+- `user_id`: UUID foreign key -> `users.id`
+- `token_hash`: string (hash of opaque refresh token; never store raw token)
+- `expires_at`: timestamp with timezone
+- `created_at`: timestamp with timezone
+- `revoked_at`: timestamp with timezone, nullable
+- `user_agent`: string, nullable
+- `ip_address`: string, nullable
+
+Indexes:
+- unique index on `token_hash`
+- index on `user_id`
+- index on `expires_at`
+
+## API Endpoints
+
+### `GET /auth/login`
+
+- Redirects to Authentik authorize URL with state and nonce.
+
+### `GET /auth/callback`
+
+- Validates state.
+- Exchanges code at Authentik token endpoint.
+- Verifies Authentik access token via JWKS.
+- Upserts local user.
+- Mints internal access JWT + opaque refresh token.
+- Persists hashed refresh token record.
+- Sets `access_token` and `refresh_token` cookies.
+
+### `POST /auth/refresh`
+
+- Reads `refresh_token` cookie.
+- Hashes and finds matching non-revoked, non-expired DB row.
+- If valid, revokes old row and creates a new row (rotation).
+- Mints new internal access JWT and new opaque refresh token.
+- Sets rotated cookies.
+
+### `POST /auth/logout`
+
+- Reads refresh cookie if present.
+- Revokes corresponding DB token row.
+- Clears access and refresh cookies.
+
+### `GET /auth/me`
+
+- Validates internal access JWT.
+- Returns current user payload.
+
+## Token Strategy
+
+### Internal access JWT
+
+Claims:
+- `sub`: local user id
+- `email`
+- `name`
+- `roles` (optional, if available)
+- `iat`, `exp`
+
+Signing:
+- Use configured backend signing secret/algorithm.
+
+### Refresh token
+
+- Opaque, random, high-entropy value
+- Hashed before persistence
+- Rotated on each refresh
+- Revoked on logout and on detected reuse
+
+## Security Rules
+
+- Never expose token contents to frontend JS (httpOnly cookies only).
+- Validate Authentik token signature and critical claims before minting local JWT.
+- Enforce strict cookie attributes by environment.
+- Log security-relevant events with safe redaction.
+- Return generic auth errors to clients; keep details in server logs.
+
+## Error Handling
+
+- Invalid code exchange -> `401`
+- JWKS verification failure -> `401`
+- Missing/invalid refresh cookie -> `401`
+- Revoked/expired refresh token -> `401`
+- Reuse detection (if token already rotated/revoked) -> revoke chain and force login
+
+Error body shape:
+- stable machine-readable code
+- non-sensitive message
+
+## Testing Strategy
+
+Unit tests:
+- cookie option builder (dev vs prod)
+- Authentik token verification helper
+- internal JWT mint/verify helpers
+- refresh hash + rotation logic
+
+Integration tests:
+- callback creates/updates user and sets cookies
+- refresh rotates token and invalidates previous token
+- logout revokes token and clears cookies
+- protected endpoint rejects invalid/expired JWT
+
+Quality gates:
+- `pytest` passes
+- `mypy .` passes
+- `ruff check .` passes
+
+## Implementation Notes
+
+- Keep auth logic in focused modules (provider client, jwt service, refresh store, route handlers).
+- Keep DB writes idempotent where feasible (user upsert path).
+- Keep changes scoped to auth-oauth and required schema support.