@oxy.so/core 1.18.0 → 3.0.0

package/src/__tests__/httpServiceRateLimitedRefresh.test.ts

@@ -1,160 +0,0 @@
-/**
- * The post-429 refresh cooldown.
- *
- * `POST /session/device/token` is budgeted at 30 mints/minute
- * (`packages/api/src/routes/sessionDevice.ts`). Once the access token is
- * EXPIRED, the request-driven refresh lanes — the request-time preflight in
- * `getAuthHeader` and the 401 retry — reattempt on
- * `EXPIRED_TOKEN_REFRESH_COOLDOWN_MS`, i.e. one mint per second, 60/min. That
- * is correct against an unreachable server (recover the instant it returns) and
- * exactly wrong against a rationing one: the retries spend the very budget they
- * are waiting on, so the limiter stays tripped for as long as the app keeps
- * issuing requests and the session can never heal itself.
- *
- * These tests pin the discrimination: a 429 lengthens the NEXT cooldown to the
- * limiter's own window, every other failure keeps the token-state cooldowns, and
- * a success clears it.
- *
- * `Date.now` is stubbed rather than using fake timers: the cooldown is a pure
- * comparison against a stored epoch, so moving the clock is the whole
- * experiment, and real microtasks keep the refresh promises resolving normally.
- */
-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`;
-}
-
-/** The server's mint budget window — the interval the fix must wait out. */
-const LIMITER_WINDOW_MS = 60_000;
-
-/** Comfortably past the expired-token cooldown (1s) but inside the 429 window. */
-const BETWEEN_COOLDOWNS_MS = 30_000;
-
-describe('HttpService — refresh cooldown after a rate-limited mint', () => {
-  let clock = 1_700_000_000_000;
-
-  beforeEach(() => {
-    clock = 1_700_000_000_000;
-    jest.spyOn(Date, 'now').mockImplementation(() => clock);
-  });
-
-  afterEach(() => {
-    jest.restoreAllMocks();
-  });
-
-  /** A client whose CURRENT access token is already past `exp`. */
-  function expiredTokenClient(): HttpService {
-    const http = new HttpService({ baseURL: 'https://api.oxy.so', enableRetry: false });
-    http.setTokens(createJwt({ userId: 'u', exp: Math.floor(clock / 1000) - 60 }));
-    return http;
-  }
-
-  it('retries an expired token ~1s after an ORDINARY failure (the unreachable-server lane is untouched)', async () => {
-    const http = expiredTokenClient();
-    const handler = jest.fn(async () => null);
-    http.setAuthRefreshHandler(handler);
-
-    expect(await http.refreshAccessToken('preflight')).toBeNull();
-    expect(handler).toHaveBeenCalledTimes(1);
-
-    clock += 1_001;
-    expect(await http.refreshAccessToken('preflight')).toBeNull();
-    expect(handler).toHaveBeenCalledTimes(2);
-  });
-
-  it('suppresses the retry for the limiter window after a 429, instead of hammering once a second', async () => {
-    const http = expiredTokenClient();
-    const handler = jest.fn(async () => {
-      // What `refreshDeviceSecretArm` does when the mint answers 429.
-      http.noteRefreshRateLimited();
-      return null;
-    });
-    http.setAuthRefreshHandler(handler);
-
-    expect(await http.refreshAccessToken('preflight')).toBeNull();
-    expect(handler).toHaveBeenCalledTimes(1);
-
-    // Past the expired-token cooldown. Without the 429 discrimination this is
-    // where the client resumes one mint per second and holds the limiter down.
-    clock += BETWEEN_COOLDOWNS_MS;
-    expect(await http.refreshAccessToken('preflight')).toBeNull();
-    expect(handler).toHaveBeenCalledTimes(1);
-
-    // Once the limiter's window has drained, exactly one probe goes out.
-    clock += LIMITER_WINDOW_MS;
-    expect(await http.refreshAccessToken('preflight')).toBeNull();
-    expect(handler).toHaveBeenCalledTimes(2);
-  });
-
-  it('holds a rate-limited client under the mint budget while requests keep arriving', async () => {
-    const http = expiredTokenClient();
-    const handler = jest.fn(async () => {
-      http.noteRefreshRateLimited();
-      return null;
-    });
-    http.setAuthRefreshHandler(handler);
-
-    // One simulated minute of a busy app: a request every 250ms, each one
-    // driving the preflight/401 refresh lane.
-    for (let elapsed = 0; elapsed < 60_000; elapsed += 250) {
-      await http.refreshAccessToken('preflight');
-      clock += 250;
-    }
-
-    // The server's budget is 30/min. The unfixed client issues 60.
-    expect(handler.mock.calls.length).toBeLessThanOrEqual(2);
-  });
-
-  it('clears the lengthened cooldown once a refresh succeeds', async () => {
-    const http = expiredTokenClient();
-    const fresh = createJwt({ userId: 'u', exp: Math.floor(clock / 1000) + 900 });
-    const handler = jest
-      .fn<Promise<string | null>, []>()
-      .mockImplementationOnce(async () => {
-        http.noteRefreshRateLimited();
-        return null;
-      })
-      .mockImplementationOnce(async () => fresh)
-      // A later ordinary failure must be back on the short cooldown, proving the
-      // 429 state did not become sticky.
-      .mockImplementation(async () => null);
-    http.setAuthRefreshHandler(handler);
-
-    await http.refreshAccessToken('preflight');
-    clock += LIMITER_WINDOW_MS + 1;
-    expect(await http.refreshAccessToken('preflight')).toBe(fresh);
-
-    // The planted token is fresh, so this is the still-valid (15s) cooldown.
-    clock += 16_000;
-    await http.refreshAccessToken('preflight');
-    expect(handler).toHaveBeenCalledTimes(3);
-
-    clock += 16_000;
-    await http.refreshAccessToken('preflight');
-    expect(handler).toHaveBeenCalledTimes(4);
-  });
-
-  it('returns to the short cooldown when a later failure is NOT a 429', async () => {
-    const http = expiredTokenClient();
-    const handler = jest
-      .fn<Promise<string | null>, []>()
-      .mockImplementationOnce(async () => {
-        http.noteRefreshRateLimited();
-        return null;
-      })
-      // The limiter window passed and the endpoint is merely erroring now.
-      .mockImplementation(async () => null);
-    http.setAuthRefreshHandler(handler);
-
-    await http.refreshAccessToken('preflight');
-    clock += LIMITER_WINDOW_MS + 1;
-    await http.refreshAccessToken('preflight');
-    expect(handler).toHaveBeenCalledTimes(2);
-
-    clock += 1_001;
-    await http.refreshAccessToken('preflight');
-    expect(handler).toHaveBeenCalledTimes(3);
-  });
-});

package/src/__tests__/httpServiceUnwrapEnvelope.test.ts

@@ -1,115 +0,0 @@
-/**
- * `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__/httpServiceWrites.test.ts

