@oxyhq/services 8.2.0 → 8.3.0

package/lib/commonjs/ui/utils/ssoBounce.js

@@ -0,0 +1,158 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.SSO_GUARD_TTL_MS = exports.SSO_CALLBACK_PATH = void 0;
+exports.guardActive = guardActive;
+exports.isCentralIdPOrigin = isCentralIdPOrigin;
+exports.ssoDestKey = ssoDestKey;
+exports.ssoGuardKey = ssoGuardKey;
+exports.ssoNavigate = ssoNavigate;
+exports.ssoNoSessionKey = ssoNoSessionKey;
+exports.ssoStateKey = ssoStateKey;
+var _core = require("@oxyhq/core");
+/**
+ * Central cross-domain SSO bounce — per-origin sessionStorage keys and small
+ * pure predicates shared by the cold-boot `sso-return` / `sso-bounce` steps and
+ * the bfcache `pageshow` re-evaluation.
+ *
+ * TRUE central SSO (Google/Meta/Clerk style) works like this for a Relying
+ * Party (mention.earth, homiio.com, alia.onl, …) with no local session:
+ *
+ *   1. `sso-bounce` (terminal, once): top-level navigate to
+ *      `auth.oxy.so/sso?prompt=none&client_id=<origin>&return_to=<origin>/__oxy/sso-callback&state=<s>`.
+ *      Before navigating it records, in this origin's `sessionStorage`, the CSRF
+ *      `state`, a guard timestamp (loop breaker), and the real destination URL
+ *      to restore after the callback.
+ *   2. The central IdP worker reads its first-party `fedcm_session`, mints a
+ *      session, stores it under an opaque single-use `code`, and 303-redirects
+ *      back to `<origin>/__oxy/sso-callback#oxy_sso=ok&code=<code>&state=<s>`
+ *      (or `#oxy_sso=none` / `#oxy_sso=error`).
+ *   3. `sso-return` parses the fragment (`parseSsoReturnFragment` from core),
+ *      validates `state`, exchanges the `code` via `oxyServices.exchangeSsoCode`,
+ *      and commits the session — then restores the original destination.
+ *
+ * Loop proof (logged-out): first load all steps skip → `sso-bounce` sets
+ * guard/state/dest and navigates; the IdP (no central session) returns
+ * `#oxy_sso=none`; the callback load's `sso-return` sees `none`, sets the
+ * no-session flag, and `sso-bounce` is then disabled. Exactly ONE bounce, no
+ * loop. An interrupted bounce (user hit back mid-redirect) self-heals once the
+ * 30s guard TTL lapses.
+ *
+ * All state lives in `sessionStorage` (per tab, cleared on tab close) and is
+ * keyed per-origin so two RPs hosted in the same browser never collide. This
+ * module is pure with respect to navigation: it only reads/writes
+ * `sessionStorage` and parses URLs; it performs no redirects itself.
+ */
+
+/**
+ * The RP callback path the central IdP redirects back to. The SSO result is
+ * delivered in the fragment of this URL; `sso-return` consumes it and then
+ * restores the user's real destination.
+ */
+const SSO_CALLBACK_PATH = exports.SSO_CALLBACK_PATH = '/__oxy/sso-callback';
+
+/**
+ * Self-healing TTL (ms) for the bounce guard. If a bounce is interrupted before
+ * the callback lands (e.g. the user navigates back mid-redirect), the guard
+ * would otherwise pin the RP signed-out forever. After this window the guard is
+ * treated as stale and a fresh single bounce is permitted.
+ */
+const SSO_GUARD_TTL_MS = exports.SSO_GUARD_TTL_MS = 30_000;
+const STATE_KEY_PREFIX = 'oxy_sso_state:';
+const GUARD_KEY_PREFIX = 'oxy_sso_guard:';
+const DEST_KEY_PREFIX = 'oxy_sso_dest:';
+const NO_SESSION_KEY_PREFIX = 'oxy_sso_no_session:';
+
+/**
+ * Perform the terminal top-level SSO bounce navigation.
+ *
+ * A thin wrapper over `window.location.assign(url)` so the single navigation
+ * seam lives in one place (and stays mockable in tests, where jsdom's
+ * `Location.assign` is a non-configurable native method). In production this is
+ * exactly `window.location.assign` — the document is torn down and replaced by
+ * the central IdP page. Off-browser it is a no-op (native never bounces).
+ */
+function ssoNavigate(url) {
+  if (typeof window === 'undefined' || typeof window.location === 'undefined') {
+    return;
+  }
+  window.location.assign(url);
+}
+
+/** Per-origin CSRF state key (matched on return to defeat fragment forgery). */
+function ssoStateKey(origin) {
+  return `${STATE_KEY_PREFIX}${origin}`;
+}
+
+/** Per-origin bounce guard key (a timestamp; loop breaker + self-heal TTL). */
+function ssoGuardKey(origin) {
+  return `${GUARD_KEY_PREFIX}${origin}`;
+}
+
+/** Per-origin destination key (the real URL to restore after the callback). */
+function ssoDestKey(origin) {
+  return `${DEST_KEY_PREFIX}${origin}`;
+}
+
+/**
+ * Per-origin "the central IdP has no session for me" key. Set after a
+ * `none`/`error` return (or a failed/forged exchange) so `sso-bounce` does not
+ * fire again this tab — the definitive loop breaker.
+ */
+function ssoNoSessionKey(origin) {
+  return `${NO_SESSION_KEY_PREFIX}${origin}`;
+}
+
+/**
+ * Whether `origin` IS the central IdP origin. We must never bounce while on
+ * `auth.oxy.so` itself (it would bounce to itself). Compared by URL origin so a
+ * trailing-slash / path difference never defeats the guard.
+ */
+function isCentralIdPOrigin(origin) {
+  let centralOrigin;
+  try {
+    centralOrigin = new URL(_core.CENTRAL_AUTH_URL).origin;
+  } catch {
+    return false;
+  }
+  let candidateOrigin;
+  try {
+    candidateOrigin = new URL(origin).origin;
+  } catch {
+    return false;
+  }
+  return candidateOrigin === centralOrigin;
+}
+
+/**
+ * Read the bounce guard and decide whether it is still ACTIVE.
+ *
+ * Active means: a guard value is present AND it parses to a finite timestamp AND
+ * less than {@link SSO_GUARD_TTL_MS} has elapsed since it was set. An active
+ * guard disables `sso-bounce` (a bounce is already in flight this tab). A
+ * missing, malformed, or expired guard is NOT active, so a fresh bounce may
+ * proceed (this is the 30s self-heal for an interrupted bounce).
+ *
+ * @param storage - The session storage to read (injected for testability).
+ * @param origin - The page origin whose guard to evaluate.
+ * @param now - Current epoch ms (injected for deterministic tests).
+ */
+function guardActive(storage, origin, now) {
+  let raw;
+  try {
+    raw = storage.getItem(ssoGuardKey(origin));
+  } catch {
+    return false;
+  }
+  if (raw === null || raw.length === 0) {
+    return false;
+  }
+  const stamp = Number(raw);
+  if (!Number.isFinite(stamp)) {
+    return false;
+  }
+  return now - stamp < SSO_GUARD_TTL_MS;
+}
+//# sourceMappingURL=ssoBounce.js.map

