@oxyhq/core 2.3.2 → 2.4.1

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,8 @@ 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;
+    readonly FEDCM_ABORT_SETTLE_GRACE_MS: 500;
     /**
      * Check if FedCM is supported in the current browser
      */

package/dist/types/utils/coldBoot.d.ts

@@ -83,6 +83,32 @@ export interface RunColdBootOptions<S> {
      * the runner does not guard against an observer that itself throws.
      */
     readonly onStepError?: (id: string, error: unknown) => void;
+    /**
+     * Optional HARD overall deadline (ms) for the entire ordered step loop —
+     * defense-in-depth so a single non-settling step can NEVER hang the whole
+     * cold boot forever.
+     *
+     * Each step's `run()` is raced against the SHARED remaining time. If a step
+     * 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. the `/sso` bounce,
+     * whose `run()` performs its 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 skipped in turn.
+     *
+     * Per-step timeouts inside `run()` remain the first line of defense and
+     * should keep every step well under this budget on a healthy load; this only
+     * trips when one of them regresses (the production FedCM-silent hang). When
+     * omitted there is NO overall deadline (unchanged legacy behaviour).
+     */
+    readonly overallDeadlineMs?: number;
+    /**
+     * Optional observer invoked once per step that was abandoned because the
+     * overall deadline expired before it settled. Receives the step `id`. Must
+     * not throw.
+     */
+    readonly onStepDeadline?: (id: string) => void;
 }
 /**
  * Run the ordered cold-boot steps and resolve to the first recovered session,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "2.3.2",
+  "version": "2.4.1",
   "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,28 @@ 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
+
+  // Grace margin between the cooperative abort deadline (`FEDCM_SILENT_TIMEOUT`
+  // / `FEDCM_TIMEOUT`) and the HARD settle of `requestIdentityCredential`. The
+  // abort fires first; a well-behaved browser surfaces its own `AbortError`
+  // within this window (keeping the existing error path intact). If — as seen
+  // in production — `navigator.credentials.get()` ignores the abort and the
+  // awaited promise never settles, the hard settle resolves the request to
+  // `null` this many ms later, guaranteeing the cold-boot step always settles.
+  // 500ms is ample for a browser to deliver an abort rejection while keeping the
+  // worst-case dead wait tight (silent: 4.5s, interactive: 15.5s).
+  public static readonly FEDCM_ABORT_SETTLE_GRACE_MS = 500;
 
   /**
    * Check if FedCM is supported in the current browser
@@ -419,6 +435,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).
@@ -586,6 +617,37 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
       controller.abort();
     }, timeoutMs);
 
+    // Hard settle guarantee for the timeout path.
+    //
+    // The `setTimeout` above aborts the request's `AbortController`, which is
+    // the COOPERATIVE cancel signal. For a regular `fetch` an abort deterministically
+    // rejects the awaited promise — but `navigator.credentials.get()` is a
+    // browser-internal FedCM primitive whose abort behaviour is NOT guaranteed
+    // to settle the awaited promise in every Chrome version / internal state
+    // (the credential request can sit "pending" while the browser-side flow is
+    // stuck, ignoring the signal). If that happens, `await credentials.get(...)`
+    // never resolves OR rejects, this IIFE hangs forever, and — because this is
+    // ONE step of the ordered cold-boot sequence — the whole cold boot hangs and
+    // the terminal `/sso` bounce never fires. That was the production hang.
+    //
+    // `settlePromise` races the credential lookup against a timer that ALWAYS
+    // resolves to `null` shortly after the abort deadline. The abort still fires
+    // first (so the browser is asked to cancel), but even if `credentials.get`
+    // never settles, the race resolves and the step falls through cleanly to the
+    // next cold-boot step. The small `FEDCM_ABORT_SETTLE_GRACE_MS` margin gives a
+    // well-behaved browser the chance to surface its own AbortError (preserving
+    // the existing error path) before we force a clean `null`.
+    let settleTimer: ReturnType<typeof setTimeout> | undefined;
+    const settlePromise = new Promise<FedCMIdentityCredential | null>((resolve) => {
+      const ctor = this.constructor as typeof OxyServicesBase & {
+        FEDCM_ABORT_SETTLE_GRACE_MS: number;
+      };
+      settleTimer = setTimeout(() => {
+        debug.log('Request hard-settled to null', timeoutMs + ctor.FEDCM_ABORT_SETTLE_GRACE_MS, 'ms (credentials.get never settled after abort)');
+        resolve(null);
+      }, timeoutMs + ctor.FEDCM_ABORT_SETTLE_GRACE_MS);
+    });
+
     // Normalise the caller's mode to the modern W3C value first. A modern
     // browser accepts it; an older one (Chrome 125–131) rejects it with a
     // synchronous TypeError, in which case we retry with the legacy value.
@@ -625,7 +687,13 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
         debug.log('Calling navigator.credentials.get with mediation:', requestedMediation, modernMode ? `mode: ${modernMode}` : '');
         let credential: FedCMIdentityCredential | null;
         try {
-          credential = await credentials.get(buildCredentialOptions(modernMode));
+          // Race the browser FedCM lookup against the hard settle guarantee so
+          // a `credentials.get` that ignores the abort signal can never hang
+          // the cold boot (see `settlePromise`).
+          credential = await Promise.race([
+            credentials.get(buildCredentialOptions(modernMode)),
+            settlePromise,
+          ]);
         } catch (modeError) {
           // Chrome 125–131 only knows the legacy 'button'/'widget' enum and
           // throws a synchronous TypeError for the modern 'active'/'passive'
@@ -633,7 +701,10 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
           if (modernMode && isUnknownModeEnumError(modeError)) {
             const legacyMode = MODERN_TO_LEGACY_MODE[modernMode];
             debug.log(`Browser rejected modern mode '${modernMode}'; retrying with legacy mode '${legacyMode}'`);
-            credential = await credentials.get(buildCredentialOptions(legacyMode));
+            credential = await Promise.race([
+              credentials.get(buildCredentialOptions(legacyMode)),
+              settlePromise,
+            ]);
           } else {
             throw modeError;
           }
@@ -660,6 +731,9 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
         throw error;
       } finally {
         clearTimeout(timeout);
+        if (settleTimer !== undefined) {
+          clearTimeout(settleTimer);
+        }
         // Only reset the shared lock if it still belongs to THIS request. When an
         // interactive request aborts a slow silent one, the silent settles (and
         // runs this `finally`) AFTER the interactive has already taken over the

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');
@@ -184,6 +192,58 @@ describe('OxyServices FedCM nonce binding', () => {
 
     await expect(oxy.silentSignInWithFedCM()).resolves.toBeNull();
   });
+
+  /**
+   * Production-hang regression. `navigator.credentials.get()` is a
+   * browser-internal FedCM primitive that, in some Chrome states, IGNORES its
+   * abort signal — the awaited promise never settles. The cooperative
+   * `setTimeout`→`controller.abort()` alone cannot unblock that await, so the
+   * `fedcm-silent` cold-boot step (and the whole cold boot) hangs forever and
+   * the terminal `/sso` bounce never fires.
+   *
+   * The hard settle guarantee (`Promise.race` against a timer that resolves
+   * `null` at `FEDCM_SILENT_TIMEOUT + FEDCM_ABORT_SETTLE_GRACE_MS`) must resolve
+   * the request to `null` regardless. This test models the hung primitive and
+   * asserts `silentSignInWithFedCM()` settles to `null` within that bound.
+   */
+  it('hard-settles to null when navigator.credentials.get never settles (ignores abort)', async () => {
+    jest.useFakeTimers();
+    try {
+      installBrowserGlobals({
+        // Never resolves or rejects, and never observes the abort signal —
+        // models the production hung FedCM credential request.
+        credentialsGet: () => new Promise<unknown>(() => {}),
+      });
+
+      const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+      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;
+        }
+        throw new Error(`unexpected request to ${url}`);
+      });
+
+      let settled = false;
+      const promise = oxy.silentSignInWithFedCM().then((r) => {
+        settled = true;
+        return r;
+      });
+
+      // Before the hard-settle deadline it must still be pending — proving the
+      // primitive really is hung (so the test would fail without the fix).
+      await jest.advanceTimersByTimeAsync(4000);
+      expect(settled).toBe(false);
+
+      // FEDCM_SILENT_TIMEOUT (4000) + FEDCM_ABORT_SETTLE_GRACE_MS (500) = 4500.
+      await jest.advanceTimersByTimeAsync(600);
+      await expect(promise).resolves.toBeNull();
+      expect(settled).toBe(true);
+    } finally {
+      jest.runOnlyPendingTimers();
+      jest.useRealTimers();
+    }
+  });
 });
 
 /**
@@ -306,6 +366,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 +526,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 +615,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);
   });
 });