@oxyhq/core 3.6.0 → 3.7.1

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

@@ -373,4 +373,129 @@ describe('runColdBoot', () => {
       expect(laterRan).not.toHaveBeenCalled();
     });
   });
+
+  /**
+   * End-to-end reproduction of the production FedCM-silent hang at the REAL
+   * overall deadline the SDK ships.
+   *
+   * `OxyContext` runs the web cold-boot chain with `COLD_BOOT_OVERALL_DEADLINE`
+   * (20000 ms): fedcm-silent → /auth/silent iframe → cookie restore →
+   * stored-session → /sso top-level bounce (terminal). The documented gotcha:
+   * `navigator.credentials.get({mediation:'silent'})` can sit pending forever,
+   * ignoring its AbortController. WITHOUT the overall deadline the whole chain
+   * hangs and the terminal `/sso` bounce never fires.
+   *
+   * These tests model that exact chain shape against the real deadline value and
+   * assert the runner (a) abandons the hung silent step at the deadline,
+   * (b) still fires the terminal bounce's synchronous side effect, and
+   * (c) always settles within the bounded budget — it never hangs.
+   */
+  describe('production cold-boot deadline semantics (FedCM-silent hang)', () => {
+    /**
+     * Mirror of `COLD_BOOT_OVERALL_DEADLINE` in
+     * `@oxyhq/services` `OxyContext` (the only consumer that arms the deadline).
+     * Kept as a local literal because core does not — and must not — import the
+     * services package; if the consumer's value changes, update this to match.
+     */
+    const COLD_BOOT_OVERALL_DEADLINE = 20000;
+
+    beforeEach(() => {
+      jest.useFakeTimers();
+    });
+    afterEach(() => {
+      jest.runOnlyPendingTimers();
+      jest.useRealTimers();
+    });
+
+    /** A step whose `run()` never settles — the hung `credentials.get`. */
+    const hungFedcmSilentStep = (): ColdBootStep<TestSession> => ({
+      id: 'fedcm-silent',
+      run: () => new Promise<ColdBootStepResult<TestSession>>(() => {}),
+    });
+
+    it('abandons the hung fedcm-silent step at the 20s deadline and fires the terminal /sso bounce', async () => {
+      const ssoBounced = jest.fn();
+      const onStepDeadline = jest.fn();
+
+      const outcomePromise = runColdBoot<TestSession>({
+        overallDeadlineMs: COLD_BOOT_OVERALL_DEADLINE,
+        onStepDeadline,
+        steps: [
+          hungFedcmSilentStep(),
+          // Every intermediate step has nothing to contribute on this load.
+          skipStep('auth-silent-iframe'),
+          skipStep('cookie-restore'),
+          skipStep('stored-session'),
+          {
+            id: 'sso-bounce',
+            // Terminal: navigates synchronously before its first await, exactly
+            // like the real top-level `/sso` bounce.
+            run: async (): Promise<ColdBootStepResult<TestSession>> => {
+              ssoBounced();
+              return { kind: 'skip' };
+            },
+          },
+        ],
+      });
+
+      // Nothing settles before the deadline — the chain is "stuck" on silent.
+      await jest.advanceTimersByTimeAsync(COLD_BOOT_OVERALL_DEADLINE - 1);
+      expect(ssoBounced).not.toHaveBeenCalled();
+
+      // At the deadline the silent step is abandoned and the chain proceeds.
+      await jest.advanceTimersByTimeAsync(1);
+      const outcome = await outcomePromise;
+
+      expect(onStepDeadline).toHaveBeenCalledWith('fedcm-silent');
+      expect(ssoBounced).toHaveBeenCalledTimes(1);
+      expect(outcome).toEqual({ kind: 'unauthenticated' });
+    });
+
+    it('settles within the bounded budget instead of hanging forever', async () => {
+      let settled = false;
+      const outcomePromise = runColdBoot<TestSession>({
+        overallDeadlineMs: COLD_BOOT_OVERALL_DEADLINE,
+        steps: [hungFedcmSilentStep(), skipStep('terminal')],
+      }).then((o) => {
+        settled = true;
+        return o;
+      });
+
+      // Just before the deadline: still pending (proves the deadline, not an
+      // accidental early settle, is what unblocks it).
+      await jest.advanceTimersByTimeAsync(COLD_BOOT_OVERALL_DEADLINE - 1);
+      expect(settled).toBe(false);
+
+      await jest.advanceTimersByTimeAsync(1);
+      await outcomePromise;
+      expect(settled).toBe(true);
+    });
+
+    it('does not penalize a fast silent success — it wins well before the deadline', async () => {
+      const laterRan = jest.fn();
+      const outcomePromise = runColdBoot<TestSession>({
+        overallDeadlineMs: COLD_BOOT_OVERALL_DEADLINE,
+        steps: [
+          {
+            id: 'fedcm-silent',
+            run: async (): Promise<ColdBootStepResult<TestSession>> => {
+              await Promise.resolve();
+              return { kind: 'session', session: { userId: 'u-silent' } };
+            },
+          },
+          sessionStep('sso-bounce', 'u-should-not-run', laterRan),
+        ],
+      });
+
+      await jest.advanceTimersByTimeAsync(0);
+      const outcome = await outcomePromise;
+
+      expect(outcome).toEqual({
+        kind: 'session',
+        via: 'fedcm-silent',
+        session: { userId: 'u-silent' },
+      });
+      expect(laterRan).not.toHaveBeenCalled();
+    });
+  });
 });

