@oxyhq/services 8.1.2 → 8.3.0

package/lib/module/ui/context/OxyContext.js

@@ -3,7 +3,10 @@
 import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
 import { OxyServices, oxyClient } from '@oxyhq/core';
 import { KeyManager } from '@oxyhq/core';
+import { runColdBoot, resolveCentralAuthUrl, parseSsoReturnFragment } from '@oxyhq/core';
 import { toast } from '@oxyhq/bloom';
+import { SSO_CALLBACK_PATH, ssoStateKey, ssoGuardKey, ssoDestKey, ssoNoSessionKey, isCentralIdPOrigin, guardActive } from "../utils/ssoBounce.js";
+import * as ssoBounce from "../utils/ssoBounce.js";
 import { useAuthStore } from "../stores/authStore.js";
 import { useShallow } from 'zustand/react/shallow';
 import { useSessionSocket } from "../hooks/useSessionSocket.js";
@@ -28,6 +31,71 @@ const OxyContext = /*#__PURE__*/createContext(null);
 // `../utils/activeAuthuser` so the session-management and auth-operations hooks
 // can share them without re-importing this 1k-line context file.
 
+/**
+ * Module-level run-once guard for the cold-boot `fedcm-silent` step.
+ *
+ * The FedCM silent step triggers a one-shot `navigator.credentials.get`
+ * handshake that must fire AT MOST ONCE per page load — otherwise a provider
+ * remount storm (route churn, StrictMode double-invoke, error-boundary
+ * recovery) becomes a credential request storm. A per-instance ref resets on
+ * every remount, so the guard must live at module scope. Keyed on
+ * `origin|baseURL` so two providers pointed at the same API from the same
+ * origin share one attempt; never cleared because only a fresh page load can
+ * change the central IdP session state, and a fresh page load starts a fresh
+ * module scope.
+ *
+ * This is a dedicated set — distinct from `useWebSSO`'s `silentSSOAttempted`
+ * (which guards the post-boot INTERACTIVE button path) and never a core
+ * module-level singleton (that re-evaluates under Metro web bundling and the
+ * guard would not hold).
+ */
+const servicesSilentAttempted = new Set();
+
+/**
+ * Build the `origin|baseURL` signature used as the silent-cold-boot guard key.
+ */
+function silentColdBootKey(oxyServices) {
+  const origin = typeof window !== 'undefined' ? window.location.origin : 'no-origin';
+  let baseURL = '';
+  try {
+    baseURL = oxyServices.getBaseURL?.() ?? '';
+  } catch {
+    baseURL = '';
+  }
+  return `${origin}|${baseURL}`;
+}
+
+/**
+ * Whether `idpOrigin` is a same-site, first-party host of the current page —
+ * i.e. it shares the page's registrable apex (last two labels), so a "no
+ * session" answer from its `/auth/session-check` iframe is authoritative for
+ * THIS app and may force a local sign-out.
+ *
+ * On a cross-site IdP (or any host whose relationship to the page can't be
+ * positively established) this returns `false`, so the visibility-driven check
+ * may surface a session-ended toast but MUST NOT clear local state — a
+ * third-party / undetermined IdP answer can never force logout. Returns `false`
+ * off-browser.
+ */
+function isSameSiteIdP(idpOrigin) {
+  if (typeof window === 'undefined') return false;
+  let idpHostname;
+  try {
+    idpHostname = new URL(idpOrigin).hostname;
+  } catch {
+    return false;
+  }
+  const pageHostname = window.location.hostname;
+  if (!idpHostname || !pageHostname) return false;
+  if (idpHostname === pageHostname) return true;
+  const apexOf = hostname => hostname.split('.').slice(-2).join('.');
+  const pageApex = apexOf(pageHostname);
+  // Require a real registrable apex (≥2 labels) AND an exact apex match AND that
+  // the IdP host is the page apex itself or a subdomain of it.
+  if (pageHostname.split('.').length < 2) return false;
+  if (apexOf(idpHostname) !== pageApex) return false;
+  return idpHostname === pageApex || idpHostname.endsWith(`.${pageApex}`);
+}
 let cachedUseFollowHook = null;
 const loadUseFollowHook = () => {
   if (cachedUseFollowHook) {
@@ -69,9 +137,19 @@ export const OxyProvider = ({
     if (providedOxyServices) {
       oxyServicesRef.current = providedOxyServices;
     } else if (baseURL) {
+      // Target the CENTRAL IdP for TRUE cross-domain SSO. Every RP
+      // (mention.earth, homiio.com, alia.onl, …) delegates to the one central
+      // `auth.oxy.so` — it owns the host-only `fedcm_session` cookie and the
+      // central session store reached via `api.oxy.so`, so a single sign-in
+      // there is observed by all RPs through the opaque-code `/sso` bounce.
+      // `resolveCentralAuthUrl(authWebUrl)` returns the explicit `authWebUrl`
+      // prop when provided (explicit always wins) and the central default
+      // otherwise. This is NOT per-apex auto-detection — central SSO is
+      // deliberately central. A consumer-provided `OxyServices` instance is
+      // never mutated; only the baseURL-only construction path applies this.
       oxyServicesRef.current = new OxyServices({
         baseURL,
-        authWebUrl,
+        authWebUrl: resolveCentralAuthUrl(authWebUrl),
         authRedirectUri
       });
     } else {
@@ -136,7 +214,9 @@ export const OxyProvider = ({
   }, [oxyServices]);
   const logger = useCallback((message, err) => {
     if (__DEV__) {
-      console.warn(`[OxyContext] ${message}`, err);
+      loggerUtil.warn(message, {
+        component: 'OxyContext'
+      }, err);
     }
   }, []);
   const storageKeys = useMemo(() => getStorageKeys(storageKeyPrefix), [storageKeyPrefix]);
@@ -355,6 +435,14 @@ export const OxyProvider = ({
   const onAuthStateChangeRef = useRef(onAuthStateChange);
   onAuthStateChangeRef.current = onAuthStateChange;
 
+  // `handleWebSSOSession` is declared further down (it depends on values that
+  // are only available there). The FedCM/iframe cold-boot steps need to commit
+  // a recovered session through it, so we route the call through a ref that is
+  // populated once the callback exists. The ref is assigned synchronously on
+  // every render before the cold-boot effect can fire (the effect is gated on
+  // `storage` + `initialized`, both of which settle after first render).
+  const handleWebSSOSessionRef = useRef(null);
+
   // Cold-boot session restore via the secure refresh cookies (web only).
   //
   // Calls `oxyServices.refreshAllSessions()` → `POST /auth/refresh-all` with
@@ -449,90 +537,363 @@ export const OxyProvider = ({
     onAuthStateChangeRef.current?.(fullUser);
     return true;
   }, [oxyServices, persistSessionDurably]);
+
+  // Native (and offline) stored-session restore — the ONLY restore path that
+  // runs on React Native, and the web fallback when no cross-domain step won.
+  //
+  // Verbatim-extracted from the previous `restoreSessionsFromStorage` body: it
+  // reads the durable `session_ids` / `active_session_id` slots, validates each
+  // stored session in parallel (bearer `validateSession`), and switches to the
+  // stored active session via the session-management `switchSession`. This body
+  // is platform-agnostic and gated by NO `enabled()` predicate so it runs on
+  // every platform — on native it is reached unconditionally (every web-only
+  // step ahead of it is disabled by `isWebBrowser()`), so native restore is
+  // exactly this and nothing else (no FedCM / iframe / refresh-all /
+  // handleAuthCallback).
+  const restoreStoredSession = useCallback(async () => {
+    if (!storage) {
+      return false;
+    }
+    const storedSessionIdsJson = await storage.getItem(storageKeys.sessionIds);
+    const storedSessionIds = storedSessionIdsJson ? JSON.parse(storedSessionIdsJson) : [];
+    const storedActiveSessionId = await storage.getItem(storageKeys.activeSessionId);
+    let validSessions = [];
+    if (storedSessionIds.length > 0) {
+      // Validate all sessions in parallel (with 8s timeout per session) to avoid
+      // sequential blocking that freezes the app on startup
+      const VALIDATION_TIMEOUT = 8000;
+      const results = await Promise.allSettled(storedSessionIds.map(async sessionId => {
+        const timeoutPromise = new Promise(resolve => setTimeout(() => resolve(null), VALIDATION_TIMEOUT));
+        const validationPromise = oxyServices.validateSession(sessionId, {
+          useHeaderValidation: true
+        }).catch(validationError => {
+          if (!isInvalidSessionError(validationError) && !isTimeoutOrNetworkError(validationError)) {
+            logger('Session validation failed during init', validationError);
+          } else if (__DEV__ && isTimeoutOrNetworkError(validationError)) {
+            loggerUtil.debug('Session validation timeout (expected when offline)', {
+              component: 'OxyContext',
+              method: 'restoreStoredSession'
+            }, validationError);
+          }
+          return null;
+        });
+        return Promise.race([validationPromise, timeoutPromise]).then(validation => {
+          if (validation?.valid && validation.user) {
+            const now = new Date();
+            return {
+              sessionId,
+              deviceId: '',
+              expiresAt: new Date(now.getTime() + 7 * 24 * 60 * 60 * 1000).toISOString(),
+              lastActive: now.toISOString(),
+              userId: validation.user.id?.toString() ?? '',
+              isCurrent: sessionId === storedActiveSessionId
+            };
+          }
+          return null;
+        });
+      }));
+      validSessions = results.filter(r => r.status === 'fulfilled').map(r => r.value).filter(s => s !== null);
+
+      // Always persist validated sessions to storage (even empty list)
+      // to clear stale/expired session IDs that would cause 401 loops on restart
+      updateSessionsRef.current(validSessions, {
+        merge: false
+      });
+    }
+    if (storedActiveSessionId) {
+      try {
+        await switchSessionRef.current(storedActiveSessionId);
+        return true;
+      } catch (switchError) {
+        // Silently handle expected errors (invalid sessions, timeouts, network issues)
+        if (isInvalidSessionError(switchError)) {
+          await storage.removeItem(storageKeys.activeSessionId);
+          updateSessionsRef.current(validSessions.filter(session => session.sessionId !== storedActiveSessionId), {
+            merge: false
+          });
+          // Don't log expected session errors during restoration
+        } else if (isTimeoutOrNetworkError(switchError)) {
+          // Timeout/network error - non-critical, don't block
+          if (__DEV__) {
+            loggerUtil.debug('Active session validation timeout (expected when offline)', {
+              component: 'OxyContext',
+              method: 'restoreStoredSession'
+            }, switchError);
+          }
+        } else {
+          // Only log unexpected errors
+          logger('Active session validation error', switchError);
+        }
+      }
+    }
+    return false;
+  }, [logger, oxyServices, storage, storageKeys.activeSessionId, storageKeys.sessionIds]);
+
+  // Central cross-domain SSO return handler (web). Parses the IdP redirect
+  // fragment, validates the CSRF `state`, exchanges the opaque single-use code
+  // for the real session, commits it, and restores the user's pre-bounce
+  // destination. Shared by the `sso-return` cold-boot step AND the bfcache
+  // `pageshow` re-evaluation, so the same security-critical logic runs exactly
+  // once per delivered fragment regardless of how the page was (re)shown.
+  //
+  // Returns `true` when a session was committed (caller short-circuits), `false`
+  // otherwise. On ANY non-ok outcome — `none`/`error`, state mismatch, missing
+  // code, or a failed/forged exchange — it sets the per-origin NO_SESSION flag
+  // so `sso-bounce` is disabled and the page cannot loop. Off-browser it is a
+  // no-op returning `false` (native never reaches it).
+  const runSsoReturn = useCallback(async () => {
+    if (!isWebBrowser()) {
+      return false;
+    }
+    const ret = parseSsoReturnFragment(window.location.hash);
+    if (!ret) {
+      // Not an oxy_sso fragment — nothing to do (do NOT touch any flags).
+      return false;
+    }
+    const origin = window.location.origin;
+    const expectedState = window.sessionStorage.getItem(ssoStateKey(origin));
+    const stateOk = !!ret.state && !!expectedState && ret.state === expectedState;
+
+    // Strip the fragment FIRST so the opaque code never lingers in the address
+    // bar, history, or a copy-paste — even if a later step throws.
+    window.history.replaceState(null, '', window.location.pathname + window.location.search);
+    window.sessionStorage.removeItem(ssoStateKey(origin));
+    const markNoSession = () => {
+      window.sessionStorage.setItem(ssoNoSessionKey(origin), '1');
+    };
+    if (ret.kind === 'none' || ret.kind === 'error') {
+      // The central IdP had no session (or the bounce failed). Record it so we
+      // do not bounce again this tab — the definitive loop breaker.
+      markNoSession();
+      return false;
+    }
+    if (!stateOk || !ret.code) {
+      // Forged / replayed / stale fragment, or a malformed ok with no code.
+      // Treat exactly like "no session": never exchange, never loop.
+      markNoSession();
+      return false;
+    }
+    const commitWebSession = handleWebSSOSessionRef.current;
+    let session;
+    try {
+      session = await oxyServices.exchangeSsoCode(ret.code);
+    } catch (error) {
+      if (__DEV__) {
+        loggerUtil.debug('SSO code exchange failed (treating as no session)', {
+          component: 'OxyContext',
+          method: 'runSsoReturn'
+        }, error);
+      }
+      markNoSession();
+      return false;
+    }
+    if (!session?.sessionId || !commitWebSession) {
+      markNoSession();
+      return false;
+    }
+    await commitWebSession(session);
+
+    // Restore the user's real destination captured before the bounce. We only
+    // rewrite the URL when we are sitting on the callback path — otherwise the
+    // current URL is already the destination.
+    if (window.location.pathname === SSO_CALLBACK_PATH) {
+      const dest = window.sessionStorage.getItem(ssoDestKey(origin));
+      if (dest) {
+        try {
+          const destUrl = new URL(dest);
+          // Same-origin only — never honour a cross-origin destination that
+          // could have been planted to redirect the freshly signed-in user.
+          if (destUrl.origin === origin) {
+            window.history.replaceState(null, '', destUrl.pathname + destUrl.search + destUrl.hash);
+          }
+        } catch {
+          // Malformed stored destination — leave the URL on the callback path.
+        }
+      }
+    }
+    window.sessionStorage.removeItem(ssoDestKey(origin));
+    return true;
+  }, [oxyServices]);
+
+  // Cold boot — the single, ordered, short-circuit session-recovery sequence,
+  // consuming the SAME `runColdBoot` core primitive as `WebOxyProvider`. The
+  // FIRST step that yields a session wins; every later step is skipped. Each
+  // web-only step is gated by `isWebBrowser()`, so on native ONLY
+  // `stored-session` runs.
+  //
+  // Order (web): redirect callback → SSO return → FedCM silent → cookie restore
+  // → stored session → SSO bounce (terminal). Order (native): stored session
+  // only (every web-only step is disabled off-browser).
   const restoreSessionsFromStorage = useCallback(async () => {
     if (!storage) {
       return;
     }
     setTokenReady(false);
+    const commitWebSession = handleWebSSOSessionRef.current;
+    const silentKey = silentColdBootKey(oxyServices);
+    const fedcmSupported = isWebBrowser() && oxyServices.isFedCMSupported?.() === true;
     try {
-      // Web cold-boot fast path: restore the active session from the secure
-      // httpOnly refresh cookie before the bearer-protected stored-session
-      // validation (which 401s on a hard reload). On success we are signed in
-      // from the cookie alone — no FedCM needed. On failure we fall through to
-      // the existing stored-session flow below; nothing is cleared.
-      if (await restoreViaRefreshCookie()) {
-        return;
-      }
-      const storedSessionIdsJson = await storage.getItem(storageKeys.sessionIds);
-      const storedSessionIds = storedSessionIdsJson ? JSON.parse(storedSessionIdsJson) : [];
-      const storedActiveSessionId = await storage.getItem(storageKeys.activeSessionId);
-      let validSessions = [];
-      if (storedSessionIds.length > 0) {
-        // Validate all sessions in parallel (with 8s timeout per session) to avoid
-        // sequential blocking that freezes the app on startup
-        const VALIDATION_TIMEOUT = 8000;
-        const results = await Promise.allSettled(storedSessionIds.map(async sessionId => {
-          const timeoutPromise = new Promise(resolve => setTimeout(() => resolve(null), VALIDATION_TIMEOUT));
-          const validationPromise = oxyServices.validateSession(sessionId, {
-            useHeaderValidation: true
-          }).catch(validationError => {
-            if (!isInvalidSessionError(validationError) && !isTimeoutOrNetworkError(validationError)) {
-              logger('Session validation failed during init', validationError);
-            } else if (__DEV__ && isTimeoutOrNetworkError(validationError)) {
-              loggerUtil.debug('Session validation timeout (expected when offline)', {
-                component: 'OxyContext',
-                method: 'restoreSessionsFromStorage'
-              }, validationError);
-            }
-            return null;
-          });
-          return Promise.race([validationPromise, timeoutPromise]).then(validation => {
-            if (validation?.valid && validation.user) {
-              const now = new Date();
+      const outcome = await runColdBoot({
+        steps: [{
+          // 0) Redirect callback wins: a popup/redirect sign-in just landed
+          // back on this page with `access_token`/`session_id` query params.
+          // `handleAuthCallback` plants the token but returns a PLACEHOLDER
+          // user (empty id), so we hydrate the REAL user via `getCurrentUser`
+          // and commit through `handleWebSSOSession` before claiming a
+          // session — never expose a placeholder user (R4).
+          id: 'redirect',
+          enabled: () => isWebBrowser(),
+          run: async () => {
+            const callbackSession = oxyServices.handleAuthCallback?.();
+            if (!callbackSession || !commitWebSession) {
               return {
-                sessionId,
-                deviceId: '',
-                expiresAt: new Date(now.getTime() + 7 * 24 * 60 * 60 * 1000).toISOString(),
-                lastActive: now.toISOString(),
-                userId: validation.user.id?.toString() ?? '',
-                isCurrent: sessionId === storedActiveSessionId
+                kind: 'skip'
               };
             }
-            return null;
-          });
-        }));
-        validSessions = results.filter(r => r.status === 'fulfilled').map(r => r.value).filter(s => s !== null);
-
-        // Always persist validated sessions to storage (even empty list)
-        // to clear stale/expired session IDs that would cause 401 loops on restart
-        updateSessionsRef.current(validSessions, {
-          merge: false
-        });
-      }
-      if (storedActiveSessionId) {
-        try {
-          await switchSessionRef.current(storedActiveSessionId);
-        } catch (switchError) {
-          // Silently handle expected errors (invalid sessions, timeouts, network issues)
-          if (isInvalidSessionError(switchError)) {
-            await storage.removeItem(storageKeys.activeSessionId);
-            updateSessionsRef.current(validSessions.filter(session => session.sessionId !== storedActiveSessionId), {
-              merge: false
+            const fullUser = await oxyServices.getCurrentUser();
+            await commitWebSession({
+              ...callbackSession,
+              user: fullUser
             });
-            // Don't log expected session errors during restoration
-          } else if (isTimeoutOrNetworkError(switchError)) {
-            // Timeout/network error - non-critical, don't block
-            if (__DEV__) {
-              loggerUtil.debug('Active session validation timeout (expected when offline)', {
-                component: 'OxyContext',
-                method: 'restoreSessionsFromStorage'
-              }, switchError);
+            return {
+              kind: 'session',
+              session: true
+            };
+          }
+        }, {
+          // 1) Central SSO return: we are landing back from an `auth.oxy.so/sso`
+          // bounce with the result in the URL fragment. Parse it, validate the
+          // CSRF state, exchange the opaque code, and commit. On any non-ok
+          // outcome `runSsoReturn` sets the per-origin NO_SESSION flag so the
+          // terminal `sso-bounce` step is disabled — the loop breaker.
+          id: 'sso-return',
+          enabled: () => isWebBrowser(),
+          run: async () => {
+            const committed = await runSsoReturn();
+            return committed ? {
+              kind: 'session',
+              session: true
+            } : {
+              kind: 'skip'
+            };
+          }
+        }, {
+          // 2) FedCM silent reauthn (Chrome) against the CENTRAL IdP
+          // (auth.oxy.so). `silentSignInWithFedCM` plants the access token
+          // internally; we commit the returned session via
+          // `handleWebSSOSession`. Guarded so it fires at most once per page
+          // load across remounts. This is an enhancement layered above the
+          // opaque-code bounce: when it succeeds the bounce never fires.
+          id: 'fedcm-silent',
+          enabled: () => fedcmSupported && !servicesSilentAttempted.has(silentKey),
+          run: async () => {
+            servicesSilentAttempted.add(silentKey);
+            const session = await oxyServices.silentSignInWithFedCM?.();
+            if (!session || !commitWebSession) {
+              return {
+                kind: 'skip'
+              };
+            }
+            await commitWebSession(session);
+            return {
+              kind: 'session',
+              session: true
+            };
+          }
+        }, {
+          // 3) Refresh-cookie restore (first-party only). On `*.oxy.so` the
+          // httpOnly `oxy_rt_${n}` cookies ride along and resurrect every
+          // device-local slot. On a cross-domain RP (mention.earth, …) the
+          // cookie is `Domain=oxy.so` so it never reaches `api.<apex>` —
+          // `refreshAllSessions` returns `{accounts:[]}` and this skips. That
+          // is correct; cross-domain restore is handled by the SSO bounce.
+          id: 'cookie-restore',
+          enabled: () => isWebBrowser(),
+          run: async () => {
+            const restored = await restoreViaRefreshCookie();
+            return restored ? {
+              kind: 'session',
+              session: true
+            } : {
+              kind: 'skip'
+            };
+          }
+        }, {
+          // 4) Stored-session bearer restore. NO `enabled` gate — runs on ALL
+          // platforms. This is native's ONLY restore path (every web-only step
+          // is disabled off-browser, so native reaches exactly this).
+          id: 'stored-session',
+          run: async () => {
+            const restored = await restoreStoredSession();
+            return restored ? {
+              kind: 'session',
+              session: true
+            } : {
+              kind: 'skip'
+            };
+          }
+        }, {
+          // 5) SSO bounce (TERMINAL, web only, at most once). No local session
+          // was found by any step above. Top-level navigate to the central
+          // `auth.oxy.so/sso?prompt=none` so the IdP can either mint a session
+          // (returning an opaque code we exchange on the callback) or report
+          // `none`. This step tears the document down on success — its `skip`
+          // result is only observed if `assign` no-ops. Disabled on the IdP
+          // itself, once the NO_SESSION flag is set, or while a bounce guard is
+          // still active (loop + self-heal protection).
+          id: 'sso-bounce',
+          enabled: () => {
+            if (!isWebBrowser() || window.top !== window.self) {
+              return false;
+            }
+            const origin = window.location.origin;
+            if (isCentralIdPOrigin(origin)) {
+              return false;
+            }
+            if (window.sessionStorage.getItem(ssoNoSessionKey(origin)) === '1') {
+              return false;
             }
-          } else {
-            // Only log unexpected errors
-            logger('Active session validation error', switchError);
+            if (guardActive(window.sessionStorage, origin, Date.now())) {
+              return false;
+            }
+            return true;
+          },
+          run: async () => {
+            const origin = window.location.origin;
+            const state = oxyServices.generateSsoState();
+            window.sessionStorage.setItem(ssoStateKey(origin), state);
+            window.sessionStorage.setItem(ssoGuardKey(origin), String(Date.now()));
+            window.sessionStorage.setItem(ssoDestKey(origin), window.location.href);
+            const url = new URL('/sso', resolveCentralAuthUrl(oxyServices.config?.authWebUrl));
+            url.searchParams.set('prompt', 'none');
+            url.searchParams.set('client_id', origin);
+            url.searchParams.set('return_to', origin + SSO_CALLBACK_PATH);
+            url.searchParams.set('state', state);
+
+            // TERMINAL: the document is torn down by this navigation. The
+            // `skip` below is only reached if `assign` is a no-op (e.g. the
+            // navigation is blocked); in that case we fall through
+            // unauthenticated, which is correct.
+            ssoBounce.ssoNavigate(url.toString());
+            return {
+              kind: 'skip'
+            };
+          }
+        }],
+        onStepError: (id, error) => {
+          if (__DEV__) {
+            loggerUtil.debug(`Cold-boot step "${id}" errored (non-fatal, falling through)`, {
+              component: 'OxyContext',
+              method: 'restoreSessionsFromStorage'
+            }, error);
           }
         }
+      });
+      if (__DEV__ && outcome.kind === 'session') {
+        loggerUtil.debug(`Cold boot recovered a session via "${outcome.via}"`, {
+          component: 'OxyContext',
+          method: 'restoreSessionsFromStorage'
+        });
       }
     } catch (error) {
       if (__DEV__) {
@@ -545,7 +906,7 @@ export const OxyProvider = ({
     } finally {
       setTokenReady(true);
     }
-  }, [logger, oxyServices, storage, storageKeys.activeSessionId, storageKeys.sessionIds, restoreViaRefreshCookie]);
+  }, [oxyServices, storage, restoreViaRefreshCookie, restoreStoredSession, runSsoReturn]);
   useEffect(() => {
     if (!storage || initialized) {
       return;
@@ -558,6 +919,37 @@ export const OxyProvider = ({
     });
   }, [restoreSessionsFromStorage, storage, initialized, logger]);
 
+  // bfcache re-evaluation (web only, registered once). When a page is restored
+  // from the back/forward cache (`e.persisted`) NO cold boot re-runs — React
+  // state is resurrected as-is — yet the page may have been frozen mid-bounce
+  // and resurrected ON the SSO callback with a fresh fragment in the URL. Re-run
+  // the `sso-return` parse so the opaque code is still exchanged (and the
+  // fragment stripped + NO_SESSION flag maintained) on a bfcache restore. Routed
+  // through a ref so the listener registers exactly once and never churns with
+  // `runSsoReturn`'s identity.
+  const runSsoReturnRef = useRef(runSsoReturn);
+  runSsoReturnRef.current = runSsoReturn;
+  useEffect(() => {
+    if (!isWebBrowser()) {
+      return;
+    }
+    const onPageShow = event => {
+      if (!event.persisted) {
+        return;
+      }
+      runSsoReturnRef.current().catch(error => {
+        if (__DEV__) {
+          loggerUtil.debug('bfcache SSO return re-evaluation failed (non-fatal)', {
+            component: 'OxyContext',
+            method: 'onPageShow'
+          }, error);
+        }
+      });
+    };
+    window.addEventListener('pageshow', onPageShow);
+    return () => window.removeEventListener('pageshow', onPageShow);
+  }, []);
+
   // Web SSO: Automatically check for cross-domain session on web platforms
   // Also used for popup auth - updates all state and persists session
   const handleWebSSOSession = useCallback(async session => {
@@ -620,7 +1012,21 @@ export const OxyProvider = ({
     onAuthStateChange?.(fullUser);
   }, [oxyServices, updateSessions, setActiveSessionId, loginSuccess, onAuthStateChange, persistSessionDurably]);
 
-  // Enable web SSO only after local storage check completes and no user found
+  // Expose `handleWebSSOSession` to the cold-boot FedCM/iframe/redirect steps,
+  // which reference it through a ref because they are declared above this
+  // callback. Assigned synchronously on every render so the ref is populated
+  // before the cold-boot effect (gated on `storage`/`initialized`) can fire.
+  handleWebSSOSessionRef.current = handleWebSSOSession;
+
+  // Cross-domain silent SSO is now owned by the `fedcm-silent` / `silent-iframe`
+  // cold-boot steps above (the ordered `runColdBoot` sequence). `useWebSSO`
+  // remains mounted for its module-level run-once guard and its interactive
+  // FedCM helpers, and as a bounded post-boot safety net: it can fire at most
+  // once per page load (its own module guard), and only AFTER cold boot has
+  // finished (`tokenReady`) with no user recovered. We deliberately keep
+  // `shouldTryWebSSO` as `tokenReady && !user && initialized` — it is NOT
+  // loosened; cold boot runs while `tokenReady` is false, so this never races
+  // the cold-boot silent step.
   const shouldTryWebSSO = isWebBrowser() && tokenReady && !user && initialized;
   useWebSSO({
     oxyServices,
@@ -640,8 +1046,16 @@ export const OxyProvider = ({
   // If session is gone (cleared/logged out), clear local session too
   const lastIdPCheckRef = useRef(0);
   const pendingIdPCleanupRef = useRef(null);
+
+  // Use the RESOLVED IdP origin (the auto-detected `auth.<rp-apex>` planted on
+  // the instance config), not the raw `authWebUrl` prop — on a cross-domain RP
+  // the prop is undefined but the instance was constructed with the detected
+  // value, so the check must target the same first-party IdP the cold-boot
+  // iframe used.
+  const resolvedAuthWebUrl = oxyServices.config?.authWebUrl;
   useEffect(() => {
     if (!isWebBrowser() || !user || !initialized) return;
+    const idpOrigin = resolvedAuthWebUrl || 'https://auth.oxy.so';
     const checkIdPSession = () => {
       // Debounce: check at most once per 30 seconds
       const now = Date.now();
@@ -654,7 +1068,6 @@ export const OxyProvider = ({
       // Load hidden iframe to check IdP session via postMessage
       const iframe = document.createElement('iframe');
       iframe.style.cssText = 'display:none;width:0;height:0;border:0';
-      const idpOrigin = authWebUrl || 'https://auth.oxy.so';
       iframe.src = `${idpOrigin}/auth/session-check?client_id=${encodeURIComponent(window.location.origin)}`;
       let cleaned = false;
       const cleanup = () => {
@@ -668,8 +1081,15 @@ export const OxyProvider = ({
         if (event.data?.type !== 'oxy-session-check') return;
         cleanup();
         if (!event.data.hasSession) {
-          toast.info('Your session has ended. Please sign in again.');
-          await clearSessionState();
+          // Only a SAME-SITE, first-party IdP answer is authoritative enough to
+          // force a local sign-out. On a cross-site / undetermined IdP the
+          // "no session" answer must never clear local state (a third-party
+          // can't be trusted to end this app's session). Surface the toast in
+          // both cases, but gate the destructive `clearSessionState()`.
+          if (isSameSiteIdP(idpOrigin)) {
+            toast.info('Your session has ended. Please sign in again.');
+            await clearSessionState();
+          }
         }
       };
       window.addEventListener('message', handleMessage);
@@ -688,7 +1108,7 @@ export const OxyProvider = ({
       pendingIdPCleanupRef.current?.();
       pendingIdPCleanupRef.current = null;
     };
-  }, [user, initialized, clearSessionState, authWebUrl]);
+  }, [user, initialized, clearSessionState, resolvedAuthWebUrl]);
   const activeSession = activeSessionId ? sessions.find(session => session.sessionId === activeSessionId) : undefined;
   const currentDeviceId = activeSession?.deviceId ?? null;
   const userId = user?.id;