@oxyhq/core 5.2.1 → 5.3.0

package/src/session/__tests__/SessionClient.state.test.ts

@@ -0,0 +1,64 @@
+import type { DeviceSessionState } from '@oxyhq/contracts';
+import { SessionClient, type SessionClientHost, type TokenTransport } from '../SessionClient';
+
+function makeHost(): SessionClientHost {
+  return {
+    makeRequest: jest.fn(),
+    getBaseURL: () => 'http://test.invalid',
+    getAccessToken: () => 't',
+    onTokensChanged: () => () => undefined,
+    setTokens: jest.fn(),
+    getCurrentAccountId: () => null,
+  };
+}
+const STATE = (rev: number, active: string | null = 'a1'): DeviceSessionState => ({
+  deviceId: 'd1', accounts: active ? [{ accountId: 'a1', sessionId: 's1', authuser: 0 }] : [], activeAccountId: active, revision: rev, updatedAt: 1720000000000,
+});
+
+// SessionClient.applyState is protected; a tiny subclass exposes it for the unit test.
+class TestClient extends SessionClient { public apply(raw: unknown): boolean { return this.applyState(raw); } }
+
+describe('SessionClient state', () => {
+  it('starts with null state', () => {
+    expect(new SessionClient(makeHost()).getState()).toBeNull();
+  });
+
+  it('applies a valid state and notifies subscribers', () => {
+    const c = new TestClient(makeHost());
+    const seen: (DeviceSessionState | null)[] = [];
+    c.subscribe((s) => seen.push(s));
+    expect(c.apply(STATE(1))).toBe(true);
+    expect(c.getState()?.revision).toBe(1);
+    expect(seen.at(-1)?.revision).toBe(1);
+  });
+
+  it('ignores a stale or equal revision (last-writer-wins)', () => {
+    const c = new TestClient(makeHost());
+    c.apply(STATE(5));
+    expect(c.apply(STATE(5))).toBe(false);
+    expect(c.apply(STATE(4))).toBe(false);
+    expect(c.getState()?.revision).toBe(5);
+  });
+
+  it('rejects an invalid (unvalidated) state without applying', () => {
+    const c = new TestClient(makeHost());
+    expect(c.apply({ deviceId: 'd1', accounts: 'nope', revision: 1 })).toBe(false);
+    expect(c.getState()).toBeNull();
+  });
+
+  it('calls transport.ensureActiveToken when a state is applied', () => {
+    const transport: TokenTransport = { ensureActiveToken: jest.fn().mockResolvedValue(undefined) };
+    const c = new TestClient(makeHost(), { transport });
+    c.apply(STATE(1));
+    expect(transport.ensureActiveToken).toHaveBeenCalledWith(expect.objectContaining({ revision: 1 }));
+  });
+
+  it('unsubscribe stops notifications', () => {
+    const c = new TestClient(makeHost());
+    const seen: unknown[] = [];
+    const off = c.subscribe((s) => seen.push(s));
+    off();
+    c.apply(STATE(1));
+    expect(seen).toHaveLength(0);
+  });
+});

package/src/session/__tests__/sessionIntegration.test.ts

