@oxyhq/core 2.3.1 → 2.3.2

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
@@ -95,10 +103,16 @@ export interface ConsumeSsoReturnDeps {
  *     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.1",
+  "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/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';
@@ -88,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();
@@ -102,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 () => {
@@ -310,13 +320,14 @@ describe('consumeSsoReturn', () => {
   });
 
   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,
@@ -326,6 +337,7 @@ describe('consumeSsoReturn', () => {
           pathname: SSO_CALLBACK_PATH,
         }),
         history,
+        dispatchPopState,
       });
 
       expect(result).toEqual(SESSION);
@@ -333,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 () => {
@@ -427,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/ssoReturn.ts

@@ -130,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;
 }
 
 /**
@@ -154,10 +162,16 @@ export interface ConsumeSsoReturnDeps {
  *     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`.
  *
@@ -184,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).
@@ -211,10 +241,39 @@ export async function consumeSsoReturn(
     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;
   }
 
@@ -222,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;
   }
 
@@ -231,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;
 }