@oxyhq/core 2.4.0 → 2.4.1

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

@@ -305,6 +305,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: 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.4.0",
+  "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/mixins/OxyServices.fedcm.ts

@@ -214,6 +214,17 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
   // 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
    */
@@ -606,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.
@@ -645,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'
@@ -653,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;
           }
@@ -680,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/__tests__/fedcm.test.ts

@@ -192,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();
+    }
+  });
 });
 
 /**

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

@@ -223,4 +223,154 @@ describe('runColdBoot', () => {
       session: { userId: 'u-ok' },
     });
   });
+
+  describe('overall deadline (defense-in-depth)', () => {
+    beforeEach(() => {
+      jest.useFakeTimers();
+    });
+    afterEach(() => {
+      jest.runOnlyPendingTimers();
+      jest.useRealTimers();
+    });
+
+    /**
+     * Reproduces the production hang: a step whose `run()` promise NEVER
+     * settles (the FedCM-silent `navigator.credentials.get` that ignored its
+     * abort signal). WITHOUT a deadline the whole `runColdBoot` promise hangs
+     * forever and the terminal step never runs.
+     */
+    it('hangs forever when a step never settles and no deadline is set', async () => {
+      const terminalRan = jest.fn();
+      let settled = false;
+
+      const outcomePromise = runColdBoot<TestSession>({
+        steps: [
+          {
+            id: 'never-settles',
+            // Never resolves or rejects — models the hung FedCM credential get.
+            run: () => new Promise<ColdBootStepResult<TestSession>>(() => {}),
+          },
+          {
+            id: 'terminal',
+            run: async (): Promise<ColdBootStepResult<TestSession>> => {
+              terminalRan();
+              return { kind: 'skip' };
+            },
+          },
+        ],
+      }).then((o) => {
+        settled = true;
+        return o;
+      });
+
+      // Advance well past any reasonable budget; nothing can unblock it.
+      await jest.advanceTimersByTimeAsync(120000);
+
+      expect(settled).toBe(false);
+      expect(terminalRan).not.toHaveBeenCalled();
+
+      // Avoid a dangling unhandled promise in the test runner.
+      void outcomePromise;
+    });
+
+    /**
+     * With `overallDeadlineMs` set, the non-settling step is abandoned at the
+     * deadline, the runner CONTINUES to the terminal step (so the cross-domain
+     * `/sso` bounce equivalent still fires), and the whole boot settles to
+     * `unauthenticated` within the bounded budget.
+     */
+    it('abandons a non-settling step at the deadline and still runs the terminal step', async () => {
+      const terminalRan = jest.fn();
+      const onStepDeadline = jest.fn();
+
+      const outcomePromise = runColdBoot<TestSession>({
+        overallDeadlineMs: 5000,
+        onStepDeadline,
+        steps: [
+          {
+            id: 'never-settles',
+            run: () => new Promise<ColdBootStepResult<TestSession>>(() => {}),
+          },
+          {
+            id: 'terminal',
+            run: async (): Promise<ColdBootStepResult<TestSession>> => {
+              terminalRan();
+              return { kind: 'skip' };
+            },
+          },
+        ],
+      });
+
+      await jest.advanceTimersByTimeAsync(5000);
+      const outcome = await outcomePromise;
+
+      expect(onStepDeadline).toHaveBeenCalledWith('never-settles');
+      expect(terminalRan).toHaveBeenCalledTimes(1);
+      expect(outcome).toEqual({ kind: 'unauthenticated' });
+    });
+
+    /**
+     * The terminal step's synchronous side effect (the real `sso-bounce`
+     * navigates BEFORE its first await) must still execute when the deadline
+     * trips on an earlier step — the cross-domain fallback is preserved.
+     */
+    it('lets the terminal step fire its synchronous side effect after the deadline trips', async () => {
+      const bounced = jest.fn();
+
+      const outcomePromise = runColdBoot<TestSession>({
+        overallDeadlineMs: 3000,
+        steps: [
+          {
+            id: 'never-settles',
+            run: () => new Promise<ColdBootStepResult<TestSession>>(() => {}),
+          },
+          {
+            id: 'sso-bounce',
+            run: async (): Promise<ColdBootStepResult<TestSession>> => {
+              // Synchronous navigation side effect, exactly like the real bounce.
+              bounced();
+              return { kind: 'skip' };
+            },
+          },
+        ],
+      });
+
+      await jest.advanceTimersByTimeAsync(3000);
+      await outcomePromise;
+
+      expect(bounced).toHaveBeenCalledTimes(1);
+    });
+
+    /**
+     * A healthy step that settles BEFORE the deadline still wins and
+     * short-circuits — the deadline never alters the happy path.
+     */
+    it('a step that settles before the deadline wins and short-circuits', async () => {
+      const laterRan = jest.fn();
+
+      const outcomePromise = runColdBoot<TestSession>({
+        overallDeadlineMs: 10000,
+        steps: [
+          {
+            id: 'fast-winner',
+            run: async (): Promise<ColdBootStepResult<TestSession>> => {
+              await Promise.resolve();
+              return { kind: 'session', session: { userId: 'u-fast' } };
+            },
+          },
+          sessionStep('later', 'u-later', laterRan),
+        ],
+      });
+
+      await jest.advanceTimersByTimeAsync(0);
+      const outcome = await outcomePromise;
+
+      expect(outcome).toEqual({
+        kind: 'session',
+        via: 'fast-winner',
+        session: { userId: 'u-fast' },
+      });
+      expect(laterRan).not.toHaveBeenCalled();
+    });
+  });
 });

