@oxyhq/core 2.3.0 → 2.3.2

package/dist/types/index.d.ts

@@ -77,7 +77,7 @@ export { CENTRAL_AUTH_URL, CENTRAL_IDP_APEX, resolveCentralAuthUrl } from './uti
 export { parseSsoReturnFragment, consumeSsoReturn } from './utils/ssoReturn';
 export type { SsoReturnKind, SsoReturnResult, ConsumeSsoReturnDeps } from './utils/ssoReturn';
 export { generateSsoState } from './mixins/OxyServices.sso';
-export { SSO_CALLBACK_PATH, SSO_GUARD_TTL_MS, ssoStateKey, ssoGuardKey, ssoDestKey, ssoNoSessionKey, ssoNavigate, buildSsoBounceUrl, isCentralIdPOrigin, guardActive, } from './utils/ssoBounce';
+export { SSO_CALLBACK_PATH, SSO_GUARD_TTL_MS, ssoStateKey, ssoGuardKey, ssoDestKey, ssoNoSessionKey, ssoAttemptedKey, ssoNavigate, buildSsoBounceUrl, isCentralIdPOrigin, guardActive, } from './utils/ssoBounce';
 export { runColdBoot } from './utils/coldBoot';
 export type { ColdBootStep, ColdBootStepResult, ColdBootSession, ColdBootSkip, ColdBootOutcome, RunColdBootOptions, } from './utils/coldBoot';
 export { packageInfo } from './constants/version';

package/dist/types/utils/ssoBounce.d.ts

@@ -26,11 +26,15 @@
  *      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
+ * guard/state/dest + the outcome-independent attempted-flag
+ * ({@link ssoAttemptedKey}) and navigates; the IdP (no central session) returns
  * `#oxy_sso=none`; the callback load's `sso-return` sees `none`, sets the
  * NO_SESSION flag ({@link ssoNoSessionKey}), and `sso-bounce` is then disabled.
  * Exactly ONE bounce, no loop. An interrupted bounce (user hit back
  * mid-redirect) self-heals once the {@link SSO_GUARD_TTL_MS} guard TTL lapses.
+ * The attempted-flag is the definitive, outcome-INDEPENDENT loop breaker: it is
+ * set pre-bounce so even if the return-side NO_SESSION write never lands, the
+ * bounce can never re-fire this tab after the self-heal 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. The
@@ -65,6 +69,16 @@ export declare function ssoDestKey(origin: string): string;
  * fire again this tab — the definitive loop breaker.
  */
 export declare function ssoNoSessionKey(origin: string): string;
+/**
+ * Per-origin, OUTCOME-INDEPENDENT once-guard. Set in `sessionStorage` BEFORE
+ * the terminal SSO bounce navigates. Gates the bounce so the silent
+ * cross-domain probe fires AT MOST ONCE per tab session — independent of
+ * whether the return-side NO_SESSION flag ever lands. The definitive loop
+ * breaker; survives the 30s self-heal `ssoGuardKey` TTL. Cleared only on an
+ * explicit sign-out/clear so a later cold boot (after the user signs in
+ * centrally) can probe again.
+ */
+export declare function ssoAttemptedKey(origin: string): string;
 /**
  * Perform the terminal top-level SSO bounce navigation.
  *

package/dist/types/utils/ssoReturn.d.ts

@@ -72,6 +72,14 @@ export interface ConsumeSsoReturnDeps {
      * fails. NEVER rethrown — `consumeSsoReturn` is total. Default: no-op.
      */
     onExchangeError?: (error: unknown) => void;