@@ -0,0 +1,202 @@
+import type { DeviceSessionState } from '@oxyhq/contracts';
+import type { User } from '../../models/interfaces';
+import { SessionClient, type TokenTransport } from '../SessionClient';
+import { createSessionClientHost } from '../sessionClientHost';
+import { createSessionClient } from '../createSessionClient';
+import {
+  accountIdsOf,
+  activeSessionIdOf,
+  activeUserOf,
+  deviceStateToClientSessions,
+} from '../projectSessionState';
+
+function fakeOxy() {
+  const listeners = new Set<(t: string | null) => void>();
+  return {
+    makeRequest: jest.fn().mockResolvedValue({ ok: true }),
+    getBaseURL: jest.fn().mockReturnValue('https://api.oxy.so'),
+    getAccessToken: jest.fn().mockReturnValue('tok'),
+    setTokens: jest.fn(),
+    onTokensChanged: jest.fn((l: (t: string | null) => void) => {
+      listeners.add(l);
+      return () => listeners.delete(l);
+    }),
+    _emit: (t: string | null) => listeners.forEach((l) => l(t)),
+  };
+}
+
+describe('createSessionClientHost', () => {
+  test('delegates REST + token methods to oxyServices', async () => {
+    const oxy = fakeOxy();
+    const host = createSessionClientHost(oxy as never);
+    await host.makeRequest('GET', '/session/device/state', undefined, { cache: false });
+    expect(oxy.makeRequest).toHaveBeenCalledWith('GET', '/session/device/state', undefined, { cache: false });
+    expect(host.getBaseURL()).toBe('https://api.oxy.so');
+    expect(host.getAccessToken()).toBe('tok');
+    host.setTokens('new');
+    expect(oxy.setTokens).toHaveBeenCalledWith('new');
+  });
+
+  test('getCurrentAccountId reflects setCurrentAccountId', () => {
+    const host = createSessionClientHost(fakeOxy() as never);
+    expect(host.getCurrentAccountId()).toBeNull();
+    host.setCurrentAccountId('u1');
+    expect(host.getCurrentAccountId()).toBe('u1');
+  });
+
+  test('onTokensChanged forwards to oxyServices and unsubscribes', () => {
+    const oxy = fakeOxy();
+    const host = createSessionClientHost(oxy as never);
+    const cb = jest.fn();
+    const unsub = host.onTokensChanged(cb);
+    oxy._emit(null);
+    expect(cb).toHaveBeenCalledWith(null);
+    unsub();
+    oxy._emit('x');
+    expect(cb).toHaveBeenCalledTimes(1);
+  });
+});
+
+function makeUser(id: string): User {
+  return {
+    id,
+    publicKey: `pk-${id}`,
+    username: `user-${id}`,
+    name: {},
+  };
+}
+
+// DeviceSessionState.updatedAt is an epoch-ms number on the wire (see
+// packages/contracts/src/deviceSession.ts: `updatedAt: z.number()`), not an
+// ISO string.
+const UPDATED_AT_MS = Date.UTC(2026, 6, 1, 0, 0, 0, 0);
+const UPDATED_AT_ISO = new Date(UPDATED_AT_MS).toISOString();
+
+const state: DeviceSessionState = {
+  deviceId: 'device-1',
+  accounts: [
+    { accountId: 'a1', sessionId: 'sess-a1', authuser: 0 },
+    { accountId: 'a2', sessionId: 'sess-a2', authuser: 1 },
+  ],
+  activeAccountId: 'a2',
+  revision: 1,
+  updatedAt: UPDATED_AT_MS,
+};
+
+const usersById = new Map<string, User>([
+  ['a1', makeUser('a1')],
+  ['a2', makeUser('a2')],
+]);
+
+describe('projectSessionState', () => {
+  describe('activeSessionIdOf', () => {
+    test('returns the active account sessionId', () => {
+      expect(activeSessionIdOf(state)).toBe('sess-a2');
+    });
+
+    test('returns null for null state', () => {
+      expect(activeSessionIdOf(null)).toBeNull();
+    });
+
+    test('returns null when activeAccountId is null', () => {
+      expect(activeSessionIdOf({ ...state, activeAccountId: null })).toBeNull();
+    });
+  });
+
+  describe('deviceStateToClientSessions', () => {
+    test('maps every account in order with isCurrent + authuser', () => {
+      const sessions = deviceStateToClientSessions(state, usersById);
+      expect(sessions).toHaveLength(2);
+      expect(sessions[0]).toEqual({
+        sessionId: 'sess-a1',
+        deviceId: 'device-1',
+        expiresAt: UPDATED_AT_ISO,
+        lastActive: UPDATED_AT_ISO,
+        userId: 'a1',
+        isCurrent: false,
+        authuser: 0,
+      });
+      expect(sessions[1]).toEqual({
+        sessionId: 'sess-a2',
+        deviceId: 'device-1',
+        expiresAt: UPDATED_AT_ISO,
+        lastActive: UPDATED_AT_ISO,
+        userId: 'a2',
+        isCurrent: true,
+        authuser: 1,
+      });
+    });
+
+    test('still projects a session for an account absent from usersById', () => {
+      const sessions = deviceStateToClientSessions(state, new Map());
+      expect(sessions).toHaveLength(2);
+      expect(sessions.map((session) => session.userId)).toEqual(['a1', 'a2']);
+    });
+  });
+
+  describe('activeUserOf', () => {
+    test('returns the active account user', () => {
+      expect(activeUserOf(state, usersById)).toEqual(makeUser('a2'));
+    });
+
+    test('returns null for null state', () => {
+      expect(activeUserOf(null, usersById)).toBeNull();
+    });
+
+    test('returns null when activeAccountId is null', () => {
+      expect(activeUserOf({ ...state, activeAccountId: null }, usersById)).toBeNull();
+    });
+
+    test('returns null when the active account id is absent from usersById', () => {
+      expect(activeUserOf(state, new Map())).toBeNull();
+    });
+  });
+
+  describe('accountIdsOf', () => {
+    test('returns every account id in order', () => {
+      expect(accountIdsOf(state)).toEqual(['a1', 'a2']);
+    });
+
+    test('returns [] for null state', () => {
+      expect(accountIdsOf(null)).toEqual([]);
+    });
+  });
+});
+
+describe('createSessionClient', () => {
+  function fakeTransport(): TokenTransport {
+    return { ensureActiveToken: jest.fn().mockResolvedValue(undefined) };
+  }
+
+  test('wires a SessionClient instance backed by the host + injected transport', () => {
+    const oxy = fakeOxy();
+
+    const { client, host } = createSessionClient(oxy as never, fakeTransport());
+
+    expect(client).toBeInstanceOf(SessionClient);
+    expect(typeof client.bootstrap).toBe('function');
+    expect(client.getState()).toBeNull();
+    expect(typeof host.setCurrentAccountId).toBe('function');
+  });
+
+  test('the returned host reflects setCurrentAccountId', () => {
+    const oxy = fakeOxy();
+
+    const { host } = createSessionClient(oxy as never, fakeTransport());
+
+    expect(host.getCurrentAccountId()).toBeNull();
+    host.setCurrentAccountId('u1');
+    expect(host.getCurrentAccountId()).toBe('u1');
+  });
+
+  test('uses the injected transport (not a hard-coded one) when the client bootstraps', async () => {
+    const oxy = fakeOxy();
+    oxy.makeRequest.mockResolvedValue({ data: { state, activeToken: null } });
+    const transport = fakeTransport();
+
+    const { client } = createSessionClient(oxy as never, transport);
+    await client.bootstrap();
+
+    expect(transport.ensureActiveToken).toHaveBeenCalledWith(expect.objectContaining({ revision: state.revision }));
+  });
+});

