@basictech/react 0.8.0-beta.2 → 0.8.0-beta.4

package/src/core/auth/AuthManager.ts

@@ -5,70 +5,137 @@ import { resolveHandle } from '../../utils/resolveDid'
 import { cleanOAuthParamsFromUrl } from '../../utils/network'
 import { log } from '../../config'
 
+const DEFINITIVE_TOKEN_ERRORS = new Set([
+  'invalid_grant',
+  'invalid_client',
+  'unauthorized_client',
+])
+const USER_RECOVERY_RETRY_COOLDOWN_MS = 30_000
+const SESSION_RECONCILE_THROTTLE_MS = 5_000
+
+class DefinitiveAuthError extends Error {
+  readonly code: string
+
+  constructor(code: string) {
+    super(`Definitive auth failure: ${code}`)
+    this.name = 'DefinitiveAuthError'
+    this.code = code
+  }
+}
+
 // --- PKCE helpers (RFC 7636) ---
 
 function generateCodeVerifier(): string {
-    const array = new Uint8Array(32)
-    crypto.getRandomValues(array)
-    return base64UrlEncode(array)
+  const array = new Uint8Array(32)
+  crypto.getRandomValues(array)
+  return base64UrlEncode(array)
 }
 
-async function generateCodeChallenge(verifier: string): Promise<{ challenge: string; method: 'S256' | 'plain' }> {
-    if (typeof crypto === 'undefined' || !crypto.subtle) {
-        log('crypto.subtle unavailable (non-secure context?) -- falling back to plain PKCE challenge')
-        return { challenge: verifier, method: 'plain' }
-    }
-    const encoder = new TextEncoder()
-    const data = encoder.encode(verifier)
-    const digest = await crypto.subtle.digest('SHA-256', data)
-    return { challenge: base64UrlEncode(new Uint8Array(digest)), method: 'S256' }
+async function generateCodeChallenge(
+  verifier: string,
+): Promise<{ challenge: string; method: 'S256' | 'plain' }> {
+  if (typeof crypto === 'undefined' || !crypto.subtle) {
+    log(
+      'crypto.subtle unavailable (non-secure context?) -- falling back to plain PKCE challenge',
+    )
+    return { challenge: verifier, method: 'plain' }
+  }
+  const encoder = new TextEncoder()
+  const data = encoder.encode(verifier)
+  const digest = await crypto.subtle.digest('SHA-256', data)
+  return { challenge: base64UrlEncode(new Uint8Array(digest)), method: 'S256' }
 }
 
 function base64UrlEncode(buffer: Uint8Array): string {
-    let str = ''
-    for (let i = 0; i < buffer.length; i++) {
-        str += String.fromCharCode(buffer[i]!)
-    }
-    return btoa(str).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+  let str = ''
+  for (let i = 0; i < buffer.length; i++) {
+    str += String.fromCharCode(buffer[i]!)
+  }
+  return btoa(str).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
 }
 
 export type Token = {
-    access_token: string
-    token_type: string
-    expires_in: number
-    refresh_token: string
+  access_token: string
+  token_type: string
+  expires_in: number
+  refresh_token: string
 }
 
 export type User = {
-    sub?: string
-    name?: string
-    email?: string
-    picture?: string
+  sub?: string
+  name?: string
+  email?: string
+  picture?: string
 }
 
+/**
+ * High-level auth lifecycle state.
+ *
+ * - `bootstrapping` — SDK is initializing; not yet determined if a session exists.
+ * - `authenticated` — User has a valid access token and active session.
+ * - `recovering`    — A session likely exists (refresh token / cached user) but
+ *                     the SDK hasn't confirmed it yet (e.g. offline, mid-refresh).
+ * - `reauth_required` — The session is definitively invalid (revoked, expired
+ *                     refresh token, etc.). The user must sign in again.
+ *                     NOTE: `isSignedIn` remains `true` in this state so the UI
+ *                     can display user info while prompting re-authentication.
+ *                     Use `authStatus === 'reauth_required'` to distinguish
+ *                     this from a healthy signed-in state.
+ * - `signed_out`    — No session. User is not authenticated.
+ *
+ * TODO: revisit naming and ergonomics — consider adding a `needsReauth` or
+ * `shouldPromptSignIn` convenience getter so consumers don't need to inspect
+ * the raw status to decide between "sign in" vs "sign out" UI.
+ */
+export type AuthStatus =
+  | 'bootstrapping'
+  | 'authenticated'
+  | 'recovering'
+  | 'reauth_required'
+  | 'signed_out'
+
 export type AuthResult = {
-    success: boolean
-    error?: string
-    code?: string
+  success: boolean
+  error?: string
+  code?: string
 }
 
 export type GetTokenOptions = {
-    forceRefresh?: boolean
+  forceRefresh?: boolean
 }
 
 export type PdsEndpoints = {
-    pds_url: string
-    authorization_endpoint: string
-    token_endpoint: string
-    userinfo_endpoint: string
+  pds_url: string
+  authorization_endpoint: string
+  token_endpoint: string
+  userinfo_endpoint: string
 }
 
 export type AuthManagerConfig = {
-    projectId: string | undefined
-    scopes: string
-    pdsUrl: string
-    adminUrl: string
-    debug: boolean
+  projectId: string | undefined
+  scopes: string
+  pdsUrl: string
+  adminUrl: string
+  debug: boolean
+}
+
+type JwtClaims = {
+  sub?: string
+  scope?: string
+  typ?: string
+  exp?: number
+}
+
+type CurrentSessionInfo = {
+  active: boolean
+  reauth_required?: boolean
+  session_id?: string | null
+  client_id?: string
+  scope?: string
+  account_did?: string
+  connection_status?: string
+  last_seen_at?: string | null
+  error?: string
 }
 
 /**
@@ -79,780 +146,1226 @@ export type AuthManagerConfig = {
  * re-renders whenever auth state changes.
  */
 export class AuthManager {
-    // --- Public state (read by the UI layer) ---
-    token: Token | null = null
-    user: User | null = null
-    isSignedIn: boolean = false
-    isAuthReady: boolean = false
-    did: string | null = null
-    /** Space-separated scopes granted in the current access token */
-    tokenScope: string | null = null
-    /** Space-separated scopes originally requested in the auth config */
-    requestedScopes: string
-
-    readonly config: AuthManagerConfig
-    readonly storage: BasicStorage
-
-    /** True only during a user-initiated OAuth code exchange (not session restore) */
-    private freshSignIn: boolean = false
-
-    // --- Private ---
-    private notify: () => void
-    private refreshPromise: Promise<Token | null> | null = null
-    private codeExchangePromise: Promise<Token | null> | null = null
-    private pendingRefresh: boolean = false
-    private isOnline: boolean = typeof navigator !== 'undefined' ? navigator.onLine : true
-    private channel: BroadcastChannel | null = null
-
-    constructor(config: AuthManagerConfig, storage: BasicStorage, notify: () => void) {
-        this.config = config
-        this.storage = storage
-        this.notify = notify
-        this.requestedScopes = config.scopes
-        this.initCrossTabSync()
-    }
-
-    private initCrossTabSync(): void {
-        if (typeof BroadcastChannel === 'undefined') return
-
-        try {
-            this.channel = new BroadcastChannel('basic-auth')
-            this.channel.onmessage = (event) => {
-                if (event.data?.type === 'token_refreshed') {
-                    log('Received token refresh from another tab')
-                    if (event.data.accessToken && this.token) {
-                        this.token = { ...this.token, access_token: event.data.accessToken }
-                    }
-                    if (event.data.did) this.did = event.data.did
-                    if (event.data.tokenScope) this.tokenScope = event.data.tokenScope
-                    this.notify()
-                }
-                if (event.data?.type === 'signed_in') {
-                    log('Received sign-in from another tab, reloading')
-                    // The signing-in tab already stored refresh_token and user_info
-                    // in localStorage. Reload so initialize() bootstraps the session.
-                    if (typeof window !== 'undefined') {
-                        window.location.reload()
-                    }
-                }
-                if (event.data?.type === 'signed_out') {
-                    log('Received sign-out from another tab, reloading')
-                    this.user = null
-                    this.isSignedIn = false
-                    this.token = null
-                    this.did = null
-                    this.tokenScope = null
-                    this.notify()
-                    // Storage and IndexedDB are already cleaned by the tab that initiated
-                    // sign-out. Reload so this tab picks up the clean slate.
-                    if (typeof window !== 'undefined') {
-                        window.location.reload()
-                    }
-                }
-            }
-        } catch {
-            log('BroadcastChannel not available for cross-tab sync')
+  // --- Public state (read by the UI layer) ---
+  token: Token | null = null
+  user: User | null = null
+  isSignedIn: boolean = false
+  isAuthReady: boolean = false
+  authStatus: AuthStatus = 'bootstrapping'
+  authErrorCode: string | null = null
+  did: string | null = null
+  /** Space-separated scopes granted in the current access token */
+  tokenScope: string | null = null
+  /** Space-separated scopes originally requested in the auth config */
+  requestedScopes: string
+
+  readonly config: AuthManagerConfig
+  readonly storage: BasicStorage
+
+  /** True only during a user-initiated OAuth code exchange (not session restore) */
+  private freshSignIn: boolean = false
+
+  // --- Private ---
+  private notify: () => void
+  private refreshPromise: Promise<Token | null> | null = null
+  private codeExchangePromise: Promise<Token | null> | null = null
+  private pendingRefresh: boolean = false
+  private isOnline: boolean =
+    typeof navigator !== 'undefined' ? navigator.onLine : true
+  private channel: BroadcastChannel | null = null
+  private nextUserRecoveryAt: number = 0
+  private sessionCheckPromise: Promise<void> | null = null
+  private lastSessionCheckAt: number = 0
+
+  constructor(
+    config: AuthManagerConfig,
+    storage: BasicStorage,
+    notify: () => void,
+  ) {
+    this.config = config
+    this.storage = storage
+    this.notify = notify
+    this.requestedScopes = config.scopes
+    this.initCrossTabSync()
+  }
+
+  private initCrossTabSync(): void {
+    if (typeof BroadcastChannel === 'undefined') return
+
+    try {
+      this.channel = new BroadcastChannel('basic-auth')
+      this.channel.onmessage = (event) => {
+        if (event.data?.type === 'token_refreshed') {
+          log('Received token refresh from another tab')
+          void this.handleExternalTokenRefresh(event.data)
         }
+        if (event.data?.type === 'signed_in') {
+          log('Received sign-in from another tab, restoring session')
+          void this.restoreStoredSession('cross-tab sign-in')
+        }
+        if (event.data?.type === 'signed_out') {
+          log('Received sign-out from another tab')
+          this.resetAuthState('signed_out')
+          this.notify()
+          // TODO: replace reload with proper cross-tab sync teardown so
+          // other tabs can clean up without a full page reload.
+          if (typeof window !== 'undefined') {
+            window.location.reload()
+          }
+        }
+        if (event.data?.type === 'session_invalidated') {
+          log('Received session invalidation from another tab')
+          void this.markReauthRequired(event.data.code || 'invalid_grant', {
+            broadcast: false,
+          })
+        }
+      }
+    } catch {
+      log('BroadcastChannel not available for cross-tab sync')
     }
-
-    private broadcastTokenRefresh(): void {
-        this.channel?.postMessage({
-            type: 'token_refreshed',
-            accessToken: this.token?.access_token,
-            did: this.did,
-            tokenScope: this.tokenScope,
-        })
-    }
-
-    private broadcastSignIn(): void {
-        this.channel?.postMessage({ type: 'signed_in' })
-    }
-
-    private broadcastSignOut(): void {
-        this.channel?.postMessage({ type: 'signed_out' })
+  }
+
+  private broadcastTokenRefresh(): void {
+    this.channel?.postMessage({
+      type: 'token_refreshed',
+      accessToken: this.token?.access_token,
+      did: this.did,
+      tokenScope: this.tokenScope,
+    })
+  }
+
+  private broadcastSignIn(): void {
+    this.channel?.postMessage({ type: 'signed_in' })
+  }
+
+  private broadcastSignOut(): void {
+    this.channel?.postMessage({ type: 'signed_out' })
+  }
+
+  private broadcastSessionInvalidated(code: string): void {
+    this.channel?.postMessage({ type: 'session_invalidated', code })
+  }
+
+  // ------------------------------------------------------------------
+  // Public API
+  // ------------------------------------------------------------------
+
+  /**
+   * Bootstrap auth: handle OAuth callback (?code=), restore session
+   * from refresh token, or load cached user for offline mode.
+   */
+  async initialize(): Promise<void> {
+    this.updateAuthStatus('bootstrapping')
+    await this.storage.set(
+      STORAGE_KEYS.DEBUG,
+      this.config.debug ? 'true' : 'false',
+    )
+
+    const storedServerUrl = await this.storage.get(STORAGE_KEYS.SERVER_URL)
+    if (storedServerUrl && storedServerUrl !== this.config.pdsUrl) {
+      log('PDS URL changed, clearing stored tokens')
+      await this.clearStoredAuth()
     }
+    await this.storage.set(STORAGE_KEYS.SERVER_URL, this.config.pdsUrl)
 
-    // ------------------------------------------------------------------
-    // Public API
-    // ------------------------------------------------------------------
+    try {
+      const params = new URLSearchParams(window.location.search)
 
-    /**
-     * Bootstrap auth: handle OAuth callback (?code=), restore session
-     * from refresh token, or load cached user for offline mode.
-     */
-    async initialize(): Promise<void> {
-        await this.storage.set(STORAGE_KEYS.DEBUG, this.config.debug ? 'true' : 'false')
-
-        const storedServerUrl = await this.storage.get(STORAGE_KEYS.SERVER_URL)
-        if (storedServerUrl && storedServerUrl !== this.config.pdsUrl) {
-            log('PDS URL changed, clearing stored tokens')
-            await this.clearStoredAuth()
+      if (params.has('code')) {
+        const code = params.get('code')
+        if (!code) {
+          this.updateAuthStatus('signed_out')
+          this.notify()
+          return
         }
-        await this.storage.set(STORAGE_KEYS.SERVER_URL, this.config.pdsUrl)
 
-        try {
-            const params = new URLSearchParams(window.location.search)
-
-            if (params.has('code')) {
-                const code = params.get('code')
-                if (!code) {
-                    this.isAuthReady = true
-                    this.notify()
-                    return
-                }
-
-                const state = await this.storage.get(STORAGE_KEYS.AUTH_STATE)
-                const urlState = params.get('state')
-                if (!state || state !== urlState) {
-                    log('error: auth state does not match')
-                    this.isAuthReady = true
-                    this.notify()
-                    await this.storage.remove(STORAGE_KEYS.AUTH_STATE)
-                    cleanOAuthParamsFromUrl()
-                    return
-                }
-
-                await this.storage.remove(STORAGE_KEYS.AUTH_STATE)
-                cleanOAuthParamsFromUrl()
-
-                this.freshSignIn = true
-                this.exchangeToken(code, false).catch((error) => {
-                    log('Error fetching token:', error)
-                })
-            } else {
-                const refreshToken = await this.storage.get(STORAGE_KEYS.REFRESH_TOKEN)
-                if (refreshToken) {
-                    log('Found refresh token in storage, attempting to refresh access token')
-                    this.exchangeToken(refreshToken, true).catch((error) => {
-                        log('Error fetching refresh token:', error)
-                    })
-                } else {
-                    const cachedUserInfo = await this.storage.get(STORAGE_KEYS.USER_INFO)
-                    if (cachedUserInfo) {
-                        try {
-                            this.user = JSON.parse(cachedUserInfo)
-                            this.isSignedIn = true
-                            log('Loaded cached user info for offline mode')
-                        } catch (error) {
-                            log('Error parsing cached user info:', error)
-                        }
-                    }
-                    this.isAuthReady = true
-                    this.notify()
-                }
-            }
-        } catch (e) {
-            log('error getting token', e)
+        const state = await this.storage.get(STORAGE_KEYS.AUTH_STATE)
+        const urlState = params.get('state')
+        if (!state || state !== urlState) {
+          log('error: auth state does not match')
+          this.updateAuthStatus('signed_out')
+          this.notify()
+          await this.storage.remove(STORAGE_KEYS.AUTH_STATE)
+          cleanOAuthParamsFromUrl()
+          return
         }
-    }
 
-    /**
-     * Get a valid access token string. Refreshes proactively (5s buffer)
-     * or on demand (forceRefresh). Mutex prevents concurrent refreshes.
-     */
-    async getToken(options?: GetTokenOptions): Promise<string> {
-        log('getting token...')
-
-        if (!this.token) {
-            const refreshToken = await this.storage.get(STORAGE_KEYS.REFRESH_TOKEN)
-            if (refreshToken) {
-                log('No token in memory, attempting to refresh from storage')
-
-                if (this.refreshPromise) {
-                    log('Token refresh already in progress, waiting...')
-                    try {
-                        const newToken = await this.refreshPromise
-                        if (newToken?.access_token) {
-                            return newToken.access_token
-                        }
-                    } catch (error) {
-                        log('In-flight refresh failed:', error)
-                        throw error
-                    }
-                }
-
-                try {
-                    const newToken = await this.exchangeToken(refreshToken, true)
-                    if (newToken?.access_token) {
-                        return newToken.access_token
-                    }
-                } catch (error) {
-                    log('Failed to refresh token from storage:', error)
-                    if (this.isNetworkError(error)) {
-                        throw new Error('Network offline - authentication will be retried when online')
-                    }
-                    throw new Error('Authentication expired. Please sign in again.')
-                }
+        await this.storage.remove(STORAGE_KEYS.AUTH_STATE)
+        cleanOAuthParamsFromUrl()
+
+        this.freshSignIn = true
+        this.exchangeToken(code, false).catch((error) => {
+          log('Error fetching token:', error)
+          this.freshSignIn = false
+          void this.restoreCachedUser({
+            hasRecoverableSession: !this.isDefinitiveAuthFailure(error),
+          })
+        })
+      } else {
+        await this.restoreStoredSession('initialize')
+      }
+    } catch (e) {
+      log('error getting token', e)
+      this.updateAuthStatus('signed_out')
+      this.notify()
+    }
+  }
+
+  /**
+   * Get a valid access token string. Refreshes proactively (5s buffer)
+   * or on demand (forceRefresh). Mutex prevents concurrent refreshes.
+   */
+  async getToken(options?: GetTokenOptions): Promise<string> {
+    log('getting token...')
+
+    if (!this.token) {
+      const refreshToken = await this.getRefreshToken()
+      if (refreshToken) {
+        log('No token in memory, attempting to refresh from storage')
+
+        if (this.refreshPromise) {
+          log('Token refresh already in progress, waiting...')
+          try {
+            const newToken = await this.refreshPromise
+            if (newToken?.access_token) {
+              return newToken.access_token
             }
-            log('no token found')
-            throw new Error('no token found')
+          } catch (error) {
+            log('In-flight refresh failed:', error)
+            throw error
+          }
         }
 
-        const decoded = jwtDecode(this.token.access_token)
-        const expirationBuffer = 5
-        const isExpired = decoded.exp && decoded.exp < (Date.now() / 1000) + expirationBuffer
-        const shouldRefresh = isExpired || options?.forceRefresh === true
-
-        if (shouldRefresh) {
-            log(options?.forceRefresh ? 'force refreshing token...' : 'token is expired - refreshing ...')
-
-            if (this.refreshPromise) {
-                log('Token refresh already in progress, waiting...')
-                try {
-                    const newToken = await this.refreshPromise
-                    return newToken?.access_token || ''
-                } catch (error) {
-                    log('In-flight refresh failed:', error)
-                    if (this.isNetworkError(error)) {
-                        log('Network issue - using expired token until network is restored')
-                        return this.token.access_token
-                    }
-                    throw error
-                }
-            }
-
-            const refreshToken = this.token.refresh_token || await this.storage.get(STORAGE_KEYS.REFRESH_TOKEN)
-            if (refreshToken) {
-                try {
-                    const newToken = await this.exchangeToken(refreshToken, true)
-                    return newToken?.access_token || ''
-                } catch (error) {
-                    log('Failed to refresh expired token:', error)
-                    if (this.isNetworkError(error)) {
-                        log('Network issue - using expired token until network is restored')
-                        return this.token.access_token
-                    }
-                    throw new Error('Authentication expired. Please sign in again.')
-                }
-            } else {
-                throw new Error('no refresh token available')
-            }
+        try {
+          const newToken = await this.exchangeToken(refreshToken, true)
+          if (newToken?.access_token) {
+            return newToken.access_token
+          }
+        } catch (error) {
+          log('Failed to refresh token from storage:', error)
+          if (this.isNetworkError(error)) {
+            throw new Error(
+              'Network offline - authentication will be retried when online',
+            )
+          }
+          if (!this.isDefinitiveAuthFailure(error)) {
+            throw error
+          }
+          throw new Error('Authentication expired. Please sign in again.')
         }
-
-        return this.token.access_token || ''
+      }
+      log('no token found')
+      throw new Error('no token found')
     }
 
-    async getSignInUrl(redirectUri?: string, endpoints?: PdsEndpoints): Promise<string> {
-        log('getting sign in link...')
-
-        if (!this.config.projectId) {
-            throw new Error('Project ID is required to generate sign-in link')
+    const decoded = jwtDecode<JwtClaims>(this.token.access_token)
+    const expirationBuffer = 5
+    const isExpired =
+      decoded.exp && decoded.exp < Date.now() / 1000 + expirationBuffer
+    const shouldRefresh = isExpired || options?.forceRefresh === true
+
+    if (shouldRefresh) {
+      log(
+        options?.forceRefresh
+          ? 'force refreshing token...'
+          : 'token is expired - refreshing ...',
+      )
+
+      if (this.refreshPromise) {
+        log('Token refresh already in progress, waiting...')
+        try {
+          const newToken = await this.refreshPromise
+          if (!newToken?.access_token)
+            throw new Error('Token refresh returned empty access token')
+          return newToken.access_token
+        } catch (error) {
+          log('In-flight refresh failed:', error)
+          if (this.isNetworkError(error)) {
+            log('Network issue - using expired token until network is restored')
+            return this.token.access_token
+          }
+          throw error
         }
+      }
 
-        const pdsEndpoints = endpoints || this.defaultPdsEndpoints()
-        await this.storage.set(STORAGE_KEYS.PDS_ENDPOINTS, JSON.stringify(pdsEndpoints))
-
-        const randomState = Math.random().toString(36).substring(6)
-        await this.storage.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')
+      const refreshToken = await this.getRefreshToken()
+      if (refreshToken) {
+        try {
+          const newToken = await this.exchangeToken(refreshToken, true)
+          if (!newToken?.access_token)
+            throw new Error('Token refresh returned empty access token')
+          return newToken.access_token
+        } catch (error) {
+          log('Failed to refresh expired token:', error)
+          if (this.isNetworkError(error)) {
+            log('Network issue - using expired token until network is restored')
+            return this.token.access_token
+          }
+          if (!this.isDefinitiveAuthFailure(error)) {
+            throw error
+          }
+          throw new Error('Authentication expired. Please sign in again.')
         }
+      } else {
+        throw new Error('no refresh token available')
+      }
+    }
 
-        await this.storage.set(STORAGE_KEYS.REDIRECT_URI, redirectUrl)
-        log('Stored redirect_uri for token exchange:', redirectUrl)
+    if (!this.token.access_token)
+      throw new Error('Token exists but access_token is empty')
+    return this.token.access_token
+  }
 
-        // PKCE: generate code_verifier and code_challenge (RFC 7636)
-        const codeVerifier = generateCodeVerifier()
-        const { challenge: codeChallenge, method: challengeMethod } = await generateCodeChallenge(codeVerifier)
-        await this.storage.set(STORAGE_KEYS.CODE_VERIFIER, codeVerifier)
+  async getSignInUrl(
+    redirectUri?: string,
+    endpoints?: PdsEndpoints,
+  ): Promise<string> {
+    log('getting sign in link...')
 
-        let baseUrl = pdsEndpoints.authorization_endpoint
-        baseUrl += `?client_id=${encodeURIComponent(normalizeClientId(this.config.projectId, this.adminHostname))}`
-        baseUrl += `&redirect_uri=${encodeURIComponent(redirectUrl)}`
-        baseUrl += `&response_type=code`
-        baseUrl += `&scope=${encodeURIComponent(this.config.scopes)}`
-        baseUrl += `&state=${randomState}`
-        baseUrl += `&code_challenge=${encodeURIComponent(codeChallenge)}`
-        baseUrl += `&code_challenge_method=${challengeMethod}`
+    if (!this.config.projectId) {
+      throw new Error('Project ID is required to generate sign-in link')
+    }
 
-        log('Generated sign-in link successfully with scopes:', this.config.scopes)
-        return baseUrl
+    const pdsEndpoints = endpoints || this.defaultPdsEndpoints()
+    await this.storage.set(
+      STORAGE_KEYS.PDS_ENDPOINTS,
+      JSON.stringify(pdsEndpoints),
+    )
+
+    const randomState = base64UrlEncode(
+      crypto.getRandomValues(new Uint8Array(16)),
+    )
+    await this.storage.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')
     }
 
-    async signIn(redirectUri?: string): Promise<void> {
-        log('signing in...')
+    await this.storage.set(STORAGE_KEYS.REDIRECT_URI, redirectUrl)
+    log('Stored redirect_uri for token exchange:', redirectUrl)
+
+    // PKCE: generate code_verifier and code_challenge (RFC 7636)
+    const codeVerifier = generateCodeVerifier()
+    const { challenge: codeChallenge, method: challengeMethod } =
+      await generateCodeChallenge(codeVerifier)
+    await this.storage.set(STORAGE_KEYS.CODE_VERIFIER, codeVerifier)
+
+    let baseUrl = pdsEndpoints.authorization_endpoint
+    baseUrl += `?client_id=${encodeURIComponent(normalizeClientId(this.config.projectId, this.adminHostname))}`
+    baseUrl += `&redirect_uri=${encodeURIComponent(redirectUrl)}`
+    baseUrl += `&response_type=code`
+    baseUrl += `&scope=${encodeURIComponent(this.config.scopes)}`
+    baseUrl += `&state=${randomState}`
+    baseUrl += `&code_challenge=${encodeURIComponent(codeChallenge)}`
+    baseUrl += `&code_challenge_method=${challengeMethod}`
+
+    log('Generated sign-in link successfully with scopes:', this.config.scopes)
+    return baseUrl
+  }
+
+  async signIn(redirectUri?: string): Promise<void> {
+    log('signing in...')
+
+    if (!this.config.projectId) {
+      log('Error: project_id is required for sign-in')
+      throw new Error('Project ID is required for authentication')
+    }
 
-        if (!this.config.projectId) {
-            log('Error: project_id is required for sign-in')
-            throw new Error('Project ID is required for authentication')
-        }
+    const signInLink = await this.getSignInUrl(redirectUri)
+    log('Generated sign-in link:', signInLink)
 
-        const signInLink = await this.getSignInUrl(redirectUri)
-        log('Generated sign-in link:', signInLink)
+    try {
+      new URL(signInLink)
+    } catch {
+      log('Error: Invalid sign-in link generated')
+      throw new Error('Failed to generate valid sign-in URL')
+    }
 
-        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
+  }
 
-        window.location.href = signInLink
-    }
+  async signInWithHandle(handle: string): Promise<void> {
+    log('signing in with handle:', handle)
 
-    async signInWithHandle(handle: string): Promise<void> {
-        log('signing in with handle:', handle)
+    if (!this.config.projectId) {
+      throw new Error('Project ID is required for authentication')
+    }
 
-        if (!this.config.projectId) {
-            throw new Error('Project ID is required for authentication')
-        }
+    const resolved = await resolveHandle(handle)
+    log('Resolved handle to PDS:', resolved.pdsUrl)
 
-        const resolved = await resolveHandle(handle)
-        log('Resolved handle to PDS:', resolved.pdsUrl)
+    const endpoints: PdsEndpoints = {
+      pds_url: resolved.pdsUrl,
+      authorization_endpoint: resolved.authorization_endpoint,
+      token_endpoint: resolved.token_endpoint,
+      userinfo_endpoint: resolved.userinfo_endpoint,
+    }
 
-        const endpoints: PdsEndpoints = {
-            pds_url: resolved.pdsUrl,
-            authorization_endpoint: resolved.authorization_endpoint,
-            token_endpoint: resolved.token_endpoint,
-            userinfo_endpoint: resolved.userinfo_endpoint
-        }
+    const signInLink = await this.getSignInUrl(undefined, endpoints)
+    log('Generated federated sign-in link:', signInLink)
 
-        const signInLink = await this.getSignInUrl(undefined, endpoints)
-        log('Generated federated sign-in link:', signInLink)
+    try {
+      new URL(signInLink)
+    } catch {
+      throw new Error('Failed to generate valid sign-in URL')
+    }
 
-        try { new URL(signInLink) } catch {
-            throw new Error('Failed to generate valid sign-in URL')
+    window.location.href = signInLink
+  }
+
+  async signInWithCode(code: string, state?: string): Promise<AuthResult> {
+    try {
+      log('signInWithCode called with code:', code)
+
+      if (!code || typeof code !== 'string') {
+        return { success: false, error: 'Invalid authorization code' }
+      }
+
+      if (state) {
+        const storedState = await this.storage.get(STORAGE_KEYS.AUTH_STATE)
+        if (storedState && storedState !== state) {
+          log('State parameter mismatch:', {
+            provided: state,
+            stored: storedState,
+          })
+          return { success: false, error: 'State parameter mismatch' }
         }
-
-        window.location.href = signInLink
+      }
+
+      await this.storage.remove(STORAGE_KEYS.AUTH_STATE)
+      cleanOAuthParamsFromUrl()
+
+      this.freshSignIn = true
+      const token = await this.exchangeToken(code, false)
+      if (token) {
+        log('signInWithCode successful')
+        return { success: true }
+      } else {
+        return { success: false, error: 'Failed to exchange code for token' }
+      }
+    } catch (error) {
+      log('signInWithCode error:', error)
+      this.freshSignIn = false
+      return {
+        success: false,
+        error: (error as Error).message || 'Authentication failed',
+      }
+    }
+  }
+
+  /**
+   * Clear auth state and storage. Does NOT handle sync/DB cleanup —
+   * the UI layer (BasicProvider) wraps this to add sync teardown.
+   */
+  async signOut(): Promise<void> {
+    log('signing out!')
+    this.resetAuthState('signed_out')
+
+    await this.storage.remove(STORAGE_KEYS.AUTH_STATE)
+    await this.storage.remove(STORAGE_KEYS.LAST_CONNECT_REPORT)
+    await this.clearStoredAuth()
+
+    this.broadcastSignOut()
+    this.notify()
+  }
+
+  async reconcileSession(
+    reason: string = 'manual',
+    options?: { forceRefresh?: boolean; throttleMs?: number },
+  ): Promise<void> {
+    if (this.authStatus === 'signed_out' || this.authStatus === 'reauth_required') {
+      return
     }
 
-    async signInWithCode(code: string, state?: string): Promise<AuthResult> {
-        try {
-            log('signInWithCode called with code:', code)
+    if (!this.isOnline) {
+      this.updateAuthStatus('recovering', this.authErrorCode)
+      this.notify()
+      return
+    }
 
-            if (!code || typeof code !== 'string') {
-                return { success: false, error: 'Invalid authorization code' }
-            }
+    const throttleMs = options?.throttleMs ?? SESSION_RECONCILE_THROTTLE_MS
+    const forceRefresh = options?.forceRefresh === true
+    const now = Date.now()
 
-            if (state) {
-                const storedState = await this.storage.get(STORAGE_KEYS.AUTH_STATE)
-                if (storedState && storedState !== state) {
-                    log('State parameter mismatch:', { provided: state, stored: storedState })
-                    return { success: false, error: 'State parameter mismatch' }
-                }
-            }
+    if (this.sessionCheckPromise) {
+      return this.sessionCheckPromise
+    }
 
-            await this.storage.remove(STORAGE_KEYS.AUTH_STATE)
-            cleanOAuthParamsFromUrl()
+    if (!forceRefresh && now - this.lastSessionCheckAt < throttleMs) {
+      return
+    }
 
-            this.freshSignIn = true
-            const token = await this.exchangeToken(code, false)
-            if (token) {
-                log('signInWithCode successful')
-                return { success: true }
-            } else {
-                return { success: false, error: 'Failed to exchange code for token' }
-            }
-        } catch (error) {
-            log('signInWithCode error:', error)
-            return {
-                success: false,
-                error: (error as Error).message || 'Authentication failed'
-            }
+    this.lastSessionCheckAt = now
+
+    let sessionCheck: Promise<void> | null = null
+    sessionCheck = (async () => {
+      try {
+        const accessToken = await this.getToken(
+          forceRefresh ? { forceRefresh: true } : undefined,
+        )
+        const currentSession = await this.fetchCurrentSession(accessToken)
+        if (currentSession?.active) {
+          this.updateAuthStatus('authenticated')
+          this.notify()
+          if (!this.user) {
+            await this.recoverMissingUserProfile(reason, accessToken)
+          }
+        }
+      } catch (error) {
+        log(`Session reconciliation failed on ${reason}:`, error)
+        if (this.isDefinitiveAuthFailure(error)) {
+          return
+        }
+        if (this.isNetworkError(error)) {
+          this.updateAuthStatus('recovering', this.authErrorCode)
+          this.notify()
+        }
+      } finally {
+        if (this.sessionCheckPromise === sessionCheck) {
+          this.sessionCheckPromise = null
+        }
+      }
+    })()
+
+    this.sessionCheckPromise = sessionCheck
+    return sessionCheck
+  }
+
+  hasScope(scope: string): boolean {
+    if (!this.tokenScope) return false
+    return this.tokenScope
+      .split(/[\s,]+/)
+      .filter(Boolean)
+      .includes(scope)
+  }
+
+  /**
+   * Returns scopes that were requested but not granted in the current token.
+   * Useful after login or when a 403 is returned.
+   */
+  missingScopes(): string[] {
+    const requested = this.requestedScopes.split(/[\s,]+/).filter(Boolean)
+    if (!this.tokenScope) return requested
+    const granted = new Set(this.tokenScope.split(/[\s,]+/).filter(Boolean))
+    return requested.filter((s) => !granted.has(s))
+  }
+
+  /**
+   * Register online/offline and visibility handlers that retry pending
+   * refreshes and proactively refresh tokens when the app resumes from
+   * background (critical for PWAs and mobile browsers where timers are
+   * frozen while backgrounded).
+   * Returns a cleanup function for useEffect teardown.
+   */
+  setupNetworkListeners(): () => void {
+    const handleOnline = async () => {
+      log('Network came back online')
+      this.isOnline = true
+      if (this.pendingRefresh) {
+        log('Retrying pending token refresh')
+        this.pendingRefresh = false
+        const refreshToken = await this.getRefreshToken()
+        if (refreshToken) {
+          this.exchangeToken(refreshToken, true).catch((error) => {
+            log('Retry refresh failed:', error)
+          })
         }
+      }
+      if (this.isSignedIn) {
+        this.reconcileSession('online event', {
+          forceRefresh: true,
+          throttleMs: 0,
+        }).catch((error) => {
+          log('Session reconciliation on online failed:', error)
+        })
+      } else if (this.user) {
+        await this.restoreStoredSession('online restore')
+      }
     }
 
-    /**
-     * Clear auth state and storage. Does NOT handle sync/DB cleanup —
-     * the UI layer (BasicProvider) wraps this to add sync teardown.
-     */
-    async signOut(): Promise<void> {
-        log('signing out!')
-        this.resetAuthState()
+    const handleOffline = () => {
+      log('Network went offline')
+      this.isOnline = false
+    }
 
-        await this.storage.remove(STORAGE_KEYS.AUTH_STATE)
-        await this.storage.remove(STORAGE_KEYS.LAST_CONNECT_REPORT)
-        await this.clearStoredAuth()
-
-        this.broadcastSignOut()
-        this.notify()
-    }
-
-    hasScope(scope: string): boolean {
-        if (!this.tokenScope) return false
-        return this.tokenScope.split(/[\s,]+/).filter(Boolean).includes(scope)
-    }
-
-    /**
-     * Returns scopes that were requested but not granted in the current token.
-     * Useful after login or when a 403 is returned.
-     */
-    missingScopes(): string[] {
-        const requested = this.requestedScopes.split(/[\s,]+/).filter(Boolean)
-        if (!this.tokenScope) return requested
-        const granted = new Set(this.tokenScope.split(/[\s,]+/).filter(Boolean))
-        return requested.filter(s => !granted.has(s))
-    }
-
-    /**
-     * Register online/offline handlers that retry pending refreshes.
-     * Returns a cleanup function for useEffect teardown.
-     */
-    setupNetworkListeners(): () => void {
-        const handleOnline = async () => {
-            log('Network came back online')
-            this.isOnline = true
-            if (this.pendingRefresh && this.token) {
-                log('Retrying pending token refresh')
-                this.pendingRefresh = false
-                const refreshToken = this.token.refresh_token || await this.storage.get(STORAGE_KEYS.REFRESH_TOKEN)
-                if (refreshToken) {
-                    this.exchangeToken(refreshToken, true).catch(error => {
-                        log('Retry refresh failed:', error)
-                    })
-                }
-            }
-        }
+    const handleVisibilityChange = () => {
+      if (document.visibilityState === 'visible' && this.isSignedIn) {
+        log('App became visible - reconciling auth session')
+        this.reconcileSession('visibility resume', {
+          forceRefresh: true,
+        }).catch((err) => {
+          log('Session reconciliation on visibility resume failed:', err)
+        })
+      }
+    }
 
-        const handleOffline = () => {
-            log('Network went offline')
-            this.isOnline = false
-        }
+    window.addEventListener('online', handleOnline)
+    window.addEventListener('offline', handleOffline)
 
-        window.addEventListener('online', handleOnline)
-        window.addEventListener('offline', handleOffline)
+    if (typeof document !== 'undefined') {
+      document.addEventListener('visibilitychange', handleVisibilityChange)
+    }
 
-        return () => {
-            window.removeEventListener('online', handleOnline)
-            window.removeEventListener('offline', handleOffline)
-        }
+    return () => {
+      window.removeEventListener('online', handleOnline)
+      window.removeEventListener('offline', handleOffline)
+      if (typeof document !== 'undefined') {
+        document.removeEventListener('visibilitychange', handleVisibilityChange)
+      }
     }
+  }
 
-    // ------------------------------------------------------------------
-    // Private
-    // ------------------------------------------------------------------
+  // ------------------------------------------------------------------
+  // Private
+  // ------------------------------------------------------------------
 
-    private get adminHostname(): string {
-        try { return new URL(this.config.adminUrl).hostname }
-        catch { return 'api.basic.tech' }
+  private get adminHostname(): string {
+    try {
+      return new URL(this.config.adminUrl).hostname
+    } catch {
+      return 'api.basic.tech'
+    }
+  }
+
+  private defaultPdsEndpoints(): PdsEndpoints {
+    return {
+      pds_url: this.config.pdsUrl,
+      authorization_endpoint: `${this.config.pdsUrl}/auth/authorize`,
+      token_endpoint: `${this.config.pdsUrl}/auth/token`,
+      userinfo_endpoint: `${this.config.pdsUrl}/auth/userinfo`,
+    }
+  }
+
+  private async getActivePdsEndpoints(): Promise<PdsEndpoints> {
+    const stored = await this.storage.get(STORAGE_KEYS.PDS_ENDPOINTS)
+    if (stored) {
+      try {
+        return JSON.parse(stored) as PdsEndpoints
+      } catch {
+        /* fall through */
+      }
+    }
+    return this.defaultPdsEndpoints()
+  }
+
+  private async reportConnection(accessToken: string): Promise<void> {
+    if (!this.config.projectId || !this.config.adminUrl) return
+    const lastReport = await this.storage.get(STORAGE_KEYS.LAST_CONNECT_REPORT)
+    if (lastReport) {
+      const elapsed = Date.now() - parseInt(lastReport, 10)
+      if (elapsed < 24 * 60 * 60 * 1000) return
+    }
+    try {
+      await fetch(
+        `${this.config.adminUrl}/project/${this.config.projectId}/user/connect`,
+        {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ token: accessToken }),
+        },
+      )
+      await this.storage.set(
+        STORAGE_KEYS.LAST_CONNECT_REPORT,
+        Date.now().toString(),
+      )
+      log('Reported connection to admin server')
+    } catch (err) {
+      log('Failed to report connection (non-blocking):', err)
+    }
+  }
+
+  /**
+   * After a new token is stored, decode JWT claims and fetch user info.
+   */
+  private async processNewToken(): Promise<void> {
+    if (!this.token) {
+      this.updateAuthStatus('signed_out')
+      this.notify()
+      return
     }
 
-    private defaultPdsEndpoints(): PdsEndpoints {
-        return {
-            pds_url: this.config.pdsUrl,
-            authorization_endpoint: `${this.config.pdsUrl}/auth/authorize`,
-            token_endpoint: `${this.config.pdsUrl}/auth/token`,
-            userinfo_endpoint: `${this.config.pdsUrl}/auth/userinfo`
-        }
+    try {
+      const decoded = jwtDecode<JwtClaims>(this.token.access_token)
+      this.applyTokenClaims(decoded)
+      this.updateAuthStatus('authenticated')
+      this.notify()
+      this.broadcastSessionUpdate()
+      await this.fetchUser(this.token.access_token)
+    } catch (error) {
+      log('Error processing token:', error)
+      this.updateAuthStatus('recovering')
+      this.notify()
+    }
+  }
+
+  private async restoreCachedUser(options?: {
+    hasRecoverableSession: boolean
+  }): Promise<void> {
+    const cached = await this.storage.get(STORAGE_KEYS.USER_INFO)
+    if (cached && options?.hasRecoverableSession) {
+      try {
+        this.user = JSON.parse(cached)
+        log('Restored cached user info for recoverable session')
+      } catch {
+        /* corrupted cache, ignore */
+      }
+    } else {
+      this.user = null
+    }
+    this.updateAuthStatus(
+      options?.hasRecoverableSession ? 'recovering' : 'signed_out',
+    )
+    this.notify()
+  }
+
+  private async fetchUser(accessToken: string): Promise<void> {
+    log('fetching user')
+    try {
+      const endpoints = await this.getActivePdsEndpoints()
+      const response = await fetch(endpoints.userinfo_endpoint, {
+        method: 'GET',
+        headers: { Authorization: `Bearer ${accessToken}` },
+      })
+
+      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 (this.token?.refresh_token) {
+        await this.storage.set(
+          STORAGE_KEYS.REFRESH_TOKEN,
+          this.token.refresh_token,
+        )
+      }
+
+      await this.storage.set(STORAGE_KEYS.USER_INFO, JSON.stringify(user))
+      log('Cached user info in storage')
+
+      this.user = user
+      if (this.authStatus !== 'reauth_required') {
+        this.updateAuthStatus('authenticated')
+      }
+      this.nextUserRecoveryAt = 0
+      this.notify()
+    } catch (error) {
+      log('Failed to fetch user info:', error)
+      await this.handleUserFetchFailure()
+    }
+  }
+
+  /**
+   * Exchange an auth code or refresh token for an access token.
+   * Handles mutex (one in-flight refresh), token validation, and
+   * triggers processNewToken on success.
+   */
+  private async exchangeToken(
+    codeOrRefreshToken: string,
+    isRefreshToken: boolean,
+  ): Promise<Token | null> {
+    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)
     }
 
-    private async getActivePdsEndpoints(): Promise<PdsEndpoints> {
-        const stored = await this.storage.get(STORAGE_KEYS.PDS_ENDPOINTS)
-        if (stored) {
-            try { return JSON.parse(stored) as PdsEndpoints } catch { /* fall through */ }
-        }
-        return this.defaultPdsEndpoints()
+    if (isRefreshToken && this.refreshPromise) {
+      log('Reusing in-flight refresh token request')
+      return this.refreshPromise
     }
 
-    private async reportConnection(accessToken: string): Promise<void> {
-        if (!this.config.projectId || !this.config.adminUrl) return
-        const lastReport = await this.storage.get(STORAGE_KEYS.LAST_CONNECT_REPORT)
-        if (lastReport) {
-            const elapsed = Date.now() - parseInt(lastReport, 10)
-            if (elapsed < 24 * 60 * 60 * 1000) return
-        }
-        try {
-            await fetch(`${this.config.adminUrl}/project/${this.config.projectId}/user/connect`, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify({ token: accessToken })
-            })
-            await this.storage.set(STORAGE_KEYS.LAST_CONNECT_REPORT, Date.now().toString())
-            log('Reported connection to admin server')
-        } catch (err) {
-            log('Failed to report connection (non-blocking):', err)
-        }
+    if (!isRefreshToken && this.codeExchangePromise) {
+      log('Reusing in-flight code exchange request')
+      return this.codeExchangePromise
     }
 
-    /**
-     * After a new token is stored, decode JWT claims and fetch user info.
-     */
-    private async processNewToken(): Promise<void> {
-        if (!this.token) {
-            this.isAuthReady = true
-            this.notify()
-            return
+    const tokenPromise = (async (): Promise<Token | null> => {
+      try {
+        if (!this.isOnline) {
+          log('Network is offline, marking refresh as pending')
+          this.pendingRefresh = true
+          throw new Error(
+            'Network offline - refresh will be retried when online',
+          )
         }
 
-        try {
-            const decoded = jwtDecode<{ sub?: string; scope?: string; typ?: string; exp?: number }>(this.token.access_token)
-
-            if (decoded.sub) this.did = decoded.sub
-            if (decoded.scope) this.tokenScope = decoded.scope
-
-            const expirationBuffer = 5
-            const isExpired = decoded.exp && decoded.exp < (Date.now() / 1000) + expirationBuffer
-
-            if (isExpired) {
-                log('token is expired - refreshing ...')
-                const refreshToken = this.token.refresh_token
-                if (!refreshToken) {
-                    log('Error: No refresh token available for expired token')
-                    this.isAuthReady = true
-                    this.notify()
-                    return
-                }
-                try {
-                    const newToken = await this.exchangeToken(refreshToken, true)
-                    await this.fetchUser(newToken?.access_token || '')
-                } catch (error) {
-                    log('Failed to refresh token in processNewToken:', error)
-                    if (this.isNetworkError(error)) {
-                        log('Network issue - continuing with expired token until online')
-                        await this.fetchUser(this.token.access_token)
-                    } else {
-                        this.isAuthReady = true
-                        this.notify()
-                    }
-                }
-            } else {
-                await this.fetchUser(this.token.access_token)
-            }
-        } catch (error) {
-            log('Error processing token:', error)
-            this.isAuthReady = true
-            this.notify()
+        const endpoints = await this.getActivePdsEndpoints()
+        let requestBody: any
+
+        if (isRefreshToken) {
+          requestBody = {
+            grant_type: 'refresh_token',
+            refresh_token: codeOrRefreshToken,
+          }
+          if (this.config.projectId) {
+            requestBody.client_id = normalizeClientId(
+              this.config.projectId,
+              this.adminHostname,
+            )
+          }
+        } else {
+          requestBody = {
+            grant_type: 'authorization_code',
+            code: codeOrRefreshToken,
+          }
+
+          const storedRedirectUri = await this.storage.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')
+          }
+
+          // PKCE: include code_verifier from the authorization request
+          const codeVerifier = await this.storage.get(
+            STORAGE_KEYS.CODE_VERIFIER,
+          )
+          if (codeVerifier) {
+            requestBody.code_verifier = codeVerifier
+          }
+
+          if (this.config.projectId) {
+            requestBody.client_id = normalizeClientId(
+              this.config.projectId,
+              this.adminHostname,
+            )
+          }
         }
-    }
 
-    private async fetchUser(accessToken: string): Promise<void> {
-        log('fetching user')
-        try {
-            const endpoints = await this.getActivePdsEndpoints()
-            const response = await fetch(endpoints.userinfo_endpoint, {
-                method: 'GET',
-                headers: { 'Authorization': `Bearer ${accessToken}` }
-            })
-
-            if (!response.ok) {
-                throw new Error(`Failed to fetch user info: ${response.status}`)
+        log('Token exchange request body:', {
+          ...requestBody,
+          ...(isRefreshToken
+            ? { refresh_token: '[REDACTED]' }
+            : { code: '[REDACTED]' }),
+          ...(requestBody.code_verifier ? { code_verifier: '[REDACTED]' } : {}),
+        })
+
+        const token = await fetch(endpoints.token_endpoint, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(requestBody),
+        })
+          .then((response) => response.json())
+          .catch((error) => {
+            log('Network error fetching token:', error)
+            if (!this.isOnline) {
+              this.pendingRefresh = true
+              throw new Error(
+                'Network offline - refresh will be retried when online',
+              )
+            }
+            throw new Error('Network error during token refresh')
+          })
+
+        if (token.access_token) {
+          try {
+            const decoded = jwtDecode<{ typ?: string }>(token.access_token)
+            if (decoded.typ === 'refresh') {
+              log('Error: received refresh token as access token')
+              throw new Error(
+                'Invalid token: received refresh token instead of access token',
+              )
+            }
+          } catch (decodeError) {
+            if ((decodeError as Error).message.includes('Invalid token')) {
+              throw decodeError
             }
+            log(
+              'Warning: could not decode access token for type check:',
+              decodeError,
+            )
+          }
+        }
 
-            const user = await response.json()
+        if (token.error) {
+          log('error fetching token', token.error)
+
+          if (
+            typeof token.error === 'string' &&
+            (token.error.includes('network') || token.error.includes('timeout'))
+          ) {
+            this.pendingRefresh = true
+            throw new Error(
+              'Network issue - refresh will be retried when online',
+            )
+          }
+
+          // Only clear stored auth on definitive OAuth rejection.
+          // Transient server errors (500, 503, etc.) should NOT wipe
+          // the refresh token — the user can retry later.
+          if (this.isDefinitiveTokenErrorCode(token.error)) {
+            await this.markReauthRequired(token.error)
+            throw new DefinitiveAuthError(token.error)
+          }
+          throw new Error(`Token refresh failed: ${token.error}`)
+        } else {
+          if (!token.access_token) {
+            throw new Error('Token response missing access token')
+          }
+          this.token = token
+          this.pendingRefresh = false
+
+          if (token.refresh_token) {
+            await this.storage.set(
+              STORAGE_KEYS.REFRESH_TOKEN,
+              token.refresh_token,
+            )
+            log('Updated refresh token in storage')
+          }
+
+          if (!isRefreshToken) {
+            await this.storage.remove(STORAGE_KEYS.REDIRECT_URI)
+            await this.storage.remove(STORAGE_KEYS.CODE_VERIFIER)
+            log(
+              'Cleaned up redirect_uri and code_verifier from storage after successful exchange',
+            )
+          }
+
+          this.reportConnection(token.access_token).catch(() => {})
+
+          await this.processNewToken()
+        }
 
-            if (user.error) {
-                log('error fetching user', user.error)
-                throw new Error(`User info error: ${user.error}`)
-            }
+        return token
+      } catch (error) {
+        log('Token refresh error:', error)
+        if (this.isDefinitiveAuthFailure(error)) {
+          log('Preserving cleared auth state after definitive token rejection')
+        } else if (this.isNetworkError(error)) {
+          log('Recoverable network auth failure - preserving session state')
+        } else {
+          log('Recoverable auth failure - preserving session state')
+        }
 
-            if (this.token?.refresh_token) {
-                await this.storage.set(STORAGE_KEYS.REFRESH_TOKEN, this.token.refresh_token)
-            }
+        throw error
+      }
+    })()
+
+    if (isRefreshToken) {
+      this.refreshPromise = tokenPromise
+      tokenPromise.finally(() => {
+        if (this.refreshPromise === tokenPromise) {
+          this.refreshPromise = null
+          log('Cleared refresh promise reference')
+        }
+      })
+    } else {
+      this.codeExchangePromise = tokenPromise
+      tokenPromise.finally(() => {
+        if (this.codeExchangePromise === tokenPromise) {
+          this.codeExchangePromise = null
+          log('Cleared code exchange promise reference')
+        }
+      })
+    }
 
-            await this.storage.set(STORAGE_KEYS.USER_INFO, JSON.stringify(user))
-            log('Cached user info in storage')
+    return tokenPromise
+  }
 
-            this.user = user
-            this.isSignedIn = true
-            this.isAuthReady = true
+  private resetAuthState(status: AuthStatus = 'signed_out'): void {
+    this.user = status === 'reauth_required' ? this.user : null
+    this.token = null
+    if (status !== 'reauth_required') {
+      this.did = null
+    }
+    this.tokenScope = null
+    this.nextUserRecoveryAt = 0
+    this.updateAuthStatus(status)
+  }
+
+  private async clearStoredAuth(): Promise<void> {
+    await this.storage.remove(STORAGE_KEYS.REFRESH_TOKEN)
+    await this.storage.remove(STORAGE_KEYS.USER_INFO)
+    await this.storage.remove(STORAGE_KEYS.REDIRECT_URI)
+    await this.storage.remove(STORAGE_KEYS.CODE_VERIFIER)
+    await this.storage.remove(STORAGE_KEYS.SERVER_URL)
+    await this.storage.remove(STORAGE_KEYS.PDS_ENDPOINTS)
+  }
+
+  private isNetworkError(error: unknown): boolean {
+    if (error instanceof TypeError) return true
+    if (error instanceof Error) {
+      return (
+        error.message.includes('offline') || error.message.includes('Network')
+      )
+    }
+    return false
+  }
+
+  private async getRefreshToken(): Promise<string | null> {
+    const storedRefreshToken = await this.storage.get(
+      STORAGE_KEYS.REFRESH_TOKEN,
+    )
+    if (storedRefreshToken) {
+      log('Using refresh token from storage')
+      if (this.token && this.token.refresh_token !== storedRefreshToken) {
+        this.token = { ...this.token, refresh_token: storedRefreshToken }
+      }
+      return storedRefreshToken
+    }
 
-            if (this.freshSignIn) {
-                this.freshSignIn = false
-                this.broadcastSignIn()
-            } else {
-                this.broadcastTokenRefresh()
-            }
+    const memoryRefreshToken = this.token?.refresh_token ?? null
+    if (memoryRefreshToken) {
+      log('Using refresh token from memory fallback')
+    } else {
+      log('No refresh token available in storage or memory')
+    }
+    return memoryRefreshToken
+  }
+
+  private async syncRefreshTokenFromStorage(): Promise<void> {
+    const storedRefreshToken = await this.storage.get(
+      STORAGE_KEYS.REFRESH_TOKEN,
+    )
+    if (
+      storedRefreshToken &&
+      this.token &&
+      this.token.refresh_token !== storedRefreshToken
+    ) {
+      this.token = { ...this.token, refresh_token: storedRefreshToken }
+      log('Synced refresh token from shared storage into memory')
+    }
+  }
+
+  private applyTokenClaims(decoded: JwtClaims): void {
+    this.did = decoded.sub || null
+    this.tokenScope = decoded.scope || null
+  }
+
+  private broadcastSessionUpdate(): void {
+    if (this.freshSignIn) {
+      this.freshSignIn = false
+      this.broadcastSignIn()
+    } else {
+      this.broadcastTokenRefresh()
+    }
+  }
+
+  private async handleUserFetchFailure(): Promise<void> {
+    if (this.isCompatibleUser(this.user)) {
+      log('Preserving existing user after userinfo failure')
+    } else if (this.user) {
+      log('Discarding stale in-memory user after userinfo failure')
+      this.user = null
+    }
 
-            this.notify()
+    if (!this.user) {
+      const cached = await this.storage.get(STORAGE_KEYS.USER_INFO)
+      if (cached) {
+        try {
+          const parsed = JSON.parse(cached) as User
+          if (this.isCompatibleUser(parsed)) {
+            this.user = parsed
+            log('Recovered cached user after userinfo failure')
+          } else {
+            log('Cached user did not match the active session')
+          }
         } catch (error) {
-            log('Failed to fetch user info:', error)
-            this.isAuthReady = true
-            this.notify()
+          log('Failed to parse cached user after userinfo failure:', error)
         }
+      }
     }
 
-    /**
-     * Exchange an auth code or refresh token for an access token.
-     * Handles mutex (one in-flight refresh), token validation, and
-     * triggers processNewToken on success.
-     */
-    private async exchangeToken(codeOrRefreshToken: string, isRefreshToken: boolean): Promise<Token | null> {
-        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.user) {
+      log('No compatible cached user available after userinfo failure')
+      this.nextUserRecoveryAt = Date.now() + USER_RECOVERY_RETRY_COOLDOWN_MS
+    } else {
+      this.nextUserRecoveryAt = 0
+    }
 
-        if (isRefreshToken && this.refreshPromise) {
-            log('Reusing in-flight refresh token request')
-            return this.refreshPromise
-        }
+    if (this.authStatus === 'bootstrapping') {
+      this.updateAuthStatus(this.token ? 'authenticated' : 'recovering')
+    }
+    this.notify()
+  }
+
+  private isCompatibleUser(user: User | null): boolean {
+    if (!user) return false
+    if (!this.did) return true
+    return user.sub === this.did
+  }
+
+  private async recoverMissingUserProfile(
+    reason: string,
+    accessToken?: string,
+  ): Promise<void> {
+    if (!this.isSignedIn || this.user) return
+    const now = Date.now()
+    if (this.nextUserRecoveryAt > now) {
+      log(
+        `Skipping user profile recovery on ${reason} until ${new Date(this.nextUserRecoveryAt).toISOString()}`,
+      )
+      return
+    }
+    log(`Attempting user profile recovery on ${reason}`)
+    const token = accessToken ?? (await this.getToken())
+    if (this.user) return
+    await this.fetchUser(token)
+  }
+
+  private isDefinitiveTokenErrorCode(code: unknown): code is string {
+    return typeof code === 'string' && DEFINITIVE_TOKEN_ERRORS.has(code)
+  }
+
+  private isDefinitiveAuthFailure(error: unknown): boolean {
+    return error instanceof DefinitiveAuthError
+  }
+
+  /**
+   * Centralised auth status setter. Derives `isSignedIn` and `isAuthReady`
+   * from the status so they stay consistent.
+   *
+   * `isSignedIn` is intentionally `true` during `reauth_required` so the
+   * UI layer can still display user info while prompting re-authentication.
+   * Consumers should check `authStatus` (or a future convenience getter)
+   * when they need to distinguish "healthy session" from "needs re-auth".
+   */
+  private updateAuthStatus(
+    status: AuthStatus,
+    errorCode: string | null = null,
+  ): void {
+    this.authStatus = status
+    this.authErrorCode = errorCode
+    this.isSignedIn =
+      status === 'authenticated' ||
+      status === 'recovering' ||
+      status === 'reauth_required'
+    this.isAuthReady = status !== 'bootstrapping'
+  }
+
+  private async clearStoredSessionTokens(): Promise<void> {
+    await this.storage.remove(STORAGE_KEYS.REFRESH_TOKEN)
+    await this.storage.remove(STORAGE_KEYS.REDIRECT_URI)
+    await this.storage.remove(STORAGE_KEYS.CODE_VERIFIER)
+  }
+
+  private async restoreStoredSession(reason: string): Promise<void> {
+    const refreshToken = await this.getRefreshToken()
+    if (!refreshToken) {
+      log(`No stored refresh token available during ${reason}`)
+      await this.restoreCachedUser({ hasRecoverableSession: false })
+      return
+    }
 
-        if (!isRefreshToken && this.codeExchangePromise) {
-            log('Reusing in-flight code exchange request')
-            return this.codeExchangePromise
-        }
+    log(`Restoring stored session during ${reason}`)
+    await this.restoreCachedUser({ hasRecoverableSession: true })
 
-        const tokenPromise = (async (): Promise<Token | null> => {
-            try {
-                if (!this.isOnline) {
-                    log('Network is offline, marking refresh as pending')
-                    this.pendingRefresh = true
-                    throw new Error('Network offline - refresh will be retried when online')
-                }
-
-                const endpoints = await this.getActivePdsEndpoints()
-                let requestBody: any
-
-                if (isRefreshToken) {
-                    requestBody = {
-                        grant_type: 'refresh_token',
-                        refresh_token: codeOrRefreshToken
-                    }
-                    if (this.config.projectId) {
-                        requestBody.client_id = normalizeClientId(this.config.projectId, this.adminHostname)
-                    }
-                } else {
-                    requestBody = {
-                        grant_type: 'authorization_code',
-                        code: codeOrRefreshToken
-                    }
-
-                    const storedRedirectUri = await this.storage.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')
-                    }
-
-                    // PKCE: include code_verifier from the authorization request
-                    const codeVerifier = await this.storage.get(STORAGE_KEYS.CODE_VERIFIER)
-                    if (codeVerifier) {
-                        requestBody.code_verifier = codeVerifier
-                    }
-
-                    if (this.config.projectId) {
-                        requestBody.client_id = normalizeClientId(this.config.projectId, this.adminHostname)
-                    }
-                }
-
-                log('Token exchange request body:', {
-                    ...requestBody,
-                    ...(isRefreshToken ? { refresh_token: '[REDACTED]' } : { code: '[REDACTED]' }),
-                    ...(requestBody.code_verifier ? { code_verifier: '[REDACTED]' } : {}),
-                })
-
-                const token = await fetch(endpoints.token_endpoint, {
-                    method: 'POST',
-                    headers: { 'Content-Type': 'application/json' },
-                    body: JSON.stringify(requestBody)
-                })
-                    .then(response => response.json())
-                    .catch(error => {
-                        log('Network error fetching token:', error)
-                        if (!this.isOnline) {
-                            this.pendingRefresh = true
-                            throw new Error('Network offline - refresh will be retried when online')
-                        }
-                        throw new Error('Network error during token refresh')
-                    })
-
-                if (token.access_token) {
-                    try {
-                        const decoded = jwtDecode<{ typ?: string }>(token.access_token)
-                        if (decoded.typ === 'refresh') {
-                            log('Error: received refresh token as access token')
-                            throw new Error('Invalid token: received refresh token instead of access token')
-                        }
-                    } catch (decodeError) {
-                        if ((decodeError as Error).message.includes('Invalid token')) {
-                            throw decodeError
-                        }
-                        log('Warning: could not decode access token for type check:', decodeError)
-                    }
-                }
-
-                if (token.error) {
-                    log('error fetching token', token.error)
-
-                    if (typeof token.error === 'string' && (token.error.includes('network') || token.error.includes('timeout'))) {
-                        this.pendingRefresh = true
-                        throw new Error('Network issue - refresh will be retried when online')
-                    }
-
-                    await this.clearStoredAuth()
-                    this.resetAuthState()
-                    this.notify()
-                    throw new Error(`Token refresh failed: ${token.error}`)
-                } else {
-                    this.token = token
-                    this.pendingRefresh = false
-
-                    if (token.refresh_token) {
-                        await this.storage.set(STORAGE_KEYS.REFRESH_TOKEN, token.refresh_token)
-                        log('Updated refresh token in storage')
-                    }
-
-                    if (!isRefreshToken) {
-                        await this.storage.remove(STORAGE_KEYS.REDIRECT_URI)
-                        await this.storage.remove(STORAGE_KEYS.CODE_VERIFIER)
-                        log('Cleaned up redirect_uri and code_verifier from storage after successful exchange')
-                    }
-
-                    this.reportConnection(token.access_token).catch(() => {})
-
-                    await this.processNewToken()
-                }
-
-                return token
-            } catch (error) {
-                log('Token refresh error:', error)
-
-                if (!this.isNetworkError(error)) {
-                    await this.clearStoredAuth()
-                    this.resetAuthState()
-                    this.notify()
-                }
-
-                throw error
-            }
-        })()
+    if (!this.isOnline) {
+      return
+    }
 
-        if (isRefreshToken) {
-            this.refreshPromise = tokenPromise
-            tokenPromise.finally(() => {
-                if (this.refreshPromise === tokenPromise) {
-                    this.refreshPromise = null
-                    log('Cleared refresh promise reference')
-                }
-            })
-        } else {
-            this.codeExchangePromise = tokenPromise
-            tokenPromise.finally(() => {
-                if (this.codeExchangePromise === tokenPromise) {
-                    this.codeExchangePromise = null
-                    log('Cleared code exchange promise reference')
-                }
-            })
+    this.exchangeToken(refreshToken, true).catch(async (error) => {
+      log(`Stored session refresh failed during ${reason}:`, error)
+      if (this.isDefinitiveAuthFailure(error)) {
+        return
+      }
+      await this.restoreCachedUser({ hasRecoverableSession: true })
+    })
+  }
+
+  private async handleExternalTokenRefresh(data: {
+    accessToken?: string
+    did?: string
+    tokenScope?: string
+  }): Promise<void> {
+    await this.syncRefreshTokenFromStorage()
+    const refreshToken = await this.getRefreshToken()
+    if (data.accessToken && refreshToken) {
+      try {
+        const decoded = jwtDecode<JwtClaims>(data.accessToken)
+        const expiresIn =
+          decoded.exp != null
+            ? Math.max(0, decoded.exp - Math.floor(Date.now() / 1000))
+            : 0
+        this.token = {
+          access_token: data.accessToken,
+          token_type: 'Bearer',
+          expires_in: expiresIn,
+          refresh_token: refreshToken,
         }
-
-        return tokenPromise
+        this.applyTokenClaims(decoded)
+      } catch (error) {
+        log('Failed to decode token refreshed by another tab:', error)
+        this.token = {
+          access_token: data.accessToken,
+          token_type: 'Bearer',
+          expires_in: 0,
+          refresh_token: refreshToken,
+        }
+      }
+      if (this.authStatus !== 'reauth_required') {
+        this.updateAuthStatus('authenticated')
+      }
+    } else if (refreshToken) {
+      await this.restoreCachedUser({ hasRecoverableSession: true })
     }
 
-    private resetAuthState(): void {
-        this.user = null
-        this.isSignedIn = false
-        this.token = null
-        this.did = null
-        this.tokenScope = null
-        this.isAuthReady = true
+    if (data.did) this.did = data.did
+    if (data.tokenScope) this.tokenScope = data.tokenScope
+    this.notify()
+  }
+
+  private async fetchCurrentSession(
+    accessToken: string,
+  ): Promise<CurrentSessionInfo | null> {
+    const endpoints = await this.getActivePdsEndpoints()
+    const response = await fetch(`${endpoints.pds_url}/auth/session`, {
+      method: 'GET',
+      headers: { Authorization: `Bearer ${accessToken}` },
+    })
+    const data = (await response.json().catch(() => ({}))) as CurrentSessionInfo
+
+    if (response.status === 401 && data.reauth_required) {
+      await this.markReauthRequired(data.error || 'invalid_session')
+      throw new DefinitiveAuthError(data.error || 'invalid_session')
     }
 
-    private async clearStoredAuth(): Promise<void> {
-        await this.storage.remove(STORAGE_KEYS.REFRESH_TOKEN)
-        await this.storage.remove(STORAGE_KEYS.USER_INFO)
-        await this.storage.remove(STORAGE_KEYS.REDIRECT_URI)
-        await this.storage.remove(STORAGE_KEYS.CODE_VERIFIER)
-        await this.storage.remove(STORAGE_KEYS.SERVER_URL)
-        await this.storage.remove(STORAGE_KEYS.PDS_ENDPOINTS)
+    if (!response.ok) {
+      throw new Error(`Failed to reconcile session: ${response.status}`)
     }
 
-    private isNetworkError(error: unknown): boolean {
-        if (error instanceof Error) {
-            return error.message.includes('offline') || error.message.includes('Network')
+    return data
+  }
+
+  private async markReauthRequired(
+    code: string,
+    options?: { broadcast?: boolean },
+  ): Promise<void> {
+    log('Marking auth session as requiring reauthentication:', code)
+    await this.clearStoredSessionTokens()
+    if (!this.user) {
+      const cached = await this.storage.get(STORAGE_KEYS.USER_INFO)
+      if (cached) {
+        try {
+          this.user = JSON.parse(cached)
+        } catch {
+          /* ignore corrupted cache */
         }
-        return false
+      }
+    }
+    this.token = null
+    this.tokenScope = null
+    this.nextUserRecoveryAt = 0
+    this.updateAuthStatus('reauth_required', code)
+    if (options?.broadcast !== false) {
+      this.broadcastSessionInvalidated(code)
     }
+    this.notify()
+  }
 }