@oxy.so/core 1.18.0 → 3.0.0

package/src/__tests__/nearExpiryMintStorm.test.ts

@@ -1,165 +0,0 @@
-/**
- * The near-expiry mint storm that signed a busy app out (OxyHQ/Mention#1140).
- *
- * What the server does: `POST /session/device/token` answers with the session's
- * STORED access token for as long as that token has not expired, and mints a
- * new one only once it is past `exp`. The mint is budgeted at 30/min per device.
- *
- * What the client did with that: the scheduler and the request-time preflight
- * both re-mint 60s before `exp`. The server handed the same token back, which
- * counted as a success (no cooldown), so the scheduler re-armed at its 1s floor
- * and every request re-ran the preflight: ~30 mints in the token's last minute,
- * then a 429, whose 60s cooldown straddled the real expiry. The next request
- * carried no bearer, drew a 401, found the refresh cooling down, and the
- * HttpService cleared the token — which the provider reads as a sign-out.
- *
- * Production logs for the device showed exactly this: a burst of ~30 mints at
- * ~1.4s intervals every ~16 minutes, a single mint ~78s later (the scheduler's
- * 5+10+20+40s backoff through the 60s rate-limit cooldown), and a sign-out on
- * the one cycle where the app was in active use across the expiry.
- *
- * This suite simulates that server against the real HttpService, refresh
- * scheduler and 401 lane.
- */
-import { OxyServices } from '../OxyServices';
-import { startTokenRefreshScheduler } from '../session/refresh';
-
-const TOKEN_TTL_SECONDS = 15 * 60;
-const MINT_BUDGET_PER_MINUTE = 30;
-
-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 expOf(token: string): number {
-  const [, payload] = token.split('.');
-  return (JSON.parse(Buffer.from(payload, 'base64url').toString()) as { exp: number }).exp;
-}
-
-/**
- * The device mint as the server implements it, including its rate limiter.
- *
- * `rotateWithinSeconds` is how close to `exp` the stored token may be before the
- * server rotates instead of handing it back: `0` is the server as it was (it
- * rotated only a token already past `exp`), a positive value is the fixed one.
- */
-function createMintServer(rotateWithinSeconds: number): {
-  mint: () => { status: 200; token: string } | { status: 429 };
-  storedToken: () => string;
-  mints: number[];
-  rateLimited: number;
-} {
-  let serial = 0;
-  const issue = (): string => {
-    serial += 1;
-    return createJwt({ userId: 'u', jti: `t${serial}`, exp: Math.floor(Date.now() / 1000) + TOKEN_TTL_SECONDS });
-  };
-  let stored = issue();
-  const mints: number[] = [];
-  const state = { rateLimited: 0 };
-  return {
-    mint: () => {
-      const now = Date.now();
-      if (mints.filter((at) => now - at < 60_000).length >= MINT_BUDGET_PER_MINUTE) {
-        state.rateLimited += 1;
-        return { status: 429 };
-      }
-      mints.push(now);
-      // `getAccessToken`: hand back the stored token unless it has expired.
-      if (expOf(stored) - Math.floor(now / 1000) < (rotateWithinSeconds > 0 ? rotateWithinSeconds : 0)) {
-        stored = issue();
-      }
-      return { status: 200, token: stored };
-    },
-    storedToken: () => stored,
-    mints,
-    get rateLimited() {
-      return state.rateLimited;
-    },
-  };
-}
-
-describe('a busy app across an access token expiry', () => {
-  const originalFetch = globalThis.fetch;
-
-  afterEach(() => {
-    globalThis.fetch = originalFetch;
-    jest.useRealTimers();
-  });
-
-  async function runBusyApp(rotateWithinSeconds: number): Promise<{
-    tokenEvents: Array<string | null>;
-    finalToken: string | null;
-    server: ReturnType<typeof createMintServer>;
-  }> {
-    jest.useFakeTimers({ now: new Date('2026-09-25T13:48:00Z') });
-    const server = createMintServer(rotateWithinSeconds);
-
-    // The app's own API: 401 without a live bearer, as any resource server does.
-    globalThis.fetch = (async (_input: unknown, init?: RequestInit) => {
-      const headers = (init?.headers ?? {}) as Record<string, string>;
-      const bearer = headers.Authorization ?? headers.authorization;
-      const token = bearer?.startsWith('Bearer ') ? bearer.slice(7) : null;
-      if (!token || expOf(token) <= Math.floor(Date.now() / 1000)) {
-        return new Response(JSON.stringify({ error: 'Unauthorized' }), {
-          status: 401,
-          headers: { 'content-type': 'application/json' },
-        });
-      }
-      return new Response(JSON.stringify({ data: { ok: true } }), {
-        status: 200,
-        headers: { 'content-type': 'application/json' },
-      });
-    }) as typeof fetch;
-
-    const oxy = new OxyServices({ baseURL: 'https://api.mention.earth', enableCache: false, enableRetry: false });
-    oxy.setTokens(server.storedToken());
-    oxy.httpService.setAuthRefreshHandler(async (reason) => {
-      const answer = server.mint();
-      if (answer.status === 429) {
-        // What `refreshDeviceSecretArm` does with a 429.
-        oxy.httpService.noteRefreshRateLimited();
-        return null;
-      }
-      oxy.setTokens(answer.token);
-      return answer.token;
-    });
-
-    const tokenEvents: Array<string | null> = [];
-    oxy.onTokensChanged((token) => tokenEvents.push(token));
-    const scheduler = startTokenRefreshScheduler(oxy);
-
-    // Twenty minutes of an app in use: a request every 700ms, straight across
-    // the first token's expiry at 14:03:00.
-    for (let elapsed = 0; elapsed < 20 * 60_000; elapsed += 700) {
-      await oxy.httpService.get('/feed').catch(() => undefined);
-      await jest.advanceTimersByTimeAsync(700);
-    }
-    scheduler.dispose();
-    return { tokenEvents, finalToken: oxy.getAccessToken(), server };
-  }
-
-  it('against the server that hands back an unexpired token: never cleared, never rate limited', async () => {
-    const { tokenEvents, finalToken, server } = await runBusyApp(0);
-
-    // Before the fix: ~30 mints of the same token, a 429, then the token was
-    // cleared (a run of `null` events) and the app was signed out.
-    expect(tokenEvents).not.toContain(null);
-    expect(finalToken).not.toBeNull();
-    expect(server.rateLimited).toBe(0);
-    // One rotation. The server still hands the expired token back for the
-    // second it expires in (it compares `exp < now`), which costs a few mints in
-    // that one second — nowhere near the budget.
-    expect(server.mints.length).toBeLessThan(MINT_BUDGET_PER_MINUTE / 3);
-  });
-
-  it('against the server that rotates a token near expiry: one mint per rotation', async () => {
-    const { tokenEvents, finalToken, server } = await runBusyApp(120);
-
-    expect(tokenEvents).not.toContain(null);
-    expect(finalToken).not.toBeNull();
-    expect(server.rateLimited).toBe(0);
-    expect(server.mints).toHaveLength(1);
-  });
-});

