@oxyhq/core 9.1.0 → 9.2.0

package/src/session/SessionClient.ts

@@ -13,10 +13,17 @@ export interface TokenTransport {
   ensureActiveToken(state: DeviceSessionState): Promise<void>;
 }
 
+export interface DeviceCredential {
+  deviceId: string;
+  deviceSecret: string;
+}
+
 export interface SessionClientHost {
   makeRequest<T>(method: 'GET' | 'POST', url: string, data?: unknown, options?: { cache?: boolean }): Promise<T>;
   getBaseURL(): string;
   getAccessToken(): string | null;
+  /** Zero-cookie device credential for socket handshake when no bearer is planted yet. */
+  getDeviceCredential(): DeviceCredential | null;
   onTokensChanged(listener: (token: string | null) => void): () => void;
   setTokens(accessToken: string): void;
   getCurrentAccountId(): string | null;
@@ -123,20 +130,33 @@ export class SessionClient {
       return false;
     }
     this.state = next;
-    this.notify();
-    if (this.options.transport) {
-      void this.options.transport.ensureActiveToken(next).catch((error) => {
+    const transport = this.options.transport;
+    const needsMintBeforeNotify =
+      transport != null && next.accounts.length > 0 && !this.host.getAccessToken();
+
+    const finishApply = (): void => {
+      this.notify();
+      if (next.accounts.length === 0 && this.options.onUnauthenticated) {
+        try {
+          this.options.onUnauthenticated();
+        } catch (error) {
+          logger.error('[SessionClient] onUnauthenticated threw', error);
+        }
+      }
+    };
+
+    if (needsMintBeforeNotify) {
+      void transport.ensureActiveToken(next).then(finishApply).catch((error) => {
         logger.warn('[SessionClient] ensureActiveToken failed', { component: 'SessionClient' }, error);
+        finishApply();
       });
-    }
-    // A device signout-all leaves zero accounts — tell the provider to clear
-    // the persisted store so a reload does not try to restore a dead session.
-    if (next.accounts.length === 0 && this.options.onUnauthenticated) {
-      try {
-        this.options.onUnauthenticated();
-      } catch (error) {
-        logger.error('[SessionClient] onUnauthenticated threw', error);
+    } else {
+      if (transport) {
+        void transport.ensureActiveToken(next).catch((error) => {
+          logger.warn('[SessionClient] ensureActiveToken failed', { component: 'SessionClient' }, error);
+        });
       }
+      finishApply();
     }
     return true;
   }
@@ -222,18 +242,23 @@ export class SessionClient {
     this.started = true;
     this.tokenUnsub = this.host.onTokensChanged((token) => {
       // A rotated/fresh bearer landed — reconnect a dropped socket so its
-      // handshake re-runs with the current token. Sign-out (null token) is
-      // handled by the consumer calling `stop()`.
-      if (!token || !this.socket) return;
-      if (!this.socket.connected) {
+      // handshake re-runs with the current token. Sign-out (null token) keeps
+      // the device-scoped socket when a device credential is available.
+      if (!this.socket) return;
+      if (token) {
+        if (!this.socket.connected) {
+          this.socket.connect();
+        }
+        return;
+      }
+      const cred = this.host.getDeviceCredential();
+      if (cred && !this.socket.connected) {
         this.socket.connect();
       }
     });
     this.openBroadcastChannel();
-    // `bootstrap` (`GET /session/device/state`) is bearer-authenticated. A
-    // signed-out client opens no socket and runs no bootstrap; a bootstrap
-    // failure is non-fatal — the socket still connects so realtime sync
-    // survives a transient state-fetch error.
+    // Device-scoped socket: bearer when authenticated, else deviceId+deviceSecret so
+    // signed-out tabs still receive `session_state` and can mint on change.
     if (this.host.getAccessToken()) {
       try {
         await this.bootstrap();
@@ -275,24 +300,41 @@ export class SessionClient {
       return;
     }
     if (!this.started) return; // stopped while the dynamic import was in flight
-    // Sockets are BEARER-ONLY: the server rejects any handshake without a valid
-    // bearer, so a signed-out client never opens a socket.
-    if (!this.host.getAccessToken()) return;
+
+    const token = this.host.getAccessToken();
+    const deviceCredential = this.host.getDeviceCredential();
+    if (!token && !deviceCredential) return;
 
     const socket = io(this.host.getBaseURL(), {
       transports: ['websocket'],
       autoConnect: true,
-      auth: (cb: (data: { token: string }) => void) => {
-        cb({ token: this.host.getAccessToken() ?? '' });
+      reconnection: true,
+      reconnectionAttempts: Infinity,
+      reconnectionDelay: 1000,
+      reconnectionDelayMax: 10000,
+      auth: (cb: (data: Record<string, string>) => void) => {
+        const bearer = this.host.getAccessToken();
+        if (bearer) {
+          cb({ token: bearer });
+          return;
+        }
+        const cred = this.host.getDeviceCredential();
+        if (cred) {
+          cb({ deviceId: cred.deviceId, deviceSecret: cred.deviceSecret });
+          return;
+        }
+        cb({ token: '' });
       },
     });
     socket.on('session_state', (payload: unknown) => {
       const applied = this.applyState(payload);
       if (!applied) return;
       // A push changed the active account on another device/tab — re-fetch state
-      // to plant the access token for the newly-active account.
+      // to plant the access token for the newly-active account. When this tab is
+      // still signed out, applyState mints via ensureActiveToken first; bootstrap
+      // requires a bearer and must not run until then.
       const active = this.state?.activeAccountId ?? null;
-      if (active && active !== this.host.getCurrentAccountId()) {
+      if (active && active !== this.host.getCurrentAccountId() && this.host.getAccessToken()) {
         void this.bootstrap().catch((error) => {
           logger.warn('[SessionClient] post-push token fetch failed', { component: 'SessionClient' }, error);
         });

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

@@ -16,6 +16,7 @@ function makeHost(makeRequest: jest.Mock, currentAccountId: string | null = null
     makeRequest,
     getBaseURL: () => 'http://test.invalid',
     getAccessToken: () => 't',
+    getDeviceCredential: () => null,
     onTokensChanged: () => () => undefined,
     setTokens: jest.fn(),
     getCurrentAccountId: () => currentAccountId,

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

@@ -55,6 +55,7 @@ function makeHost(over: Partial<SessionClientHost> = {}): SessionClientHost {
     makeRequest: jest.fn().mockResolvedValue(SYNC(1)),
     getBaseURL: () => 'http://test.invalid',
     getAccessToken: () => 'tok',
+    getDeviceCredential: () => null,
     onTokensChanged: () => () => undefined,
     setTokens: jest.fn(),
     getCurrentAccountId: () => 'a1',

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

@@ -11,6 +11,7 @@ function makeHost(makeRequest: jest.Mock): SessionClientHost {
     makeRequest,
     getBaseURL: () => 'http://test.invalid',
     getAccessToken: () => 't',
+    getDeviceCredential: () => null,
     onTokensChanged: () => () => undefined,
     setTokens: jest.fn(),
     getCurrentAccountId: () => null,

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

@@ -10,6 +10,7 @@ function makeHost(makeRequest: jest.Mock): SessionClientHost {
     makeRequest,
     getBaseURL: () => 'http://test.invalid',
     getAccessToken: () => 't',
+    getDeviceCredential: () => null,
     onTokensChanged: () => () => undefined,
     setTokens: jest.fn(),
     getCurrentAccountId: () => null,

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

@@ -30,6 +30,7 @@ function makeHost(over: Partial<SessionClientHost> = {}): SessionClientHost {
     makeRequest: jest.fn().mockResolvedValue(SYNC(1)),
     getBaseURL: () => 'http://test.invalid',
     getAccessToken: () => 'tok',
+    getDeviceCredential: () => null,
     onTokensChanged: () => () => undefined,
     setTokens: jest.fn(),
     getCurrentAccountId: () => 'a1',

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

@@ -32,6 +32,7 @@ function makeHost(over: Partial<SessionClientHost> = {}): SessionClientHost {
     makeRequest: jest.fn().mockResolvedValue(SYNC(1)),
     getBaseURL: () => 'http://test.invalid',
     getAccessToken: () => 'tok',
+    getDeviceCredential: () => null,
     onTokensChanged: () => () => undefined,
     setTokens: jest.fn(),
     getCurrentAccountId: () => 'a1',

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

@@ -6,6 +6,7 @@ function makeHost(): SessionClientHost {
     makeRequest: jest.fn(),
     getBaseURL: () => 'http://test.invalid',
     getAccessToken: () => 't',
+    getDeviceCredential: () => null,
     onTokensChanged: () => () => undefined,
     setTokens: jest.fn(),
     getCurrentAccountId: () => null,

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

@@ -22,6 +22,7 @@ function host(): SessionClientHost {
     makeRequest: jest.fn(),
     getBaseURL: () => 'http://test.invalid',
     getAccessToken: () => 'token',
+    getDeviceCredential: () => null,
     onTokensChanged: () => () => undefined,
     setTokens: jest.fn(),
     getCurrentAccountId: () => null,
@@ -533,7 +534,23 @@ describe('AccountDialogController — sign in with Oxy', () => {
 });
 
 describe('AccountDialogController — openPasswordAtOxyAuth', () => {
-  it('builds the IdP sign-in URL with redirect_uri + client_id and invokes openUrl', () => {
+  beforeEach(() => {
+    const store = new Map<string, string>();
+    Object.defineProperty(globalThis, 'sessionStorage', {
+      value: {
+        getItem: (key: string) => store.get(key) ?? null,
+        setItem: (key: string, value: string) => {
+          store.set(key, value);
+        },
+        removeItem: (key: string) => {
+          store.delete(key);
+        },
+      },
+      configurable: true,
+    });
+  });
+
+  it('builds the IdP sign-in URL with redirect_uri + client_id and invokes openUrl', async () => {
     const oxy = makeOxy();
     const sc = new TestSessionClient(host());
     const openUrl = jest.fn();
@@ -544,17 +561,32 @@ describe('AccountDialogController — openPasswordAtOxyAuth', () => {
       openUrl,
     });
 
-    const url = controller.openPasswordAtOxyAuth({ returnUrl: 'https://mention.earth/', state: 'xyz' });
+    const url = await controller.openPasswordAtOxyAuth({ returnUrl: 'https://mention.earth/dashboard' });
     const parsed = new URL(url);
     expect(parsed.origin).toBe('https://auth.oxy.so');
     expect(parsed.pathname).toBe('/login');
-    expect(parsed.searchParams.get('redirect_uri')).toBe('https://mention.earth/');
+    expect(parsed.searchParams.get('redirect_uri')).toBe('https://mention.earth');
     expect(parsed.searchParams.get('client_id')).toBe('oxy_dk_test');
-    expect(parsed.searchParams.get('state')).toBe('xyz');
+    expect(parsed.searchParams.get('state')).toBeTruthy();
+    expect(parsed.searchParams.get('code_challenge')).toBeTruthy();
+    expect(parsed.searchParams.get('code_challenge_method')).toBe('S256');
     expect(openUrl).toHaveBeenCalledWith(url);
   });
 
-  it('honors an idpApex override', () => {
+  it('honors authRedirectUri over returnUrl', async () => {
+    const oxy = makeOxy();
+    const sc = new TestSessionClient(host());
+    const controller = new AccountDialogController({
+      oxyServices: oxy as unknown as OxyServices,
+      sessionClient: sc,
+      authRedirectUri: 'https://inbox.oxy.so',
+    });
+
+    const url = await controller.openPasswordAtOxyAuth({ returnUrl: 'https://inbox.oxy.so/mail' });
+    expect(new URL(url).searchParams.get('redirect_uri')).toBe('https://inbox.oxy.so');
+  });
+
+  it('honors an idpApex override', async () => {
     const oxy = makeOxy();
     const sc = new TestSessionClient(host());
     const controller = new AccountDialogController({
@@ -562,7 +594,7 @@ describe('AccountDialogController — openPasswordAtOxyAuth', () => {
       sessionClient: sc,
       idpApex: 'alia.onl',
     });
-    const url = controller.openPasswordAtOxyAuth({ returnUrl: 'https://alia.onl/' });
+    const url = await controller.openPasswordAtOxyAuth({ returnUrl: 'https://alia.onl/' });
     expect(new URL(url).origin).toBe('https://auth.alia.onl');
   });
 });

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

@@ -44,6 +44,13 @@ describe('createSessionClientHost', () => {
     expect(host.getCurrentAccountId()).toBe('u1');
   });
 
+  test('setDeviceCredential reflects on getDeviceCredential', () => {
+    const host = createSessionClientHost(fakeOxy() as never);
+    expect(host.getDeviceCredential()).toBeNull();
+    host.setDeviceCredential({ deviceId: 'd1', deviceSecret: 's1' });
+    expect(host.getDeviceCredential()).toEqual({ deviceId: 'd1', deviceSecret: 's1' });
+  });
+
   test('onTokensChanged forwards to oxyServices and unsubscribes', () => {
     const oxy = fakeOxy();
     const host = createSessionClientHost(oxy as never);

package/src/session/accountDialogController.ts

@@ -31,6 +31,12 @@ import type { SessionLoginResponse, MinimalUserData } from '../models/session';
 import type { User } from '../models/interfaces';
 import { logger } from '../utils/loggerUtils';
 import { CENTRAL_IDP_APEX } from '../utils/authWebUrl';
+import {
+  generateOAuthState,
+  generatePkcePair,
+  normalizeOAuthRedirectUri,
+  persistOAuthHandshake,
+} from '../utils/oauthPkce';
 import { SessionClient } from './SessionClient';
 import {
   projectSwitchableAccounts,
@@ -111,6 +117,12 @@ export interface AccountDialogControllerOptions {
   onSignedIn?: (user: MinimalUserData) => void;
   /** Central IdP apex for `openPasswordAtOxyAuth` (defaults to `CENTRAL_IDP_APEX`). */
   idpApex?: string;
+  /**
+   * Registered OAuth redirect URI for this RP (exact match against
+   * `Application.redirectUris`). When set, wins over `returnUrl` /
+   * `location.origin` normalization in {@link openPasswordAtOxyAuth}.
+   */
+  authRedirectUri?: string | null;
   /** QR device-flow poll interval in ms (default 3000). */
   pollIntervalMs?: number;
   /**
@@ -145,6 +157,7 @@ export class AccountDialogController {
   private readonly commitSession?: (session: SessionLoginResponse) => Promise<void>;
   private readonly onSignedIn?: (user: MinimalUserData) => void;
   private readonly idpApex: string;
+  private readonly authRedirectUri: string | null;
   private readonly pollIntervalMs: number;
   private readonly openUrl?: (url: string) => void;
 
@@ -181,6 +194,7 @@ export class AccountDialogController {
     this.commitSession = options.commitSession;
     this.onSignedIn = options.onSignedIn;
     this.idpApex = options.idpApex ?? CENTRAL_IDP_APEX;
+    this.authRedirectUri = options.authRedirectUri ?? null;
     this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
     this.openUrl = options.openUrl;
     this.snapshot = this.computeSnapshot();
@@ -548,18 +562,30 @@ export class AccountDialogController {
    * @param params.state - Optional opaque state echoed back on return.
    * @returns The absolute auth.oxy.so sign-in URL.
    */
-  openPasswordAtOxyAuth(params: { returnUrl?: string; state?: string } = {}): string {
+  async openPasswordAtOxyAuth(
+    params: { returnUrl?: string; state?: string; redirectUri?: string } = {},
+  ): Promise<string> {
     const base = `https://auth.${this.idpApex}`;
     const url = new URL('/login', base);
-    const returnUrl = params.returnUrl ?? currentLocationHref();
-    if (returnUrl) {
-      url.searchParams.set('redirect_uri', returnUrl);
+    const rawRedirect =
+      params.redirectUri ??
+      this.authRedirectUri ??
+      params.returnUrl ??
+      currentLocationOrigin();
+    const redirectUri = rawRedirect ? normalizeOAuthRedirectUri(rawRedirect) : '';
+    if (redirectUri) {
+      url.searchParams.set('redirect_uri', redirectUri);
     }
     if (this.clientId) {
       url.searchParams.set('client_id', this.clientId);
     }
-    if (params.state) {
-      url.searchParams.set('state', params.state);
+    const state = params.state ?? (await generateOAuthState());
+    url.searchParams.set('state', state);
+    const { codeChallenge, codeVerifier } = await generatePkcePair();
+    url.searchParams.set('code_challenge', codeChallenge);
+    url.searchParams.set('code_challenge_method', 'S256');
+    if (!persistOAuthHandshake(state, codeVerifier)) {
+      throw new Error('Could not persist OAuth handshake for password sign-in');
     }
     const href = url.toString();
     this.openUrl?.(href);
@@ -748,8 +774,8 @@ export function createAccountDialogController(
 // Local helpers
 // ---------------------------------------------------------------------------
 
-/** Current document URL on web; empty string where `location` is absent (native/SSR). */
-function currentLocationHref(): string {
-  const location = (globalThis as { location?: { href?: string } }).location;
-  return typeof location?.href === 'string' ? location.href : '';
+/** Current document origin on web; empty string where `location` is absent (native/SSR). */
+function currentLocationOrigin(): string {
+  const location = (globalThis as { location?: { origin?: string } }).location;
+  return typeof location?.origin === 'string' ? location.origin : '';
 }

package/src/session/authStateStore.ts

@@ -5,7 +5,7 @@
  * a reload restores the session locally without a redirect: `deviceId` +
  * `deviceSecret` mint a fresh access token via `POST /session/device/token`.
  * This module is the storage seam: a tiny `load / save / clear` interface plus
- * platform factories, so the cold boot (`coldBootV2`) and the unified re-mint
+ * platform factories, so the cold boot (`sessionColdBoot`) and the unified re-mint
  * handler (`refresh.ts`) never touch a platform storage API directly.
  *
  * Platform-agnostic — the native factory takes an INJECTED key/value store
@@ -106,17 +106,26 @@ function deserialize(raw: string | null): PersistedAuthState | null {
     return null;
   }
   const candidate = parsed as Record<string, unknown>;
-  if (
-    typeof candidate.sessionId !== 'string' ||
-    typeof candidate.userId !== 'string' ||
-    candidate.sessionId.length === 0 ||
-    candidate.userId.length === 0
-  ) {
+  const hasDeviceCredential =
+    typeof candidate.deviceId === 'string' &&
+    candidate.deviceId.length > 0 &&
+    typeof candidate.deviceSecret === 'string' &&
+    candidate.deviceSecret.length > 0;
+
+  const hasSessionIdentity =
+    typeof candidate.sessionId === 'string' &&
+    typeof candidate.userId === 'string' &&
+    candidate.sessionId.length > 0 &&
+    candidate.userId.length > 0;
+
+  // Device-only bootstrap (post join, pre-sign-in): durable credential without session.
+  if (!hasSessionIdentity && !hasDeviceCredential) {
     return null;
   }
+
   const state: PersistedAuthState = {
-    sessionId: candidate.sessionId,
-    userId: candidate.userId,
+    sessionId: hasSessionIdentity ? (candidate.sessionId as string) : '',
+    userId: hasSessionIdentity ? (candidate.userId as string) : '',
   };
   if (typeof candidate.deviceId === 'string' && candidate.deviceId.length > 0) {
     state.deviceId = candidate.deviceId;

package/src/session/hubSync.ts

@@ -0,0 +1,79 @@
+/**
+ * Post-sign-in hub sync — plant device credentials on auth.oxy.so via a
+ * one-time server ticket (no secrets in URL fragments).
+ */
+
+import type { OxyServices } from '../OxyServices';
+import type { AuthStateStore } from './authStateStore';
+import {
+  buildHubSyncUrl,
+  buildIdpHubOrigin,
+  isIdpHubOrigin,
+  isOfficialWebOrigin,
+} from '../utils/officialOrigins';
+
+export interface SyncHubAfterSignInOptions {
+  /** Skip sync when false (OxyProvider hubSync prop). @default true */
+  enabled?: boolean;
+}
+
+/**
+ * After a successful sign-in on an official web app, mint a hub ticket and
+ * redirect to auth.oxy.so/sync so the IdP hub can redeem it and persist the
+ * shared device credential for silent OAuth restore on other origins.
+ *
+ * No-op on native, non-official origins, and when already on the IdP hub.
+ */
+export async function syncHubAfterSignIn(
+  oxy: Pick<OxyServices, 'issueHubTicket'>,
+  opts?: SyncHubAfterSignInOptions,
+): Promise<boolean> {
+  if (opts?.enabled === false) {
+    return false;
+  }
+
+  if (typeof globalThis === 'undefined') {
+    return false;
+  }
+
+  const location = (globalThis as { location?: Location }).location;
+  if (!location) {
+    return false;
+  }
+
+  if (isIdpHubOrigin()) {
+    return false;
+  }
+
+  if (!isOfficialWebOrigin(location.origin)) {
+    return false;
+  }
+
+  const hubOrigin = buildIdpHubOrigin();
+  const issued = await oxy.issueHubTicket(hubOrigin);
+  const returnUrl = `${location.origin}${location.pathname}${location.search}`;
+  const syncUrl = buildHubSyncUrl(issued.ticket, returnUrl);
+
+  window.location.assign(syncUrl);
+  return true;
+}
+
+/** Redeem a hub ticket on auth.oxy.so and persist credentials locally. */
+export async function redeemHubTicketOnHub(
+  oxy: Pick<OxyServices, 'redeemHubTicket'>,
+  store: AuthStateStore,
+  ticket: string,
+): Promise<boolean> {
+  const hubOrigin = buildIdpHubOrigin();
+  const creds = await oxy.redeemHubTicket(ticket, hubOrigin);
+  const prior = await store.load();
+  await store.save({
+    sessionId: prior?.sessionId ?? '',
+    userId: prior?.userId ?? '',
+    deviceId: creds.deviceId,
+    deviceSecret: creds.deviceSecret,
+    ...(prior?.accessToken ? { accessToken: prior.accessToken } : {}),
+    ...(prior?.expiresAt ? { expiresAt: prior.expiresAt } : {}),
+  });
+  return true;
+}

package/src/session/sessionClientHost.ts

@@ -1,5 +1,5 @@
 import type { OxyServices } from '../OxyServices';
-import type { SessionClientHost } from './SessionClient';
+import type { DeviceCredential, SessionClientHost } from './SessionClient';
 
 /**
  * Thin `SessionClientHost` adapter over an `OxyServices` instance.
@@ -15,17 +15,25 @@ import type { SessionClientHost } from './SessionClient';
  */
 export function createSessionClientHost(
   oxyServices: OxyServices,
-): SessionClientHost & { setCurrentAccountId(id: string | null): void } {
+): SessionClientHost & {
+  setCurrentAccountId(id: string | null): void;
+  setDeviceCredential(credential: DeviceCredential | null): void;
+} {
   let currentAccountId: string | null = null;
+  let deviceCredential: DeviceCredential | null = null;
   return {
     makeRequest: (method, url, data, options) => oxyServices.makeRequest(method, url, data, options),
     getBaseURL: () => oxyServices.getBaseURL(),
     getAccessToken: () => oxyServices.getAccessToken(),
+    getDeviceCredential: () => deviceCredential,
     onTokensChanged: (listener) => oxyServices.onTokensChanged(listener),
     setTokens: (accessToken) => oxyServices.setTokens(accessToken),
     getCurrentAccountId: () => currentAccountId,
     setCurrentAccountId: (id) => {
       currentAccountId = id;
     },
+    setDeviceCredential: (credential) => {
+      deviceCredential = credential;
+    },
   };
 }

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

@@ -0,0 +1,74 @@
+import {
+  buildHubSyncUrl,
+  buildIdpHubOrigin,
+  isAllowedDeviceJoinOrigin,
+  isIdpHubOrigin,
+  isOfficialWebOrigin,
+  normalizeOfficialReturnOrigin,
+  parseHubSyncReturnUrl,
+} from '../officialOrigins';
+
+describe('officialOrigins', () => {
+  it('builds the IdP hub origin', () => {
+    expect(buildIdpHubOrigin()).toBe('https://auth.oxy.so');
+  });
+
+  it('allows official first-party origins', () => {
+    expect(isOfficialWebOrigin('https://inbox.oxy.so')).toBe(true);
+    expect(isOfficialWebOrigin('https://mention.earth')).toBe(true);
+    expect(isOfficialWebOrigin('https://evil.example')).toBe(false);
+  });
+
+  it('keeps the deprecated alias in sync with isOfficialWebOrigin', () => {
+    expect(isAllowedDeviceJoinOrigin('https://accounts.oxy.so')).toBe(true);
+    expect(isAllowedDeviceJoinOrigin('https://evil.example')).toBe(false);
+  });
+
+  it('normalizes return origins to origin only', () => {
+    expect(normalizeOfficialReturnOrigin('https://accounts.oxy.so/settings')).toBe(
+      'https://accounts.oxy.so',
+    );
+    expect(normalizeOfficialReturnOrigin('https://evil.example/')).toBeNull();
+  });
+
+  it('parses hub-sync return URLs', () => {
+    expect(parseHubSyncReturnUrl('https://inbox.oxy.so/messages')).toBe(
+      'https://inbox.oxy.so/messages',
+    );
+    expect(parseHubSyncReturnUrl('https://evil.example/')).toBeNull();
+  });
+
+  it('builds hub sync URLs with ticket and optional return', () => {
+    const url = new URL(buildHubSyncUrl('tk-abc', 'https://accounts.oxy.so/'));
+    expect(url.pathname).toBe('/sync');
+    expect(url.searchParams.get('ticket')).toBe('tk-abc');
+    expect(url.searchParams.get('return')).toBe('https://accounts.oxy.so/');
+  });
+
+  describe('isIdpHubOrigin', () => {
+    const originalLocation = globalThis.location;
+
+    afterEach(() => {
+      Object.defineProperty(globalThis, 'location', {
+        configurable: true,
+        value: originalLocation,
+      });
+    });
+
+    it('returns true on auth.oxy.so', () => {
+      Object.defineProperty(globalThis, 'location', {
+        configurable: true,
+        value: { href: 'https://auth.oxy.so/sync' },
+      });
+      expect(isIdpHubOrigin()).toBe(true);
+    });
+
+    it('returns false on satellite origins', () => {
+      Object.defineProperty(globalThis, 'location', {
+        configurable: true,
+        value: { href: 'https://inbox.oxy.so/' },
+      });
+      expect(isIdpHubOrigin()).toBe(false);
+    });
+  });
+});

package/src/utils/coldBoot.ts

@@ -16,7 +16,7 @@
  *     web bundle — the reason any run-once guard for a step must live in the
  *     calling consumer, never in a core module-level singleton).
  *   - Architecture-agnostic: it knows nothing about HOW a step resolves a
- *     session; `runSessionColdBoot` (`boot/coldBootV2.ts`) is the current
+ *     session; `runSessionColdBoot` (`boot/sessionColdBoot.ts`) is the current
  *     device-first consumer.
  *
  * A step is skipped (without running) when its `enabled` predicate returns
@@ -106,7 +106,7 @@ export interface RunColdBootOptions<S> {
    * fails to settle before the deadline, the runner abandons the await for that
    * step (reporting it via `onStepDeadline`) and CONTINUES to the next step,
    * each now racing against an already-expired deadline. This is deliberate:
-   * the runner keeps iterating so the TERMINAL step (e.g. `coldBootV2`'s
+   * the runner keeps iterating so the TERMINAL step (e.g. `sessionColdBoot`'s
    * `bootstrap-hop`, whose `run()` performs its navigation side effect
    * synchronously before its first `await`) still gets to fire. A step that
    * has nothing to contribute after the deadline simply doesn't settle and is