@oxy.so/core 1.0.0

package/src/__tests__/httpServiceQueueDeadlock.test.ts

@@ -0,0 +1,128 @@
+/**
+ * RequestQueue deadlock regression.
+ *
+ * The auth preflight (`getAuthHeader` → single-flight `refreshAccessToken` → the
+ * device-secret mint) used to run INSIDE a RequestQueue slot, and the mint itself
+ * went through the queue. When `maxConcurrentRequests` requests all parked in
+ * slots awaiting that same mint, the mint could never acquire a slot to run —
+ * a systemic deadlock in which NOTHING settles (observed on a real device: the
+ * running count climbs to the pool size with zero settled requests, including a
+ * public GET /health). The fix: (1) `bypassQueue` runs control-plane calls (the
+ * mint) directly, and (2) the preflight is resolved OUTSIDE the slot, so an
+ * auth-blocked request never holds a slot while the shared mint runs.
+ */
+import { HttpService } from '../HttpService';
+
+function createJwt(payload: Record<string, unknown>): string {
+  const encode = (value: unknown): string => Buffer.from(JSON.stringify(value)).toString('base64url');
+  return `${encode({ alg: 'HS256', typ: 'JWT' })}.${encode(payload)}.signature`;
+}
+
+function jsonResponse(data: unknown): Response {
+  return new Response(JSON.stringify({ data }), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+/** Resolve to `true` if `promise` settles within `ms`, else `false`. Always
+ *  clears its timer so no pending timeout leaks into jest's teardown. */
+async function settlesWithin(promise: Promise<unknown>, ms: number): Promise<boolean> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<false>((resolve) => {
+    timer = setTimeout(() => resolve(false), ms);
+  });
+  try {
+    return await Promise.race([promise.then(() => true), timeout]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+describe('HttpService RequestQueue deadlock', () => {
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.restoreAllMocks();
+  });
+
+  it('runs a bypassQueue control-plane request even when every slot is held', async () => {
+    const releases: Array<() => void> = [];
+    globalThis.fetch = (async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.includes('/slow')) {
+        // Occupy the slot indefinitely until explicitly released.
+        await new Promise<void>((resolve) => releases.push(resolve));
+        return jsonResponse({ slow: true });
+      }
+      return jsonResponse({ minted: true });
+    }) as typeof fetch;
+
+    const http = new HttpService({
+      baseURL: 'https://api.oxy.so',
+      maxConcurrentRequests: 2,
+      enableRetry: false,
+    });
+
+    // Saturate both slots with requests whose fetch never settles.
+    const slowA = http.get('/slow/a', { skipAuth: true });
+    const slowB = http.get('/slow/b', { skipAuth: true });
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    // The device-secret mint (bypassQueue) must still run despite full saturation.
+    const mint = http.post(
+      '/session/device/token',
+      { deviceId: 'd', deviceSecret: 's' },
+      { skipAuth: true, bypassQueue: true, retry: false },
+    );
+
+    expect(await settlesWithin(mint, 500)).toBe(true);
+
+    releases.forEach((release) => release());
+    await Promise.all([slowA, slowB]);
+  });
+
+  it('does not deadlock when a boot burst larger than the pool all trigger the same preflight mint', async () => {
+    const now = Math.floor(Date.now() / 1000);
+    // Within the 60s refresh lead window → every request's preflight refreshes.
+    const nearExpiry = createJwt({ userId: 'u', exp: now + 30 });
+    const fresh = createJwt({ userId: 'u', exp: now + 3600, jti: 'fresh' });
+
+    let mintCalls = 0;
+    globalThis.fetch = (async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.includes('/session/device/token')) {
+        mintCalls += 1;
+        return jsonResponse({ minted: true });
+      }
+      return jsonResponse({ ok: true });
+    }) as typeof fetch;
+
+    const http = new HttpService({
+      baseURL: 'https://api.oxy.so',
+      maxConcurrentRequests: 2,
+      enableRetry: false,
+    });
+    http.setTokens(nearExpiry);
+
+    http.setAuthRefreshHandler(async () => {
+      // Mirror refreshDeviceSecretArm: mint via a bypassQueue request through the
+      // SAME instance, then plant + return the fresh token.
+      await http.post(
+        '/session/device/token',
+        { deviceId: 'd', deviceSecret: 's' },
+        { skipAuth: true, bypassQueue: true, retry: false },
+      );
+      http.setTokens(fresh);
+      return fresh;
+    });
+
+    // A boot burst of 4 against a pool of 2, all in the near-expiry window.
+    const burst = Promise.all([http.get('/a'), http.get('/b'), http.get('/c'), http.get('/d')]);
+
+    expect(await settlesWithin(burst, 800)).toBe(true);
+    // The single-flight refresh coalesces the whole burst into ONE mint.
+    expect(mintCalls).toBe(1);
+  });
+});

