@basictech/react 0.7.0 → 0.8.0-beta.1

package/src/AuthContext.tsx

@@ -1,23 +1,30 @@
 import React, { createContext, useContext, useEffect, useState, useRef } from 'react'
-import { jwtDecode } from 'jwt-decode'
 
 import { BasicSync, initDexieExtensions } from './sync'
 import { RemoteDB, DBMode, BasicDB } from './core/db'
+import { AuthManager } from './core/auth/AuthManager'
+import type { Token, User, AuthResult, GetTokenOptions, PdsEndpoints } from './core/auth/AuthManager'
 
 import { log } from './config'
 import { version as currentVersion } from '../package.json'
 import { createVersionUpdater } from './updater/versionUpdater'
 import { getMigrations } from './updater/updateMigrations'
-import { BasicStorage, LocalStorageAdapter, STORAGE_KEYS, getCookie, setCookie, clearCookie } from './utils/storage'
-import { isDevelopment, checkForNewVersion, cleanOAuthParamsFromUrl, getSyncStatus } from './utils/network'
-import { getSchemaStatus, validateAndCheckSchema } from './utils/schema'
+import { BasicStorage, LocalStorageAdapter, STORAGE_KEYS } from './utils/storage'
+import { isDevelopment, checkForNewVersion, getSyncStatus } from './utils/network'
+import { validateAndCheckSchema } from './utils/schema'
 
 export type { BasicStorage, LocalStorageAdapter } from './utils/storage'
 export type { DBMode, BasicDB, Collection } from './core/db'
+export type { Token, User, AuthResult, GetTokenOptions, PdsEndpoints }
 
 export type AuthConfig = {
     scopes?: string | string[];
+    /** @deprecated Use pds_url instead */
     server_url?: string;
+    /** PDS URL for auth and data (default: https://pds.basic.id) */
+    pds_url?: string;
+    /** Admin server URL for connect reporting (default: https://api.basic.tech) */
+    admin_url?: string;
     ws_url?: string;
 }
 