package/lib/commonjs/ui/utils/ssoBounce.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_core","require","SSO_CALLBACK_PATH","exports","SSO_GUARD_TTL_MS","STATE_KEY_PREFIX","GUARD_KEY_PREFIX","DEST_KEY_PREFIX","NO_SESSION_KEY_PREFIX","ssoNavigate","url","window","location","assign","ssoStateKey","origin","ssoGuardKey","ssoDestKey","ssoNoSessionKey","isCentralIdPOrigin","centralOrigin","URL","CENTRAL_AUTH_URL","candidateOrigin","guardActive","storage","now","raw","getItem","length","stamp","Number","isFinite"],"sourceRoot":"../../../../src","sources":["ui/utils/ssoBounce.ts"],"mappings":";;;;;;;;;;;;;AAkCA,IAAAA,KAAA,GAAAC,OAAA;AAlCA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAIA;AACA;AACA;AACA;AACA;AACO,MAAMC,iBAAiB,GAAAC,OAAA,CAAAD,iBAAA,GAAG,qBAAqB;;AAEtD;AACA;AACA;AACA;AACA;AACA;AACO,MAAME,gBAAgB,GAAAD,OAAA,CAAAC,gBAAA,GAAG,MAAM;AAEtC,MAAMC,gBAAgB,GAAG,gBAAgB;AACzC,MAAMC,gBAAgB,GAAG,gBAAgB;AACzC,MAAMC,eAAe,GAAG,eAAe;AACvC,MAAMC,qBAAqB,GAAG,qBAAqB;;AAEnD;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,WAAWA,CAACC,GAAW,EAAQ;EAC7C,IAAI,OAAOC,MAAM,KAAK,WAAW,IAAI,OAAOA,MAAM,CAACC,QAAQ,KAAK,WAAW,EAAE;IAC3E;EACF;EACAD,MAAM,CAACC,QAAQ,CAACC,MAAM,CAACH,GAAG,CAAC;AAC7B;;AAEA;AACO,SAASI,WAAWA,CAACC,MAAc,EAAU;EAClD,OAAO,GAAGV,gBAAgB,GAAGU,MAAM,EAAE;AACvC;;AAEA;AACO,SAASC,WAAWA,CAACD,MAAc,EAAU;EAClD,OAAO,GAAGT,gBAAgB,GAAGS,MAAM,EAAE;AACvC;;AAEA;AACO,SAASE,UAAUA,CAACF,MAAc,EAAU;EACjD,OAAO,GAAGR,eAAe,GAAGQ,MAAM,EAAE;AACtC;;AAEA;AACA;AACA;AACA;AACA;AACO,SAASG,eAAeA,CAACH,MAAc,EAAU;EACtD,OAAO,GAAGP,qBAAqB,GAAGO,MAAM,EAAE;AAC5C;;AAEA;AACA;AACA;AACA;AACA;AACO,SAASI,kBAAkBA,CAACJ,MAAc,EAAW;EAC1D,IAAIK,aAAqB;EACzB,IAAI;IACFA,aAAa,GAAG,IAAIC,GAAG,CAACC,sBAAgB,CAAC,CAACP,MAAM;EAClD,CAAC,CAAC,MAAM;IACN,OAAO,KAAK;EACd;EACA,IAAIQ,eAAuB;EAC3B,IAAI;IACFA,eAAe,GAAG,IAAIF,GAAG,CAACN,MAAM,CAAC,CAACA,MAAM;EAC1C,CAAC,CAAC,MAAM;IACN,OAAO,KAAK;EACd;EACA,OAAOQ,eAAe,KAAKH,aAAa;AAC1C;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASI,WAAWA,CAACC,OAAgB,EAAEV,MAAc,EAAEW,GAAW,EAAW;EAClF,IAAIC,GAAkB;EACtB,IAAI;IACFA,GAAG,GAAGF,OAAO,CAACG,OAAO,CAACZ,WAAW,CAACD,MAAM,CAAC,CAAC;EAC5C,CAAC,CAAC,MAAM;IACN,OAAO,KAAK;EACd;EACA,IAAIY,GAAG,KAAK,IAAI,IAAIA,GAAG,CAACE,MAAM,KAAK,CAAC,EAAE;IACpC,OAAO,KAAK;EACd;EACA,MAAMC,KAAK,GAAGC,MAAM,CAACJ,GAAG,CAAC;EACzB,IAAI,CAACI,MAAM,CAACC,QAAQ,CAACF,KAAK,CAAC,EAAE;IAC3B,OAAO,KAAK;EACd;EACA,OAAOJ,GAAG,GAAGI,KAAK,GAAG1B,gBAAgB;AACvC","ignoreList":[]}

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