package/src/session/createSessionClient.ts

@@ -0,0 +1,31 @@
+import type { OxyServices } from '../OxyServices';
+import { SessionClient, type TokenTransport } from './SessionClient';
+import { createSessionClientHost } from './sessionClientHost';
+
+/**
+ * Wires a `SessionClient` over the given `OxyServices` instance: builds the
+ * `SessionClientHost` adapter and passes it through together with a
+ * caller-supplied `TokenTransport`.
+ *
+ * The transport is a required parameter (not constructed here) because it is
+ * the one piece of this integration that is NOT platform-agnostic: `services`
+ * branches native (shared-keychain sign-in) vs. web (silent sign-in), while
+ * `auth-sdk` is web-only. Each consumer builds its own transport and passes
+ * it in; this factory only wires the platform-agnostic parts (host + client)
+ * so neither consumer re-implements them.
+ *
+ * The host is returned alongside the client (not just the client) so the
+ * caller can call `host.setCurrentAccountId(...)` as the active account
+ * changes.
+ */
+export function createSessionClient(
+  oxyServices: OxyServices,
+  transport: TokenTransport,
+): {
+  client: SessionClient;
+  host: ReturnType<typeof createSessionClientHost>;
+} {
+  const host = createSessionClientHost(oxyServices);
+  const client = new SessionClient(host, { transport });
+  return { client, host };
+}

package/src/session/projectSessionState.ts

