@oxyhq/core 2.3.2 → 2.4.1

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();
+  });
+});

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' };
 }