+    /**
+     * Notify URL-driven routers (Expo Router / React Navigation web) that the
+     * location changed via `history.replaceState`, which does NOT itself emit
+     * `popstate`. Default: dispatch a real `PopStateEvent` on `window` when
+     * present; no-op off-web. Called ONLY after a successful same-origin
+     * dest restore (never when the dest is rejected/absent). NEVER throws.
+     */
+    dispatchPopState?: () => void;
 }
 /**
  * Consume an SSO return: the commit-free, security-critical kernel of the
@@ -91,14 +99,20 @@ export interface ConsumeSsoReturnDeps {
  *     or a `Referer` header even if a later step throws.
  *   - `state` must match (CSRF). A mismatch or a missing code sets the
  *     NO_SESSION flag so `sso-bounce` is disabled (no rebounce loop).
- *   - `none`/`error` outcomes set the NO_SESSION flag (the load2 half of the
- *     loop proof).
+ *   - `none`/`error` outcomes set BOTH the NO_SESSION flag and the
+ *     outcome-independent attempted-flag (the load2 half of the loop proof).
  *   - A throwing exchange is caught, reported via `onExchangeError`, and
  *     treated exactly like "no session" (never loops, never rethrows).
- *   - After a successful exchange landing on {@link SSO_CALLBACK_PATH}, the real
- *     destination is restored from the DEST key — same-origin only (an
- *     attacker-planted cross-origin or relative-evil dest is rejected). The
- *     DEST key is removed unconditionally.
+ *   - On EVERY consumed outcome (ok, none, error, state-mismatch, no-code,
+ *     failed-exchange, no-sessionId) — not just ok — if the page landed on
+ *     {@link SSO_CALLBACK_PATH}, the real pre-bounce destination is restored
+ *     from the DEST key so the user is never stranded on the internal callback
+ *     path. Same-origin only (an attacker-planted cross-origin or relative-evil
+ *     dest is rejected). The DEST key is removed unconditionally.
+ *   - After a same-origin dest restore (which uses `history.replaceState`, that
+ *     does NOT itself emit `popstate`), a synthetic `popstate` is dispatched so
+ *     URL-driven routers (Expo Router / React Navigation web) re-sync to the
+ *     restored route. It is NOT dispatched when the dest is rejected/absent.
  *
  * Total: this function NEVER throws. Off-web it is a no-op returning `null`.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "2.3.0",
+  "version": "2.3.2",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/index.ts

@@ -384,6 +384,7 @@ export {
     ssoGuardKey,
     ssoDestKey,
     ssoNoSessionKey,
+    ssoAttemptedKey,
     ssoNavigate,
     buildSsoBounceUrl,
     isCentralIdPOrigin,

package/src/utils/__tests__/consumeSsoReturn.test.ts

@@ -1,10 +1,15 @@
 /**
+ * @jest-environment jsdom
+ *
  * `consumeSsoReturn` — the commit-free, security-critical kernel of the
  * cross-domain SSO `sso-return` step.
  *
  * Every web seam is injected (storage / location / history / isWeb) so the
  * full CSRF / fragment-strip-order / exchange / dest-restore / loop-breaker
- * sequence is asserted deterministically without a DOM.
+ * sequence is asserted deterministically. The injected-seam tests do not need
+ * a DOM; the `default dispatchPopState` suite exercises the real
+ * `window.dispatchEvent(new PopStateEvent(...))` path, so this file runs under
+ * the jsdom environment.
  */
 
 import { consumeSsoReturn } from '../ssoReturn';
@@ -14,6 +19,7 @@ import {
   ssoGuardKey,
   ssoDestKey,
   ssoNoSessionKey,
+  ssoAttemptedKey,
 } from '../ssoBounce';
 import type { SessionLoginResponse } from '../../models/session';
 
