@oxyhq/services 8.1.2 → 8.3.0

package/src/ui/context/OxyContext.tsx

@@ -14,7 +14,18 @@ import type { User, ApiError, SessionLoginResponse } from '@oxyhq/core';
 import type { ManagedAccount, CreateManagedAccountInput } from '@oxyhq/core';
 import { KeyManager } from '@oxyhq/core';
 import type { ClientSession } 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';
+import * as ssoBounce from '../utils/ssoBounce';
 import { useAuthStore, type AuthState } from '../stores/authStore';
 import { useShallow } from 'zustand/react/shallow';
 import { useSessionSocket } from '../hooks/useSessionSocket';
@@ -113,6 +124,72 @@ export interface OxyContextProviderProps {
   onError?: (error: ApiError) => void;
 }
 
+/**
+ * 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<string>();
+
+/**
+ * Build the `origin|baseURL` signature used as the silent-cold-boot guard key.
+ */
+function silentColdBootKey(oxyServices: OxyServices): string {
+  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: string): boolean {
+  if (typeof window === 'undefined') return false;
+  let idpHostname: string;
+  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: string): string => 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: UseFollowHook | null = null;
 
 const loadUseFollowHook = (): UseFollowHook => {
@@ -159,9 +236,19 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
     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 {
@@ -234,7 +321,7 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
 
   const logger = useCallback((message: string, err?: unknown) => {
     if (__DEV__) {
-      console.warn(`[OxyContext] ${message}`, err);
+      loggerUtil.warn(message, { component: 'OxyContext' }, err);
     }
   }, []);
 
@@ -453,6 +540,14 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
   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<((session: SessionLoginResponse) => Promise<void>) | null>(null);
+
   // Cold-boot session restore via the secure refresh cookies (web only).
   //
   // Calls `oxyServices.refreshAllSessions()` → `POST /auth/refresh-all` with
@@ -546,99 +641,369 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
     return true;
   }, [oxyServices, persistSessionDurably]);
 
-  const restoreSessionsFromStorage = useCallback(async (): Promise<void> => {
+  // 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 (): Promise<boolean> => {
     if (!storage) {
-      return;
+      return false;
     }
 
-    setTokenReady(false);
+    const storedSessionIdsJson = await storage.getItem(storageKeys.sessionIds);
+    const storedSessionIds: string[] = storedSessionIdsJson ? JSON.parse(storedSessionIdsJson) : [];
+    const storedActiveSessionId = await storage.getItem(storageKeys.activeSessionId);
+
+    let validSessions: ClientSession[] = [];
+
+    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<null>((resolve) =>
+            setTimeout(() => resolve(null), VALIDATION_TIMEOUT),
+          );
+          const validationPromise = oxyServices
+            .validateSession(sessionId, { useHeaderValidation: true })
+            .catch((validationError: unknown) => {
+              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 as unknown);
+              }
+              return null;
+            });
 
-    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;
+          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,
+              } as ClientSession;
+            }
+            return null;
+          });
+        }),
+      );
+
+      validSessions = results
+        .filter((r): r is PromiseFulfilledResult<ClientSession | null> => r.status === 'fulfilled')
+        .map((r) => r.value)
+        .filter((s): s is ClientSession => 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 as unknown);
+          }
+        } else {
+          // Only log unexpected errors
+          logger('Active session validation error', switchError);
+        }
       }
+    }
 
-      const storedSessionIdsJson = await storage.getItem(storageKeys.sessionIds);
-      const storedSessionIds: string[] = storedSessionIdsJson ? JSON.parse(storedSessionIdsJson) : [];
-      const storedActiveSessionId = await storage.getItem(storageKeys.activeSessionId);
+    return false;
+  }, [
+    logger,
+    oxyServices,
+    storage,
+    storageKeys.activeSessionId,
+    storageKeys.sessionIds,
+  ]);
 
-      let validSessions: ClientSession[] = [];
+  // 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 (): Promise<boolean> => {
+    if (!isWebBrowser()) {
+      return false;
+    }
 
-      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<null>((resolve) =>
-              setTimeout(() => resolve(null), VALIDATION_TIMEOUT),
-            );
-            const validationPromise = oxyServices
-              .validateSession(sessionId, { useHeaderValidation: true })
-              .catch((validationError: unknown) => {
-                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 as unknown);
-                }
-                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,
-                } as ClientSession;
-              }
-              return null;
-            });
-          }),
-        );
+    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;
 
-        validSessions = results
-          .filter((r): r is PromiseFulfilledResult<ClientSession | null> => r.status === 'fulfilled')
-          .map((r) => r.value)
-          .filter((s): s is ClientSession => s !== null);
+    // 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;
+    }
 
-        // 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 (!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: SessionLoginResponse;
+    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;
+    }
 
-      if (storedActiveSessionId) {
+    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 {
-          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 },
-            );
-            // 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 as unknown);
-            }
-          } else {
-            // Only log unexpected errors
-            logger('Active session validation error', switchError);
+          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 (): Promise<void> => {
+    if (!storage) {
+      return;
+    }
+
+    setTokenReady(false);
+
+    const commitWebSession = handleWebSSOSessionRef.current;
+    const silentKey = silentColdBootKey(oxyServices);
+    const fedcmSupported = isWebBrowser() && oxyServices.isFedCMSupported?.() === true;
+
+    try {
+      const outcome = await runColdBoot<true>({
+        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 { kind: 'skip' };
+              }
+              const fullUser = await oxyServices.getCurrentUser();
+              await commitWebSession({ ...callbackSession, user: fullUser });
+              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;
+              }
+              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__) {
         loggerUtil.error('Auth init error', error instanceof Error ? error : new Error(String(error)), { component: 'OxyContext', method: 'restoreSessionsFromStorage' });
@@ -648,12 +1013,11 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
       setTokenReady(true);
     }
   }, [
-    logger,
     oxyServices,
     storage,
-    storageKeys.activeSessionId,
-    storageKeys.sessionIds,
     restoreViaRefreshCookie,
+    restoreStoredSession,
+    runSsoReturn,
   ]);
 
   useEffect(() => {
@@ -669,6 +1033,39 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
     });
   }, [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: PageTransitionEvent) => {
+      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: SessionLoginResponse) => {
@@ -729,7 +1126,21 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
     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({
@@ -749,9 +1160,18 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
   const lastIdPCheckRef = useRef<number>(0);
   const pendingIdPCleanupRef = useRef<(() => void) | null>(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();
@@ -764,7 +1184,6 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
       // 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;
@@ -781,8 +1200,15 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
         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();
+          }
         }
       };
 
@@ -804,7 +1230,7 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
       pendingIdPCleanupRef.current?.();
       pendingIdPCleanupRef.current = null;
     };
-  }, [user, initialized, clearSessionState, authWebUrl]);
+  }, [user, initialized, clearSessionState, resolvedAuthWebUrl]);
 
   const activeSession = activeSessionId
     ? sessions.find((session) => session.sessionId === activeSessionId)