# AT Proto OAuth Authentication Implementation Plan

## Architecture Overview
Combine patterns from both reference projects:
- **statusphere**: AT Proto OAuth client with DB-backed session/state storage
- **solid-test**: Cookie-based session management with vinxi/http useSession
- **Our approach**: AT Proto OAuth + iron-session cookies storing only session ID + full session data in DB

## Database Schema Changes (`src/db/schema.ts`)
1. Add `auth_session` table (key: string PK, session: JSON/text)
2. Add `auth_state` table (key: string PK, state: JSON/text)
3. Add `user` table (did: string PK, handle: varchar, createdAt: timestamp)
4. Add `user_session` table (sessionId: string PK, did: string FK, createdAt: timestamp, expiresAt: timestamp)

## New Files to Create
1. `src/auth/client.ts` - NodeOAuthClient setup
2. `src/auth/storage.ts` - StateStore & SessionStore classes (DB-backed)
3. `src/auth/session.ts` - iron-session helper for cookie management
4. `src/auth/index.ts` - Export auth utilities

## Server Actions (`src/api/server.ts`)
1. `initiateLogin(handle: string)` - Start OAuth flow
2. `handleOAuthCallback(params: URLSearchParams)` - Complete OAuth, create user session
3. `logout()` - Destroy session
4. `getUser()` - Retrieve user from session

## Routes
1. Update `src/routes/login.tsx` - AT Proto handle input
2. Add OAuth callback route/handler
3. Protect routes requiring auth

## Environment Variables
Add to `.env`:
- `COOKIE_SECRET` - for iron-session
- `PUBLIC_URL` - for OAuth client metadata (optional, dev uses localhost)

## Flow
1. User enters handle → `initiateLogin` → OAuth authorize URL
2. Redirect to PDS → User approves
3. Callback → `handleOAuthCallback` → Store OAuth session in DB, create user_session, set cookie with sessionId
4. Cookie contains only sessionId → Server reads sessionId → Looks up user_session → Gets DID → Restores OAuth session from DB → Gets Agent