package/src/__tests__/parseHttpErrorBody.test.ts

@@ -1,116 +0,0 @@
-import { isHttpRequestError, parseHttpErrorBody } from '../utils/errorUtils';
-
-/**
- * `parseHttpErrorBody` is the ONE place the SDK decides what a failed request's
- * message, code and details are, across every error envelope the Oxy ecosystem
- * emits. The bug it exists to prevent is silent: a nested
- * `{ error: { code, message } }` assigned straight to `new Error(...)` yields
- * the literal string `"[object Object]"`, which reads as a rendering bug in
- * whichever app surfaces it, arbitrarily far from here.
- *
- * Each case below pins one envelope AND the discrimination it depends on — in
- * particular, whether the top-level `error` string is a machine CODE or human
- * prose is decided solely by whether a sibling human field is present, so both
- * sides of that fork need a fixture or the rule is untested.
- */
-describe('parseHttpErrorBody', () => {
-    it('reads the nested { error: { code, message, details } } envelope', () => {
-        expect(
-            parseHttpErrorBody({
-                error: { code: 'case_conflict', message: 'A case already exists', details: { caseId: 'c_1' } },
-            }),
-        ).toEqual({
-            message: 'A case already exists',
-            code: 'case_conflict',
-            details: { caseId: 'c_1' },
-        });
-    });
-
-    it("reads oxy-api's { error: '<CODE>', message } shape — error IS the code", () => {
-        expect(parseHttpErrorBody({ error: 'VALIDATION_ERROR', message: 'username is taken' })).toEqual({
-            message: 'username is taken',
-            code: 'VALIDATION_ERROR',
-            details: undefined,
-        });
-    });
-
-    it("reads RFC 6749 { error: '<CODE>', error_description } from the OAuth endpoints", () => {
-        // The OAuth token/userinfo endpoints are the one part of the API that
-        // does not use the `{ error, message }` envelope. Without this arm the
-        // human text is dropped and the raw code is shown to the user.
-        expect(
-            parseHttpErrorBody({ error: 'invalid_grant', error_description: 'Authorization code expired' }),
-        ).toEqual({
-            message: 'Authorization code expired',
-            code: 'invalid_grant',
-            details: undefined,
-        });
-    });
-
-    it("treats a LONE { error: '<text>' } as the message, never as a code", () => {
-        // The discriminator is the ABSENCE of a sibling human field. Promoting a
-        // bare string to `code` would put prose where callers switch on codes,
-        // so this case and the two above have to disagree.
-        expect(parseHttpErrorBody({ error: 'Something went wrong' })).toEqual({
-            message: 'Something went wrong',
-            code: undefined,
-            details: undefined,
-        });
-    });
-
-    it('reads the flat { message, code } shape (CSRF rejections)', () => {
-        expect(parseHttpErrorBody({ message: 'Invalid CSRF token', code: 'CSRF_TOKEN_INVALID' })).toEqual({
-            message: 'Invalid CSRF token',
-            code: 'CSRF_TOKEN_INVALID',
-            details: undefined,
-        });
-    });
-
-    it('ignores whitespace-only strings rather than reporting them as a message', () => {
-        // A blank message is worse than none: it replaces the status fallback
-        // with an empty error surface the user cannot act on.
-        expect(parseHttpErrorBody({ message: '   ', error: '' })).toEqual({
-            message: undefined,
-            code: undefined,
-            details: undefined,
-        });
-    });
-
-    it('ignores a non-object `details` instead of passing it through', () => {
-        expect(parseHttpErrorBody({ message: 'nope', details: 'not-an-object' }).details).toBeUndefined();
-        expect(parseHttpErrorBody({ message: 'nope', details: ['a'] }).details).toBeUndefined();
-    });
-
-    it.each([null, undefined, [], 'a string', 42, true])('returns {} for the non-object body %p', (body) => {
-        expect(parseHttpErrorBody(body)).toEqual({});
-    });
-
-    it('returns {} for an object carrying none of the known fields', () => {
-        expect(parseHttpErrorBody({ unrelated: 'field' })).toEqual({
-            message: undefined,
-            code: undefined,
-            details: undefined,
-        });
-    });
-});
-
-describe('isHttpRequestError', () => {
-    it('accepts an Error carrying a numeric status', () => {
-        const error = Object.assign(new Error('boom'), { status: 409 });
-        expect(isHttpRequestError(error)).toBe(true);
-    });
-
-    it('rejects a plain ApiError object — those are objects, not Errors', () => {
-        // The distinction is load-bearing: an ApiError has to go through
-        // `handleHttpError` first, and a truthy answer here would let a caller
-        // read `.stack`/`.name` off something that has neither.
-        expect(isHttpRequestError({ message: 'boom', status: 409, code: 'CONFLICT' })).toBe(false);
-    });
-
-    it('rejects an Error whose status is a non-number', () => {
-        // `'409'` is the shape a hand-built error most plausibly carries, and
-        // the narrowing promises callers a number they can compare.
-        expect(isHttpRequestError(Object.assign(new Error('boom'), { status: '409' }))).toBe(false);
-        expect(isHttpRequestError(new Error('boom'))).toBe(false);
-    });
-});