@@ -0,0 +1,83 @@
+import type { DeviceSessionState } from '@oxyhq/contracts';
+import type { ClientSession } from '../models/session';
+import type { User } from '../models/interfaces';
+
+/**
+ * Pure projection helpers: `DeviceSessionState` (the device-scoped
+ * multi-account session-sync state produced by `SessionClient`) -> the
+ * shapes consumers (`@oxyhq/services`, `@oxyhq/auth`) render today
+ * (`ClientSession[]`, an active session id, an active `User`).
+ *
+ * No I/O. The caller fetches profiles via
+ * `oxyServices.getUsersByIds(accountIdsOf(state))` and builds `usersById`
+ * from the result before calling `deviceStateToClientSessions` /
+ * `activeUserOf`.
+ */
+
+/**
+ * Maps every `SessionAccount` in `state.accounts` to a `ClientSession`.
+ *
+ * `DeviceSessionState` carries no per-account `expiresAt` / `lastActive` —
+ * both are set to `state.updatedAt` (converted to an ISO-8601 string; the
+ * wire value is an epoch-ms number) as a provisional value.
+ *
+ * `usersById` is accepted for signature symmetry with `activeUserOf` even
+ * though `ClientSession` only stores `userId` — a session is still
+ * projected for an account whose id is absent from `usersById` (no
+ * placeholder user is fabricated).
+ */
+export function deviceStateToClientSessions(
+  state: DeviceSessionState,
+  usersById: Map<string, User>,
+): ClientSession[] {
+  const provisionalTimestamp = new Date(state.updatedAt).toISOString();
+  return state.accounts.map((account) => ({
+    sessionId: account.sessionId,
+    deviceId: state.deviceId,
+    // provisional: expiresAt/lastActive are not carried on DeviceSessionState
+    expiresAt: provisionalTimestamp,
+    lastActive: provisionalTimestamp,
+    userId: account.accountId,
+    isCurrent: account.accountId === state.activeAccountId,
+    authuser: account.authuser,
+  }));
+}
+
+/**
+ * The active account's `sessionId`, or `null` when there is no state or no
+ * active account is set.
+ */
+export function activeSessionIdOf(state: DeviceSessionState | null): string | null {
+  if (state === null || state.activeAccountId === null) {
+    return null;
+  }
+  const activeAccountId = state.activeAccountId;
+  const activeAccount = state.accounts.find((account) => account.accountId === activeAccountId);
+  return activeAccount?.sessionId ?? null;
+}
+
+/**
+ * The active account's `User`, resolved from `usersById`. `null` when there
+ * is no state, no active account is set, or the active account id is absent
+ * from `usersById`.
+ */
+export function activeUserOf(
+  state: DeviceSessionState | null,
+  usersById: Map<string, User>,
+): User | null {
+  if (state === null || state.activeAccountId === null) {
+    return null;
+  }
+  return usersById.get(state.activeAccountId) ?? null;
+}
+
+/**
+ * All account ids in `state`, suitable for an `oxyServices.getUsersByIds(...)`
+ * fetch. `[]` for `null` state.
+ */
+export function accountIdsOf(state: DeviceSessionState | null): string[] {
+  if (state === null) {
+    return [];
+  }
+  return state.accounts.map((account) => account.accountId);
+}

package/src/session/sessionClientHost.ts

@@ -0,0 +1,32 @@
+import type { OxyServices } from '../OxyServices';
+import type { SessionClientHost } from './SessionClient';
+
+/**
+ * Thin `SessionClientHost` adapter over an `OxyServices` instance.
+ *
+ * `SessionClient` is host-agnostic: it only needs a REST + token surface.
+ * `OxyServices` already exposes all of that except `getCurrentAccountId`,
+ * which has no direct equivalent — the adapter holds a mutable ref set by
+ * the caller (`OxyContext` in `@oxyhq/services`, `WebOxyProvider` in
+ * `@oxyhq/auth`) via `setCurrentAccountId`.
+ *
+ * Shared here (rather than duplicated per consumer) because it is entirely
+ * platform-agnostic: every method it calls exists identically on
+ * `OxyServices` regardless of host (web, Expo/RN, Node).
+ */
+export function createSessionClientHost(
+  oxyServices: OxyServices,
+): SessionClientHost & { setCurrentAccountId(id: string | null): void } {
+  let currentAccountId: string | null = null;
+  return {
+    makeRequest: (method, url, data, options) => oxyServices.makeRequest(method, url, data, options),
+    getBaseURL: () => oxyServices.getBaseURL(),
+    getAccessToken: () => oxyServices.getAccessToken(),
+    onTokensChanged: (listener) => oxyServices.onTokensChanged(listener),
+    setTokens: (accessToken) => oxyServices.setTokens(accessToken),
+    getCurrentAccountId: () => currentAccountId,
+    setCurrentAccountId: (id) => {
+      currentAccountId = id;
+    },
+  };
+}

