@oxyhq/core 3.4.4 → 3.4.5

package/dist/types/index.d.ts

@@ -80,7 +80,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, ssoAttemptedKey, ssoNavigate, buildSsoBounceUrl, isCentralIdPOrigin, guardActive, } from './utils/ssoBounce';
+export { SSO_CALLBACK_PATH, SSO_GUARD_TTL_MS, ssoStateKey, ssoGuardKey, ssoDestKey, ssoNoSessionKey, ssoAttemptedKey, ssoCallbackBootstrapKey, ssoNavigate, getSsoCallbackBootstrapScript, 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

@@ -79,6 +79,29 @@ export declare function ssoNoSessionKey(origin: string): string;
  * centrally) can probe again.
  */
 export declare function ssoAttemptedKey(origin: string): string;
+/**
+ * Per-origin marker written by the pre-hydration callback bootstrap.
+ *
+ * Static Expo exports render unknown paths as `+not-found`; on
+ * `/__oxy/sso-callback` that can fail hydration before the React provider has a
+ * chance to run `consumeSsoReturn`. The bootstrap runs in the HTML head, moves
+ * the URL to a hydratable route while preserving the SSO fragment, and writes
+ * this marker so `consumeSsoReturn` still restores the original destination as
+ * if the page were physically on the callback path.
+ */
+export declare function ssoCallbackBootstrapKey(origin: string): string;
+/**
+ * Inline script for Expo/static web apps.
+ *
+ * Must run before the app bundle hydrates. It is intentionally tiny and
+ * dependency-free: if the browser lands on the internal callback route with an
+ * Oxy SSO fragment, it marks the handoff and rewrites the path to `/` while
+ * preserving `#oxy_sso=...`. The normal SDK cold-boot `sso-return` step then
+ * consumes the fragment from a route that can hydrate. If the internal route is
+ * reached without a valid SSO fragment, it leaves the route via a hard root
+ * navigation because there is no session material to preserve.
+ */
+export declare function getSsoCallbackBootstrapScript(): string;
 /**
  * Perform the terminal top-level SSO bounce navigation.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "3.4.4",
+  "version": "3.4.5",
   "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

@@ -458,7 +458,9 @@ export {
     ssoDestKey,
     ssoNoSessionKey,
     ssoAttemptedKey,
+    ssoCallbackBootstrapKey,
     ssoNavigate,
+    getSsoCallbackBootstrapScript,
     buildSsoBounceUrl,
     isCentralIdPOrigin,
     guardActive,

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

@@ -7,7 +7,42 @@
  * `null` for anything that is not an oxy_sso fragment.
  */
 
-import { parseSsoReturnFragment } from '../ssoReturn';
+import type { SessionLoginResponse } from '../../models/session';
+import { consumeSsoReturn, parseSsoReturnFragment } from '../ssoReturn';
+import {
+  getSsoCallbackBootstrapScript,
+  ssoAttemptedKey,
+  ssoCallbackBootstrapKey,
+  ssoDestKey,
+  ssoNoSessionKey,
+  ssoStateKey,
+} from '../ssoBounce';
+
+class MemorySsoStorage implements Pick<Storage, 'getItem' | 'setItem' | 'removeItem'> {
+  private readonly values = new Map<string, string>();
+
+  getItem(key: string): string | null {
+    return this.values.get(key) ?? null;
+  }
+
+  setItem(key: string, value: string): void {
+    this.values.set(key, value);
+  }
+
+  removeItem(key: string): void {
+    this.values.delete(key);
+  }
+}
+
+const ORIGIN = 'https://app.mention.earth';
+
+const exchangedSession: SessionLoginResponse = {
+  sessionId: 'sess_sso',
+  deviceId: 'device_sso',
+  accessToken: 'access_sso',
+  expiresAt: '2030-01-01T00:00:00.000Z',
+  user: { id: 'user_sso', username: 'sso-user' },
+};
 
 describe('parseSsoReturnFragment', () => {
   describe('ok', () => {
@@ -118,3 +153,99 @@ describe('parseSsoReturnFragment', () => {
     });
   });
 });
