@oxyhq/services 8.2.0 → 8.3.1

package/src/ui/context/OxyContext.tsx

@@ -14,8 +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 { autoDetectAuthWebUrl, runColdBoot } from '@oxyhq/core';
+import { runColdBoot, resolveCentralAuthUrl, parseSsoReturnFragment, autoDetectAuthWebUrl } 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';
@@ -115,19 +125,19 @@ export interface OxyContextProviderProps {
 }
 
 /**
- * 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).
@@ -226,19 +236,19 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
     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 {
@@ -735,14 +745,115 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
     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 (): Promise<boolean> => {
+    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: 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;
+    }
+
+    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 (central) →
+  // silent iframe (per-apex, the durable reload path) → cookie restore →
+  // stored session → SSO bounce (terminal). The per-apex silent iframe is what
+  // restores a durable cross-domain session on reload WITHOUT a top-level
+  // bounce, so when it wins `sso-bounce` never fires (no flash, no loop).
+  // Order (native): stored session only (every web-only step is disabled
+  // off-browser).
   const restoreSessionsFromStorage = useCallback(async (): Promise<void> => {
     if (!storage) {
       return;
@@ -758,7 +869,7 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
       const outcome = await runColdBoot<true>({
         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`
@@ -777,10 +888,25 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
             },
           },
           {
-            // 2) FedCM silent reauthn (Chrome). `silentSignInWithFedCM` plants
-            // the access token internally; we commit the returned session via
+            // 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.
+            // 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 () => {
@@ -794,20 +920,36 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
             },
           },
           {
-            // 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.
+            // 3) First-party silent iframe at the PER-APEX IdP — the DURABLE
+            // cross-domain reload-restore path. The durable session lives as a
+            // first-party `fedcm_session` cookie on `auth.<rp-apex>` (e.g.
+            // `auth.mention.earth`), established during the `/sso` bounce's
+            // `/sso/establish` hop. That host is SAME-SITE to the RP page, so
+            // the cookie is first-party under Safari ITP / Firefox TCP — and
+            // an iframe read is NOT a top-level navigation, so it restores on
+            // reload with NO flash and works in a backgrounded tab. This is the
+            // step that prevents the re-bounce loop: when it finds a session,
+            // the terminal `sso-bounce` never fires.
+            //
+            // The instance is configured with `authWebUrl=auth.oxy.so` (central,
+            // for the bounce + FedCM), so we explicitly point the iframe at the
+            // per-apex host via `autoDetectAuthWebUrl()` and `silentSignIn`'s
+            // `authWebUrlOverride`. On a `*.oxy.so` RP the per-apex host IS the
+            // central host (`auth.oxy.so`), so this is a same-host no-op-
+            // equivalent. When auto-detection bails (localhost/IP/single-label)
+            // there is no per-apex IdP and the step skips. Web only; on native
+            // `isWebBrowser()` gates it off, so native never runs an iframe.
             id: 'silent-iframe',
-            enabled: () =>
-              isWebBrowser() &&
-              oxyServices.isFedCMSupported?.() !== true &&
-              !servicesSilentAttempted.has(silentKey),
+            enabled: () => isWebBrowser(),
             run: async () => {
-              servicesSilentAttempted.add(silentKey);
-              const session = await oxyServices.silentSignIn?.();
-              if (!session || !commitWebSession) {
+              const perApexAuthUrl = autoDetectAuthWebUrl();
+              if (!perApexAuthUrl || !commitWebSession) {
+                return { kind: 'skip' };
+              }
+              const session = await oxyServices.silentSignIn?.({
+                authWebUrlOverride: perApexAuthUrl,
+              });
+              if (!session?.user || !session?.sessionId) {
                 return { kind: 'skip' };
               }
               await commitWebSession(session);
@@ -815,12 +957,12 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
             },
           },
           {
-            // 4) Refresh-cookie restore (same-site only). On `*.oxy.so` the
+            // 4) 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 () => {
@@ -830,14 +972,61 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
           },
           {
             // 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).
+            // 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' };
             },
           },
+          {
+            // 6) 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__) {
@@ -869,6 +1058,7 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
     storage,
     restoreViaRefreshCookie,
     restoreStoredSession,
+    runSsoReturn,
   ]);
 
   useEffect(() => {
@@ -884,6 +1074,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) => {

package/src/ui/utils/ssoBounce.ts

@@ -0,0 +1,146 @@
+/**
+ * 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.
+ */
+
+import { CENTRAL_AUTH_URL } from '@oxyhq/core';
+
+/**
+ * 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.
+ */
+export const 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.
+ */
+export const 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).
+ */
+export function ssoNavigate(url: string): void {
+  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). */
+export function ssoStateKey(origin: string): string {
+  return `${STATE_KEY_PREFIX}${origin}`;
+}
+
+/** Per-origin bounce guard key (a timestamp; loop breaker + self-heal TTL). */
+export function ssoGuardKey(origin: string): string {
+  return `${GUARD_KEY_PREFIX}${origin}`;
+}
+
+/** Per-origin destination key (the real URL to restore after the callback). */
+export function ssoDestKey(origin: string): string {
+  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.
+ */
+export function ssoNoSessionKey(origin: string): string {
+  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.
+ */
+export function isCentralIdPOrigin(origin: string): boolean {
+  let centralOrigin: string;
+  try {
+    centralOrigin = new URL(CENTRAL_AUTH_URL).origin;
+  } catch {
+    return false;
+  }
+  let candidateOrigin: string;
+  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).
+ */
+export function guardActive(storage: Storage, origin: string, now: number): boolean {
+  let raw: string | null;
+  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;
+}