@@ -3,8 +3,10 @@
 import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
 import { OxyServices, oxyClient } from '@oxyhq/core';
 import { KeyManager } from '@oxyhq/core';
-import { autoDetectAuthWebUrl, runColdBoot } 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";
@@ -30,19 +32,19 @@ const OxyContext = /*#__PURE__*/createContext(null);
 // can share them without re-importing this 1k-line context file.
 
 /**
- * Module-level run-once guard for the cold-boot silent SSO steps
- * (`fedcm-silent` and `silent-iframe`).
+ * Module-level run-once guard for the cold-boot `fedcm-silent` step.
  *
- * Both steps trigger a one-shot browser credential / iframe 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 IdP session state, and a fresh page load
- * starts a fresh module scope.
+ * 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 NEW, dedicated set — distinct from `useWebSSO`'s `silentSSOAttempted`
+ * 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).
@@ -135,19 +137,19 @@ export const OxyProvider = ({
     if (providedOxyServices) {
       oxyServicesRef.current = providedOxyServices;
     } else if (baseURL) {
-      // Auto-detect the FAPI (IdP) origin from the current browser hostname so
-      // a consuming RP (mention.earth, homiio.com, alia.onl, …) targets
-      // `auth.<rp-apex>` for FedCM + the silent iframe WITHOUT passing
-      // `authWebUrl` explicitly — that is what makes both the FedCM config and
-      // the `/auth/silent` iframe first-party with the RP (Safari ITP /
-      // Firefox TCP need first-party). An explicit `authWebUrl` prop still
-      // wins. On native `autoDetectAuthWebUrl()` returns `undefined`
-      // (off-browser), leaving the value unchanged. We only auto-detect on the
-      // baseURL-only path — a consumer-provided `OxyServices` instance is
-      // never mutated.
+      // 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 ?? autoDetectAuthWebUrl(),
+        authWebUrl: resolveCentralAuthUrl(authWebUrl),
         authRedirectUri
       });
     } else {
@@ -627,14 +629,101 @@ export const OxyProvider = ({
     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 → FedCM silent → silent iframe → refresh
-  // cookie → stored session. Order (native): stored session only.
+  // 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;
@@ -646,7 +735,7 @@ export const OxyProvider = ({
     try {
       const outcome = await runColdBoot({
         steps: [{
-          // 1) Redirect callback wins: a popup/redirect sign-in just landed
+          // 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`
@@ -672,37 +761,34 @@ export const OxyProvider = ({
             };
           }
         }, {
-          // 2) FedCM silent reauthn (Chrome). `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.
-          id: 'fedcm-silent',
-          enabled: () => fedcmSupported && !servicesSilentAttempted.has(silentKey),
+          // 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 () => {
-            servicesSilentAttempted.add(silentKey);
-            const session = await oxyServices.silentSignInWithFedCM?.();
-            if (!session || !commitWebSession) {
-              return {
-                kind: 'skip'
-              };
-            }
-            await commitWebSession(session);
-            return {
+            const committed = await runSsoReturn();
+            return committed ? {
               kind: 'session',
               session: true
+            } : {
+              kind: 'skip'
             };
           }
         }, {
-          // 3) Silent first-party iframe ({authWebUrl}/auth/silent) for
-          // browsers without FedCM (Safari / Firefox). After auto-detection
-          // `authWebUrl` is `auth.<rp-apex>`, so the iframe + its
-          // `fedcm_session` cookie are first-party with the RP. Shares the
-          // one-shot guard with the FedCM step.
-          id: 'silent-iframe',
-          enabled: () => isWebBrowser() && oxyServices.isFedCMSupported?.() !== true && !servicesSilentAttempted.has(silentKey),
+          // 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.silentSignIn?.();
+            const session = await oxyServices.silentSignInWithFedCM?.();
             if (!session || !commitWebSession) {
               return {
                 kind: 'skip'
@@ -715,12 +801,12 @@ export const OxyProvider = ({
             };
           }
         }, {
-          // 4) Refresh-cookie restore (same-site only). On `*.oxy.so` the
+          // 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; there is deliberately NO `api.<apex>` bridge.
+          // `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 () => {
@@ -733,9 +819,9 @@ export const OxyProvider = ({
             };
           }
         }, {
-          // 5) Stored-session bearer restore. NO `enabled` gate — runs on ALL
-          // platforms. This is native's ONLY restore path (every web-only
-          // step above is disabled off-browser).
+          // 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();
@@ -746,6 +832,53 @@ export const OxyProvider = ({
               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__) {
@@ -773,7 +906,7 @@ export const OxyProvider = ({
     } finally {
       setTokenReady(true);
     }
-  }, [oxyServices, storage, restoreViaRefreshCookie, restoreStoredSession]);
+  }, [oxyServices, storage, restoreViaRefreshCookie, restoreStoredSession, runSsoReturn]);
   useEffect(() => {
     if (!storage || initialized) {
       return;
@@ -786,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 => {