@oxyhq/core 2.3.1 → 2.4.0

package/dist/types/AuthManager.d.ts

@@ -8,7 +8,7 @@
  */
 import type { OxyServices } from './OxyServices';
 import type { SessionLoginResponse, MinimalUserData } from './models/session';
-import type { AuthManagerAccount, RestoreFromCookiesResult, SwitchAuthuserResult } from './AuthManagerTypes';
+import type { AuthManagerAccount, RestoreFromCookiesResult, RestoreFromCookiesOptions, SwitchAuthuserResult } from './AuthManagerTypes';
 /**
  * Storage adapter interface for platform-agnostic storage.
  */
@@ -269,7 +269,7 @@ export declare class AuthManager {
      * Returns the active user on success, or `null` when neither path
      * restored a session.
      */
-    initialize(): Promise<MinimalUserData | null>;
+    initialize(options?: RestoreFromCookiesOptions): Promise<MinimalUserData | null>;
     /**
      * Read the persisted active `authuser` slot index. Returns `null` when
      * none is persisted, the value is corrupt, or the storage adapter has no
@@ -343,7 +343,7 @@ export declare class AuthManager {
      * proceed unauthenticated. State is NOT cleared on failure; existing
      * accounts (if any) remain intact.
      */
-    restoreFromCookies(): Promise<RestoreFromCookiesResult>;
+    restoreFromCookies(options?: RestoreFromCookiesOptions): Promise<RestoreFromCookiesResult>;
     /**
      * Switch the active account to a different device-local slot.
      *

package/dist/types/AuthManagerTypes.d.ts

@@ -55,6 +55,23 @@ export interface RestoreFromCookiesResult {
     accounts: AuthManagerAccount[];
     activeAuthuser: number | null;
 }
+/**
+ * Options for `AuthManager.restoreFromCookies()` / `AuthManager.initialize()`.
+ */
+export interface RestoreFromCookiesOptions {
+    /**
+     * Abort the underlying `POST /auth/refresh-all` after this many milliseconds
+     * and treat it as "no signed-in accounts" instead of hanging. Forwarded
+     * verbatim to `OxyServices.refreshAllSessions({ timeout })`.
+     *
+     * Intended for the cold-boot cookie-restore step on a cross-domain RP, where
+     * the `Domain=oxy.so` refresh cookie never reaches `api.<apex>` and the
+     * request can stall with no useful answer. Omit (the default) to wait
+     * indefinitely — the warm cross-tab cascade path passes nothing, preserving
+     * its existing behaviour.
+     */
+    timeout?: number;
+}
 /**
  * Outcome of `AuthManager.switchAuthuser()`.
  *

package/dist/types/index.d.ts

@@ -21,7 +21,7 @@ export { OxyServices, OxyAuthenticationError, OxyAuthenticationTimeoutError } fr
 export { OXY_CLOUD_URL, oxyClient } from './OxyServices';
 export { AuthManager, createAuthManager } from './AuthManager';
 export type { StorageAdapter, AuthStateChangeCallback, AuthMethod, AuthManagerConfig, } from './AuthManager';
-export type { AuthManagerAccount, RestoreFromCookiesResult, SwitchAuthuserResult, } from './AuthManagerTypes';
+export type { AuthManagerAccount, RestoreFromCookiesResult, RestoreFromCookiesOptions, SwitchAuthuserResult, } from './AuthManagerTypes';
 export { CrossDomainAuth, createCrossDomainAuth } from './CrossDomainAuth';
 export type { CrossDomainAuthOptions } from './CrossDomainAuth';
 export type { FedCMAuthOptions, FedCMConfig, AuthorizedApp } from './mixins/OxyServices.fedcm';

package/dist/types/mixins/OxyServices.auth.d.ts

@@ -10,6 +10,25 @@ export interface ChallengeResponse {
     challenge: string;
     expiresAt: string;
 }
+/**
+ * Options for {@link refreshAllSessions}.
+ */
+export interface RefreshAllOptions {
+    /**
+     * Abort the `POST /auth/refresh-all` request after this many milliseconds and
+     * resolve as "no signed-in accounts" (`{ accounts: [] }`) rather than hanging.
+     *
+     * Why: on a cross-domain RP (e.g. `mention.earth`) the `Domain=oxy.so` refresh
+     * cookie never reaches `api.<apex>`, so this request can stall behind a slow
+     * or unreachable endpoint with no useful answer coming back. As one step of
+     * the ordered cold-boot sequence, a stalled refresh is dead latency in front
+     * of the steps that actually hold the answer. A bounded abort lets cold boot
+     * fall through quickly. Omit (or pass `0`/negative) to wait indefinitely
+     * (the legacy behaviour). The abort is treated identically to a 401 — the
+     * "not signed in on this device" path — never an error.
+     */
+    timeout?: number;
+}
 export interface RegistrationRequest {
     publicKey: string;
     username: string;
@@ -293,7 +312,7 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
          * tokens do. Each access token still needs to be planted via
          * `setTokens(...)` (or per-account in-memory storage) at the consumer.
          */
-        refreshAllSessions(): Promise<RefreshAllResponse>;
+        refreshAllSessions(options?: RefreshAllOptions): Promise<RefreshAllResponse>;
         /**
          * Rotate a single refresh-cookie slot and return the fresh access token.
          *

package/dist/types/mixins/OxyServices.fedcm.d.ts

@@ -304,7 +304,7 @@ export declare function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(
     };
     readonly DEFAULT_CONFIG_URL: "https://auth.oxy.so/fedcm.json";
     readonly FEDCM_TIMEOUT: 15000;
-    readonly FEDCM_SILENT_TIMEOUT: 10000;
+    readonly FEDCM_SILENT_TIMEOUT: 4000;
     /**
      * Check if FedCM is supported in the current browser
      */

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.4.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/AuthManager.ts

@@ -20,6 +20,7 @@ import type {
 import type {
   AuthManagerAccount,
   RestoreFromCookiesResult,
+  RestoreFromCookiesOptions,
   SwitchAuthuserResult,
 } from './AuthManagerTypes';
 import { retryAsync } from './utils/asyncUtils';
@@ -899,9 +900,10 @@ export class AuthManager {
    * Returns the active user on success, or `null` when neither path
    * restored a session.
    */
-  async initialize(): Promise<MinimalUserData | null> {
-    // 1. Cookie path (preferred).
-    const cookieResult = await this.restoreFromCookies();
+  async initialize(options: RestoreFromCookiesOptions = {}): Promise<MinimalUserData | null> {
+    // 1. Cookie path (preferred). Forward the optional cold-boot fail-fast
+    // timeout so a cross-domain stall cannot hang provider init.
+    const cookieResult = await this.restoreFromCookies(options);
     if (cookieResult.accounts.length > 0) {
       return this.currentUser;
     }
@@ -1126,7 +1128,7 @@ export class AuthManager {
    * proceed unauthenticated. State is NOT cleared on failure; existing
    * accounts (if any) remain intact.
    */
-  async restoreFromCookies(): Promise<RestoreFromCookiesResult> {
+  async restoreFromCookies(options: RestoreFromCookiesOptions = {}): Promise<RestoreFromCookiesResult> {
     // Cross-tab cascade debounce. If we restored within the last
     // _RESTORE_DEBOUNCE_MS for the currently-active slot, skip the network
     // round-trip and return the cached registry verbatim. A burst of N
@@ -1145,7 +1147,9 @@ export class AuthManager {
 
     let snapshot: RefreshAllResponse;
     try {
-      snapshot = await this.oxyServices.refreshAllSessions();
+      // Forward the optional cold-boot fail-fast timeout. Undefined (the warm
+      // cross-tab cascade default) preserves the wait-indefinitely behaviour.
+      snapshot = await this.oxyServices.refreshAllSessions({ timeout: options.timeout });
     } catch {
       return { accounts: [], activeAuthuser: null };
     }

package/src/AuthManagerTypes.ts

@@ -59,6 +59,24 @@ export interface RestoreFromCookiesResult {
   activeAuthuser: number | null;
 }
 
+/**
+ * Options for `AuthManager.restoreFromCookies()` / `AuthManager.initialize()`.
+ */
+export interface RestoreFromCookiesOptions {
+  /**
+   * Abort the underlying `POST /auth/refresh-all` after this many milliseconds
+   * and treat it as "no signed-in accounts" instead of hanging. Forwarded
+   * verbatim to `OxyServices.refreshAllSessions({ timeout })`.
+   *
+   * Intended for the cold-boot cookie-restore step on a cross-domain RP, where
+   * the `Domain=oxy.so` refresh cookie never reaches `api.<apex>` and the
+   * request can stall with no useful answer. Omit (the default) to wait
+   * indefinitely — the warm cross-tab cascade path passes nothing, preserving
+   * its existing behaviour.
+   */
+  timeout?: number;
+}
+
 /**
  * Outcome of `AuthManager.switchAuthuser()`.
  *

package/src/index.ts

@@ -39,6 +39,7 @@ export type {
 export type {
     AuthManagerAccount,
     RestoreFromCookiesResult,
+    RestoreFromCookiesOptions,
     SwitchAuthuserResult,
 } from './AuthManagerTypes';
 

package/src/mixins/OxyServices.auth.ts

@@ -20,6 +20,26 @@ export interface ChallengeResponse {
   expiresAt: string;
 }
 
+/**
+ * Options for {@link refreshAllSessions}.
+ */
+export interface RefreshAllOptions {
+  /**
+   * Abort the `POST /auth/refresh-all` request after this many milliseconds and
+   * resolve as "no signed-in accounts" (`{ accounts: [] }`) rather than hanging.
+   *
+   * Why: on a cross-domain RP (e.g. `mention.earth`) the `Domain=oxy.so` refresh
+   * cookie never reaches `api.<apex>`, so this request can stall behind a slow
+   * or unreachable endpoint with no useful answer coming back. As one step of
+   * the ordered cold-boot sequence, a stalled refresh is dead latency in front
+   * of the steps that actually hold the answer. A bounded abort lets cold boot
+   * fall through quickly. Omit (or pass `0`/negative) to wait indefinitely
+   * (the legacy behaviour). The abort is treated identically to a 401 — the
+   * "not signed in on this device" path — never an error.
+   */
+  timeout?: number;
+}
+
 export interface RegistrationRequest {
   publicKey: string;
   username: string;
@@ -619,18 +639,41 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
      * tokens do. Each access token still needs to be planted via
      * `setTokens(...)` (or per-account in-memory storage) at the consumer.
      */
-    async refreshAllSessions(): Promise<RefreshAllResponse> {
+    async refreshAllSessions(options: RefreshAllOptions = {}): Promise<RefreshAllResponse> {
       const url = `${this.getSessionBaseUrl().replace(/\/$/, '')}/auth/refresh-all`;
 
+      // Optional bounded abort (see `RefreshAllOptions.timeout`). A positive
+      // timeout arms an `AbortController` that aborts the in-flight request; an
+      // abort is treated as "no signed-in accounts on this device" — the same
+      // outcome as a 401 — so a cross-domain stall falls through cleanly instead
+      // of hanging the cold boot.
+      const timeout = typeof options.timeout === 'number' && options.timeout > 0 ? options.timeout : undefined;
+      const controller = timeout !== undefined ? new AbortController() : undefined;
+      const timeoutId = timeout !== undefined && controller
+        ? setTimeout(() => controller.abort(), timeout)
+        : undefined;
+
       let response: Response;
       try {
         response = await fetch(url, {
           method: 'POST',
           credentials: 'include',
           headers: { Accept: 'application/json' },
+          signal: controller?.signal,
         });
       } catch (error) {
+        // A bounded-timeout abort is the "not signed in / cross-domain stall"
+        // path, NOT an error. The browser raises a DOMException named
+        // 'AbortError' (some runtimes use a generic Error); match on the name so
+        // we never throw the timeout into the cold-boot error handler.
+        if (error instanceof Error && error.name === 'AbortError') {
+          return { accounts: [] };
+        }
         throw this.handleError(error);
+      } finally {
+        if (timeoutId !== undefined) {
+          clearTimeout(timeoutId);
+        }
       }
 
       if (response.status === 401) {

package/src/mixins/OxyServices.fedcm.ts

@@ -202,12 +202,17 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
   }
 
   public static readonly FEDCM_TIMEOUT = 15000; // 15 seconds for interactive
-  // Silent mediation runs on page load (e.g. re-signing-in a user whose stored
-  // session was cleared after a cold-boot token fetch 401'd). The real silent
-  // round-trip — mint nonce → navigator.credentials.get → /fedcm/exchange — was
-  // measured to take more than 3s for live users, so a 3s budget timed out and
-  // left them signed out on reload. 10s gives ample margin while staying bounded.
-  public static readonly FEDCM_SILENT_TIMEOUT = 10000; // 10 seconds for silent mediation
+  // Silent mediation runs on page load as ONE step of the ordered cold-boot
+  // sequence (mint nonce → navigator.credentials.get → /fedcm/exchange). The
+  // real round-trip was measured at >3s for live users, so the budget must stay
+  // comfortably above 3s. It must ALSO be tight: on a logged-out browser this
+  // step never resolves a credential, and every millisecond it spends timing
+  // out is pure latency in front of the steps that actually hold the answer
+  // (stored-session bearer, the per-apex silent iframe, the /sso bounce). 4s is
+  // the floor that preserves the >3s success margin while bounding the dead
+  // wait — down from the previous 10s, which alone could account for most of a
+  // 20-30s cold-boot stall. Do NOT lower below 4s (it would clip live success).
+  public static readonly FEDCM_SILENT_TIMEOUT = 4000; // 4 seconds for silent mediation
 
   /**
    * Check if FedCM is supported in the current browser
@@ -419,6 +424,21 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
 
     const loginHint = this.getStoredLoginHint();
 
+    // Fast-skip: with no stored login hint this browser has never completed a
+    // FedCM sign-in for any Oxy account, so silent mediation cannot return a
+    // credential — the IdP has nothing to silently re-issue. Doing the full
+    // round-trip anyway (mint a nonce via `POST /fedcm/nonce`, then a
+    // `navigator.credentials.get` that aborts after `FEDCM_SILENT_TIMEOUT`) is
+    // pure latency in the cold-boot critical path. Return `null` immediately so
+    // the next cold-boot step (stored-session / iframe / bounce) runs without
+    // the wasted nonce mint + abort wait. A genuinely associated browser always
+    // has a hint (it is stored only after a real exchange), so this never skips
+    // a recoverable session.
+    if (!loginHint) {
+      debug.log('Silent SSO: No stored login hint — skipping silent mediation (no association on this browser)');
+      return null;
+    }
+
     try {
       // Server-minted, origin-bound nonce — required for `/fedcm/exchange`
       // to accept the resulting ID token (anti-replay binding).

package/src/mixins/OxyServices.popup.ts

@@ -522,8 +522,25 @@ export function OxyServicesPopupAuthMixin<T extends typeof OxyServicesBase>(Base
         resolve(session || null);
       };
 
+      // Fail-fast on a load failure. When the per-apex `/auth/silent` host is
+      // unreachable, blocked by CSP `frame-ancestors`/`X-Frame-Options`, or the
+      // network drops, the iframe never posts a message — without this handler
+      // the silent restore would block for the FULL `timeout` (dead latency in
+      // the cold-boot critical path). `onerror`/`onabort` fire on a failed load,
+      // so resolve `null` immediately and let the next cold-boot step run. The
+      // success path posts a message and is handled above; these only catch the
+      // no-message failure modes.
+      const failFast = () => {
+        cleanup();
+        resolve(null);
+      };
+      iframe.onerror = failFast;
+      iframe.onabort = failFast;
+
       const cleanup = () => {
         clearTimeout(timeoutId);
+        iframe.onerror = null;
+        iframe.onabort = null;
         window.removeEventListener('message', messageHandler);
       };
 

package/src/mixins/__tests__/fedcm.test.ts

@@ -82,6 +82,11 @@ describe('OxyServices FedCM nonce binding', () => {
     });
 
     const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    // Silent mediation now fast-skips when there is NO stored login hint (a
+    // browser with no prior FedCM association can never get a silent credential,
+    // so the nonce mint + credential request would be pure latency). Seed a hint
+    // so the silent round-trip actually runs and we can assert the nonce binding.
+    localStorage.setItem('oxy_fedcm_login_hint', 'prior-user-id');
     const makeRequest = jest
       .spyOn(oxy, 'makeRequest')
       .mockImplementation(async (_method: string, url: string) => {
@@ -147,6 +152,9 @@ describe('OxyServices FedCM nonce binding', () => {
     });
 
     const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    // Seed a login hint so the silent path runs past the no-hint fast-skip and
+    // exercises the nonce-mint fallback.
+    localStorage.setItem('oxy_fedcm_login_hint', 'prior-user-id');
     jest.spyOn(oxy, 'makeRequest').mockImplementation(async (_method: string, url: string) => {
       if (url === '/fedcm/nonce') {
         throw new Error('network down');
@@ -306,6 +314,9 @@ describe('OxyServices FedCM mode enum (active/passive)', () => {
     });
 
     const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    // Seed a login hint so the silent path runs past the no-hint fast-skip and
+    // reaches `navigator.credentials.get` (where the mode/mediation are set).
+    localStorage.setItem('oxy_fedcm_login_hint', 'prior-user-id');
     jest.spyOn(oxy, 'makeRequest').mockImplementation(async (_method: string, url: string) => {
       if (url === '/fedcm/nonce') {
         return { nonce: 'n', expiresAt: new Date(Date.now() + 60000).toISOString() } as never;
@@ -463,6 +474,10 @@ describe('OxyServices FedCM single-flight lock (interactive aborts silent)', ()
     let interactiveRan = false;
 
     const store = new Map<string, string>();
+    // Seed a stored login hint so the silent request runs past the no-hint
+    // fast-skip and actually reaches `navigator.credentials.get` (where it then
+    // hangs, which is what this test needs to observe being aborted).
+    store.set('oxy_fedcm_login_hint', 'prior-user-id');
     const localStorageStub = {
       getItem: (k: string) => (store.has(k) ? (store.get(k) as string) : null),
       setItem: (k: string, v: string) => { store.set(k, v); },
@@ -548,7 +563,53 @@ describe('OxyServices FedCM single-flight lock (interactive aborts silent)', ()
 });
 
 describe('OxyServices FedCM silent timeout', () => {
-  it('uses a 10s silent timeout (enough budget for the real on-load round-trip)', () => {
-    expect(OxyServices.FEDCM_SILENT_TIMEOUT).toBe(10000);
+  it('uses a 4s silent timeout (above the >3s live round-trip, tight enough to bound cold-boot latency)', () => {
+    // 4s keeps the >3s measured live success margin while bounding the dead
+    // wait on a logged-out browser. Lowered from 10s, which alone could account
+    // for most of a 20-30s serial cold-boot stall. Must never drop below 4s.
+    expect(OxyServices.FEDCM_SILENT_TIMEOUT).toBe(4000);
+    expect(OxyServices.FEDCM_SILENT_TIMEOUT).toBeGreaterThanOrEqual(4000);
+  });
+});
+
+/**
+ * Silent FedCM no-login-hint fast-skip regression test.
+ *
+ * A browser that has never completed a FedCM sign-in for any Oxy account has no
+ * stored login hint, so silent mediation can never return a credential — the
+ * IdP has nothing to silently re-issue. Doing the full round-trip anyway (mint a
+ * nonce, then a `navigator.credentials.get` that aborts after the silent
+ * timeout) is pure latency in the cold-boot critical path. The silent path must
+ * return `null` immediately WITHOUT minting a nonce or calling
+ * `navigator.credentials.get`.
+ */
+describe('OxyServices FedCM silent fast-skip with no login hint', () => {
+  afterEach(() => {
+    clearBrowserGlobals();
+    jest.restoreAllMocks();
+  });
+
+  it('returns null immediately without minting a nonce or calling credentials.get when no hint is stored', async () => {
+    let credentialsGetCalled = false;
+    installBrowserGlobals({
+      credentialsGet: async () => {
+        credentialsGetCalled = true;
+        return null;
+      },
+    });
+
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    // No stored login hint (fresh empty localStorage) → fast-skip.
+    const makeRequest = jest.spyOn(oxy, 'makeRequest').mockImplementation(async (_method: string, url: string) => {
+      throw new Error(`unexpected request to ${url}`);
+    });
+
+    const result = await oxy.silentSignInWithFedCM();
+
+    expect(result).toBeNull();
+    // The nonce mint was NOT attempted and the browser credential UI was never
+    // touched — the round-trip was skipped entirely.
+    expect(makeRequest).not.toHaveBeenCalled();
+    expect(credentialsGetCalled).toBe(false);
   });
 });

package/src/mixins/__tests__/popup.test.ts

@@ -305,3 +305,70 @@ describe('OxyServices popup mixin — openBlankPopup helper', () => {
     expect(oxy.openBlankPopup()).toBeNull();
   });
 });
+
+/**
+ * `waitForIframeAuth` fail-fast regression tests.
+ *
+ * The cross-domain durable-restore iframe (`/auth/silent` at the per-apex host)
+ * posts a message on success. On a FAILED load — host unreachable, blocked by
+ * CSP `frame-ancestors`/`X-Frame-Options`, or a dropped network — it never
+ * posts, so without an `onerror`/`onabort` handler the silent restore would
+ * block for the FULL timeout (dead latency in the cold-boot critical path). The
+ * handler must resolve `null` immediately on a load failure, well before the
+ * timeout fires.
+ */
+interface FakeIframe {
+  onerror: ((this: unknown, ...args: unknown[]) => unknown) | null;
+  onabort: ((this: unknown, ...args: unknown[]) => unknown) | null;
+}
+
+describe('OxyServices waitForIframeAuth fail-fast on iframe load error', () => {
+  afterEach(() => {
+    clearBrowserGlobals();
+    jest.restoreAllMocks();
+  });
+
+  it('resolves null immediately when the iframe fires onerror (does not wait for the timeout)', async () => {
+    installBrowserGlobals();
+
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    const iframe: FakeIframe = { onerror: null, onabort: null };
+
+    // A long timeout proves the resolution comes from `onerror`, not the timer.
+    const LONG_TIMEOUT = 100000;
+    const settled = oxy.waitForIframeAuth(
+      iframe as unknown as HTMLIFrameElement,
+      LONG_TIMEOUT,
+      'https://auth.mention.earth',
+    );
+
+    // The handler is installed synchronously; fire it on the next tick.
+    await Promise.resolve();
+    expect(typeof iframe.onerror).toBe('function');
+    iframe.onerror?.call(iframe);
+
+    await expect(settled).resolves.toBeNull();
+    // Cleanup detaches the handlers so a late event cannot double-resolve.
+    expect(iframe.onerror).toBeNull();
+    expect(iframe.onabort).toBeNull();
+  });
+
+  it('resolves null immediately when the iframe fires onabort', async () => {
+    installBrowserGlobals();
+
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    const iframe: FakeIframe = { onerror: null, onabort: null };
+
+    const settled = oxy.waitForIframeAuth(
+      iframe as unknown as HTMLIFrameElement,
+      100000,
+      'https://auth.mention.earth',
+    );
+
+    await Promise.resolve();
+    expect(typeof iframe.onabort).toBe('function');
+    iframe.onabort?.call(iframe);
+
+    await expect(settled).resolves.toBeNull();
+  });
+});