package/src/utils/coldBoot.ts

@@ -73,6 +73,16 @@ export type ColdBootOutcome<S> =
   | { readonly kind: 'session'; readonly via: string; readonly session: S }
   | { readonly kind: 'unauthenticated' };
 
+/**
+ * The unique sentinel a step's `run()` resolves to (via the internal race)
+ * when the overall cold-boot deadline expires before that step settled. It is
+ * NOT a {@link ColdBootStepResult} — the runner detects it by identity and
+ * treats it as "this step did not settle in time; move on".
+ *
+ * @internal
+ */
+const DEADLINE_EXPIRED: unique symbol = Symbol('coldBoot.deadlineExpired');
+
 /**
  * Options for {@link runColdBoot}.
  */
@@ -85,6 +95,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;
 }
 
 /**
@@ -105,32 +141,75 @@ export interface RunColdBootOptions<S> {
 export async function runColdBoot<S>(
   options: RunColdBootOptions<S>
 ): Promise<ColdBootOutcome<S>> {
-  const { steps, onStepError } = options;
+  const { steps, onStepError, overallDeadlineMs, onStepDeadline } = options;
 
-  for (const step of steps) {
-    if (step.enabled) {
-      let isEnabled: boolean;
+  // Arm the optional overall deadline. The budget is SHARED across the whole
+  // loop (not reset per step): a single timer resolves a reusable
+  // `DEADLINE_EXPIRED` sentinel that every per-step race can observe. Once it
+  // fires, later steps race against an already-resolved promise and so never
+  // block, yet the loop keeps iterating so the terminal step still fires.
+  const deadlineMs =
+    typeof overallDeadlineMs === 'number' &&
+    Number.isFinite(overallDeadlineMs) &&
+    overallDeadlineMs > 0
+      ? overallDeadlineMs
+      : null;
+
+  let deadlineTimer: ReturnType<typeof setTimeout> | undefined;
+  let deadlinePromise: Promise<typeof DEADLINE_EXPIRED> | undefined;
+  if (deadlineMs !== null) {
+    deadlinePromise = new Promise<typeof DEADLINE_EXPIRED>((resolve) => {
+      deadlineTimer = setTimeout(() => resolve(DEADLINE_EXPIRED), deadlineMs);
+    });
+  }
+
+  try {
+    for (const step of steps) {
+      if (step.enabled) {
+        let isEnabled: boolean;
+        try {
+          isEnabled = step.enabled();
+        } catch (error) {
+          onStepError?.(step.id, error);
+          continue;
+        }
+        if (!isEnabled) continue;
+      }
+
+      let result: ColdBootStepResult<S> | typeof DEADLINE_EXPIRED;
       try {
-        isEnabled = step.enabled();
+        // Without a deadline: legacy behaviour — await the step directly.
+        // With a deadline: race the step against the shared deadline. The
+        // step's `run()` still STARTS synchronously up to its first `await`
+        // (so a terminal step's synchronous navigation side effect always
+        // executes), but a non-settling step can no longer block the loop —
+        // the race resolves with the sentinel and we move on.
+        result = deadlinePromise
+          ? await Promise.race([step.run(), deadlinePromise])
+          : await step.run();
       } catch (error) {
         onStepError?.(step.id, error);
         continue;
       }
-      if (!isEnabled) continue;
-    }
 
-    let result: ColdBootStepResult<S>;
-    try {
-      result = await step.run();
-    } catch (error) {
-      onStepError?.(step.id, error);
-      continue;
+      if (result === DEADLINE_EXPIRED) {
+        // The deadline tripped before this step settled. Abandon the await and
+        // continue: subsequent steps race against the already-resolved deadline
+        // (so they cannot block), which lets a terminal side-effect step still
+        // run while guaranteeing the loop terminates promptly.
+        onStepDeadline?.(step.id);
+        continue;
+      }
+
+      if (result.kind === 'session') {
+        return { kind: 'session', via: step.id, session: result.session };
+      }
     }
 
-    if (result.kind === 'session') {
-      return { kind: 'session', via: step.id, session: result.session };
+    return { kind: 'unauthenticated' };
+  } finally {
+    if (deadlineTimer !== undefined) {
+      clearTimeout(deadlineTimer);
     }
   }
-
-  return { kind: 'unauthenticated' };
 }