@@ -43,57 +50,23 @@ export type BasicProviderProps = {
 
 const DEFAULT_AUTH_CONFIG = {
     scopes: 'profile,email,app:admin',
-    server_url: 'https://api.basic.tech',
+    pds_url: 'https://pds.basic.id',
+    admin_url: 'https://api.basic.tech',
     ws_url: 'wss://pds.basic.id/ws'
 } as const
 
 
-type BasicSyncType = {
-    basic_schema: any;
-    connect: (options: { access_token: string; ws_url?: string }) => void;
-    debugeroo: () => void;
-    collection: (name: string) => {
-        ref: {
-            toArray: () => Promise<any[]>;
-            count: () => Promise<number>;
-        };
-    };
-    [key: string]: any;
-};
-
-
-enum DBStatus {
+export enum DBStatus {
     LOADING = "LOADING",
     OFFLINE = "OFFLINE",
     CONNECTING = "CONNECTING",
     ONLINE = "ONLINE",
     SYNCING = "SYNCING",
-    ERROR = "ERROR"
-}
-
-type User = {
-    name?: string,
-    email?: string,
-    id?: string,
-    primaryEmailAddress?: {
-        emailAddress: string
-    },
-    fullName?: string
-}
-type Token = {
-    access_token: string,
-    token_type: string,
-    expires_in: number,
-    refresh_token: string,
-}
-
-/**
- * Auth result type for signInWithCode
- */
-export type AuthResult = {
-    success: boolean;
-    error?: string;
-    code?: string;
+    ERROR = "ERROR",
+    /** Sync reported an error but will retry (e.g. expired token). Used for status code 4 from dexie-syncable. */
+    ERROR_WILL_RETRY = "ERROR_WILL_RETRY",
+    /** Token expired; the SDK is refreshing and will reconnect automatically. */
+    ERROR_TOKEN_EXPIRED = "ERROR_TOKEN_EXPIRED"
 }
 
 /**
@@ -104,21 +77,30 @@ export type BasicContextType = {
     isReady: boolean;
     isSignedIn: boolean;
     user: User | null;
-    
+    /** The user's DID (Decentralized Identifier), extracted from the access token `sub` claim */
+    did: string | null;
+    /** Space-separated scope string from the access token */
+    scope: string | null;
+    /** Check if a specific scope is granted (e.g., hasScope('profile')) */
+    hasScope: (scope: string) => boolean;
+    /** Returns scopes that were requested but not granted in the current token */
+    missingScopes: () => string[];
+
     // Auth actions (new camelCase naming)
     signIn: () => Promise<void>;
+    signInWithHandle: (handle: string) => Promise<void>;
     signOut: () => Promise<void>;
     signInWithCode: (code: string, state?: string) => Promise<AuthResult>;
-    
+
     // Token management
-    getToken: () => Promise<string>;
+    getToken: (options?: GetTokenOptions) => Promise<string>;
     getSignInUrl: (redirectUri?: string) => Promise<string>;
-    
+
     // DB access
     db: BasicDB;
     dbStatus: DBStatus;
     dbMode: DBMode;
-    
+
     // Legacy aliases (deprecated - will be removed in future version)
     /** @deprecated Use isReady instead */
     isAuthReady: boolean;
@@ -143,21 +125,26 @@ export const BasicContext = createContext<BasicContextType>({
     isReady: false,
     isSignedIn: false,
     user: null,
-    
+    did: null,
+    scope: null,
+    hasScope: () => false,
+    missingScopes: () => [],
+
     // Auth actions
     signIn: () => Promise.resolve(),
+    signInWithHandle: () => Promise.resolve(),
     signOut: () => Promise.resolve(),
     signInWithCode: () => Promise.resolve({ success: false }),
-    
+
     // Token management
-    getToken: () => Promise.reject(new Error('no token')),
+    getToken: (_options?: GetTokenOptions) => Promise.reject(new Error('no token')),
     getSignInUrl: () => Promise.resolve(""),
-    
+
     // DB access
     db: noDb,
     dbStatus: DBStatus.LOADING,
     dbMode: 'sync',
-    
+
     // Legacy aliases
     isAuthReady: false,
     signin: () => Promise.resolve(),
@@ -172,6 +159,27 @@ type ErrorObject = {
     message: string;
 }
 
+// Tracks the subset of AuthManager state that React effects depend on.
+type AuthSnapshot = {
+    isSignedIn: boolean
+    hasToken: boolean
+    isAuthReady: boolean
+    user: User | null
+    did: string | null
+    tokenScope: string | null
+}
+
+function snapshotAuth(mgr: AuthManager): AuthSnapshot {
+    return {
+        isSignedIn: mgr.isSignedIn,
+        hasToken: !!mgr.token,
+        isAuthReady: mgr.isAuthReady,
+        user: mgr.user,
+        did: mgr.did,
+        tokenScope: mgr.tokenScope,
+    }
+}
+
 export function BasicProvider({
     children,
     project_id: project_id_prop,
@@ -181,88 +189,103 @@ export function BasicProvider({
     auth,
     dbMode = 'sync'
 }: BasicProviderProps) {
-    // Extract project_id from schema, fall back to prop for backward compatibility
     const project_id = schema?.project_id || project_id_prop
-    
-    const [isAuthReady, setIsAuthReady] = useState(false)
-    const [isSignedIn, setIsSignedIn] = useState<boolean>(false)
-    const [token, setToken] = useState<Token | null>(null)
-    const [user, setUser] = useState<User>({})
-    const [shouldConnect, setShouldConnect] = useState<boolean>(false)
-    const [isReady, setIsReady] = useState<boolean>(false)
 
-    const [dbStatus, setDbStatus] = useState<DBStatus>(DBStatus.OFFLINE)
-    const [error, setError] = useState<ErrorObject | null>(null)
-    const [isOnline, setIsOnline] = useState<boolean>(navigator.onLine)
-    const [pendingRefresh, setPendingRefresh] = useState<boolean>(false)
-
-    const syncRef = useRef<BasicSync | null>(null);
-    const remoteDbRef = useRef<RemoteDB | null>(null);
-    const storageAdapter = storage || new LocalStorageAdapter();
-    
-    // Merge auth config with defaults
+    // Merge auth config with defaults (server_url is deprecated in favor of pds_url)
+    if (auth?.server_url && !auth?.pds_url) {
+        log('Warning: auth.server_url is deprecated, use auth.pds_url instead')
+    }
     const authConfig = {
         scopes: auth?.scopes || DEFAULT_AUTH_CONFIG.scopes,
-        server_url: auth?.server_url || DEFAULT_AUTH_CONFIG.server_url,
+        pds_url: auth?.pds_url || auth?.server_url || DEFAULT_AUTH_CONFIG.pds_url,
+        admin_url: auth?.admin_url || DEFAULT_AUTH_CONFIG.admin_url,
         ws_url: auth?.ws_url || DEFAULT_AUTH_CONFIG.ws_url
     }
-    
-    // Normalize scopes to space-separated string
-    const scopesString = Array.isArray(authConfig.scopes) 
-        ? authConfig.scopes.join(' ') 
-        : authConfig.scopes;
 
-    // Token refresh mutex to prevent concurrent refreshes
-    const refreshPromiseRef = useRef<Promise<Token | null> | null>(null);
+    const scopesString = Array.isArray(authConfig.scopes)
+        ? authConfig.scopes.join(' ')
+        : authConfig.scopes
+
+    const storageRef = useRef<BasicStorage>(storage || new LocalStorageAdapter())
+    const storageAdapter = storageRef.current
+
+    // --- AuthManager (stable instance held in a ref) ---
+    const [authState, setAuthState] = useState<AuthSnapshot>({
+        isSignedIn: false,
+        hasToken: false,
+        isAuthReady: false,
+        user: null,
+        did: null,
+        tokenScope: null,
+    })
+
+    const authRef = useRef<AuthManager>(null!)
+    if (!authRef.current) {
+        authRef.current = new AuthManager(
+            {
+                projectId: project_id,
+                scopes: scopesString,
+                pdsUrl: authConfig.pds_url,
+                adminUrl: authConfig.admin_url,
+                debug,
+            },
+            storageAdapter,
+            () => setAuthState(snapshotAuth(authRef.current)),
+        )
+    }
 
-    const isDevMode = () => isDevelopment(debug)
+    // --- DB state (stays in React) ---
+    const syncRef = useRef<BasicSync | null>(null)
+    const remoteDbRef = useRef<RemoteDB | null>(null)
+    const [shouldConnect, setShouldConnect] = useState(false)
+    const [dbStatus, setDbStatus] = useState<DBStatus>(DBStatus.OFFLINE)
+    const [isReady, setIsReady] = useState(false)
+    const [error, setError] = useState<ErrorObject | null>(null)
 
-    const cleanOAuthParams = () => cleanOAuthParamsFromUrl()
+    const isDevMode = () => isDevelopment(debug)
 
+    // --- Mount: version updater + auth init + DB init ---
     useEffect(() => {
-        const handleOnline = () => {
-            log('Network came back online')
-            setIsOnline(true)
-            if (pendingRefresh) {
-                log('Retrying pending token refresh')
-                setPendingRefresh(false)
-                if (token) {
-                    const refreshToken = token.refresh_token || localStorage.getItem('basic_refresh_token')
-                    if (refreshToken) {
-                        fetchToken(refreshToken, true).catch(error => {
-                            log('Retry refresh failed:', error)
-                        })
-                    }
+        // Version updater (SDK migration, not auth-related)
+        const runVersionUpdater = async () => {
+            try {
+                const versionUpdater = createVersionUpdater(storageAdapter, currentVersion, getMigrations())
+                const updateResult = await versionUpdater.checkAndUpdate()
+
+                if (updateResult.updated) {
+                    log(`App updated from ${updateResult.fromVersion} to ${updateResult.toVersion}`)
+                } else {
+                    log(`App version ${updateResult.toVersion} is current`)
                 }
+            } catch (error) {
+                log('Version update failed:', error)
             }
         }
 
-        const handleOffline = () => {
-            log('Network went offline')
-            setIsOnline(false)
-        }
-
-        window.addEventListener('online', handleOnline)
-        window.addEventListener('offline', handleOffline)
+        runVersionUpdater()
+        authRef.current.initialize()
 
-        return () => {
-            window.removeEventListener('online', handleOnline)
-            window.removeEventListener('offline', handleOffline)
-        }
-    }, [pendingRefresh, token])
+        return authRef.current.setupNetworkListeners()
+    }, [])
 
+    // --- DB init (separate mount effect) ---
     useEffect(() => {
         async function initSyncDb(options: { shouldConnect: boolean }) {
             if (!syncRef.current) {
                 log('Initializing Basic Sync DB')
-                
-                // Initialize Dexie extensions before creating BasicSync
+
                 await initDexieExtensions()
-                
+
                 syncRef.current = new BasicSync('basicdb', { schema: schema });
 
-                syncRef.current.syncable.on('statusChanged', (status: number, url: string) => {
-                    setDbStatus(getSyncStatus(status) as DBStatus)
+                syncRef.current.syncable.on('statusChanged', (status: number) => {
+                    const newStatus = getSyncStatus(status) as DBStatus
+                    setDbStatus(newStatus)
+
+                    if (newStatus === DBStatus.ERROR_WILL_RETRY) {
+                        log('Sync entered ERROR_WILL_RETRY - proactively refreshing token')
+                        authRef.current.getToken({ forceRefresh: true }).catch(() => {})
+                    }
                 })
 
                 if (options.shouldConnect) {
@@ -289,15 +312,14 @@ export function BasicProvider({
 
                 log('Initializing Basic Remote DB')
                 remoteDbRef.current = new RemoteDB({
-                    serverUrl: authConfig.server_url,
+                    serverUrl: authConfig.pds_url,
                     projectId: project_id,
-                    getToken: getToken,
+                    getToken: (opts) => authRef.current.getToken(opts),
                     schema: schema,
                     debug: debug,
                     onAuthError: (error) => {
                         log('RemoteDB auth error:', error)
-                        // Sign out user when authentication fails after retry
-                        signout()
+                        handleSignOut()
                     }
                 })
                 setDbStatus(DBStatus.ONLINE)
@@ -311,7 +333,7 @@ export function BasicProvider({
             if (!result.isValid) {
                 let errorMessage = ''
                 if (result.errors) {
-                    result.errors.forEach((error, index) => {
+                    result.errors.forEach((error: any, index: number) => {
                         errorMessage += `${index + 1}: ${error.message} - at ${error.instancePath}\n`
                     })
                 }
@@ -324,15 +346,17 @@ export function BasicProvider({
                 return null
             }
 
-            // Initialize the appropriate DB based on mode
             if (dbMode === 'remote') {
                 initRemoteDb()
             } else {
-                // Sync mode
                 if (result.schemaStatus.valid) {
                     await initSyncDb({ shouldConnect: true })
                 } else {
-                    log('Schema is invalid!', result.schemaStatus)
+                    if (result.schemaStatus.status === 'unpublished') {
+                        log('Schema not published yet (version 0) - sync is disabled. Publish your schema to enable sync.')
+                    } else {
+                        log('Schema is invalid!', result.schemaStatus)
+                    }
                     await initSyncDb({ shouldConnect: false })
                 }
             }
@@ -343,7 +367,6 @@ export function BasicProvider({
         if (schema) {
             checkSchema()
         } else {
-            // No schema - still initialize remote DB if in remote mode
             if (dbMode === 'remote' && project_id) {
                 initRemoteDb()
             } else {
@@ -352,270 +375,41 @@ export function BasicProvider({
         }
     }, []);
 
+    // --- Connect sync DB when auth is ready ---
     useEffect(() => {
-        async function connectToDb() {
-            if (token && syncRef.current && isSignedIn && shouldConnect) {
-                const tok = await getToken()
-                if (!tok) {
-                    log('no token found')
-                    return
-                }
+        if (authState.hasToken && syncRef.current && authState.isSignedIn && shouldConnect) {
+            log('connecting to db...')
 
-                log('connecting to db...')
-
-                syncRef.current?.connect({ 
-                    access_token: tok,
-                    ws_url: authConfig.ws_url 
+            syncRef.current?.connect({
+                getToken: (opts?: GetTokenOptions) => authRef.current.getToken(opts),
+                ws_url: authConfig.ws_url
+            })
+                .catch((e: any) => {
+                    log('error connecting to db', e)
                 })
-                    .catch((e) => {
-                        log('error connecting to db', e)
-                    })
-            }
         }
-        connectToDb()
-
-    }, [isSignedIn, shouldConnect])
+    }, [authState.isSignedIn, authState.hasToken, shouldConnect])
 
-    useEffect(() => {
-        const initializeAuth = async () => {
-            await storageAdapter.set(STORAGE_KEYS.DEBUG, debug ? 'true' : 'false')
-
-            // Check if server URL has changed - if so, clear tokens
-            const storedServerUrl = await storageAdapter.get(STORAGE_KEYS.SERVER_URL)
-            if (storedServerUrl && storedServerUrl !== authConfig.server_url) {
-                log('Server URL changed, clearing stored tokens')
-                await storageAdapter.remove(STORAGE_KEYS.REFRESH_TOKEN)
-                await storageAdapter.remove(STORAGE_KEYS.USER_INFO)
-                await storageAdapter.remove(STORAGE_KEYS.AUTH_STATE)
-                await storageAdapter.remove(STORAGE_KEYS.REDIRECT_URI)
-                clearCookie('basic_token')
-                clearCookie('basic_access_token')
-            }
-            await storageAdapter.set(STORAGE_KEYS.SERVER_URL, authConfig.server_url)
-
-            try {
-                const versionUpdater = createVersionUpdater(storageAdapter, currentVersion, getMigrations())
-                const updateResult = await versionUpdater.checkAndUpdate()
-
-                if (updateResult.updated) {
-                    log(`App updated from ${updateResult.fromVersion} to ${updateResult.toVersion}`)
-                } else {
-                    log(`App version ${updateResult.toVersion} is current`)
-                }
-            } catch (error) {
-                log('Version update failed:', error)
-            }
-
-            try {
-                if (window.location.search.includes('code')) {
-                    let code = window.location?.search?.split('code=')[1]?.split('&')[0]
-                    if (!code) return
-
-                    const state = await storageAdapter.get(STORAGE_KEYS.AUTH_STATE)
-                    const urlState = window.location.search.split('state=')[1]?.split('&')[0]
-                    if (!state || state !== urlState) {
-                        log('error: auth state does not match')
-                        setIsAuthReady(true)
-
-                        await storageAdapter.remove(STORAGE_KEYS.AUTH_STATE)
-                        cleanOAuthParams()
-                        return
-                    }
-
-                    await storageAdapter.remove(STORAGE_KEYS.AUTH_STATE)
-                    cleanOAuthParams()
-
-                    fetchToken(code, false).catch((error) => {
-                        log('Error fetching token:', error)
-                    })
-                } else {
-                    const refreshToken = await storageAdapter.get(STORAGE_KEYS.REFRESH_TOKEN)
-                    if (refreshToken) {
-                        log('Found refresh token in storage, attempting to refresh access token')
-                        fetchToken(refreshToken, true).catch((error) => {
-                            log('Error fetching refresh token:', error)
-                        })
-                    } else {
-                        let cookie_token = getCookie('basic_token')
-                        if (cookie_token !== '') {
-                            const tokenData = JSON.parse(cookie_token)
-                            setToken(tokenData)
-                            if (tokenData.refresh_token) {
-                                await storageAdapter.set(STORAGE_KEYS.REFRESH_TOKEN, tokenData.refresh_token)
-                            }
-                        } else {
-                            const cachedUserInfo = await storageAdapter.get(STORAGE_KEYS.USER_INFO)
-                            if (cachedUserInfo) {
-                                try {
-                                    const userData = JSON.parse(cachedUserInfo)
-                                    setUser(userData)
-                                    setIsSignedIn(true)
-                                    log('Loaded cached user info for offline mode')
-                                } catch (error) {
-                                    log('Error parsing cached user info:', error)
-                                }
-                            }
-                            setIsAuthReady(true)
-                        }
-                    }
-                }
-
-            } catch (e) {
-                log('error getting token', e)
-            }
-        }
-
-        initializeAuth()
-    }, [])
-
-    useEffect(() => {
-        async function fetchUser(acc_token: string) {
-            console.info('fetching user')
+    // --- Sign out (auth cleanup + sync teardown) ---
+    const handleSignOut = async () => {
+        await authRef.current.signOut()
+        if (syncRef.current) {
             try {
-                const response = await fetch(`${authConfig.server_url}/auth/userInfo`, {
-                    method: 'GET',
-                    headers: {
-                        'Authorization': `Bearer ${acc_token}`
-                    }
-                })
-
-                if (!response.ok) {
-                    throw new Error(`Failed to fetch user info: ${response.status}`)
-                }
-
-                const user = await response.json()
-
-                if (user.error) {
-                    log('error fetching user', user.error)
-                    throw new Error(`User info error: ${user.error}`)
-                }
-
-                if (token?.refresh_token) {
-                    await storageAdapter.set(STORAGE_KEYS.REFRESH_TOKEN, token.refresh_token)
-                }
-
-                await storageAdapter.set(STORAGE_KEYS.USER_INFO, JSON.stringify(user))
-                log('Cached user info in storage')
-
-                setCookie('basic_access_token', token?.access_token || '', { httpOnly: false });
-                setCookie('basic_token', JSON.stringify(token));
-
-                setUser(user)
-                setIsSignedIn(true)
-                setIsAuthReady(true)
+                await syncRef.current.close()
+                await syncRef.current.delete({ disableAutoOpen: false })
+                syncRef.current = null
+                window?.location?.reload()
             } catch (error) {
-                log('Failed to fetch user info:', error)
-                // Don't clear tokens here - may be temporary network issue
-                setIsAuthReady(true)
-            }
-        }
-
-        async function checkToken() {
-            if (!token) {
-                log('error: no user token found')
-
-                setIsAuthReady(true)
-                return
-            }
-
-            const decoded = jwtDecode(token?.access_token)
-            // Add 5 second buffer to prevent edge cases
-            const expirationBuffer = 5
-            const isExpired = decoded.exp && decoded.exp < (Date.now() / 1000) + expirationBuffer
-
-            if (isExpired) {
-                log('token is expired - refreshing ...')
-                const refreshToken = token?.refresh_token
-                if (!refreshToken) {
-                    log('Error: No refresh token available for expired token')
-                    setIsAuthReady(true)
-                    return
-                }
-                try {
-                    const newToken = await fetchToken(refreshToken, true)
-                    fetchUser(newToken?.access_token || '')
-                } catch (error) {
-                    log('Failed to refresh token in checkToken:', error)
-
-                    if ((error as Error).message.includes('offline') || (error as Error).message.includes('Network')) {
-                        log('Network issue - continuing with expired token until online')
-                        fetchUser(token?.access_token || '')
-                    } else {
-                        setIsAuthReady(true)
-                    }
-                }
-            } else {
-                fetchUser(token?.access_token || '')
+                console.error('Error during database cleanup:', error)
             }
         }
-
-        if (token) {
-            checkToken()
-        }
-    }, [token])
-
-    const getSignInLink = async (redirectUri?: string) => {
-        try {
-            log('getting sign in link...')
-
-            if (!project_id) {
-                throw new Error('Project ID is required to generate sign-in link')
-            }
-
-            const randomState = Math.random().toString(36).substring(6);
-            await storageAdapter.set(STORAGE_KEYS.AUTH_STATE, randomState)
-
-            const redirectUrl = redirectUri || window.location.href
-
-            if (!redirectUrl || (!redirectUrl.startsWith('http://') && !redirectUrl.startsWith('https://'))) {
-                throw new Error('Invalid redirect URI provided')
-            }
-
-            // Store redirect_uri for token exchange
-            await storageAdapter.set(STORAGE_KEYS.REDIRECT_URI, redirectUrl)
-            log('Stored redirect_uri for token exchange:', redirectUrl)
-
-            let baseUrl = `${authConfig.server_url}/auth/authorize`
-            baseUrl += `?client_id=${project_id}`
-            baseUrl += `&redirect_uri=${encodeURIComponent(redirectUrl)}`
-            baseUrl += `&response_type=code`
-            baseUrl += `&scope=${encodeURIComponent(scopesString)}`
-            baseUrl += `&state=${randomState}`
-
-            log('Generated sign-in link successfully with scopes:', scopesString)
-            return baseUrl;
-
-        } catch (error) {
-            log('Error generating sign-in link:', error)
-            throw error
-        }
     }
 
-    const signin = async () => {
+    // --- Sign in wrappers (add dev-mode error display) ---
+    const handleSignIn = async () => {
         try {
-            log('signing in...')
-
-            if (!project_id) {
-                log('Error: project_id is required for sign-in')
-                throw new Error('Project ID is required for authentication')
-            }
-
-            const signInLink = await getSignInLink()
-            log('Generated sign-in link:', signInLink)
-
-            // Validate URL format (supports https://, http://, and custom URI schemes)
-            try {
-                new URL(signInLink)
-            } catch {
-                log('Error: Invalid sign-in link generated')
-                throw new Error('Failed to generate valid sign-in URL')
-            }
-
-            window.location.href = signInLink
-
+            await authRef.current.signIn()
         } catch (error) {
-            log('Error during sign-in:', error)
-
             if (isDevMode()) {
                 setError({
                     code: 'signin_error',
@@ -623,325 +417,26 @@ export function BasicProvider({
                     message: (error as Error).message || 'An error occurred during sign-in. Please try again.'
                 })
             }
-
             throw error
         }
     }
 
-    const signinWithCode = async (code: string, state?: string): Promise<{ success: boolean, error?: string }> => {
+    const handleSignInWithHandle = async (handle: string) => {
         try {
-            log('signinWithCode called with code:', code)
-
-            if (!code || typeof code !== 'string') {
-                return { success: false, error: 'Invalid authorization code' }
-            }
-
-            if (state) {
-                const storedState = await storageAdapter.get(STORAGE_KEYS.AUTH_STATE)
-                if (storedState && storedState !== state) {
-                    log('State parameter mismatch:', { provided: state, stored: storedState })
-                    return { success: false, error: 'State parameter mismatch' }
-                }
-            }
-
-            await storageAdapter.remove(STORAGE_KEYS.AUTH_STATE)
-            cleanOAuthParams()
-
-            const token = await fetchToken(code, false)
-
-            if (token) {
-                log('signinWithCode successful')
-                return { success: true }
-            } else {
-                return { success: false, error: 'Failed to exchange code for token' }
-            }
+            await authRef.current.signInWithHandle(handle)
         } catch (error) {
-            log('signinWithCode error:', error)
-            return {
-                success: false,
-                error: (error as Error).message || 'Authentication failed'
-            }
-        }
-    }
-
-    const signout = async () => {
-        log('signing out!')
-        setUser({})
-        setIsSignedIn(false)
-        setToken(null)
-
-        clearCookie('basic_token');
-        clearCookie('basic_access_token');
-        await storageAdapter.remove(STORAGE_KEYS.AUTH_STATE)
-        await storageAdapter.remove(STORAGE_KEYS.REFRESH_TOKEN)
-        await storageAdapter.remove(STORAGE_KEYS.USER_INFO)
-        await storageAdapter.remove(STORAGE_KEYS.REDIRECT_URI)
-        await storageAdapter.remove(STORAGE_KEYS.SERVER_URL)
-        if (syncRef.current) {
-            (async () => {
-                try {
-                    await syncRef.current?.close()
-                    await syncRef.current?.delete({ disableAutoOpen: false })
-                    syncRef.current = null
-                    window?.location?.reload()
-                } catch (error) {
-                    console.error('Error during database cleanup:', error)
-                }
-            })()
-        }
-    }
-
-    const getToken = async (): Promise<string> => {
-        log('getting token...')
-
-        if (!token) {
-            // Try to recover from storage refresh token
-            const refreshToken = await storageAdapter.get(STORAGE_KEYS.REFRESH_TOKEN)
-            if (refreshToken) {
-                log('No token in memory, attempting to refresh from storage')
-                
-                // Check if refresh is already in progress
-                if (refreshPromiseRef.current) {
-                    log('Token refresh already in progress, waiting...')
-                    try {
-                        const newToken = await refreshPromiseRef.current
-                        if (newToken?.access_token) {
-                            return newToken.access_token
-                        }
-                    } catch (error) {
-                        log('In-flight refresh failed:', error)
-                        throw error
-                    }
-                }
-                
-                try {
-                    const newToken = await fetchToken(refreshToken, true)
-                    if (newToken?.access_token) {
-                        return newToken.access_token
-                    }
-                } catch (error) {
-                    log('Failed to refresh token from storage:', error)
-
-                    if ((error as Error).message.includes('offline') || (error as Error).message.includes('Network')) {
-                        log('Network issue - continuing with potentially expired token')
-                        const lastToken = localStorage.getItem('basic_access_token')
-                        if (lastToken) {
-                            return lastToken
-                        }
-                        throw new Error('Network offline - authentication will be retried when online')
-                    }
-
-                    throw new Error('Authentication expired. Please sign in again.')
-                }
-            }
-            log('no token found')
-            throw new Error('no token found')
-        }
-
-        const decoded = jwtDecode(token?.access_token)
-        // Add 5 second buffer to prevent edge cases where token expires during request
-        const expirationBuffer = 5
-        const isExpired = decoded.exp && decoded.exp < (Date.now() / 1000) + expirationBuffer
-
-        if (isExpired) {
-            log('token is expired - refreshing ...')
-            
-            // Check if refresh is already in progress
-            if (refreshPromiseRef.current) {
-                log('Token refresh already in progress, waiting...')
-                try {
-                    const newToken = await refreshPromiseRef.current
-                    return newToken?.access_token || ''
-                } catch (error) {
-                    log('In-flight refresh failed:', error)
-                    
-                    if ((error as Error).message.includes('offline') || (error as Error).message.includes('Network')) {
-                        log('Network issue - using expired token until network is restored')
-                        return token.access_token
-                    }
-                    
-                    throw error
-                }
-            }
-            
-            const refreshToken = token?.refresh_token || await storageAdapter.get(STORAGE_KEYS.REFRESH_TOKEN)
-            if (refreshToken) {
-                try {
-                    const newToken = await fetchToken(refreshToken, true)
-                    return newToken?.access_token || ''
-                } catch (error) {
-                    log('Failed to refresh expired token:', error)
-
-                    if ((error as Error).message.includes('offline') || (error as Error).message.includes('Network')) {
-                        log('Network issue - using expired token until network is restored')
-                        return token.access_token
-                    }
-
-                    throw new Error('Authentication expired. Please sign in again.')
-                }
-            } else {
-                throw new Error('no refresh token available')
-            }
-        }
-
-        return token?.access_token || ''
-    }
-
-    const fetchToken = async (codeOrRefreshToken: string, isRefreshToken: boolean = false): Promise<Token | null> => {
-        // Validate input
-        if (!codeOrRefreshToken || codeOrRefreshToken.trim() === '') {
-            const errorMsg = isRefreshToken ? 'Refresh token is empty or undefined' : 'Authorization code is empty or undefined'
-            log('Error:', errorMsg)
-            throw new Error(errorMsg)
-        }
-
-        // If this is a refresh token request and one is already in progress, return that promise
-        if (isRefreshToken && refreshPromiseRef.current) {
-            log('Reusing in-flight refresh token request')
-            return refreshPromiseRef.current
-        }
-
-        // Create new promise for this refresh attempt
-        const refreshPromise = (async (): Promise<Token | null> => {
-            try {
-                if (!isOnline) {
-                    log('Network is offline, marking refresh as pending')
-                    setPendingRefresh(true)
-                    throw new Error('Network offline - refresh will be retried when online')
-                }
-
-                let requestBody: any
-
-                if (isRefreshToken) {
-                    // Refresh token request
-                    requestBody = { 
-                        grant_type: 'refresh_token',
-                        refresh_token: codeOrRefreshToken
-                    }
-                    // Include client_id if available for validation
-                    if (project_id) {
-                        requestBody.client_id = project_id
-                    }
-                } else {
-                    // Authorization code exchange
-                    requestBody = { 
-                        grant_type: 'authorization_code',
-                        code: codeOrRefreshToken
-                    }
-                    
-                    // Retrieve stored redirect_uri (required by OAuth2 spec)
-                    const storedRedirectUri = await storageAdapter.get(STORAGE_KEYS.REDIRECT_URI)
-                    if (storedRedirectUri) {
-                        requestBody.redirect_uri = storedRedirectUri
-                        log('Including redirect_uri in token exchange:', storedRedirectUri)
-                    } else {
-                        log('Warning: No redirect_uri found in storage for token exchange')
-                    }
-                    
-                    // Include client_id for validation
-                    if (project_id) {
-                        requestBody.client_id = project_id
-                    }
-                }
-
-                log('Token exchange request body:', { ...requestBody, refresh_token: isRefreshToken ? '[REDACTED]' : undefined, code: !isRefreshToken ? '[REDACTED]' : undefined })
-
-                const token = await fetch(`${authConfig.server_url}/auth/token`, {
-                    method: 'POST',
-                    headers: {
-                        'Content-Type': 'application/json'
-                    },
-                    body: JSON.stringify(requestBody)
+            if (isDevMode()) {
+                setError({
+                    code: 'signin_error',
+                    title: 'Sign-in Failed',
+                    message: (error as Error).message || 'An error occurred during sign-in. Please try again.'
                 })
-                    .then(response => response.json())
-                    .catch(error => {
-                        log('Network error fetching token:', error)
-                        if (!isOnline) {
-                            setPendingRefresh(true)
-                            throw new Error('Network offline - refresh will be retried when online')
-                        }
-                        throw new Error('Network error during token refresh')
-                    })
-
-                if (token.error) {
-                    log('error fetching token', token.error)
-
-                    if (token.error.includes('network') || token.error.includes('timeout')) {
-                        setPendingRefresh(true)
-                        throw new Error('Network issue - refresh will be retried when online')
-                    }
-
-                    await storageAdapter.remove(STORAGE_KEYS.REFRESH_TOKEN)
-                    await storageAdapter.remove(STORAGE_KEYS.USER_INFO)
-                    await storageAdapter.remove(STORAGE_KEYS.REDIRECT_URI)
-                    await storageAdapter.remove(STORAGE_KEYS.SERVER_URL)
-                    clearCookie('basic_token');
-                    clearCookie('basic_access_token');
-
-                    setUser({})
-                    setIsSignedIn(false)
-                    setToken(null)
-                    setIsAuthReady(true)
-
-                    throw new Error(`Token refresh failed: ${token.error}`)
-                } else {
-                    setToken(token)
-                    setPendingRefresh(false)
-
-                    if (token.refresh_token) {
-                        await storageAdapter.set(STORAGE_KEYS.REFRESH_TOKEN, token.refresh_token)
-                        log('Updated refresh token in storage')
-                    }
-
-                    // Clean up redirect_uri after successful token exchange
-                    if (!isRefreshToken) {
-                        await storageAdapter.remove(STORAGE_KEYS.REDIRECT_URI)
-                        log('Cleaned up redirect_uri from storage after successful exchange')
-                    }
-
-                    setCookie('basic_access_token', token.access_token, { httpOnly: false });
-                    setCookie('basic_token', JSON.stringify(token));
-                    log('Updated access token and full token in cookies')
-                }
-                return token
-            } catch (error) {
-                log('Token refresh error:', error)
-
-                if (!(error as Error).message.includes('offline') && !(error as Error).message.includes('Network')) {
-                    await storageAdapter.remove(STORAGE_KEYS.REFRESH_TOKEN)
-                    await storageAdapter.remove(STORAGE_KEYS.USER_INFO)
-                    await storageAdapter.remove(STORAGE_KEYS.REDIRECT_URI)
-                    await storageAdapter.remove(STORAGE_KEYS.SERVER_URL)
-                    clearCookie('basic_token');
-                    clearCookie('basic_access_token');
-
-                    setUser({})
-                    setIsSignedIn(false)
-                    setToken(null)
-                    setIsAuthReady(true)
-                }
-
-                throw error
             }
-        })()
-
-        // Store promise if this is a refresh token request
-        if (isRefreshToken) {
-            refreshPromiseRef.current = refreshPromise
-            
-            // Clear the promise reference when done (success or failure)
-            refreshPromise.finally(() => {
-                if (refreshPromiseRef.current === refreshPromise) {
-                    refreshPromiseRef.current = null
-                    log('Cleared refresh promise reference')
-                }
-            })
+            throw error
         }
-
-        return refreshPromise
     }
 
-    // Get the current DB instance based on mode
+    // --- DB accessor ---
     const getCurrentDb = (): BasicDB => {
         if (dbMode === 'remote') {
             return remoteDbRef.current || noDb
@@ -949,33 +444,38 @@ export function BasicProvider({
         return syncRef.current || noDb
     }
 
-    // Create context value with new names and legacy aliases
+    // --- Context value ---
     const contextValue: BasicContextType = {
-        // Auth state (new naming)
-        isReady: isAuthReady,
-        isSignedIn,
-        user,
-        
-        // Auth actions (new camelCase naming)
-        signIn: signin,
-        signOut: signout,
-        signInWithCode: signinWithCode,
-        
+        // Auth state
+        isReady: authState.isAuthReady,
+        isSignedIn: authState.isSignedIn,
+        user: authState.user,
+        did: authState.did,
+        scope: authState.tokenScope,
+        hasScope: (scope: string) => authRef.current.hasScope(scope),
+        missingScopes: () => authRef.current.missingScopes(),
+
+        // Auth actions
+        signIn: handleSignIn,
+        signInWithHandle: handleSignInWithHandle,
+        signOut: handleSignOut,
+        signInWithCode: (code: string, state?: string) => authRef.current.signInWithCode(code, state),
+
         // Token management
-        getToken,
-        getSignInUrl: getSignInLink,
-        
+        getToken: (opts?: GetTokenOptions) => authRef.current.getToken(opts),
+        getSignInUrl: (redirectUri?: string) => authRef.current.getSignInUrl(redirectUri),
+
         // DB access
         db: getCurrentDb(),
         dbStatus,
         dbMode,
-        
+
         // Legacy aliases (deprecated)
-        isAuthReady,
-        signin,
-        signout,
-        signinWithCode,
-        getSignInLink,
+        isAuthReady: authState.isAuthReady,
+        signin: handleSignIn,
+        signout: handleSignOut,
+        signinWithCode: (code: string, state?: string) => authRef.current.signInWithCode(code, state),
+        getSignInLink: (redirectUri?: string) => authRef.current.getSignInUrl(redirectUri),
     }
 
     return (