@@ -87,13 +93,15 @@ describe('consumeSsoReturn', () => {
 
   it('returns null for a non-oxy fragment without touching any flags', async () => {
     const oxy = okExchange();
-    const storage = makeStorage();
+    const storage = makeStorage({ [ssoDestKey(ORIGIN)]: `${ORIGIN}/profile` });
     const history = makeHistory();
+    const dispatchPopState = jest.fn();
     const result = await consumeSsoReturn(oxy, {
       isWeb: () => true,
       storage,
       location: makeLocation({ hash: '#section=about' }),
       history,
+      dispatchPopState,
     });
 
     expect(result).toBeNull();
@@ -101,6 +109,9 @@ describe('consumeSsoReturn', () => {
     expect(storage.map.has(ssoNoSessionKey(ORIGIN))).toBe(false);
     // No fragment strip for an unrelated fragment.
     expect(history.calls).toHaveLength(0);
+    // Nothing was consumed — the dest key must be untouched and no popstate.
+    expect(storage.map.get(ssoDestKey(ORIGIN))).toBe(`${ORIGIN}/profile`);
+    expect(dispatchPopState).not.toHaveBeenCalled();
   });
 
   it('sets NO_SESSION and returns null on a "none" outcome', async () => {
@@ -116,10 +127,31 @@ describe('consumeSsoReturn', () => {
     expect(result).toBeNull();
     expect(oxy.exchangeSsoCode).not.toHaveBeenCalled();
     expect(storage.map.get(ssoNoSessionKey(ORIGIN))).toBe('1');
+    expect(storage.map.get(ssoAttemptedKey(ORIGIN))).toBe('1');
     expect(storage.map.has(ssoStateKey(ORIGIN))).toBe(false);
     expect(storage.map.has(ssoGuardKey(ORIGIN))).toBe(false);
   });
 
+  it('sets BOTH ssoNoSessionKey AND ssoAttemptedKey on a none outcome', async () => {
+    const oxy = okExchange();
+    const storage = makeStorage({ [ssoStateKey(ORIGIN)]: 's' });
+    const history = makeHistory();
+    const result = await consumeSsoReturn(oxy, {
+      isWeb: () => true,
+      storage,
+      location: makeLocation({ hash: '#oxy_sso=none&state=s' }),
+      history,
+    });
+
+    expect(result).toBeNull();
+    expect(oxy.exchangeSsoCode).not.toHaveBeenCalled();
+    expect(storage.map.get(ssoNoSessionKey(ORIGIN))).toBe('1');
+    expect(storage.map.get(ssoAttemptedKey(ORIGIN))).toBe('1');
+    // Fragment stripped FIRST (history.replaceState called).
+    expect(history.calls.length).toBeGreaterThanOrEqual(1);
+    expect(history.calls[0]?.[2]).toBe(SSO_CALLBACK_PATH);
+  });
+
   it('sets NO_SESSION and returns null on an "error" outcome', async () => {
     const oxy = okExchange();
     const storage = makeStorage({ [ssoStateKey(ORIGIN)]: 's' });
@@ -132,6 +164,7 @@ describe('consumeSsoReturn', () => {
 
     expect(result).toBeNull();
     expect(storage.map.get(ssoNoSessionKey(ORIGIN))).toBe('1');
+    expect(storage.map.get(ssoAttemptedKey(ORIGIN))).toBe('1');
   });
 
   it('sets NO_SESSION and returns null on a state mismatch (CSRF)', async () => {
@@ -147,6 +180,7 @@ describe('consumeSsoReturn', () => {
     expect(result).toBeNull();
     expect(oxy.exchangeSsoCode).not.toHaveBeenCalled();
     expect(storage.map.get(ssoNoSessionKey(ORIGIN))).toBe('1');
+    expect(storage.map.get(ssoAttemptedKey(ORIGIN))).toBe('1');
   });
 
   it('sets NO_SESSION and returns null when ok carries no code', async () => {
@@ -162,6 +196,7 @@ describe('consumeSsoReturn', () => {
     expect(result).toBeNull();
     expect(oxy.exchangeSsoCode).not.toHaveBeenCalled();
     expect(storage.map.get(ssoNoSessionKey(ORIGIN))).toBe('1');
+    expect(storage.map.get(ssoAttemptedKey(ORIGIN))).toBe('1');
   });
 
   it('exchanges, returns the session, strips the fragment, and removes state/guard keys on ok', async () => {
@@ -187,6 +222,9 @@ describe('consumeSsoReturn', () => {
     expect(storage.map.has(ssoStateKey(ORIGIN))).toBe(false);
     expect(storage.map.has(ssoGuardKey(ORIGIN))).toBe(false);
     expect(storage.map.has(ssoNoSessionKey(ORIGIN))).toBe(false);
+    // The ok happy-path must NOT set the attempted-flag — a future sign-out
+    // should be able to re-probe the central IdP.
+    expect(storage.map.has(ssoAttemptedKey(ORIGIN))).toBe(false);
     // Fragment stripped to pathname+search (the first replaceState).
     expect(history.calls[0]?.[2]).toBe('/feed?tab=home');
   });
@@ -242,6 +280,7 @@ describe('consumeSsoReturn', () => {
     expect(result).toBeNull();
     expect(onExchangeError).toHaveBeenCalledWith(boom);
     expect(storage.map.get(ssoNoSessionKey(ORIGIN))).toBe('1');
+    expect(storage.map.get(ssoAttemptedKey(ORIGIN))).toBe('1');
   });
 
   it('does not throw when the exchange throws and no onExchangeError hook is given', async () => {
@@ -277,16 +316,18 @@ describe('consumeSsoReturn', () => {
 
     expect(result).toBeNull();
     expect(storage.map.get(ssoNoSessionKey(ORIGIN))).toBe('1');
+    expect(storage.map.get(ssoAttemptedKey(ORIGIN))).toBe('1');
   });
 
   describe('dest restore', () => {
-    it('restores a same-origin destination when on the callback path and removes the dest key', async () => {
+    it('restores a same-origin destination when on the callback path, removes the dest key, and dispatches popstate', async () => {
       const oxy = okExchange();
       const storage = makeStorage({
         [ssoStateKey(ORIGIN)]: 's',
         [ssoDestKey(ORIGIN)]: `${ORIGIN}/profile?x=1#frag`,
       });
       const history = makeHistory();
+      const dispatchPopState = jest.fn();
 
       const result = await consumeSsoReturn(oxy, {
         isWeb: () => true,
@@ -296,6 +337,7 @@ describe('consumeSsoReturn', () => {
           pathname: SSO_CALLBACK_PATH,
         }),
         history,
+        dispatchPopState,
       });
 
       expect(result).toEqual(SESSION);
@@ -303,6 +345,8 @@ describe('consumeSsoReturn', () => {
       const last = history.calls[history.calls.length - 1];
       expect(last?.[2]).toBe('/profile?x=1#frag');
       expect(storage.map.has(ssoDestKey(ORIGIN))).toBe(false);
+      // URL-driven routers must be told the location changed.
+      expect(dispatchPopState).toHaveBeenCalledTimes(1);
     });
 
     it('restores a relative same-origin destination (new URL(dest, origin))', async () => {
@@ -397,5 +441,184 @@ describe('consumeSsoReturn', () => {
       expect(history.calls[0]?.[2]).toBe('/already-here?a=1');
       expect(storage.map.has(ssoDestKey(ORIGIN))).toBe(false);
     });
+
+    it('restores dest + dispatches popstate on a "none" outcome (no-stranding regression)', async () => {
+      const oxy = okExchange();
+      const storage = makeStorage({
+        [ssoStateKey(ORIGIN)]: 's',
+        [ssoDestKey(ORIGIN)]: `${ORIGIN}/explore?x=1#sec`,
+      });
+      const history = makeHistory();
+      const dispatchPopState = jest.fn();
+
+      const result = await consumeSsoReturn(oxy, {
+        isWeb: () => true,
+        storage,
+        location: makeLocation({
+          hash: '#oxy_sso=none&state=s',
+          pathname: SSO_CALLBACK_PATH,
+        }),
+        history,
+        dispatchPopState,
+      });
+
+      expect(result).toBeNull();
+      expect(oxy.exchangeSsoCode).not.toHaveBeenCalled();
+      // Last replaceState targets the captured dest — the user is returned.
+      const last = history.calls[history.calls.length - 1];
+      expect(last?.[2]).toBe('/explore?x=1#sec');
+      expect(storage.map.has(ssoDestKey(ORIGIN))).toBe(false);
+      expect(dispatchPopState).toHaveBeenCalledTimes(1);
+      // Loop-breaker flags must still be set.
+      expect(storage.map.get(ssoNoSessionKey(ORIGIN))).toBe('1');
+      expect(storage.map.get(ssoAttemptedKey(ORIGIN))).toBe('1');
+    });
+
+    it('restores dest + dispatches popstate on an "error" outcome', async () => {
+      const oxy = okExchange();
+      const storage = makeStorage({
+        [ssoStateKey(ORIGIN)]: 's',
+        [ssoDestKey(ORIGIN)]: `${ORIGIN}/feed`,
+      });
+      const history = makeHistory();
+      const dispatchPopState = jest.fn();
+
+      const result = await consumeSsoReturn(oxy, {
+        isWeb: () => true,
+        storage,
+        location: makeLocation({
+          hash: '#oxy_sso=error&state=s',
+          pathname: SSO_CALLBACK_PATH,
+        }),
+        history,
+        dispatchPopState,
+      });
+
+      expect(result).toBeNull();
+      const last = history.calls[history.calls.length - 1];
+      expect(last?.[2]).toBe('/feed');
+      expect(storage.map.has(ssoDestKey(ORIGIN))).toBe(false);
+      expect(dispatchPopState).toHaveBeenCalledTimes(1);
+      expect(storage.map.get(ssoNoSessionKey(ORIGIN))).toBe('1');
+      expect(storage.map.get(ssoAttemptedKey(ORIGIN))).toBe('1');
+    });
+
+    it('restores dest + dispatches popstate on a state mismatch', async () => {
+      const oxy = okExchange();
+      const storage = makeStorage({
+        [ssoStateKey(ORIGIN)]: 'expected',
+        [ssoDestKey(ORIGIN)]: `${ORIGIN}/notifications`,
+      });
+      const history = makeHistory();
+      const dispatchPopState = jest.fn();
+
+      const result = await consumeSsoReturn(oxy, {
+        isWeb: () => true,
+        storage,
+        location: makeLocation({
+          hash: '#oxy_sso=ok&code=c&state=forged',
+          pathname: SSO_CALLBACK_PATH,
+        }),
+        history,
+        dispatchPopState,
+      });
+
+      expect(result).toBeNull();
+      expect(oxy.exchangeSsoCode).not.toHaveBeenCalled();
+      const last = history.calls[history.calls.length - 1];
+      expect(last?.[2]).toBe('/notifications');
+      expect(storage.map.has(ssoDestKey(ORIGIN))).toBe(false);
+      expect(dispatchPopState).toHaveBeenCalledTimes(1);
+      expect(storage.map.get(ssoNoSessionKey(ORIGIN))).toBe('1');
+    });
+
+    it('does NOT restore dest on a "none" outcome when not on the callback path', async () => {
+      const oxy = okExchange();
+      const storage = makeStorage({
+        [ssoStateKey(ORIGIN)]: 's',
+        [ssoDestKey(ORIGIN)]: `${ORIGIN}/should-not-apply`,
+      });
+      const history = makeHistory();
+      const dispatchPopState = jest.fn();
+
+      const result = await consumeSsoReturn(oxy, {
+        isWeb: () => true,
+        storage,
+        location: makeLocation({
+          hash: '#oxy_sso=none&state=s',
+          pathname: '/explore',
+          search: '?a=1',
+        }),
+        history,
+        dispatchPopState,
+      });
+
+      expect(result).toBeNull();
+      // Only the fragment strip ran — no dest restore off the callback path.
+      expect(history.calls).toHaveLength(1);
+      expect(history.calls[0]?.[2]).toBe('/explore?a=1');
+      expect(storage.map.has(ssoDestKey(ORIGIN))).toBe(false);
+      expect(dispatchPopState).not.toHaveBeenCalled();
+    });
+
+    it('rejects a cross-origin dest on a "none" outcome and does NOT dispatch popstate', async () => {
+      const oxy = okExchange();
+      const storage = makeStorage({
+        [ssoStateKey(ORIGIN)]: 's',
+        [ssoDestKey(ORIGIN)]: 'https://evil.example/phish',
+      });
+      const history = makeHistory();
+      const dispatchPopState = jest.fn();
+
+      const result = await consumeSsoReturn(oxy, {
+        isWeb: () => true,
+        storage,
+        location: makeLocation({
+          hash: '#oxy_sso=none&state=s',
+          pathname: SSO_CALLBACK_PATH,
+        }),
+        history,
+        dispatchPopState,
+      });
+
+      expect(result).toBeNull();
+      // Only the fragment-strip replaceState ran — the cross-origin dest is rejected.
+      expect(history.calls).toHaveLength(1);
+      expect(storage.map.has(ssoDestKey(ORIGIN))).toBe(false);
+      expect(dispatchPopState).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('default dispatchPopState (jsdom)', () => {
+    it('fires a real popstate listener after a "none" dest restore on the callback path', async () => {
+      const oxy = okExchange();
+      const storage = makeStorage({
+        [ssoStateKey(ORIGIN)]: 's',
+        [ssoDestKey(ORIGIN)]: '/dashboard?tab=home',
+      });
+      const history = makeHistory();
+      const onPopState = jest.fn();
+      window.addEventListener('popstate', onPopState);
+
+      try {
+        const result = await consumeSsoReturn(oxy, {
+          isWeb: () => true,
+          storage,
+          location: makeLocation({
+            hash: '#oxy_sso=none&state=s',
+            pathname: SSO_CALLBACK_PATH,
+          }),
+          history,
+          // No injected dispatchPopState — exercise the real default.
+        });
+
+        expect(result).toBeNull();
+        const last = history.calls[history.calls.length - 1];
+        expect(last?.[2]).toBe('/dashboard?tab=home');
+        expect(onPopState).toHaveBeenCalledTimes(1);
+      } finally {
+        window.removeEventListener('popstate', onPopState);
+      }
+    });
   });
 });

package/src/utils/__tests__/ssoBounce.test.ts

@@ -14,6 +14,7 @@ import {
   ssoGuardKey,
   ssoDestKey,
   ssoNoSessionKey,
+  ssoAttemptedKey,
   buildSsoBounceUrl,
   isCentralIdPOrigin,
   guardActive,
@@ -35,6 +36,7 @@ describe('per-origin key builders', () => {
     expect(ssoGuardKey(origin)).toBe('oxy_sso_guard:https://mention.earth');
     expect(ssoDestKey(origin)).toBe('oxy_sso_dest:https://mention.earth');
     expect(ssoNoSessionKey(origin)).toBe('oxy_sso_no_session:https://mention.earth');
+    expect(ssoAttemptedKey(origin)).toBe('oxy_sso_attempted:https://mention.earth');
   });
 
   it('namespaces keys per origin so two RPs never collide', () => {

package/src/utils/ssoBounce.ts

@@ -26,11 +26,15 @@
  *      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
+ * guard/state/dest + the outcome-independent attempted-flag
+ * ({@link ssoAttemptedKey}) and navigates; the IdP (no central session) returns
  * `#oxy_sso=none`; the callback load's `sso-return` sees `none`, sets the
  * NO_SESSION flag ({@link ssoNoSessionKey}), and `sso-bounce` is then disabled.
  * Exactly ONE bounce, no loop. An interrupted bounce (user hit back
  * mid-redirect) self-heals once the {@link SSO_GUARD_TTL_MS} guard TTL lapses.
+ * The attempted-flag is the definitive, outcome-INDEPENDENT loop breaker: it is
+ * set pre-bounce so even if the return-side NO_SESSION write never lands, the
+ * bounce can never re-fire this tab after the self-heal 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. The
@@ -62,6 +66,7 @@ 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:';
+const ATTEMPTED_KEY_PREFIX = 'oxy_sso_attempted:';
 
 /** Per-origin CSRF state key (matched on return to defeat fragment forgery). */
 export function ssoStateKey(origin: string): string {
@@ -87,6 +92,19 @@ export function ssoNoSessionKey(origin: string): string {
   return `${NO_SESSION_KEY_PREFIX}${origin}`;
 }
 
+/**
+ * Per-origin, OUTCOME-INDEPENDENT once-guard. Set in `sessionStorage` BEFORE
+ * the terminal SSO bounce navigates. Gates the bounce so the silent
+ * cross-domain probe fires AT MOST ONCE per tab session — independent of
+ * whether the return-side NO_SESSION flag ever lands. The definitive loop
+ * breaker; survives the 30s self-heal `ssoGuardKey` TTL. Cleared only on an
+ * explicit sign-out/clear so a later cold boot (after the user signs in
+ * centrally) can probe again.
+ */
+export function ssoAttemptedKey(origin: string): string {
+  return `${ATTEMPTED_KEY_PREFIX}${origin}`;
+}
+
 /**
  * Perform the terminal top-level SSO bounce navigation.
  *

package/src/utils/ssoReturn.ts

@@ -28,6 +28,7 @@ import {
   ssoGuardKey,
   ssoDestKey,
   ssoNoSessionKey,
+  ssoAttemptedKey,
 } from './ssoBounce';
 
 /**
@@ -129,6 +130,14 @@ export interface ConsumeSsoReturnDeps {
    * fails. NEVER rethrown — `consumeSsoReturn` is total. Default: no-op.
    */
   onExchangeError?: (error: unknown) => void;
+  /**
+   * Notify URL-driven routers (Expo Router / React Navigation web) that the
+   * location changed via `history.replaceState`, which does NOT itself emit
+   * `popstate`. Default: dispatch a real `PopStateEvent` on `window` when
+   * present; no-op off-web. Called ONLY after a successful same-origin
+   * dest restore (never when the dest is rejected/absent). NEVER throws.
+   */
+  dispatchPopState?: () => void;
 }
 
 /**
@@ -149,14 +158,20 @@ export interface ConsumeSsoReturnDeps {
  *     or a `Referer` header even if a later step throws.
  *   - `state` must match (CSRF). A mismatch or a missing code sets the
  *     NO_SESSION flag so `sso-bounce` is disabled (no rebounce loop).
- *   - `none`/`error` outcomes set the NO_SESSION flag (the load2 half of the
- *     loop proof).
+ *   - `none`/`error` outcomes set BOTH the NO_SESSION flag and the
+ *     outcome-independent attempted-flag (the load2 half of the loop proof).
  *   - A throwing exchange is caught, reported via `onExchangeError`, and
  *     treated exactly like "no session" (never loops, never rethrows).
- *   - After a successful exchange landing on {@link SSO_CALLBACK_PATH}, the real
- *     destination is restored from the DEST key — same-origin only (an
- *     attacker-planted cross-origin or relative-evil dest is rejected). The
- *     DEST key is removed unconditionally.
+ *   - On EVERY consumed outcome (ok, none, error, state-mismatch, no-code,
+ *     failed-exchange, no-sessionId) — not just ok — if the page landed on
+ *     {@link SSO_CALLBACK_PATH}, the real pre-bounce destination is restored
+ *     from the DEST key so the user is never stranded on the internal callback
+ *     path. Same-origin only (an attacker-planted cross-origin or relative-evil
+ *     dest is rejected). The DEST key is removed unconditionally.
+ *   - After a same-origin dest restore (which uses `history.replaceState`, that
+ *     does NOT itself emit `popstate`), a synthetic `popstate` is dispatched so
+ *     URL-driven routers (Expo Router / React Navigation web) re-sync to the
+ *     restored route. It is NOT dispatched when the dest is rejected/absent.
  *
  * Total: this function NEVER throws. Off-web it is a no-op returning `null`.
  *
@@ -183,6 +198,22 @@ export async function consumeSsoReturn(
   const history = deps.history ?? window.history;
   const onExchangeError = deps.onExchangeError;
 
+  // Default: emit a synthetic `popstate` so URL-driven routers re-sync after a
+  // `history.replaceState` (which does NOT emit `popstate` on its own). Feature-
+  // detected end to end so it never throws in any environment.
+  const dispatchPopState =
+    deps.dispatchPopState ??
+    (() => {
+      if (typeof window === 'undefined' || typeof window.dispatchEvent !== 'function') {
+        return;
+      }
+      if (typeof PopStateEvent !== 'undefined') {
+        window.dispatchEvent(new PopStateEvent('popstate'));
+      } else if (typeof Event !== 'undefined') {
+        window.dispatchEvent(new Event('popstate'));
+      }
+    });
+
   const ret = parseSsoReturnFragment(location.hash);
   if (!ret) {
     // Not an oxy_sso fragment — nothing to do (do NOT touch any flags).
@@ -204,12 +235,45 @@ export async function consumeSsoReturn(
 
   const markNoSession = () => {
     storage.setItem(ssoNoSessionKey(origin), '1');
+    // A return was consumed, so the probe definitively happened. Set the
+    // outcome-independent attempted-flag too so the bounce can never re-fire
+    // even if some consumer path skipped setting it pre-bounce.
+    storage.setItem(ssoAttemptedKey(origin), '1');
+  };
+
+  // Restore the user's real pre-bounce destination so they are never stranded
+  // on the internal callback path — invoked on EVERY consumed outcome, not just
+  // success. Same-origin only — never honour a cross-origin/protocol-relative
+  // dest that could have been planted to redirect the user. The DEST key is
+  // removed unconditionally. After a successful same-origin restore a synthetic
+  // `popstate` is dispatched so URL-driven routers re-sync.
+  const restoreDest = (): void => {
+    if (location.pathname === SSO_CALLBACK_PATH) {
+      const dest = storage.getItem(ssoDestKey(origin));
+      if (dest) {
+        try {
+          const destUrl = new URL(dest, origin);
+          if (destUrl.origin === origin) {
+            history.replaceState(
+              null,
+              '',
+              destUrl.pathname + destUrl.search + destUrl.hash,
+            );
+            dispatchPopState();
+          }
+        } catch {
+          // Malformed stored destination — leave the URL on the callback path.
+        }
+      }
+    }
+    storage.removeItem(ssoDestKey(origin));
   };
 
   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();
+    restoreDest();
     return null;
   }
 
@@ -217,6 +281,7 @@ export async function consumeSsoReturn(
     // Forged / replayed / stale fragment, or a malformed ok with no code. Treat
     // exactly like "no session": never exchange, never loop.
     markNoSession();
+    restoreDest();
     return null;
   }
 
@@ -226,37 +291,17 @@ export async function consumeSsoReturn(
   } catch (error) {
     onExchangeError?.(error);
     markNoSession();
+    restoreDest();
     return null;
   }
 
   if (!session?.sessionId) {
     markNoSession();
+    restoreDest();
     return null;
   }
 
-  // If we landed on the internal callback path, restore the user's real
-  // destination (captured at bounce time). Same-origin only — never honour a
-  // cross-origin destination that could have been planted to redirect the
-  // freshly signed-in user. `new URL(dest, origin)` tolerates relative dests
-  // and is still re-checked against the page origin.
-  if (location.pathname === SSO_CALLBACK_PATH) {
-    const dest = storage.getItem(ssoDestKey(origin));
-    if (dest) {
-      try {
-        const destUrl = new URL(dest, origin);
-        if (destUrl.origin === origin) {
-          history.replaceState(
-            null,
-            '',
-            destUrl.pathname + destUrl.search + destUrl.hash,
-          );
-        }
-      } catch {
-        // Malformed stored destination — leave the URL on the callback path.
-      }
-    }
-  }
-  storage.removeItem(ssoDestKey(origin));
+  restoreDest();
 
   return session;
 }