This repository has no description
1# OAuth Migration Guide: Custom Implementation → @atproto/oauth-client-browser
2
3This guide explains how to migrate from your current custom OAuth implementation to the official `@atproto/oauth-client-browser` package, which provides better reliability, maintenance, and features.
4
5## Overview of Changes
6
7### What's Being Replaced
8
9**Current Implementation:**
10- Custom PKCE flow with manual code generation (`bluesky-auth.ts`)
11- Manual DPoP token generation and nonce handling
12- Complex token refresh logic with multiple retry strategies
13- Custom API proxy routes (`/api/auth/token`, `/api/auth/nonce`)
14- Manual storage management across localStorage/sessionStorage
15- Complex auth context with manual state management
16
17**New Implementation:**
18- Official `@atproto/oauth-client-browser` with automatic session management
19- Automatic token refresh and DPoP handling
20- Built-in IndexedDB storage
21- Direct integration with `@atproto/api`
22- Simplified auth context
23- No need for custom API routes
24
25## Migration Steps
26
27### 1. Update App Layout to Use New Auth Context
28
29Replace the old auth context with the new one in your main layout:
30
31```tsx
32// Before: app/src/app/layout.tsx
33import { AuthProvider } from '@/lib/auth-context'
34
35// After:
36import { AuthProvider } from '@/lib/auth-context-new'
37```
38
39### 2. Replace Login Page
40
41```tsx
42// Replace: app/src/app/auth/login/page.tsx
43// With: app/src/app/auth/login/page-new.tsx
44
45// Then rename page-new.tsx to page.tsx
46```
47
48### 3. Replace Callback Page
49
50```tsx
51// Replace: app/src/app/auth/callback/page.tsx
52// With: app/src/app/auth/callback/page-new.tsx
53
54// Then rename page-new.tsx to page.tsx
55```
56
57### 4. Update API Calls
58
59Replace your existing API calls with the new simplified client:
60
61```tsx
62// Before:
63import { getProfile, makeAuthenticatedRequest } from '@/lib/bluesky-api'
64import { useAuth } from '@/lib/auth-context'
65
66const { accessToken, keyPair, dpopNonce, pdsEndpoint } = useAuth()
67const profile = await getProfile(accessToken, keyPair, dpopNonce, handle, pdsEndpoint)
68
69// After:
70import { getProfile } from '@/lib/api-client'
71import { useAuth } from '@/lib/auth-context-new'
72
73const { session } = useAuth()
74if (session) {
75 const profile = await getProfile(session)
76}
77```
78
79### 5. Update Components Using Auth
80
81Update any components that use the auth context:
82
83```tsx
84// Before:
85const { isAuthenticated, accessToken, did, handle } = useAuth()
86
87// After:
88const { isAuthenticated, session } = useAuth()
89const did = session?.sub
90const handle = session?.info?.handle
91// Note: accessToken is available as session?.accessToken if needed for legacy code
92```
93
94### 6. Remove Old Files
95
96After migration is complete and tested, you can remove these files:
97
98- `app/src/lib/bluesky-auth.ts` - Custom OAuth implementation
99- `app/src/lib/auth-context.tsx` - Old auth context (rename from auth-context-new.tsx)
100- `app/src/lib/storage-util.ts` - Custom storage utilities
101- `app/src/app/api/auth/token/route.ts` - Custom token exchange API
102- `app/src/app/api/auth/nonce/route.ts` - Custom nonce retrieval API
103- Old login and callback pages after replacement
104
105### 7. Update Existing API Usage
106
107Replace complex API calls with simplified versions:
108
109```tsx
110// Before: Making a post
111import { createPost } from '@/lib/bluesky-api'
112await createPost(accessToken, keyPair, dpopNonce, postData, pdsEndpoint)
113
114// After:
115import { createPost } from '@/lib/api-client'
116await createPost(session, { text: "Hello world!" })
117```
118
119## Benefits of Migration
120
121### 1. **Simplified Codebase**
122- ~1000 lines of custom OAuth code removed
123- No more manual DPoP token generation
124- No more complex nonce handling
125- No more custom API routes
126
127### 2. **Better Reliability**
128- Official implementation tested across many apps
129- Automatic retry logic for failed requests
130- Better error handling and recovery
131- Proper session lifecycle management
132
133### 3. **Improved Security**
134- Uses secure IndexedDB storage instead of localStorage
135- Proper token refresh with automatic retries
136- Better handling of session invalidation
137- DPoP implementation follows latest specs
138
139### 4. **Enhanced Features**
140- Automatic handle resolution
141- Built-in support for third-party PDS servers
142- Session restoration across browser sessions
143- Event listeners for session changes
144
145### 5. **Better Maintenance**
146- Official package maintained by AT Protocol team
147- Regular updates and security patches
148- Better TypeScript support
149- Comprehensive documentation
150
151## Compatibility Notes
152
153### Third-Party PDS Support
154The new implementation maintains full support for third-party PDS servers like `geese.blue`. The OAuth client automatically:
155- Resolves handle to find the correct PDS
156- Uses the appropriate OAuth endpoints
157- Manages cross-PDS authentication flows
158
159### Legacy Code Support
160The new auth context provides backward compatibility properties:
161- `accessToken` - Available as `session?.accessToken`
162- `refreshToken` - Available as `session?.refreshToken`
163- `did` - Available as `session?.sub`
164- `handle` - Available as `session?.info?.handle`
165- `pdsEndpoint` - Extracted from session info
166
167## Testing the Migration
168
169### 1. Test Basic Authentication
170- Sign in with a Bluesky handle (e.g., `alice.bsky.social`)
171- Verify the callback completes successfully
172- Check that session is restored on page refresh
173
174### 2. Test Third-Party PDS
175- Sign in with a third-party PDS handle (e.g., `alice.geese.blue`)
176- Verify it resolves to the correct PDS
177- Test that API calls work correctly
178
179### 3. Test Session Management
180- Sign in and close the browser
181- Reopen and verify session is restored
182- Test sign out functionality
183
184### 4. Test API Calls
185- Verify profile loading works
186- Test creating posts
187- Test liking/unliking posts
188- Test following/unfollowing users
189
190## Rollback Plan
191
192If issues arise, you can quickly rollback:
193
1941. Revert the auth context import in `layout.tsx`
1952. Restore the original login/callback pages
1963. Keep the old implementation files until migration is stable
197
198The old API routes and implementation can remain in place during testing for safety.
199
200## Support
201
202If you encounter issues during migration:
2031. Check browser console for OAuth client errors
2042. Verify the client metadata URL is accessible
2053. Test with different handle types (Bluesky vs third-party)
2064. Check that the redirect URI matches exactly
207
208The new implementation should handle most edge cases that the custom implementation addressed, but with much less complexity.