+
+describe('consumeSsoReturn pre-hydration callback bootstrap', () => {
+  it('continues an ok callback after the HTML bootstrap moved the URL to a hydratable route', async () => {
+    const storage = new MemorySsoStorage();
+    const replaceStateCalls: string[] = [];
+    const dispatchPopState = jest.fn();
+    const hardRedirect = jest.fn();
+    const exchangeSsoCode = jest.fn(async (): Promise<SessionLoginResponse> => exchangedSession);
+
+    storage.setItem(ssoStateKey(ORIGIN), 'state-ok');
+    storage.setItem(ssoDestKey(ORIGIN), `${ORIGIN}/explore?tab=home#top`);
+    storage.setItem(ssoCallbackBootstrapKey(ORIGIN), '1');
+
+    const session = await consumeSsoReturn(
+      { exchangeSsoCode },
+      {
+        isWeb: () => true,
+        storage,
+        location: {
+          hash: '#oxy_sso=ok&code=opaque-code&state=state-ok',
+          origin: ORIGIN,
+          pathname: '/',
+          search: '',
+        },
+        history: {
+          replaceState: (_data: unknown, _unused: string, url?: string | URL | null): void => {
+            replaceStateCalls.push(String(url ?? ''));
+          },
+        },
+        dispatchPopState,
+        hardRedirect,
+      },
+    );
+
+    expect(session).toBe(exchangedSession);
+    expect(exchangeSsoCode).toHaveBeenCalledWith('opaque-code');
+    expect(replaceStateCalls).toEqual(['/', '/explore?tab=home#top']);
+    expect(dispatchPopState).toHaveBeenCalledTimes(1);
+    expect(hardRedirect).not.toHaveBeenCalled();
+    expect(storage.getItem(ssoCallbackBootstrapKey(ORIGIN))).toBeNull();
+    expect(storage.getItem(ssoDestKey(ORIGIN))).toBeNull();
+    expect(storage.getItem(ssoNoSessionKey(ORIGIN))).toBeNull();
+  });
+
+  it('leaves a bootstrapped none callback with loop breakers set and no exchange', async () => {
+    const storage = new MemorySsoStorage();
+    const replaceStateCalls: string[] = [];
+    const dispatchPopState = jest.fn();
+    const hardRedirect = jest.fn();
+    const exchangeSsoCode = jest.fn(async (): Promise<SessionLoginResponse> => exchangedSession);
+
+    storage.setItem(ssoStateKey(ORIGIN), 'state-none');
+    storage.setItem(ssoDestKey(ORIGIN), `${ORIGIN}/library`);
+    storage.setItem(ssoCallbackBootstrapKey(ORIGIN), '1');
+
+    const session = await consumeSsoReturn(
+      { exchangeSsoCode },
+      {
+        isWeb: () => true,
+        storage,
+        location: {
+          hash: '#oxy_sso=none&state=state-none',
+          origin: ORIGIN,
+          pathname: '/',
+          search: '',
+        },
+        history: {
+          replaceState: (_data: unknown, _unused: string, url?: string | URL | null): void => {
+            replaceStateCalls.push(String(url ?? ''));
+          },
+        },
+        dispatchPopState,
+        hardRedirect,
+      },
+    );
+
+    expect(session).toBeNull();
+    expect(exchangeSsoCode).not.toHaveBeenCalled();
+    expect(replaceStateCalls).toEqual(['/']);
+    expect(dispatchPopState).not.toHaveBeenCalled();
+    expect(hardRedirect).toHaveBeenCalledWith(`${ORIGIN}/library`);
+    expect(storage.getItem(ssoCallbackBootstrapKey(ORIGIN))).toBeNull();
+    expect(storage.getItem(ssoDestKey(ORIGIN))).toBeNull();
+    expect(storage.getItem(ssoNoSessionKey(ORIGIN))).toBe('1');
+    expect(storage.getItem(ssoAttemptedKey(ORIGIN))).toBe('1');
+  });
+
+  it('exposes a pre-hydration script that preserves the SSO fragment', () => {
+    const script = getSsoCallbackBootstrapScript();
+
+    expect(script).toContain('/__oxy/sso-callback');
+    expect(script).toContain('oxy_sso=');
+    expect(script).toContain('window.history.replaceState');
+    expect(script).toContain('window.location.hash');
+  });
+});