package/src/session/socketLoader.ts

@@ -0,0 +1,28 @@
+import { logger } from '../utils/loggerUtils';
+
+export interface MinimalSocket {
+  connected: boolean;
+  on(event: string, handler: (...args: unknown[]) => void): void;
+  off(event: string, handler?: (...args: unknown[]) => void): void;
+  connect(): void;
+  disconnect(): void;
+}
+
+export type SocketIOFactory = (uri: string, opts?: Record<string, unknown>) => MinimalSocket;
+
+let cachedFactory: SocketIOFactory | null = null;
+let loadAttempted = false;
+
+export async function getSocketIO(): Promise<SocketIOFactory | null> {
+  if (cachedFactory) return cachedFactory;
+  if (loadAttempted) return null;
+  loadAttempted = true;
+  try {
+    const mod = (await import('socket.io-client')) as { io?: SocketIOFactory; default?: SocketIOFactory };
+    cachedFactory = mod.io ?? mod.default ?? null;
+    return cachedFactory;
+  } catch (error) {
+    logger.warn('[SessionClient] socket.io-client import failed; realtime session sync disabled', { component: 'SessionClient' }, error);
+    return null;
+  }
+}

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

@@ -0,0 +1,204 @@
+/**
+ * `establishIdpSessionAfterClaim` — the post-claim durable-session hop.
+ *
+ * After a WEB device-flow ("Sign in with Oxy" QR) claim commits, the app holds
+ * only in-memory tokens: no `fedcm_session` cookie was ever planted at the IdP,
+ * so a reload cannot re-mint a token. This primitive performs ONE top-level
+ * establish hop (via the RP-minted establish-URL) so the per-apex IdP cookie is
+ * planted and a reload restores via the existing `sso-return` / silent-iframe
+ * paths.
+ *
+ * Invariants pinned here:
+ *  - web only (no-op off-web / native);
+ *  - never fires while sitting on the central IdP origin (would loop);
+ *  - persists the SAME bounce state (`ssoStateKey`/`ssoGuardKey`/`ssoDestKey`)
+ *    the `buildSsoBounceUrl` machinery primes, so the post-bounce `sso-return`
+ *    step validates the state, exchanges the code, and restores the dest;
+ *  - persists ONLY after the establish-URL request succeeds (no stale state on
+ *    failure);
+ *  - navigates exactly once, to the server-returned establish URL;
+ *  - total: an establish-request failure leaves the committed in-memory session
+ *    untouched, does NOT navigate, and returns `false` (user no worse off).
+ */
+
+import { establishIdpSessionAfterClaim } from '../ssoEstablish';
+import {
+  ssoStateKey,
+  ssoGuardKey,
+  ssoDestKey,
+} from '../ssoBounce';
+import { CENTRAL_AUTH_URL } from '../authWebUrl';
+
+const RP_ORIGIN = 'https://accounts.oxy.so';
+const RP_HREF = 'https://accounts.oxy.so/settings';
+const ESTABLISH_URL =
+  'https://auth.oxy.so/sso/establish?et=jwt.abc.def&return_to=https%3A%2F%2Faccounts.oxy.so%2F__oxy%2Fsso-callback&state=state-xyz';
+
+function makeStorage(): {
+  storage: Pick<Storage, 'getItem' | 'setItem'>;
+  map: Map<string, string>;
+} {
+  const map = new Map<string, string>();
+  return {
+    map,
+    storage: {
+      getItem: (k: string) => (map.has(k) ? (map.get(k) as string) : null),
+      setItem: (k: string, v: string) => {
+        map.set(k, v);
+      },
+    },
+  };
+}
+
+describe('establishIdpSessionAfterClaim', () => {
+  it('requests the establish URL with the RP origin + generated state and navigates once (web)', async () => {
+    const { storage, map } = makeStorage();
+    const navigated: string[] = [];
+    const requestSsoEstablishUrl = jest.fn(async (origin: string, state: string) => {
+      expect(origin).toBe(RP_ORIGIN);
+      expect(state).toBe('state-xyz');
+      return { establishUrl: ESTABLISH_URL };
+    });
+
+    const result = await establishIdpSessionAfterClaim(
+      { requestSsoEstablishUrl },
+      {
+        isWeb: () => true,
+        storage,
+        location: { origin: RP_ORIGIN, href: RP_HREF },
+        navigate: (url) => navigated.push(url),
+        generateState: () => 'state-xyz',
+        now: () => 1_700_000_000_000,
+      },
+    );
+
+    expect(result).toBe(true);
+    expect(requestSsoEstablishUrl).toHaveBeenCalledTimes(1);
+    expect(navigated).toEqual([ESTABLISH_URL]);
+
+    // Bounce state persisted so the post-bounce `sso-return` step validates it.
+    expect(map.get(ssoStateKey(RP_ORIGIN))).toBe('state-xyz');
+    expect(map.get(ssoGuardKey(RP_ORIGIN))).toBe(String(1_700_000_000_000));
+    expect(map.get(ssoDestKey(RP_ORIGIN))).toBe(RP_HREF);
+  });
+
+  it('is a no-op off-web (native): no request, no navigation, no state', async () => {
+    const { storage, map } = makeStorage();
+    const navigated: string[] = [];
+    const requestSsoEstablishUrl = jest.fn(async () => ({ establishUrl: ESTABLISH_URL }));
+
+    const result = await establishIdpSessionAfterClaim(
+      { requestSsoEstablishUrl },
+      {
+        isWeb: () => false,
+        storage,
+        location: { origin: RP_ORIGIN, href: RP_HREF },
+        navigate: (url) => navigated.push(url),
+      },
+    );
+
+    expect(result).toBe(false);
+    expect(requestSsoEstablishUrl).not.toHaveBeenCalled();
+    expect(navigated).toEqual([]);
+    expect(map.size).toBe(0);
+  });
+
+  it('never fires while sitting on the central IdP origin (loop guard)', async () => {
+    const { storage, map } = makeStorage();
+    const navigated: string[] = [];
+    const requestSsoEstablishUrl = jest.fn(async () => ({ establishUrl: ESTABLISH_URL }));
+
+    const result = await establishIdpSessionAfterClaim(
+      { requestSsoEstablishUrl },
+      {
+        isWeb: () => true,
+        storage,
+        location: { origin: new URL(CENTRAL_AUTH_URL).origin, href: `${CENTRAL_AUTH_URL}/` },
+        navigate: (url) => navigated.push(url),
+      },
+    );
+
+    expect(result).toBe(false);
+    expect(requestSsoEstablishUrl).not.toHaveBeenCalled();
+    expect(navigated).toEqual([]);
+    expect(map.size).toBe(0);
+  });
+
+  it('on an establish-request failure: no navigation, no persisted state, returns false (single attempt)', async () => {
+    const { storage, map } = makeStorage();
+    const navigated: string[] = [];
+    const onError = jest.fn();
+    const requestSsoEstablishUrl = jest.fn(async () => {
+      throw new Error('403 unapproved origin');
+    });
+
+    const result = await establishIdpSessionAfterClaim(
+      { requestSsoEstablishUrl },
+      {
+        isWeb: () => true,
+        storage,
+        location: { origin: RP_ORIGIN, href: RP_HREF },
+        navigate: (url) => navigated.push(url),
+        generateState: () => 'state-xyz',
+        onError,
+      },
+    );
+
+    expect(result).toBe(false);
+    expect(requestSsoEstablishUrl).toHaveBeenCalledTimes(1);
+    expect(navigated).toEqual([]);
+    // No stale bounce state left behind on failure.
+    expect(map.size).toBe(0);
+    expect(onError).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not navigate when the server returns no establish URL', async () => {
+    const { storage, map } = makeStorage();
+    const navigated: string[] = [];
+    const requestSsoEstablishUrl = jest.fn(async () => ({ establishUrl: '' }));
+
+    const result = await establishIdpSessionAfterClaim(
+      { requestSsoEstablishUrl },
+      {
+        isWeb: () => true,
+        storage,
+        location: { origin: RP_ORIGIN, href: RP_HREF },
+        navigate: (url) => navigated.push(url),
+        generateState: () => 'state-xyz',
+      },
+    );
+
+    expect(result).toBe(false);
+    expect(navigated).toEqual([]);
+    expect(map.size).toBe(0);
+  });
+
+  it.each([
+    ['unparseable', 'not a url'],
+    ['non-https (http)', 'http://auth.oxy.so/sso/establish?et=x&state=s'],
+    ['wrong path', 'https://auth.oxy.so/evil?et=x&state=s'],
+    ['non-auth host', 'https://evil.oxy.so/sso/establish?et=x&state=s'],
+  ])(
+    'aborts silently (no navigation, no state) for a %s establish URL',
+    async (_label, badUrl) => {
+      const { storage, map } = makeStorage();
+      const navigated: string[] = [];
+      const requestSsoEstablishUrl = jest.fn(async () => ({ establishUrl: badUrl }));
+
+      const result = await establishIdpSessionAfterClaim(
+        { requestSsoEstablishUrl },
+        {
+          isWeb: () => true,
+          storage,
+          location: { origin: RP_ORIGIN, href: RP_HREF },
+          navigate: (url) => navigated.push(url),
+          generateState: () => 'state-xyz',
+        },
+      );
+
+      expect(result).toBe(false);
+      expect(navigated).toEqual([]);
+      expect(map.size).toBe(0);
+    },
+  );
+});

