docs: add OAuth implementation design for ATB-14

Complete design for AT Protocol OAuth authentication covering:
- Decentralized PDS authority model
- @atproto/oauth-client-node integration
- Pluggable session storage (in-memory → Redis migration path)
- Authentication middleware and route protection
- Client metadata configuration
- Error handling and security considerations

Includes implementation roadmap with 5 phases and testing strategy.

docs/plans/2026-02-07-oauth-implementation-design.md

···
+# OAuth Implementation Design
+
+**Issue:** ATB-14
+**Author:** Claude Code
+**Date:** 2026-02-07
+**Status:** Approved
+
+## Overview
+
+Implement AT Protocol OAuth authentication for the atBB forum. Users authenticate with their AT Protocol identity (DID) to perform write operations. The AppView acts as an OAuth client, requesting delegated access from each user's PDS (the authorization server).
+
+## Requirements
+
+- Support both end users and admins
+- Pluggable session storage (in-memory default, Redis-ready)
+- AppView owns OAuth flow, issues session tokens to Web UI
+- Respect decentralized PDS authority model
+
+## Architecture
+
+### Authority Model
+
+**Critical:** Each user's PDS is the authorization server, NOT the AppView.
+
+- **User's PDS** = Authorization Server for that user's account
+  - Issues access tokens for their DID
+  - Validates credentials
+  - User approves scopes here
+
+- **AppView** = OAuth Client
+  - Requests authorization from user's PDS
+  - Receives delegated access tokens
+  - Uses tokens to write records to user's PDS on behalf
+
+**Example:**
+- User A on `bsky.social` → AppView redirects to `bsky.social`'s OAuth endpoint
+- User B on `self-hosted.example` → AppView redirects to `self-hosted.example`'s OAuth endpoint
+- Same AppView client, different authorization servers per user
+
+### OAuth Package Selection
+
+**Using: `@atproto/oauth-client-node` v0.5.14**
+
+Rationale:
+- Official Node.js OAuth client for AT Protocol
+- Handles OAuth 2.1 requirements: PKCE, DPoP, PAR (Pushed Authorization Requests)
+- Manages token refresh automatically
+- Production-ready security (nonce rotation, state management)
+- Integrates cleanly with `@atproto/api` Agent
+
+### Client Metadata Approach
+
+AT Protocol uses client metadata documents instead of pre-registration.
+
+The AppView will:
+- Serve public `/.well-known/oauth-client-metadata` endpoint
+- Use metadata URL as `client_id` (e.g., `https://forum.example.com/.well-known/oauth-client-metadata`)
+- Declare redirect URIs, scopes (`atproto`), grant types
+
+No pre-registration required—the forum's metadata URL is the identity.
+
+### Session Token Strategy
+
+Sessions use signed, opaque tokens (not JWTs):
+- HTTP-only cookies prevent XSS attacks
+- SameSite=Lax prevents CSRF
+- Server-side storage maps tokens to OAuth sessions (DID, handle, access tokens)
+- Tokens are random UUIDs (allows instant revocation)
+
+## Implementation Details
+
+### OAuth Routes
+
+**`GET /api/auth/login?handle=user.bsky.social`**
+1. Extract handle from query param
+2. Resolve handle → DID → PDS endpoint (using `@atproto/identity`)
+3. Create OAuth client for that PDS
+4. Generate state + PKCE verifier (stored server-side keyed by state)
+5. Build authorization URL with state, code_challenge, redirect_uri
+6. Return redirect response to PDS's authorization endpoint
+
+**`GET /api/auth/callback?code=...&state=...`**
+1. Validate state parameter (CSRF protection)
+2. Retrieve stored PKCE verifier for this state
+3. Exchange authorization code for tokens (using code_verifier)
+4. Extract user DID, handle, PDS endpoint from token response
+5. Create session record with tokens + metadata
+6. Generate session token (UUID), set HTTP-only cookie
+7. Clean up state storage
+8. Redirect to Web UI homepage
+
+**`GET /api/auth/logout`**
+1. Extract session token from cookie
+2. Delete session from storage
+3. Optionally revoke tokens at PDS (if supported)
+4. Clear cookie
+5. Return 200 or redirect to homepage
+
+**`GET /api/auth/session`**
+1. Extract session token from cookie
+2. Lookup session in storage
+3. Check if access token expired
+4. If expired, refresh using refresh token
+5. Return: `{ did, handle, authenticated: true }` or 401
+
+### Session Storage
+
+**Interface:**
+```typescript
+interface SessionData {
+  did: string;
+  handle: string;
+  pdsUrl: string;
+  accessToken: string;
+  refreshToken?: string;
+  expiresAt: Date;
+  createdAt: Date;
+}
+
+interface SessionStore {
+  set(token: string, session: SessionData, ttl?: number): Promise<void>;
+  get(token: string): Promise<SessionData | null>;
+  delete(token: string): Promise<void>;
+  cleanup?(): Promise<void>;
+}
+```
+
+**Implementations:**
+
+1. **MemorySessionStore (MVP Default)**
+   - In-memory Map storage
+   - Auto-cleanup with TTL timers
+   - Limitation: lost on restart, single-instance only
+
+2. **RedisSessionStore (Future)**
+   - Uses Redis SETEX for automatic expiration
+   - Supports multi-instance deployment
+   - Drop-in replacement via same interface
+
+**Factory in AppContext:**
+```typescript
+export interface AppConfig {
+  sessionStore?: SessionStore;  // Optional injection
+}
+
+export async function createAppContext(config: AppConfig) {
+  const sessionStore = config.sessionStore ?? new MemorySessionStore();
+}
+```
+
+### Authentication Middleware
+
+**`requireAuth(ctx: AppContext)`**
+- Validates session token from cookie
+- Checks access token expiration
+- Triggers refresh if needed
+- Creates Agent with user's tokens
+- Attaches `AuthenticatedUser` to Hono context: `c.get('user')`
+- Returns 401 if invalid/expired
+
+**`optionalAuth(ctx: AppContext)`**
+- Same logic but doesn't return 401
+- Sets `c.get('user')` only if valid session exists
+- Allows endpoints to work for both authenticated and unauthenticated users
+
+**Usage:**
+```typescript
+app.post('/api/posts', requireAuth(ctx), async (c) => {
+  const user = c.get('user');  // Type: AuthenticatedUser
+  const agent = user.agent;
+
+  await agent.com.atproto.repo.createRecord({
+    repo: user.did,
+    collection: 'space.atbb.post',
+    record: { /* ... */ }
+  });
+});
+```
+
+### Error Handling
+
+**Categories:**
+
+1. **User-Initiated Errors (4xx)**
+   - User denies authorization → Redirect with `?error=access_denied`
+   - Invalid handle → "Handle not found"
+   - No PDS found → "Could not locate your AT Protocol server"
+
+2. **Integration Errors (transient)**
+   - PDS unreachable → "Your server is not responding, try again"
+   - Token exchange timeout → "Authorization timed out, try again"
+   - Refresh fails → Log out, "Session expired, please log in again"
+
+3. **Configuration Errors (5xx)**
+   - Invalid client metadata → Log error, show generic message
+   - Missing env vars → Fail fast at startup
+   - PKCE state not found → Log warning, "Authorization expired"
+
+**Logging Strategy:**
+- Structured JSON logs for all OAuth events
+- Never log tokens or secrets
+- Include event type, timestamp, relevant IDs
+- Dev mode shows error details, production shows generic messages
+
+**Security:**
+- Never log access_token, refresh_token, PKCE verifier
+- Validate redirect_uri matches client metadata
+- Constant-time state comparison (prevent timing attacks)
+- Clear expired state regularly (prevent memory leaks)
+
+### Client Metadata Configuration
+
+**Endpoint:** `GET /.well-known/oauth-client-metadata`
+
+Dynamic generation based on environment:
+```json
+{
+  "client_id": "https://forum.example.com/.well-known/oauth-client-metadata",
+  "client_name": "atBB Forum",
+  "redirect_uris": ["https://forum.example.com/api/auth/callback"],
+  "scope": "atproto transition:generic",
+  "grant_types": ["authorization_code", "refresh_token"],
+  "response_types": ["code"],
+  "token_endpoint_auth_method": "none",
+  "application_type": "web",
+  "dpop_bound_access_tokens": true
+}
+```
+
+**Environment Variables:**
+```bash
+OAUTH_PUBLIC_URL=https://forum.example.com
+SESSION_SECRET=generate-random-32-byte-hex
+SESSION_TTL_DAYS=7
+REDIS_URL=redis://localhost:6379  # Optional
+```
+
+**Startup Validation:**
+- SESSION_SECRET must be ≥32 characters
+- OAUTH_PUBLIC_URL required in production
+- Warn if using in-memory sessions in production
+
+## File Structure
+
+**New Files:**
+```
+apps/appview/src/
+├── lib/
+│   ├── session-store.ts
+│   ├── oauth-service.ts
+│   └── state-store.ts
+├── middleware/
+│   └── auth.ts
+└── routes/
+    └── auth.ts
+```
+
+**Modified Files:**
+```
+apps/appview/src/
+├── lib/
+│   ├── app-context.ts
+│   └── config.ts
+├── index.ts
+└── types.ts (new)
+
+apps/appview/package.json
+.env.example
+```
+
+## Implementation Order
+
+### Phase 1: Foundation
+1. Create session-store.ts (interface + in-memory implementation)
+2. Create state-store.ts (OAuth state storage)
+3. Update app-context.ts (add sessionStore)
+4. Add OAuth env vars to config.ts
+5. Test: Session store CRUD operations
+
+### Phase 2: OAuth Service
+6. Install @atproto/oauth-client-node + @atproto/identity
+7. Create oauth-service.ts (wrap NodeOAuthClient)
+8. Implement PDS discovery (handle → DID → PDS)
+9. Test: Generate authorization URLs
+
+### Phase 3: Auth Routes
+10. Create routes/auth.ts (all four endpoints)
+11. Add /.well-known/oauth-client-metadata endpoint
+12. Test: Manual OAuth flow with bsky.social
+13. Verify: Callback receives tokens, creates session
+
+### Phase 4: Middleware
+14. Create middleware/auth.ts (requireAuth, optionalAuth)
+15. Add Hono context types
+16. Test: Protected endpoints require session
+17. Test: Token refresh works
+
+### Phase 5: Polish
+18. Add structured logging
+19. Implement error handling
+20. Test error cases (deny, expired state, invalid tokens)
+21. Document testing in Linear issue
+
+## Testing Strategy
+
+**Manual Testing:**
+- Happy path: login → approve → callback → session → logout
+- Error cases: deny, invalid handle, expired state, token expiration
+- Token refresh: wait for expiration, verify auto-refresh
+- Multi-PDS: test with bsky.social + self-hosted PDS
+
+**Test Accounts:**
+- bsky.social account (official PDS)
+- Optional: self-hosted PDS for multi-PDS validation
+
+**Development Setup:**
+- ngrok/cloudflare tunnel for public redirect URI
+- Or: use localhost redirect (some PDSs allow)
+- Update client metadata to match deployment URL
+
+**Verification:**
+```bash
+# Before login
+curl -c cookies.txt http://localhost:3000/api/auth/session  # → 401
+
+# After manual login
+curl -b cookies.txt http://localhost:3000/api/auth/session  # → { did, handle, authenticated: true }
+
+# Protected endpoint
+curl -b cookies.txt -X POST http://localhost:3000/api/posts -d '{...}'  # → Success
+
+# Logout
+curl -b cookies.txt http://localhost:3000/api/auth/logout
+curl -b cookies.txt http://localhost:3000/api/auth/session  # → 401
+```
+
+## Security Considerations
+
+1. **HTTP-only cookies** prevent XSS
+2. **SameSite=Lax** prevents CSRF
+3. **State parameter** validated for CSRF protection
+4. **PKCE** prevents authorization code interception
+5. **DPoP** binds tokens to client key (required by spec)
+6. **Constant-time comparison** for state validation
+7. **Never log tokens** in production or development
+
+## Edge Cases
+
+- **User changes handle:** Session valid (keyed by DID)
+- **User migrates PDS:** Session invalid, must re-authenticate
+- **Concurrent refresh:** NodeOAuthClient handles locking
+- **Session cookie stolen:** Mitigated by HTTP-only + SameSite
+
+## Complexity Estimate
+
+- **Lines of code:** ~600-800
+- **Time:** 1-2 days
+- **Risk areas:** PDS discovery, token refresh timing, state management
+
+## Dependencies
+
+- **Blocks:** ATB-12, ATB-15, ATB-16, ATB-17 (all need authenticated users)
+- **Blocked by:** None (can start immediately)
+
+## References
+
+- [AT Protocol OAuth Spec](https://atproto.com/specs/oauth)
+- [@atproto/oauth-client-node](https://www.npmjs.com/package/@atproto/oauth-client-node)
+- [@atproto/api OAUTH.md](https://github.com/bluesky-social/atproto/blob/main/packages/api/OAUTH.md)
+- [OAuth Client Implementation | Bluesky](https://docs.bsky.app/docs/advanced-guides/oauth-client)