package/src/utils/ssoBounce.ts

@@ -67,6 +67,7 @@ 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:';
+const CALLBACK_BOOTSTRAP_KEY_PREFIX = 'oxy_sso_callback_bootstrap:';
 
 /** Per-origin CSRF state key (matched on return to defeat fragment forgery). */
 export function ssoStateKey(origin: string): string {
@@ -105,6 +106,38 @@ export function ssoAttemptedKey(origin: string): string {
   return `${ATTEMPTED_KEY_PREFIX}${origin}`;
 }
 
+/**
+ * Per-origin marker written by the pre-hydration callback bootstrap.
+ *
+ * Static Expo exports render unknown paths as `+not-found`; on
+ * `/__oxy/sso-callback` that can fail hydration before the React provider has a
+ * chance to run `consumeSsoReturn`. The bootstrap runs in the HTML head, moves
+ * the URL to a hydratable route while preserving the SSO fragment, and writes
+ * this marker so `consumeSsoReturn` still restores the original destination as
+ * if the page were physically on the callback path.
+ */
+export function ssoCallbackBootstrapKey(origin: string): string {
+  return `${CALLBACK_BOOTSTRAP_KEY_PREFIX}${origin}`;
+}
+
+/**
+ * Inline script for Expo/static web apps.
+ *
+ * Must run before the app bundle hydrates. It is intentionally tiny and
+ * dependency-free: if the browser lands on the internal callback route with an
+ * Oxy SSO fragment, it marks the handoff and rewrites the path to `/` while
+ * preserving `#oxy_sso=...`. The normal SDK cold-boot `sso-return` step then
+ * consumes the fragment from a route that can hydrate. If the internal route is
+ * reached without a valid SSO fragment, it leaves the route via a hard root
+ * navigation because there is no session material to preserve.
+ */
+export function getSsoCallbackBootstrapScript(): string {
+  const callbackPath = JSON.stringify(SSO_CALLBACK_PATH);
+  const bootstrapPrefix = JSON.stringify(CALLBACK_BOOTSTRAP_KEY_PREFIX);
+
+  return `(function(){var p=${callbackPath};if(window.location.pathname!==p)return;var h=window.location.hash||"";if(!/(?:^#|&)oxy_sso=(?:ok|none|error)(?:&|$)/.test(h)){window.location.replace("/");return;}try{window.sessionStorage.setItem(${bootstrapPrefix}+window.location.origin,"1");}catch(e){window.__oxySsoCallbackBootstrapError=e instanceof Error?e.message:String(e);}try{window.history.replaceState(null,"","/"+h);}catch(e){window.__oxySsoCallbackBootstrapError=e instanceof Error?e.message:String(e);window.location.replace("/"+h);}})();`;
+}
+
 /**
  * Perform the terminal top-level SSO bounce navigation.
  *

package/src/utils/ssoReturn.ts

@@ -29,6 +29,7 @@ import {
   ssoDestKey,
   ssoNoSessionKey,
   ssoAttemptedKey,
+  ssoCallbackBootstrapKey,
 } from './ssoBounce';
 
 /**
@@ -257,6 +258,8 @@ export async function consumeSsoReturn(
   }
 
   const origin = location.origin;
+  const callbackBootstrapKey = ssoCallbackBootstrapKey(origin);
+  const wasCallbackBootstrapped = storage.getItem(callbackBootstrapKey) === '1';
   const expectedState = storage.getItem(ssoStateKey(origin));
   const stateOk = !!ret.state && !!expectedState && ret.state === expectedState;
 
@@ -286,7 +289,8 @@ export async function consumeSsoReturn(
   // (so it can be fed to either `history.replaceState` or a `hardRedirect`),
   // or `null` when the page is not on the callback path (nothing to leave).
   const consumeCallbackTarget = (): string | null => {
-    if (location.pathname !== SSO_CALLBACK_PATH) {
+    storage.removeItem(callbackBootstrapKey);
+    if (location.pathname !== SSO_CALLBACK_PATH && !wasCallbackBootstrapped) {
       // Not on the callback path — still drop the dest key (consumed) but there
       // is nothing to navigate away from.
       storage.removeItem(ssoDestKey(origin));