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