package/src/utils/cacheKey.ts

@@ -0,0 +1,98 @@
+/**
+ * Cache-key primitives for the identity-scoped HTTP GET response cache.
+ *
+ * Extracted from {@link HttpService} so the identity-tag derivation is a pure,
+ * independently testable function with no dependency on instance/token state.
+ * The HTTP service injects the live access token and acting-as id; everything
+ * here is referentially transparent given those inputs.
+ */
+
+import { jwtDecode } from 'jwt-decode';
+
+/**
+ * Minimal JWT payload shape we read for cache scoping. The identity discriminator
+ * comes from `userId` (preferred) or `id`; nothing else is consulted here.
+ */
+export interface CacheIdentityJwtPayload {
+  userId?: string;
+  id?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Discriminator used when there is no access token at all. Anonymous responses
+ * must never collide with any authenticated identity.
+ */
+export const ANON_IDENTITY = 'anon';
+
+/**
+ * FNV-1a 32-bit non-cryptographic hash.
+ *
+ * Used by the cache-key generator for large payloads where full JSON inclusion
+ * would balloon the cache map keys, and as the fallback discriminator for an
+ * undecodable access token. Content-addressed: every byte of the input
+ * contributes to the digest, so two inputs with the same top-level shape but
+ * different field values produce different keys (the previous `keys + length`
+ * heuristic collided on these).
+ *
+ * Trade-offs:
+ *  - 32 bits is ample for an in-process cache (collision risk negligible at our
+ *    key counts; we also prefix with method + url which further partitions the
+ *    keyspace).
+ *  - Not cryptographically secure — never use for security decisions.
+ *  - Zero dependencies, branch-free hot loop, ~1 GiB/s on V8.
+ */
+export function fnv1a32(str: string): string {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i);
+    // h * 16777619 mod 2^32, written as shift-and-add for portability and
+    // to avoid 53-bit JS number truncation in the intermediate multiply.
+    h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;
+  }
+  return h.toString(16).padStart(8, '0');
+}
+
+/**
+ * Derive a stable, non-sensitive identity discriminator for cache scoping.
+ *
+ * The GET-response cache MUST be partitioned by caller identity: endpoints with
+ * optional auth (e.g. `GET /profiles/recommendations`) return different content
+ * for an anonymous vs an authenticated caller, and per-user content for
+ * different authenticated users. Keying solely on `method:url:data` let an
+ * anonymous response be served to an authenticated caller — surfacing as
+ * "Who to follow" recommending accounts the user already follows after a
+ * cold-boot session restore.
+ *
+ * Resolution order:
+ *  - no token            → {@link ANON_IDENTITY} (`'anon'`).
+ *  - decodable token     → the token's `userId || id`.
+ *  - undecodable token   → a short FNV-1a hash of the token, prefixed `t` so it
+ *                          can never collide with `'anon'` or a real user id.
+ *
+ * We use the decoded user id rather than the raw JWT so the token never lands
+ * in a cache key (no token leakage through any cache-key logging, no key bloat).
+ * The acting-as id is folded in because managed-account responses differ per
+ * acting identity — and `X-Acting-As` already changes the server response for
+ * the same bearer token.
+ *
+ * @param accessToken The current bearer access token, or `null` when anonymous.
+ * @param actingAsUserId The active managed-account id, or `null`.
+ */
+export function computeIdentityTag(
+  accessToken: string | null,
+  actingAsUserId: string | null,
+): string {
+  let principal = ANON_IDENTITY;
+  if (accessToken) {
+    try {
+      const decoded = jwtDecode<CacheIdentityJwtPayload>(accessToken);
+      principal = decoded.userId || decoded.id || `t${fnv1a32(accessToken)}`;
+    } catch {
+      // Undecodable token — still partition it away from anon and from other
+      // tokens via a hash. Never silently fall back to ANON_IDENTITY.
+      principal = `t${fnv1a32(accessToken)}`;
+    }
+  }
+  return actingAsUserId ? `${principal}~as${actingAsUserId}` : principal;
+}

package/src/utils/errorUtils.ts

@@ -180,6 +180,31 @@ export function getErrorCodeFromStatus(status: number): string {
   }
 }
 
+/**
+ * Best-effort extraction of an HTTP status code from a thrown value.
+ *
+ * `HttpService` annotates the errors it throws with both `error.status` and
+ * `error.response.status`; an already-normalized {@link ApiError} carries
+ * `error.status`. This reads either, returning `undefined` when the value is
+ * not an object or carries no numeric status (e.g. a thrown string, a network
+ * `TypeError`). Used by discovery/read paths to distinguish a 404 "not found"
+ * from a transport/server failure for observability without re-deriving the
+ * narrowing at every call site.
+ */
+export function extractErrorStatus(error: unknown): number | undefined {
+  if (!error || typeof error !== 'object') {
+    return undefined;
+  }
+  const record = error as { status?: unknown; response?: { status?: unknown } };
+  if (typeof record.status === 'number') {
+    return record.status;
+  }
+  if (typeof record.response?.status === 'number') {
+    return record.response.status;
+  }
+  return undefined;
+}
+
 /**
  * Validate required fields and throw error if missing
  */