@@ -1,175 +0,0 @@
-import { HttpService } from '../HttpService';
-
-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 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>;
-}
-
-/**
- * Writes carry exactly one credential: the bearer, when there is one. Oxy's API
- * has no CSRF layer (issue #1044) and the SDK neither fetches `/csrf-token` nor
- * sends `X-CSRF-Token` / `X-Native-App`, for its own API or a linked one.
- */
-describe('HttpService writes', () => {
-  const originalFetch = globalThis.fetch;
-
-  afterEach(() => {
-    globalThis.fetch = originalFetch;
-    jest.restoreAllMocks();
-  });
-
-  function recordFetches(respond: (url: string) => Response = () => jsonResponse({ ok: true })): FetchCall[] {
-    const calls: FetchCall[] = [];
-    globalThis.fetch = async (input, init) => {
-      const url = String(input);
-      calls.push({ url, init });
-      return respond(url);
-    };
-    return calls;
-  }
-
-  it('sends a bearer-authenticated write as a single request', async () => {
-    const calls = recordFetches();
-
-    const http = new HttpService({ baseURL: 'https://api.mention.earth', enableRetry: false });
-    const accessToken = createJwt({
-      userId: 'user_1',
-      exp: Math.floor(Date.now() / 1000) + 3600,
-    });
-    http.setTokens(accessToken);
-
-    await http.post('/posts', { text: 'hello' });
-
-    expect(calls.map((call) => call.url)).toEqual(['https://api.mention.earth/posts']);
-    const headers = readHeaders(calls[0].init);
-    expect(headers.Authorization).toBe(`Bearer ${accessToken}`);
-    expect(headers['X-CSRF-Token']).toBeUndefined();
-    expect(headers['X-Native-App']).toBeUndefined();
-  });
-
-  it('sends a write without a bearer as a single request with no CSRF preflight', async () => {
-    const calls = recordFetches();
-
-    const http = new HttpService({ baseURL: 'https://api.oxy.so', enableRetry: false });
-
-    await http.post('/users/by-ids', { ids: ['user_1'] });
-
-    // POSITIVE CONTROL: the write itself went out, so the absence below is not
-    // the absence of any request at all.
-    expect(calls.map((call) => call.url)).toEqual(['https://api.oxy.so/users/by-ids']);
-    const headers = readHeaders(calls[0].init);
-    expect(headers.Authorization).toBeUndefined();
-    expect(headers['X-CSRF-Token']).toBeUndefined();
-    expect(headers['X-Native-App']).toBeUndefined();
-  });
-
-  it('keeps a valid near-expiry bearer token when preflight refresh cannot refresh', async () => {
-    const calls = recordFetches();
-
-    const http = new HttpService({ baseURL: 'https://api.mention.earth', enableRetry: false });
-    const accessToken = createJwt({
-      userId: 'user_1',
-      exp: Math.floor(Date.now() / 1000) + 30,
-    });
-    let refreshAttempts = 0;
-    http.setTokens(accessToken);
-    http.setAuthRefreshHandler(async () => {
-      refreshAttempts += 1;
-      return null;
-    });
-
-    await http.post('/posts', { text: 'hello' });
-
-    expect(refreshAttempts).toBe(1);
-    expect(calls.map((call) => call.url)).toEqual(['https://api.mention.earth/posts']);
-    expect(readHeaders(calls[0].init).Authorization).toBe(`Bearer ${accessToken}`);
-  });
-
-  it('does not use an expired bearer token when preflight refresh cannot refresh', async () => {
-    const calls = recordFetches();
-
-    const http = new HttpService({ baseURL: 'https://api.mention.earth', enableRetry: false });
-    const accessToken = createJwt({
-      userId: 'user_1',
-      exp: Math.floor(Date.now() / 1000) - 10,
-    });
-    let refreshAttempts = 0;
-    http.setTokens(accessToken);
-    http.setAuthRefreshHandler(async () => {
-      refreshAttempts += 1;
-      return null;
-    });
-
-    await http.post('/posts', { text: 'hello' });
-
-    expect(refreshAttempts).toBe(1);
-    expect(calls.map((call) => call.url)).toEqual(['https://api.mention.earth/posts']);
-    expect(readHeaders(calls[0].init).Authorization).toBeUndefined();
-  });
-
-  it('does not retry a 403, whatever its code says', async () => {
-    const calls = recordFetches(
-      () =>
-        new Response(JSON.stringify({ code: 'CSRF_TOKEN_INVALID' }), {
-          status: 403,
-          statusText: 'Forbidden',
-          headers: { 'content-type': 'application/json' },
-        }),
-    );
-
-    const http = new HttpService({ baseURL: 'https://api.mention.earth', enableRetry: false });
-
-    await expect(http.post('/posts', { text: 'hello' })).rejects.toBeDefined();
-    expect(calls.map((call) => call.url)).toEqual(['https://api.mention.earth/posts']);
-  });
-
-  it('includes credentials for configured API origin requests', async () => {
-    const calls = recordFetches();
-
-    const http = new HttpService({ baseURL: 'https://api.oxy.so', enableRetry: false });
-
-    await http.get('/users/me');
-
-    expect(calls).toHaveLength(1);
-    expect(calls[0].url).toBe('https://api.oxy.so/users/me');
-    expect(calls[0].init?.credentials).toBe('include');
-  });
-
-  it('omits credentials for caller-supplied absolute URLs outside the configured API origin', async () => {
-    const calls = recordFetches();
-
-    const http = new HttpService({ baseURL: 'https://api.oxy.so', enableRetry: false });
-
-    await http.get('https://attacker.oxy.so/collect');
-
-    expect(calls).toHaveLength(1);
-    expect(calls[0].url).toBe('https://attacker.oxy.so/collect');
-    expect(calls[0].init?.credentials).toBe('omit');
-  });
-});