docs: add Phase 1 auth system design spec

docs/superpowers/specs/2026-03-28-phase-1-auth-design.md

@@ -0,0 +1,118 @@
+# Phase 1 — Auth System Design
+
+**Date:** 2026-03-28
+**Status:** Approved
+
+## Goal
+
+Implement full JWT-based authentication: backend routes, DB queries, password hashing, token management, and frontend login/signup UI with Zustand state.
+
+## Backend
+
+### Files
+- `backend/auth/password.py` — bcrypt hash (cost=12) and verify
+- `backend/auth/jwt.py` — sign and verify HS256 access token (15min); generate opaque refresh token string
+- `backend/db/connection.py` — asyncpg connection pool, initialised via `init_db_pool()` on startup
+- `backend/db/queries.py` — all SQL: user insert, user lookup by email, refresh token insert/lookup/delete
+- `backend/routers/auth.py` — four routes with request/response Pydantic models
+- `backend/main.py` — wire routers, call `init_db_pool()` in lifespan
+
+### Auth Flow
+
+```
+SIGNUP  POST /api/auth/signup
+  Body: { full_name, email, password, role, class_code? }
+  → if role=student: lookup batch by class_code, get batch_id (400 if not found)
+  → bcrypt hash password (cost=12)
+  → INSERT user
+  → sign access token { user_id, role, batch_id, email, exp }
+  → generate refresh token string → hash → INSERT refresh_tokens
+  → Set-Cookie: refresh_token=<raw> (httpOnly, SameSite=Lax)
+  → return { access_token, user: { id, role, full_name, batch_id } }
+
+LOGIN   POST /api/auth/login
+  Body: { email, password }
+  → lookup user by email (401 if not found)
+  → bcrypt verify (401 if wrong)
+  → same token flow as signup
+
+REFRESH POST /api/auth/refresh
+  → read refresh_token cookie (401 if missing)
+  → hash cookie value → lookup in refresh_tokens (401 if not found or expired)
+  → sign new access token
+  → return { access_token }
+
+LOGOUT  POST /api/auth/logout
+  → read refresh_token cookie
+  → DELETE from refresh_tokens where token_hash matches
+  → clear cookie
+  → return { ok: true }
+```
+
+### Route Protection (added to main.py, used in Phase 2+)
+
+```python
+async def get_current_user(token: str = Depends(oauth2_scheme)) -> dict:
+    # verify JWT, return payload
+    # raises 401 on failure
+
+async def require_instructor(user = Depends(get_current_user)) -> dict: ...
+async def require_student(user = Depends(get_current_user)) -> dict: ...
+```
+
+## Frontend
+
+### Files
+- `frontend/src/api/client.ts` — base `apiFetch`: injects Bearer token, retries once on 401 after refresh
+- `frontend/src/api/auth.ts` — `signup()`, `login()`, `logout()`, `refreshToken()`
+- `frontend/src/store/authStore.ts` — Zustand store, persisted to localStorage
+- `frontend/src/App.tsx` — React Router v6, role-based redirect, ProtectedRoute
+- `frontend/src/pages/Login.tsx` — dark card form, error state, loading button
+- `frontend/src/pages/Signup.tsx` — same style + role toggle + conditional class code field
+
+### Zustand Store Shape
+
+```typescript
+interface AuthStore {
+  accessToken: string | null
+  user: { id: string; role: string; full_name: string; batch_id: string | null } | null
+  setAuth: (token: string, user: User) => void
+  clearAuth: () => void
+}
+// persisted to localStorage via zustand/middleware persist
+```
+
+### apiFetch Behaviour
+
+1. Get `accessToken` from `authStore`
+2. Fetch with `Authorization: Bearer <token>` + `credentials: 'include'`
+3. If response is 401 → call `refreshToken()` → retry original request once
+4. If retry also 401 → `clearAuth()` + redirect to `/login`
+
+### Routing (App.tsx)
+
+```
+/login           → Login (redirect to dashboard if already authed)
+/signup          → Signup (redirect to dashboard if already authed)
+/student/*       → ProtectedRoute (role=student)
+/instructor/*    → ProtectedRoute (role=instructor)
+/                → redirect based on role
+```
+
+### UI Spec (Login + Signup)
+
+- Dark card: `bg-gray-900 border border-gray-800 rounded-xl p-8 w-full max-w-md`
+- Page bg: `min-h-screen bg-gray-950 flex items-center justify-center`
+- Input: `bg-gray-800 border border-gray-700 rounded-lg px-4 py-2 text-white w-full`
+- Button: `bg-indigo-600 hover:bg-indigo-500 text-white rounded-lg px-4 py-2 w-full`
+- Loading: button disabled + "..." text
+- Error: red text below form `text-red-400 text-sm`
+- Signup role toggle: two buttons (Student / Instructor), active = indigo fill
+- Class code field: visible only when role = student
+
+## Key Decisions
+
+- Refresh token stored as raw string in cookie; only the bcrypt hash goes to DB — cookie theft alone is not enough
+- `apiFetch` handles token refresh transparently — pages never deal with 401 manually
+- Zustand `persist` middleware saves auth to localStorage so page refresh doesn't log users out
+- `class_code` lookup happens at signup time; `batch_id` is embedded in the JWT so subsequent requests don't need a DB lookup for basic auth