package/src/utils/ssoBounce.ts

@@ -135,18 +135,18 @@ export function ssoPriorSessionKey(origin: string): string {
  * per-tab `sessionStorage` the loop-breaker keys use — it must survive a reload.
  *
  * It exists purely to suppress AUTOMATIC silent restore after a deliberate
- * sign-out: a still-live IdP session (the central `fedcm_session` / the FedCM
- * credential association) would otherwise let `fedcm-silent` / the per-apex
- * `/auth/silent` iframe re-mint a session on the very next cold boot, so a user
- * who pressed "Sign out" gets silently signed back in on reload. With this flag
- * set, those silent cold-boot steps are skipped while the Gmail-style
- * returning-account fast-path is otherwise preserved.
+ * sign-out: a still-live IdP session (the central `fedcm_session`) would
+ * otherwise let the per-apex `/auth/silent` iframe re-mint a session on the
+ * very next cold boot, so a user who pressed "Sign out" gets silently signed
+ * back in on reload. With this flag set, that silent cold-boot step is
+ * skipped while the Gmail-style returning-account fast-path is otherwise
+ * preserved.
  *
  * Lifecycle (mirrors the existing gate machinery — set on a definitive event,
  * cleared on its inverse):
  *   - SET on EXPLICIT full sign-out (alongside clearing the prior-session hint
  *     and the SSO bounce state).
- *   - CLEARED on ANY deliberate sign-in (password, FedCM, account switch, device
+ *   - CLEARED on ANY deliberate sign-in (password, account switch, device
  *     claim) so a real sign-in fully re-enables silent restore — there is no
  *     "stuck signed out" state.
  *
@@ -303,8 +303,8 @@ export function guardActive(
  * Whether AUTOMATIC silent restore is SUPPRESSED for this origin because the
  * user deliberately signed out (the durable {@link ssoSignedOutKey} flag).
  *
- * When `true`, the silent cold-boot steps that can re-mint a session from a
- * still-live IdP session WITHOUT user intent — `fedcm-silent` and the per-apex
+ * When `true`, the silent cold-boot step that can re-mint a session from a
+ * still-live IdP session WITHOUT user intent — the per-apex
  * `/auth/silent` iframe — MUST be skipped, so a user who pressed "Sign out" is
  * not silently signed back in on the next reload. Interactive sign-in clears the
  * flag, so this never blocks a deliberate re-sign-in.