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

package/dist/index.mjs

@@ -71,6 +71,7 @@ var init_syncProtocol = __esm({
           var requestId = 0;
           var acceptCallbacks = {};
           var refreshTimer = null;
+          var pendingTokenUpdate = null;
           log("Connecting to", url);
           var ws = new WebSocket(url);
           function sendChanges(changes2, baseRevision2, partial2, onChangesAccepted2) {
@@ -93,6 +94,12 @@ var init_syncProtocol = __esm({
               refreshTimer = null;
             }
           }
+          function sendTokenUpdate(token) {
+            if (ws.readyState !== WebSocket.OPEN) return false;
+            pendingTokenUpdate = token;
+            ws.send(JSON.stringify({ type: "tokenUpdate", authToken: token }));
+            return true;
+          }
           function resolveGetToken() {
             var fn = getTokenGetter(url);
             if (!fn) throw new Error("No token getter registered for " + url);
@@ -108,10 +115,8 @@ var init_syncProtocol = __esm({
             refreshTimer = setTimeout(async function() {
               try {
                 var newToken = await resolveGetToken()({ forceRefresh: true });
-                if (ws.readyState === WebSocket.OPEN) {
+                if (sendTokenUpdate(newToken)) {
                   log("Sending tokenUpdate on existing WebSocket");
-                  ws.send(JSON.stringify({ type: "tokenUpdate", authToken: newToken }));
-                  scheduleTokenRefresh(newToken);
                 }
               } catch (err) {
                 log("Proactive token refresh failed (non-fatal):", err);
@@ -137,14 +142,34 @@ var init_syncProtocol = __esm({
               onError("Authentication failed: " + (err.message || err), RECONNECT_DELAY);
             }
           };
+          function handleVisibilityResume() {
+            if (document.visibilityState === "visible" && ws.readyState === WebSocket.OPEN) {
+              log("Page became visible - refreshing token for WebSocket");
+              resolveGetToken()({ forceRefresh: true }).then(function(newToken) {
+                sendTokenUpdate(newToken);
+              }).catch(function(err) {
+                log("Token refresh on visibility resume failed:", err);
+              });
+            }
+          }
+          if (typeof document !== "undefined") {
+            document.addEventListener("visibilitychange", handleVisibilityResume);
+          }
+          function cleanupVisibilityListener() {
+            if (typeof document !== "undefined") {
+              document.removeEventListener("visibilitychange", handleVisibilityResume);
+            }
+          }
           ws.onerror = function(event) {
             clearRefreshTimer();
+            cleanupVisibilityListener();
             ws.close();
             log("ws.onerror", event);
             onError(event?.message, RECONNECT_DELAY);
           };
           ws.onclose = function(event) {
             clearRefreshTimer();
+            cleanupVisibilityListener();
             onError("Socket closed: " + event.reason, RECONNECT_DELAY);
           };
           var isFirstRound = true;
@@ -181,11 +206,25 @@ var init_syncProtocol = __esm({
                     },
                     disconnect: function() {
                       clearRefreshTimer();
+                      cleanupVisibilityListener();
                       ws.close();
                     }
                   });
                   isFirstRound = false;
                 }
+              } else if (requestFromServer.type == "tokenUpdateAck") {
+                if (requestFromServer.ok) {
+                  scheduleTokenRefresh(requestFromServer.authToken || pendingTokenUpdate);
+                  pendingTokenUpdate = null;
+                } else {
+                  log("tokenUpdate rejected by server:", requestFromServer.code || requestFromServer.message);
+                  pendingTokenUpdate = null;
+                  ws.close(4001, requestFromServer.code || "token_update_failed");
+                  onError(
+                    requestFromServer.message || "Authentication refresh failed",
+                    RECONNECT_DELAY
+                  );
+                }
               } else if (requestFromServer.type == "ack") {
                 var requestId2 = requestFromServer.requestId;
                 var acceptCallback = acceptCallbacks[requestId2.toString()];
@@ -220,7 +259,7 @@ var init_syncProtocol = __esm({
 var version;
 var init_package = __esm({
   "package.json"() {
-    version = "0.8.0-beta.2";
+    version = "0.8.0-beta.4";
   }
 });
 
@@ -305,7 +344,7 @@ function cleanOAuthParamsFromUrl() {
     const url = new URL(window.location.href);
     url.searchParams.delete("code");
     url.searchParams.delete("state");
-    window.history.pushState({}, document.title, url.pathname + url.search);
+    window.history.replaceState({}, document.title, url.pathname + url.search);
     log("Cleaned OAuth parameters from URL");
   }
 }
@@ -363,6 +402,8 @@ var init_context = __esm({
     BasicContext = createContext({
       isReady: false,
       isSignedIn: false,
+      authStatus: "bootstrapping",
+      authErrorCode: null,
       user: null,
       did: null,
       scope: null,
@@ -1018,7 +1059,14 @@ var init_BasicDevToolbar = __esm({
 });
 
 // src/AuthContext.tsx
-import { useCallback as useCallback2, useEffect, useRef, useState as useState2, Suspense, lazy } from "react";
+import {
+  useCallback as useCallback2,
+  useEffect,
+  useRef,
+  useState as useState2,
+  Suspense,
+  lazy
+} from "react";
 
 // src/sync/index.ts
 init_config();
@@ -1612,6 +1660,21 @@ async function resolveHandle(handle) {
 // src/core/auth/AuthManager.ts
 init_network();
 init_config();
+var DEFINITIVE_TOKEN_ERRORS = /* @__PURE__ */ new Set([
+  "invalid_grant",
+  "invalid_client",
+  "unauthorized_client"
+]);
+var USER_RECOVERY_RETRY_COOLDOWN_MS = 3e4;
+var SESSION_RECONCILE_THROTTLE_MS = 5e3;
+var DefinitiveAuthError = class extends Error {
+  code;
+  constructor(code) {
+    super(`Definitive auth failure: ${code}`);
+    this.name = "DefinitiveAuthError";
+    this.code = code;
+  }
+};
 function generateCodeVerifier() {
   const array = new Uint8Array(32);
   crypto.getRandomValues(array);
@@ -1619,7 +1682,9 @@ function generateCodeVerifier() {
 }
 async function generateCodeChallenge(verifier) {
   if (typeof crypto === "undefined" || !crypto.subtle) {
-    log("crypto.subtle unavailable (non-secure context?) -- falling back to plain PKCE challenge");
+    log(
+      "crypto.subtle unavailable (non-secure context?) -- falling back to plain PKCE challenge"
+    );
     return { challenge: verifier, method: "plain" };
   }
   const encoder = new TextEncoder();
@@ -1640,6 +1705,8 @@ var AuthManager = class {
   user = null;
   isSignedIn = false;
   isAuthReady = false;
+  authStatus = "bootstrapping";
+  authErrorCode = null;
   did = null;
   /** Space-separated scopes granted in the current access token */
   tokenScope = null;
@@ -1656,6 +1723,9 @@ var AuthManager = class {
   pendingRefresh = false;
   isOnline = typeof navigator !== "undefined" ? navigator.onLine : true;
   channel = null;
+  nextUserRecoveryAt = 0;
+  sessionCheckPromise = null;
+  lastSessionCheckAt = 0;
   constructor(config, storage, notify) {
     this.config = config;
     this.storage = storage;
@@ -1670,31 +1740,26 @@ var AuthManager = class {
       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();
+          void this.handleExternalTokenRefresh(event.data);
         }
         if (event.data?.type === "signed_in") {
-          log("Received sign-in from another tab, reloading");
-          if (typeof window !== "undefined") {
-            window.location.reload();
-          }
+          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, reloading");
-          this.user = null;
-          this.isSignedIn = false;
-          this.token = null;
-          this.did = null;
-          this.tokenScope = null;
+          log("Received sign-out from another tab");
+          this.resetAuthState("signed_out");
           this.notify();
           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");
@@ -1714,6 +1779,9 @@ var AuthManager = class {
   broadcastSignOut() {
     this.channel?.postMessage({ type: "signed_out" });
   }
+  broadcastSessionInvalidated(code) {
+    this.channel?.postMessage({ type: "session_invalidated", code });
+  }
   // ------------------------------------------------------------------
   // Public API
   // ------------------------------------------------------------------
@@ -1722,7 +1790,11 @@ var AuthManager = class {
    * from refresh token, or load cached user for offline mode.
    */
   async initialize() {
-    await this.storage.set(STORAGE_KEYS.DEBUG, this.config.debug ? "true" : "false");
+    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");
@@ -1734,7 +1806,7 @@ var AuthManager = class {
       if (params.has("code")) {
         const code = params.get("code");
         if (!code) {
-          this.isAuthReady = true;
+          this.updateAuthStatus("signed_out");
           this.notify();
           return;
         }
@@ -1742,7 +1814,7 @@ var AuthManager = class {
         const urlState = params.get("state");
         if (!state || state !== urlState) {
           log("error: auth state does not match");
-          this.isAuthReady = true;
+          this.updateAuthStatus("signed_out");
           this.notify();
           await this.storage.remove(STORAGE_KEYS.AUTH_STATE);
           cleanOAuthParamsFromUrl();
@@ -1753,31 +1825,18 @@ var AuthManager = class {
         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 {
-        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();
-        }
+        await this.restoreStoredSession("initialize");
       }
     } catch (e) {
       log("error getting token", e);
+      this.updateAuthStatus("signed_out");
+      this.notify();
     }
   }
   /**
@@ -1787,7 +1846,7 @@ var AuthManager = class {
   async getToken(options) {
     log("getting token...");
     if (!this.token) {
-      const refreshToken = await this.storage.get(STORAGE_KEYS.REFRESH_TOKEN);
+      const refreshToken = await this.getRefreshToken();
       if (refreshToken) {
         log("No token in memory, attempting to refresh from storage");
         if (this.refreshPromise) {
@@ -1810,7 +1869,12 @@ var AuthManager = class {
         } 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(
+              "Network offline - authentication will be retried when online"
+            );
+          }
+          if (!this.isDefinitiveAuthFailure(error)) {
+            throw error;
           }
           throw new Error("Authentication expired. Please sign in again.");
         }
@@ -1823,12 +1887,16 @@ var AuthManager = class {
     const isExpired = decoded.exp && decoded.exp < Date.now() / 1e3 + expirationBuffer;
     const shouldRefresh = isExpired || options?.forceRefresh === true;
     if (shouldRefresh) {
-      log(options?.forceRefresh ? "force refreshing token..." : "token is expired - refreshing ...");
+      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 || "";
+          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)) {
@@ -1838,24 +1906,31 @@ var AuthManager = class {
           throw error;
         }
       }
-      const refreshToken = this.token.refresh_token || await this.storage.get(STORAGE_KEYS.REFRESH_TOKEN);
+      const refreshToken = await this.getRefreshToken();
       if (refreshToken) {
         try {
           const newToken = await this.exchangeToken(refreshToken, true);
-          return newToken?.access_token || "";
+          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");
       }
     }
-    return this.token.access_token || "";
+    if (!this.token.access_token)
+      throw new Error("Token exists but access_token is empty");
+    return this.token.access_token;
   }
   async getSignInUrl(redirectUri, endpoints) {
     log("getting sign in link...");
@@ -1863,8 +1938,13 @@ var AuthManager = class {
       throw new Error("Project ID is required to generate sign-in link");
     }
     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.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://")) {
@@ -1933,7 +2013,10 @@ var AuthManager = class {
       if (state) {
         const storedState = await this.storage.get(STORAGE_KEYS.AUTH_STATE);
         if (storedState && storedState !== state) {
-          log("State parameter mismatch:", { provided: state, stored: storedState });
+          log("State parameter mismatch:", {
+            provided: state,
+            stored: storedState
+          });
           return { success: false, error: "State parameter mismatch" };
         }
       }
@@ -1949,6 +2032,7 @@ var AuthManager = class {
       }
     } catch (error) {
       log("signInWithCode error:", error);
+      this.freshSignIn = false;
       return {
         success: false,
         error: error.message || "Authentication failed"
@@ -1961,13 +2045,64 @@ var AuthManager = class {
    */
   async signOut() {
     log("signing out!");
-    this.resetAuthState();
+    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 = "manual", options) {
+    if (this.authStatus === "signed_out" || this.authStatus === "reauth_required") {
+      return;
+    }
+    if (!this.isOnline) {
+      this.updateAuthStatus("recovering", this.authErrorCode);
+      this.notify();
+      return;
+    }
+    const throttleMs = options?.throttleMs ?? SESSION_RECONCILE_THROTTLE_MS;
+    const forceRefresh = options?.forceRefresh === true;
+    const now = Date.now();
+    if (this.sessionCheckPromise) {
+      return this.sessionCheckPromise;
+    }
+    if (!forceRefresh && now - this.lastSessionCheckAt < throttleMs) {
+      return;
+    }
+    this.lastSessionCheckAt = now;
+    let sessionCheck = null;
+    sessionCheck = (async () => {
+      try {
+        const accessToken = await this.getToken(
+          forceRefresh ? { forceRefresh: true } : void 0
+        );
+        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) {
     if (!this.tokenScope) return false;
     return this.tokenScope.split(/[\s,]+/).filter(Boolean).includes(scope);
@@ -1983,33 +2118,62 @@ var AuthManager = class {
     return requested.filter((s) => !granted.has(s));
   }
   /**
-   * Register online/offline handlers that retry pending refreshes.
+   * 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() {
     const handleOnline = async () => {
       log("Network came back online");
       this.isOnline = true;
-      if (this.pendingRefresh && this.token) {
+      if (this.pendingRefresh) {
         log("Retrying pending token refresh");
         this.pendingRefresh = false;
-        const refreshToken = this.token.refresh_token || await this.storage.get(STORAGE_KEYS.REFRESH_TOKEN);
+        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");
+      }
     };
     const handleOffline = () => {
       log("Network went offline");
       this.isOnline = false;
     };
+    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);
+        });
+      }
+    };
     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);
+      if (typeof document !== "undefined") {
+        document.removeEventListener("visibilitychange", handleVisibilityChange);
+      }
     };
   }
   // ------------------------------------------------------------------
@@ -2048,12 +2212,18 @@ var AuthManager = class {
       if (elapsed < 24 * 60 * 60 * 1e3) 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());
+      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);
@@ -2064,54 +2234,46 @@ var AuthManager = class {
    */
   async processNewToken() {
     if (!this.token) {
-      this.isAuthReady = true;
+      this.updateAuthStatus("signed_out");
       this.notify();
       return;
     }
     try {
       const decoded = jwtDecode(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() / 1e3 + 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);
-      }
+      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.isAuthReady = true;
+      this.updateAuthStatus("recovering");
       this.notify();
     }
   }
+  async restoreCachedUser(options) {
+    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 {
+      }
+    } else {
+      this.user = null;
+    }
+    this.updateAuthStatus(
+      options?.hasRecoverableSession ? "recovering" : "signed_out"
+    );
+    this.notify();
+  }
   async fetchUser(accessToken) {
     log("fetching user");
     try {
       const endpoints = await this.getActivePdsEndpoints();
       const response = await fetch(endpoints.userinfo_endpoint, {
         method: "GET",
-        headers: { "Authorization": `Bearer ${accessToken}` }
+        headers: { Authorization: `Bearer ${accessToken}` }
       });
       if (!response.ok) {
         throw new Error(`Failed to fetch user info: ${response.status}`);
@@ -2122,24 +2284,22 @@ var AuthManager = class {
         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.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;
-      this.isSignedIn = true;
-      this.isAuthReady = true;
-      if (this.freshSignIn) {
-        this.freshSignIn = false;
-        this.broadcastSignIn();
-      } else {
-        this.broadcastTokenRefresh();
+      if (this.authStatus !== "reauth_required") {
+        this.updateAuthStatus("authenticated");
       }
+      this.nextUserRecoveryAt = 0;
       this.notify();
     } catch (error) {
       log("Failed to fetch user info:", error);
-      this.isAuthReady = true;
-      this.notify();
+      await this.handleUserFetchFailure();
     }
   }
   /**
@@ -2166,7 +2326,9 @@ var AuthManager = class {
         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");
+          throw new Error(
+            "Network offline - refresh will be retried when online"
+          );
         }
         const endpoints = await this.getActivePdsEndpoints();
         let requestBody;
@@ -2176,26 +2338,36 @@ var AuthManager = class {
             refresh_token: codeOrRefreshToken
           };
           if (this.config.projectId) {
-            requestBody.client_id = normalizeClientId(this.config.projectId, this.adminHostname);
+            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);
+          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");
           }
-          const codeVerifier = await this.storage.get(STORAGE_KEYS.CODE_VERIFIER);
+          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);
+            requestBody.client_id = normalizeClientId(
+              this.config.projectId,
+              this.adminHostname
+            );
           }
         }
         log("Token exchange request body:", {
@@ -2211,7 +2383,9 @@ var AuthManager = class {
           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 offline - refresh will be retried when online"
+            );
           }
           throw new Error("Network error during token refresh");
         });
@@ -2220,36 +2394,52 @@ var AuthManager = class {
             const decoded = jwtDecode(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");
+              throw new Error(
+                "Invalid token: received refresh token instead of access token"
+              );
             }
           } catch (decodeError) {
             if (decodeError.message.includes("Invalid token")) {
               throw decodeError;
             }
-            log("Warning: could not decode access token for type check:", 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");
+            throw new Error(
+              "Network issue - refresh will be retried when online"
+            );
+          }
+          if (this.isDefinitiveTokenErrorCode(token.error)) {
+            await this.markReauthRequired(token.error);
+            throw new DefinitiveAuthError(token.error);
           }
-          await this.clearStoredAuth();
-          this.resetAuthState();
-          this.notify();
           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);
+            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");
+            log(
+              "Cleaned up redirect_uri and code_verifier from storage after successful exchange"
+            );
           }
           this.reportConnection(token.access_token).catch(() => {
           });
@@ -2258,10 +2448,12 @@ var AuthManager = class {
         return token;
       } catch (error) {
         log("Token refresh error:", error);
-        if (!this.isNetworkError(error)) {
-          await this.clearStoredAuth();
-          this.resetAuthState();
-          this.notify();
+        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");
         }
         throw error;
       }
@@ -2285,13 +2477,15 @@ var AuthManager = class {
     }
     return tokenPromise;
   }
-  resetAuthState() {
-    this.user = null;
-    this.isSignedIn = false;
+  resetAuthState(status = "signed_out") {
+    this.user = status === "reauth_required" ? this.user : null;
     this.token = null;
-    this.did = null;
+    if (status !== "reauth_required") {
+      this.did = null;
+    }
     this.tokenScope = null;
-    this.isAuthReady = true;
+    this.nextUserRecoveryAt = 0;
+    this.updateAuthStatus(status);
   }
   async clearStoredAuth() {
     await this.storage.remove(STORAGE_KEYS.REFRESH_TOKEN);
@@ -2302,11 +2496,221 @@ var AuthManager = class {
     await this.storage.remove(STORAGE_KEYS.PDS_ENDPOINTS);
   }
   isNetworkError(error) {
+    if (error instanceof TypeError) return true;
     if (error instanceof Error) {
       return error.message.includes("offline") || error.message.includes("Network");
     }
     return false;
   }
+  async getRefreshToken() {
+    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;
+    }
+    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;
+  }
+  async syncRefreshTokenFromStorage() {
+    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");
+    }
+  }
+  applyTokenClaims(decoded) {
+    this.did = decoded.sub || null;
+    this.tokenScope = decoded.scope || null;
+  }
+  broadcastSessionUpdate() {
+    if (this.freshSignIn) {
+      this.freshSignIn = false;
+      this.broadcastSignIn();
+    } else {
+      this.broadcastTokenRefresh();
+    }
+  }
+  async handleUserFetchFailure() {
+    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;
+    }
+    if (!this.user) {
+      const cached = await this.storage.get(STORAGE_KEYS.USER_INFO);
+      if (cached) {
+        try {
+          const parsed = JSON.parse(cached);
+          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 parse cached user after userinfo failure:", error);
+        }
+      }
+    }
+    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 (this.authStatus === "bootstrapping") {
+      this.updateAuthStatus(this.token ? "authenticated" : "recovering");
+    }
+    this.notify();
+  }
+  isCompatibleUser(user) {
+    if (!user) return false;
+    if (!this.did) return true;
+    return user.sub === this.did;
+  }
+  async recoverMissingUserProfile(reason, accessToken) {
+    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);
+  }
+  isDefinitiveTokenErrorCode(code) {
+    return typeof code === "string" && DEFINITIVE_TOKEN_ERRORS.has(code);
+  }
+  isDefinitiveAuthFailure(error) {
+    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".
+   */
+  updateAuthStatus(status, errorCode = null) {
+    this.authStatus = status;
+    this.authErrorCode = errorCode;
+    this.isSignedIn = status === "authenticated" || status === "recovering" || status === "reauth_required";
+    this.isAuthReady = status !== "bootstrapping";
+  }
+  async clearStoredSessionTokens() {
+    await this.storage.remove(STORAGE_KEYS.REFRESH_TOKEN);
+    await this.storage.remove(STORAGE_KEYS.REDIRECT_URI);
+    await this.storage.remove(STORAGE_KEYS.CODE_VERIFIER);
+  }
+  async restoreStoredSession(reason) {
+    const refreshToken = await this.getRefreshToken();
+    if (!refreshToken) {
+      log(`No stored refresh token available during ${reason}`);
+      await this.restoreCachedUser({ hasRecoverableSession: false });
+      return;
+    }
+    log(`Restoring stored session during ${reason}`);
+    await this.restoreCachedUser({ hasRecoverableSession: true });
+    if (!this.isOnline) {
+      return;
+    }
+    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 });
+    });
+  }
+  async handleExternalTokenRefresh(data) {
+    await this.syncRefreshTokenFromStorage();
+    const refreshToken = await this.getRefreshToken();
+    if (data.accessToken && refreshToken) {
+      try {
+        const decoded = jwtDecode(data.accessToken);
+        const expiresIn = decoded.exp != null ? Math.max(0, decoded.exp - Math.floor(Date.now() / 1e3)) : 0;
+        this.token = {
+          access_token: data.accessToken,
+          token_type: "Bearer",
+          expires_in: expiresIn,
+          refresh_token: refreshToken
+        };
+        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 });
+    }
+    if (data.did) this.did = data.did;
+    if (data.tokenScope) this.tokenScope = data.tokenScope;
+    this.notify();
+  }
+  async fetchCurrentSession(accessToken) {
+    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(() => ({}));
+    if (response.status === 401 && data.reauth_required) {
+      await this.markReauthRequired(data.error || "invalid_session");
+      throw new DefinitiveAuthError(data.error || "invalid_session");
+    }
+    if (!response.ok) {
+      throw new Error(`Failed to reconcile session: ${response.status}`);
+    }
+    return data;
+  }
+  async markReauthRequired(code, options) {
+    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 {
+        }
+      }
+    }
+    this.token = null;
+    this.tokenScope = null;
+    this.nextUserRecoveryAt = 0;
+    this.updateAuthStatus("reauth_required", code);
+    if (options?.broadcast !== false) {
+      this.broadcastSessionInvalidated(code);
+    }
+    this.notify();
+  }
 };
 
 // src/AuthContext.tsx
@@ -2555,6 +2959,8 @@ function snapshotAuth(mgr) {
     isSignedIn: mgr.isSignedIn,
     hasToken: !!mgr.token,
     isAuthReady: mgr.isAuthReady,
+    authStatus: mgr.authStatus,
+    authErrorCode: mgr.authErrorCode,
     user: mgr.user,
     did: mgr.did,
     tokenScope: mgr.tokenScope
@@ -2589,6 +2995,8 @@ function BasicProvider({
     isSignedIn: false,
     hasToken: false,
     isAuthReady: false,
+    authStatus: "bootstrapping",
+    authErrorCode: null,
     user: null,
     did: null,
     tokenScope: null
@@ -2611,9 +3019,11 @@ function BasicProvider({
   const remoteDbRef = useRef(null);
   const [shouldConnect, setShouldConnect] = useState2(false);
   const [dbStatus, setDbStatus] = useState2("OFFLINE" /* OFFLINE */);
-  const [isReady, setIsReady] = useState2(false);
+  const [isDbReady, setIsDbReady] = useState2(false);
   const [error, setError] = useState2(null);
-  const [schemaDevInfo, setSchemaDevInfo] = useState2(null);
+  const [schemaDevInfo, setSchemaDevInfo] = useState2(
+    null
+  );
   const isDevMode = () => isDevelopment(debug);
   const refreshSchemaStatus = useCallback2(async () => {
     const s = schemaRef.current;
@@ -2653,10 +3063,16 @@ function BasicProvider({
   useEffect(() => {
     const runVersionUpdater = async () => {
       try {
-        const versionUpdater = createVersionUpdater(storageAdapter, version, getMigrations());
+        const versionUpdater = createVersionUpdater(
+          storageAdapter,
+          version,
+          getMigrations()
+        );
         const updateResult = await versionUpdater.checkAndUpdate();
         if (updateResult.updated) {
-          log(`App updated from ${updateResult.fromVersion} to ${updateResult.toVersion}`);
+          log(
+            `App updated from ${updateResult.fromVersion} to ${updateResult.toVersion}`
+          );
         } else {
           log(`App version ${updateResult.toVersion} is current`);
         }
@@ -2678,8 +3094,13 @@ function BasicProvider({
           const newStatus = getSyncStatus(status);
           setDbStatus(newStatus);
           if (newStatus === "ERROR_WILL_RETRY" /* ERROR_WILL_RETRY */) {
-            log("Sync entered ERROR_WILL_RETRY - proactively refreshing token");
-            authRef.current.getToken({ forceRefresh: true }).catch(() => {
+            log(
+              "Sync entered ERROR_WILL_RETRY - reconciling auth session before retry"
+            );
+            authRef.current.reconcileSession("sync retry", {
+              forceRefresh: true,
+              throttleMs: 0
+            }).catch(() => {
             });
           }
         });
@@ -2688,7 +3109,7 @@ function BasicProvider({
         } else {
           log("Sync is disabled");
         }
-        setIsReady(true);
+        setIsDbReady(true);
       }
     }
     function initRemoteDb() {
@@ -2699,7 +3120,7 @@ function BasicProvider({
             title: "Project ID Required",
             message: "Remote mode requires a project_id. Provide it via schema.project_id or the project_id prop."
           });
-          setIsReady(true);
+          setIsDbReady(true);
           return;
         }
         log("Initializing Basic Remote DB");
@@ -2711,11 +3132,20 @@ function BasicProvider({
           debug,
           onAuthError: (error2) => {
             log("RemoteDB auth error:", error2);
-            handleSignOut();
+            if (error2.errorType === "forbidden") {
+              log("403 Forbidden - user lacks required scope, not signing out");
+              return;
+            }
+            authRef.current.reconcileSession(`remote db ${error2.errorType}`, {
+              forceRefresh: error2.errorType !== "network",
+              throttleMs: 0
+            }).catch((reconcileError) => {
+              log("RemoteDB auth recovery failed:", reconcileError);
+            });
           }
         });
         setDbStatus("ONLINE" /* ONLINE */);
-        setIsReady(true);
+        setIsDbReady(true);
       }
     }
     async function checkSchema() {
@@ -2741,7 +3171,7 @@ function BasicProvider({
           title: "Basic Schema is invalid!",
           message: errorMessage
         });
-        setIsReady(true);
+        setIsDbReady(true);
         return null;
       }
       setSchemaDevInfo({
@@ -2758,7 +3188,9 @@ function BasicProvider({
           await initSyncDb({ shouldConnect: true });
         } else {
           if (result.schemaStatus.status === "unpublished") {
-            log("Schema not published yet (version 0) - sync is disabled. Publish your schema to enable sync.");
+            log(
+              "Schema not published yet (version 0) - sync is disabled. Publish your schema to enable sync."
+            );
           } else {
             log("Schema is invalid!", result.schemaStatus);
           }
@@ -2782,12 +3214,12 @@ function BasicProvider({
       if (dbMode === "remote" && project_id) {
         initRemoteDb();
       } else {
-        setIsReady(true);
+        setIsDbReady(true);
       }
     }
   }, []);
   useEffect(() => {
-    if (authState.hasToken && syncRef.current && authState.isSignedIn && shouldConnect) {
+    if (authState.hasToken && syncRef.current && authState.isSignedIn && authState.authStatus !== "reauth_required" && shouldConnect) {
       log("connecting to db...");
       syncRef.current?.connect({
         getToken: (opts) => authRef.current.getToken(opts),
@@ -2796,7 +3228,22 @@ function BasicProvider({
         log("error connecting to db", e);
       });
     }
-  }, [authState.isSignedIn, authState.hasToken, shouldConnect]);
+  }, [
+    authState.authStatus,
+    authState.isSignedIn,
+    authState.hasToken,
+    shouldConnect
+  ]);
+  useEffect(() => {
+    if (authState.authStatus !== "reauth_required" || !syncRef.current) {
+      return;
+    }
+    log("Auth requires reauthentication - disconnecting sync without deleting local DB");
+    setDbStatus("ERROR_TOKEN_EXPIRED" /* ERROR_TOKEN_EXPIRED */);
+    syncRef.current.disconnect({ ws_url: authConfig.ws_url }).catch((disconnectError) => {
+      log("Error disconnecting sync after auth invalidation:", disconnectError);
+    });
+  }, [authConfig.ws_url, authState.authStatus]);
   const handleSignOut = async () => {
     await authRef.current.signOut();
     if (syncRef.current) {
@@ -2804,11 +3251,13 @@ function BasicProvider({
         await syncRef.current.close();
         await syncRef.current.delete({ disableAutoOpen: false });
         syncRef.current = null;
-        window?.location?.reload();
       } catch (error2) {
         console.error("Error during database cleanup:", error2);
       }
     }
+    if (typeof window !== "undefined") {
+      window.location.reload();
+    }
   };
   const handleSignIn = async () => {
     try {
@@ -2847,6 +3296,8 @@ function BasicProvider({
   const contextValue = {
     isReady: authState.isAuthReady,
     isSignedIn: authState.isSignedIn,
+    authStatus: authState.authStatus,
+    authErrorCode: authState.authErrorCode,
     user: authState.user,
     did: authState.did,
     scope: authState.tokenScope,
@@ -2872,7 +3323,7 @@ function BasicProvider({
   return /* @__PURE__ */ jsxs2(BasicContext.Provider, { value: contextValue, children: [
     error && isDevMode() && /* @__PURE__ */ jsx2(ErrorDisplay, { error }),
     devToolbar && isDevMode() && /* @__PURE__ */ jsx2(Suspense, { fallback: null, children: /* @__PURE__ */ jsx2(BasicDevToolbar2, { debug }) }),
-    isReady && children
+    isDbReady && authState.isAuthReady && children
   ] });
 }
 function ErrorDisplay({ error }) {