package/src/__tests__/httpServiceUnwrapEnvelope.test.ts

@@ -0,0 +1,115 @@
+/**
+ * `HttpService.unwrapResponse` envelope tests — driven through the REAL class
+ * against a stubbed `fetch`, never by calling the private method.
+ *
+ * The convenience unwrap reduces the house `{ data: <payload> }` envelope to its
+ * payload, and in doing so it discards every sibling key. That silently killed
+ * pagination on the account audit trails (`GET /accounts/:id/audit` and
+ * `GET /accounts/:id/billing/audit`, which answer `{ data, count, nextCursor }`):
+ * the caller got a bare array, `getNextPageParam` read `undefined`, and there was
+ * nothing at the call site to show that page 2 could never be requested.
+ *
+ * The three cases below are the whole contract, and each is load-bearing:
+ *
+ *  - a cursor page travels WHOLE (the regression),
+ *  - a `{ data, pagination }` page still travels whole (the behaviour that
+ *    already existed — the positive control for "pages are preserved"),
+ *  - a bare `{ data }` body still unwraps (the control proving the convenience
+ *    every other call site depends on is intact).
+ *
+ * Reverting the fix must redden the first and leave the other two green.
+ */
+
+import { HttpService } from '../HttpService';
+
+/** One entry of an audit page — only the shape matters here. */
+const ENTRY = { source: 'application_credential', eventType: 'created' } as const;
+
+function jsonBody(body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+describe('HttpService response-envelope unwrapping', () => {
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  /** Drive a real `HttpService.get` against a stubbed wire body. */
+  async function fetchWireBody<T>(body: unknown): Promise<T> {
+    globalThis.fetch = jest.fn(async () => jsonBody(body)) as unknown as typeof fetch;
+    const http = new HttpService({ baseURL: 'http://api.test.invalid' });
+    return http.get<T>('/accounts/acct-1/audit', { cache: false });
+  }
+
+  it('preserves a cursor page whole — `count` and `nextCursor` reach the caller', async () => {
+    const wire = { data: [ENTRY], count: 1, nextCursor: 'CURSOR-XYZ' };
+
+    const page = await fetchWireBody<typeof wire>(wire);
+
+    expect(page).toEqual(wire);
+    // The cursor is the only thing that says where page 2 starts. Asserted on
+    // its own because `toEqual` above would also pass a body that merely
+    // happened to be an array of one entry.
+    expect(page.nextCursor).toBe('CURSOR-XYZ');
+    expect(page.count).toBe(1);
+    expect(page.data).toEqual([ENTRY]);
+  });
+
+  it('preserves the LAST cursor page, where `nextCursor` is null', async () => {
+    // The recognition is by key presence, not truthiness: if the envelope
+    // collapsed into a bare array exactly when the stream ended, every caller
+    // would crash on the final page instead of finishing.
+    const wire = { data: [ENTRY], count: 1, nextCursor: null };
+
+    const page = await fetchWireBody<typeof wire>(wire);
+
+    expect(page).toEqual(wire);
+    expect(page.nextCursor).toBeNull();
+  });
+
+  it('preserves the offset-paginated `{ data, pagination }` envelope (control)', async () => {
+    const wire = {
+      data: [ENTRY],
+      pagination: { total: 1, limit: 50, offset: 0, hasMore: false },
+    };
+
+    const page = await fetchWireBody<typeof wire>(wire);
+
+    expect(page).toEqual(wire);
+  });
+
+  it('still unwraps a bare `{ data }` success envelope to its payload (control)', async () => {
+    const payload = { id: 'acct-1', name: 'Acme' };
+
+    const unwrapped = await fetchWireBody<typeof payload>({ data: payload });
+
+    expect(unwrapped).toEqual(payload);
+  });
+
+  it('still unwraps `{ data, count }`, which a dozen callers type as the bare payload', async () => {
+    // `{ data, count }` is answered by ~15 routes whose Console call sites type
+    // the result `Array<T>`. `count` is `data.length` — recoverable — so this
+    // envelope deliberately does NOT survive, and widening the rule to "any
+    // sibling key" would break every one of those callers at runtime.
+    const entries = [ENTRY, ENTRY];
+
+    const unwrapped = await fetchWireBody<typeof entries>({ data: entries, count: 2 });
+
+    expect(unwrapped).toEqual(entries);
+  });
+
+  it('passes through a body that has no `data` key at all', async () => {
+    // The cursor surfaces already in the SDK (`{ follows, nextCursor }`,
+    // `{ records, nextCursor }`) rely on this lane.
+    const wire = { follows: [{ relationshipId: 'rel-1' }], nextCursor: 'CURSOR-ABC' };
+
+    const passed = await fetchWireBody<typeof wire>(wire);
+
+    expect(passed).toEqual(wire);
+  });
+});

package/src/__tests__/inSessionRefresh.test.ts

@@ -0,0 +1,260 @@
+/**
+ * In-session access-token refresh plumbing.
+ *
+ * These guard the HttpService surface that `@oxy.so/services`' OxyContext now
+ * drives via `setAuthRefreshHandler`: a 401 re-mints through the handler and
+ * retries the ORIGINAL request with the fresh token; an unrecoverable refresh
+ * clears tokens and notifies listeners (the reconcile signal that flips the RN
+ * provider out of its zombie logged-in state); concurrent refreshes coalesce and
+ * a failed refresh is cooldown-guarded (no refresh storm). Plus the new
+ * `OxyServices.getAccessTokenExpiry()` helper the proactive scheduler reads.
+ */
+import { HttpService } from '../HttpService';
+import { OxyServices } from '../OxyServices';
+
+interface FetchCall {
+  url: string;
+  init: RequestInit | undefined;
+}
+
+function createJwt(payload: Record<string, unknown>): string {
+  const encode = (value: unknown): string => Buffer.from(JSON.stringify(value)).toString('base64url');
+  return `${encode({ alg: 'HS256', typ: 'JWT' })}.${encode(payload)}.signature`;
+}
+
+function jsonResponse(data: unknown): Response {
+  return new Response(JSON.stringify({ data }), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+function unauthorized(): Response {
+  return new Response(JSON.stringify({ error: 'token expired' }), {
+    status: 401,
+    statusText: 'Unauthorized',
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+function readHeaders(init: RequestInit | undefined): Record<string, string> {
+  const headers = init?.headers;
+  if (!headers) return {};
+  if (headers instanceof Headers) return Object.fromEntries(headers.entries());
+  if (Array.isArray(headers)) return Object.fromEntries(headers);
+  return headers as Record<string, string>;
+}
+
+const farFutureExp = (): number => Math.floor(Date.now() / 1000) + 3600;
+
+describe('HttpService in-session refresh handler', () => {
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.restoreAllMocks();
+  });
+
+  it('refreshes via the handler on a 401 and retries the original request with the fresh token', async () => {
+    const oldToken = createJwt({ userId: 'u', exp: farFutureExp(), jti: 'old' });
+    const newToken = createJwt({ userId: 'u', exp: farFutureExp(), jti: 'new' });
+    const calls: FetchCall[] = [];
+    let feedAttempts = 0;
+    globalThis.fetch = async (input, init) => {
+      const url = String(input);
+      calls.push({ url, init });
+      if (url.endsWith('/feed')) {
+        feedAttempts += 1;
+        if (feedAttempts === 1) return unauthorized();
+      }
+      return jsonResponse({ ok: true });
+    };
+
+    const http = new HttpService({ baseURL: 'https://api.mention.earth', enableRetry: false });
+    http.setTokens(oldToken);
+
+    let handlerCalls = 0;
+    const reasons: string[] = [];
+    http.setAuthRefreshHandler(async (reason) => {
+      handlerCalls += 1;
+      reasons.push(reason);
+      // Simulate a silent arm planting the rotated token internally.
+      http.setTokens(newToken);
+      return newToken;
+    });
+
+    const result = await http.post('/feed', { cursor: 0 }, { retry: false });
+
+    expect(result).toEqual({ ok: true });
+    expect(handlerCalls).toBe(1);
+    expect(reasons).toEqual(['response-401']);
+
+    const feedCalls = calls.filter((call) => call.url.endsWith('/feed'));
+    expect(feedCalls).toHaveLength(2);
+    // The original request is retried carrying the FRESH bearer.
+    expect(readHeaders(feedCalls[1].init).Authorization).toBe(`Bearer ${newToken}`);
+    expect(http.getAccessToken()).toBe(newToken);
+  });
+
+  it('clears tokens and notifies listeners when the handler cannot refresh on a 401 (reconcile signal)', async () => {
+    globalThis.fetch = async (input) => {
+      const url = String(input);
+      if (url.endsWith('/feed')) return unauthorized();
+      return jsonResponse({ ok: true });
+    };
+
+    const oxy = new OxyServices({ baseURL: 'https://api.mention.earth' });
+    oxy.setTokens(createJwt({ userId: 'u', exp: farFutureExp() }));
+
+    const tokenEvents: Array<string | null> = [];
+    oxy.onTokensChanged((token) => tokenEvents.push(token));
+
+    oxy.getClient().setAuthRefreshHandler(async () => null);
+
+    await expect(oxy.getClient().post('/feed', {}, { retry: false })).rejects.toBeDefined();
+
+    // The dead session reconciles: token cleared + a null change emitted (which
+    // OxyContext's `handleTokenChange(null)` turns into a local sign-out).
+    expect(oxy.getAccessToken()).toBeNull();
+    expect(tokenEvents).toContain(null);
+  });
+
+  it('coalesces concurrent refreshes into a single handler invocation', async () => {
+    globalThis.fetch = async () => jsonResponse({ ok: true });
+    const newToken = createJwt({ userId: 'u', exp: farFutureExp(), jti: 'fresh' });
+
+    const http = new HttpService({ baseURL: 'https://api.mention.earth', enableRetry: false });
+    http.setTokens(createJwt({ userId: 'u', exp: farFutureExp() }));
+
+    let handlerCalls = 0;
+    http.setAuthRefreshHandler(async () => {
+      handlerCalls += 1;
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      http.setTokens(newToken);
+      return newToken;
+    });
+
+    const [a, b, c] = await Promise.all([
+      http.refreshAccessToken('preflight'),
+      http.refreshAccessToken('preflight'),
+      http.refreshAccessToken('preflight'),
+    ]);
+
+    expect(handlerCalls).toBe(1);
+    expect([a, b, c]).toEqual([newToken, newToken, newToken]);
+  });
+
+  it('cooldown-guards a failed refresh so it does not storm the handler', async () => {
+    globalThis.fetch = async () => jsonResponse({ ok: true });
+
+    const http = new HttpService({ baseURL: 'https://api.mention.earth', enableRetry: false });
+    http.setTokens(createJwt({ userId: 'u', exp: farFutureExp() }));
+
+    let handlerCalls = 0;
+    http.setAuthRefreshHandler(async () => {
+      handlerCalls += 1;
+      return null;
+    });
+
+    const first = await http.refreshAccessToken('preflight');
+    const second = await http.refreshAccessToken('preflight');
+
+    expect(first).toBeNull();
+    expect(second).toBeNull();
+    // The second call is inside the post-failure cooldown → handler not re-run.
+    expect(handlerCalls).toBe(1);
+  });
+
+  it('lets an EXPIRED token re-mint promptly instead of waiting out the long proactive cooldown', async () => {
+    // Regression: an ECS rolling-deploy blip briefly fails a mint; the 15s
+    // proactive cooldown then left the client forwarding/omitting a now-expired
+    // bearer for up to 15s after the endpoint recovered (Mention /privacy 401s).
+    // An already-expired token must recover on the short cooldown instead.
+    globalThis.fetch = async () => jsonResponse({ ok: true });
+    const nowSpy = jest.spyOn(Date, 'now');
+    const T0 = 1_000_000_000_000;
+    nowSpy.mockReturnValue(T0);
+
+    const http = new HttpService({ baseURL: 'https://api.mention.earth', enableRetry: false });
+    // Current token is already 10s past exp (exp is in SECONDS).
+    http.setTokens(createJwt({ userId: 'u', exp: Math.floor(T0 / 1000) - 10 }));
+
+    let handlerCalls = 0;
+    http.setAuthRefreshHandler(async () => {
+      handlerCalls += 1;
+      return null;
+    });
+
+    // First attempt fails → records the failure timestamp.
+    await http.refreshAccessToken('preflight');
+    expect(handlerCalls).toBe(1);
+
+    // 500ms later: still inside the SHORT expired cooldown → NOT re-run. This is
+    // the storm guard — an expired token does not fully bypass the cooldown.
+    nowSpy.mockReturnValue(T0 + 500);
+    await http.refreshAccessToken('preflight');
+    expect(handlerCalls).toBe(1);
+
+    // 1.5s later: past the short expired cooldown but WELL inside the 15s
+    // proactive cooldown → the expired token re-mints promptly.
+    nowSpy.mockReturnValue(T0 + 1500);
+    await http.refreshAccessToken('preflight');
+    expect(handlerCalls).toBe(2);
+
+    nowSpy.mockRestore();
+  });
+
+  it('keeps the full 15s cooldown for a still-valid (proactive) near-expiry refresh', async () => {
+    globalThis.fetch = async () => jsonResponse({ ok: true });
+    const nowSpy = jest.spyOn(Date, 'now');
+    const T0 = 1_000_000_000_000;
+    nowSpy.mockReturnValue(T0);
+
+    const http = new HttpService({ baseURL: 'https://api.mention.earth', enableRetry: false });
+    // Token is still valid for another hour — a proactive refresh, not expired.
+    http.setTokens(createJwt({ userId: 'u', exp: Math.floor(T0 / 1000) + 3600 }));
+
+    let handlerCalls = 0;
+    http.setAuthRefreshHandler(async () => {
+      handlerCalls += 1;
+      return null;
+    });
+
+    await http.refreshAccessToken('preflight');
+    expect(handlerCalls).toBe(1);
+
+    // 1.5s later: past the short expired cooldown, but the token is NOT expired,
+    // so the full proactive cooldown still applies → no re-run (no storm).
+    nowSpy.mockReturnValue(T0 + 1500);
+    await http.refreshAccessToken('preflight');
+    expect(handlerCalls).toBe(1);
+
+    nowSpy.mockRestore();
+  });
+});
+
+describe('OxyServices.getAccessTokenExpiry', () => {
+  it('returns the JWT exp (seconds) of the current access token', () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    const exp = Math.floor(Date.now() / 1000) + 1234;
+    oxy.setTokens(createJwt({ userId: 'u', exp }));
+    expect(oxy.getAccessTokenExpiry()).toBe(exp);
+  });
+
+  it('returns null when there is no access token', () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    expect(oxy.getAccessTokenExpiry()).toBeNull();
+  });
+
+  it('returns null for an opaque / non-JWT token', () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    oxy.setTokens('opaque-not-a-jwt');
+    expect(oxy.getAccessTokenExpiry()).toBeNull();
+  });
+
+  it('returns null for a JWT with no numeric exp claim', () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    oxy.setTokens(createJwt({ userId: 'u' }));
+    expect(oxy.getAccessTokenExpiry()).toBeNull();
+  });
+});