package/src/__tests__/publicInterfaceParity.test.ts

@@ -1,75 +0,0 @@
-/**
- * The middleware options a CONSUMER can pass must be the ones the middleware
- * actually takes.
- *
- * `src/OxyServices.ts` re-declares `auth()` and `serviceAuth()` by hand, with
- * their option objects written out inline, because declaration emit for the
- * mixin pipeline does not carry them. That hand-written interface is what
- * downstream packages see — `OxyAuthMiddlewareOptions` in `server/auth.ts` is
- * literally `Parameters<OxyServices['auth']>[0]` — so an option that exists on
- * the mixin and not there exists for this package and for nobody else.
- *
- * `onRefusal` shipped in 1.5.0 exactly that way: implemented, tested, exported,
- * and rejected by the first host that tried to pass it
- * (`TS2345 … has no properties in common with`). Nothing in this package could
- * see it, because everything in this package resolves the mixin's own
- * declaration, where the option is present. Only the published `.d.ts` loses it.
- *
- * So the check is on the SOURCE TEXT of the two declarations, which is the
- * thing that diverges. It is not a type test: a type test here reads the merged
- * interface and passes either way — measured, by deleting the option and
- * watching `tsc --noEmit` stay green.
- */
-
-import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
-
-const SRC = join(__dirname, '..');
-
-/** Every `name?:` key declared directly inside one brace-balanced block. */
-function optionKeys(source: string, startPattern: RegExp): string[] {
-  const match = startPattern.exec(source);
-  if (!match) throw new Error(`declaration not found: ${String(startPattern)}`);
-  let depth = 0;
-  let index = source.indexOf('{', match.index);
-  const open = index;
-  do {
-    const char = source[index];
-    if (char === '{') depth += 1;
-    else if (char === '}') depth -= 1;
-    index += 1;
-  } while (depth > 0 && index < source.length);
-  const body = source.slice(open + 1, index - 1);
-  // Only keys at THIS level: a nested object literal would otherwise contribute
-  // its own keys. None exist today; the guard keeps that from becoming silent.
-  const withoutNested = body.replace(/\{[^{}]*\}/g, '');
-  return [...withoutNested.matchAll(/^\s*(\w+)\??\s*:/gm)].map((m) => m[1] as string).sort();
-}
-
-describe('the public OxyServices interface declares the options the mixin takes', () => {
-  const mixin = readFileSync(join(SRC, 'mixins/OxyServices.utility.ts'), 'utf8');
-  const publicInterface = readFileSync(join(SRC, 'OxyServices.ts'), 'utf8');
-
-  it('auth() — same option names on both declarations', () => {
-    const declared = optionKeys(mixin, /interface AuthMiddlewareOptions/);
-    const published = optionKeys(publicInterface, /^ {2}auth\(options\?: \{/m);
-
-    expect(declared).toContain('onRefusal');
-    expect(published).toEqual(declared);
-  });
-
-  it('serviceAuth() — same option names on both declarations', () => {
-    const declared = optionKeys(mixin, /^ {4}serviceAuth\(options: \{/m);
-    const published = optionKeys(publicInterface, /^ {2}serviceAuth\(options\?: \{/m);
-
-    expect(declared).toContain('onRefusal');
-    expect(published).toEqual(declared);
-  });
-
-  it('reads real declarations rather than matching nothing', () => {
-    // The floor. A regex that stopped matching would make both cases above
-    // compare two empty lists and pass.
-    expect(optionKeys(mixin, /interface AuthMiddlewareOptions/).length).toBeGreaterThan(5);
-    expect(optionKeys(publicInterface, /^ {2}auth\(options\?: \{/m).length).toBeGreaterThan(5);
-  });
-});

package/src/__tests__/serverValueImportsDeclared.test.ts

@@ -1,120 +0,0 @@
-/**
- * Every package `@oxy.so/core/server` VALUE-imports must be a real dependency.
- *
- * ## The failure this exists for, which happened
- *
- * `helmet` was declared an OPTIONAL peer dependency. `src/server/securityHeaders.ts`
- * imports it at the top level, and the server barrel re-exports that module — so
- * importing *anything* from `@oxy.so/core/server` loads helmet, and a consumer
- * that believed the "optional" marking did not install it.
- *
- * The result was a backend that could not boot: `Cannot find package 'helmet'`.
- * `tsc` passed clean the whole time, because types resolve from a peer whether
- * or not the runtime can find the module. It was found by a test suite failing
- * to resolve 29 of 63 files while every typecheck was green — which is a very
- * expensive way to learn it.
- *
- * ## Why value imports and not all imports
- *
- * `express` is imported by eight files here and every one of them is
- * `import type`. Those vanish at build time, so an optional peer is a truthful
- * declaration for it: a consumer of the client entry never needs express
- * installed. The distinction this test draws is exactly the one that decides
- * whether a missing package is a warning or a crash.
- */
-
-import { readFileSync, readdirSync } from 'node:fs';
-import path from 'node:path';
-
-const packageRoot = path.resolve(__dirname, '../..');
-const serverDir = path.join(packageRoot, 'src', 'server');
-
-const manifest = JSON.parse(readFileSync(path.join(packageRoot, 'package.json'), 'utf8')) as {
-  dependencies?: Record<string, string>;
-  peerDependencies?: Record<string, string>;
-  peerDependenciesMeta?: Record<string, { optional?: boolean }>;
-};
-
-const dependencies = new Set(Object.keys(manifest.dependencies ?? {}));
-const requiredPeers = new Set(
-  Object.keys(manifest.peerDependencies ?? {}).filter(
-    (name) => manifest.peerDependenciesMeta?.[name]?.optional !== true
-  )
-);
-
-/**
- * Bare specifiers imported for their VALUE — `import x from 'y'`,
- * `import { a } from 'y'`, `import 'y'` — but never `import type`.
- */
-function valueImports(source: string): string[] {
-  const found: string[] = [];
-  // Strip comments first: prose in a doc comment can otherwise read as code.
-  const code = source.replace(/\/\*[\s\S]*?\*\//g, ' ').replace(/(^|[^:])\/\/[^\n]*/g, '$1 ');
-  for (const match of code.matchAll(/import\s+(?!type\b)([^;']*?)from\s*'([^']+)'/g)) {
-    // `import { type A, type B } from 'x'` is still type-only in effect.
-    const clause = match[1];
-    const specifier = match[2];
-    if (specifier.startsWith('.') || specifier.startsWith('node:')) continue;
-    const names = clause.replace(/[{}]/g, '').split(',').map((n) => n.trim()).filter(Boolean);
-    if (names.length > 0 && names.every((n) => n.startsWith('type '))) continue;
-    found.push(specifier);
-  }
-  for (const match of code.matchAll(/import\s*'([^']+)'/g)) {
-    if (!match[1].startsWith('.') && !match[1].startsWith('node:')) found.push(match[1]);
-  }
-  return found;
-}
-
-function packageNameOf(specifier: string): string {
-  const parts = specifier.split('/');
-  return specifier.startsWith('@') ? `${parts[0]}/${parts[1]}` : parts[0];
-}
-
-const files = readdirSync(serverDir).filter((f) => f.endsWith('.ts') && !f.endsWith('.d.ts'));
-
-describe('@oxy.so/core/server value imports are installable', () => {
-  it('reads a non-trivial number of server modules', () => {
-    // Vacuity floor: a traversal that found nothing would satisfy every
-    // assertion below by having nothing to check.
-    expect(files.length).toBeGreaterThan(5);
-  });
-
-  it('declares every value-imported package as a dependency or a REQUIRED peer', () => {
-    const undeclared: string[] = [];
-    for (const file of files) {
-      const source = readFileSync(path.join(serverDir, file), 'utf8');
-      for (const specifier of valueImports(source)) {
-        const name = packageNameOf(specifier);
-        if (dependencies.has(name) || requiredPeers.has(name)) continue;
-        undeclared.push(`${file} → ${name}`);
-      }
-    }
-
-    // An OPTIONAL peer is not enough here and that is the whole point: the
-    // module is loaded the moment anything is imported from the server barrel,
-    // so "optional" describes a package the consumer cannot actually omit.
-    expect(undeclared.sort()).toEqual([]);
-  });
-
-  it('keeps helmet installable rather than optional', () => {
-    // The specific regression, asserted by name so a failure says what broke
-    // rather than only showing it inside a list.
-    expect(dependencies.has('helmet')).toBe(true);
-    expect(manifest.peerDependenciesMeta?.helmet?.optional).toBeUndefined();
-  });
-
-  it('keeps express-rate-limit installable rather than a peer', () => {
-    // Same class as helmet: `rateLimit.ts` value-imports it and the server
-    // barrel re-exports that module, so a missing install crashes at boot.
-    expect(dependencies.has('express-rate-limit')).toBe(true);
-    expect(manifest.peerDependencies?.['express-rate-limit']).toBeUndefined();
-  });
-
-  it('leaves express as an optional peer, because it is type-only here', () => {
-    // The counter-example that stops this test from being read as "declare
-    // everything": type imports vanish at build time, so an optional peer is a
-    // truthful declaration for express and making it required would nag every
-    // React Native consumer about a package they never load.
-    expect(manifest.peerDependenciesMeta?.express?.optional).toBe(true);
-  });
-});

package/src/__tests__/serviceTokenWorkloadFallback.test.ts

@@ -1,85 +0,0 @@
-import { describe, expect, it, jest } from '@jest/globals';
-
-import { OxyServices } from '../OxyServices';
-
-/**
- * How an official service stops holding a secret WITHOUT a code change.
- *
- * `getServiceToken()` has always required an api key and secret. It now falls
- * back to workload identity (ADR 0026) when there is none — which means the
- * migration for each of Oxy's own services is "delete two environment
- * variables", not "edit and redeploy an app".
- *
- * Three things have to be true for that to be safe, and each is asserted below:
- *
- *  1. A configured credential still wins. The fallback must not quietly change
- *     how an already-working service authenticates.
- *  2. With no credential AND no way to attest — a laptop, a CI box — the caller
- *     gets the same "no credentials" error as before, not a confusing failure
- *     from a container credentials endpoint that is not there.
- *  3. The token is cached, so a service does not mint one per request.
- */
-
-jest.mock('../server/workloadIdentity', () => ({
-  canAttestWorkloadIdentity: () => Boolean(process.env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI),
-  requestWorkloadServiceToken: jest.fn(async () => ({
-    token: 'token-from-attestation',
-    expiresIn: 3600,
-    appName: 'Mention',
-  })),
-}));
-
-import { requestWorkloadServiceToken } from '../server/workloadIdentity';
-
-const attestations = requestWorkloadServiceToken as unknown as jest.Mock;
-
-function client() {
-  return new OxyServices({ baseURL: 'https://api.oxy.so' });
-}
-
-describe('service token — workload fallback', () => {
-  const previous = process.env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI;
-
-  beforeEach(() => {
-    attestations.mockClear();
-    process.env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI = '/v2/credentials/abc';
-  });
-
-  afterAll(() => {
-    // Cleared by assignment rather than `delete`: Biome refuses `delete` on a
-    // property access, and an empty value reads as "cannot attest" everywhere
-    // that matters here.
-    process.env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI = previous ?? '';
-  });
-
-  it('attests when no credential is configured', async () => {
-    await expect(client().getServiceToken()).resolves.toBe('token-from-attestation');
-    expect(attestations).toHaveBeenCalledWith({ baseUrl: 'https://api.oxy.so' });
-  });
-
-  it('mints once and serves the cached token afterwards', async () => {
-    const oxy = client();
-
-    await oxy.getServiceToken();
-    await oxy.getServiceToken();
-
-    expect(attestations).toHaveBeenCalledTimes(1);
-  });
-
-  it('leaves a configured credential alone', async () => {
-    const oxy = client();
-    oxy.configureServiceAuth('oxy_dk_example', 'secret-example');
-    // The credential path goes to the network; failing there is fine — what
-    // matters is that it did not silently attest instead.
-    await oxy.getServiceToken().catch(() => undefined);
-
-    expect(attestations).not.toHaveBeenCalled();
-  });
-
-  it('still says "no credentials" where nothing can be attested', async () => {
-    process.env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI = '';
-
-    await expect(client().getServiceToken()).rejects.toThrow(/Service credentials not provided/);
-    expect(attestations).not.toHaveBeenCalled();
-  });
-});