@oxy.so/core 1.18.0 → 3.0.0

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

@@ -1,496 +0,0 @@
-import {
-  runColdBoot,
-  type ColdBootStep,
-  type ColdBootStepResult,
-} from '../coldBoot';
-
-interface TestSession {
-  readonly userId: string;
-}
-
-function sessionStep(
-  id: string,
-  userId: string,
-  onRun?: () => void
-): ColdBootStep<TestSession> {
-  return {
-    id,
-    run: async (): Promise<ColdBootStepResult<TestSession>> => {
-      onRun?.();
-      return { kind: 'session', session: { userId } };
-    },
-  };
-}
-
-function skipStep(id: string, onRun?: () => void): ColdBootStep<TestSession> {
-  return {
-    id,
-    run: async (): Promise<ColdBootStepResult<TestSession>> => {
-      onRun?.();
-      return { kind: 'skip' };
-    },
-  };
-}
-
-describe('runColdBoot', () => {
-  it('returns the first session and short-circuits remaining steps', async () => {
-    const ranLater = jest.fn();
-    const outcome = await runColdBoot<TestSession>({
-      steps: [
-        skipStep('first'),
-        sessionStep('winner', 'u-123'),
-        sessionStep('later', 'u-999', ranLater),
-      ],
-    });
-
-    expect(outcome).toEqual({
-      kind: 'session',
-      via: 'winner',
-      session: { userId: 'u-123' },
-    });
-    expect(ranLater).not.toHaveBeenCalled();
-  });
-
-  it('outcome.via is the winning step id', async () => {
-    const outcome = await runColdBoot<TestSession>({
-      steps: [skipStep('a'), skipStep('b'), sessionStep('c', 'u-7')],
-    });
-
-    expect(outcome.kind).toBe('session');
-    if (outcome.kind === 'session') {
-      expect(outcome.via).toBe('c');
-      expect(outcome.session).toEqual({ userId: 'u-7' });
-    }
-  });
-
-  it('returns unauthenticated when every step skips', async () => {
-    const outcome = await runColdBoot<TestSession>({
-      steps: [skipStep('a'), skipStep('b'), skipStep('c')],
-    });
-
-    expect(outcome).toEqual({ kind: 'unauthenticated' });
-  });
-
-  it('returns unauthenticated for an empty step list', async () => {
-    const outcome = await runColdBoot<TestSession>({ steps: [] });
-    expect(outcome).toEqual({ kind: 'unauthenticated' });
-  });
-
-  it('skips a disabled step WITHOUT calling its run()', async () => {
-    const disabledRun = jest.fn();
-    const outcome = await runColdBoot<TestSession>({
-      steps: [
-        {
-          id: 'disabled',
-          enabled: () => false,
-          run: async (): Promise<ColdBootStepResult<TestSession>> => {
-            disabledRun();
-            return { kind: 'session', session: { userId: 'should-not-run' } };
-          },
-        },
-        sessionStep('enabled', 'u-ok'),
-      ],
-    });
-
-    expect(disabledRun).not.toHaveBeenCalled();
-    expect(outcome).toEqual({
-      kind: 'session',
-      via: 'enabled',
-      session: { userId: 'u-ok' },
-    });
-  });
-
-  it('runs an enabled:()=>true step', async () => {
-    const outcome = await runColdBoot<TestSession>({
-      steps: [
-        {
-          id: 'gated',
-          enabled: () => true,
-          run: async (): Promise<ColdBootStepResult<TestSession>> => ({
-            kind: 'session',
-            session: { userId: 'u-gated' },
-          }),
-        },
-      ],
-    });
-
-    expect(outcome).toEqual({
-      kind: 'session',
-      via: 'gated',
-      session: { userId: 'u-gated' },
-    });
-  });
-
-  it('reports a thrown run() via onStepError and continues to the next step', async () => {
-    const onStepError = jest.fn();
-    const boom = new Error('run exploded');
-    const outcome = await runColdBoot<TestSession>({
-      steps: [
-        {
-          id: 'throws',
-          run: async (): Promise<ColdBootStepResult<TestSession>> => {
-            throw boom;
-          },
-        },
-        sessionStep('recovers', 'u-after-throw'),
-      ],
-      onStepError,
-    });
-
-    expect(onStepError).toHaveBeenCalledTimes(1);
-    expect(onStepError).toHaveBeenCalledWith('throws', boom);
-    expect(outcome).toEqual({
-      kind: 'session',
-      via: 'recovers',
-      session: { userId: 'u-after-throw' },
-    });
-  });
-
-  it('treats a thrown enabled() as disabled, reports via onStepError, and continues', async () => {
-    const onStepError = jest.fn();
-    const enabledThrew = new Error('enabled exploded');
-    const guardedRun = jest.fn();
-    const outcome = await runColdBoot<TestSession>({
-      steps: [
-        {
-          id: 'enabled-throws',
-          enabled: () => {
-            throw enabledThrew;
-          },
-          run: async (): Promise<ColdBootStepResult<TestSession>> => {
-            guardedRun();
-            return { kind: 'session', session: { userId: 'should-not-run' } };
-          },
-        },
-        sessionStep('next', 'u-next'),
-      ],
-      onStepError,
-    });
-
-    expect(guardedRun).not.toHaveBeenCalled();
-    expect(onStepError).toHaveBeenCalledTimes(1);
-    expect(onStepError).toHaveBeenCalledWith('enabled-throws', enabledThrew);
-    expect(outcome).toEqual({
-      kind: 'session',
-      via: 'next',
-      session: { userId: 'u-next' },
-    });
-  });
-
-  it('returns unauthenticated when all steps error and reports each', async () => {
-    const onStepError = jest.fn();
-    const outcome = await runColdBoot<TestSession>({
-      steps: [
-        {
-          id: 'a',
-          run: async (): Promise<ColdBootStepResult<TestSession>> => {
-            throw new Error('a');
-          },
-        },
-        {
-          id: 'b',
-          enabled: () => {
-            throw new Error('b');
-          },
-          run: async (): Promise<ColdBootStepResult<TestSession>> => ({
-            kind: 'skip',
-          }),
-        },
-      ],
-      onStepError,
-    });
-
-    expect(outcome).toEqual({ kind: 'unauthenticated' });
-    expect(onStepError).toHaveBeenCalledTimes(2);
-  });
-
-  it('does not require onStepError to be provided when a step throws', async () => {
-    const outcome = await runColdBoot<TestSession>({
-      steps: [
-        {
-          id: 'throws',
-          run: async (): Promise<ColdBootStepResult<TestSession>> => {
-            throw new Error('no observer');
-          },
-        },
-        sessionStep('ok', 'u-ok'),
-      ],
-    });
-
-    expect(outcome).toEqual({
-      kind: 'session',
-      via: 'ok',
-      session: { userId: 'u-ok' },
-    });
-  });
-
-  describe('overall deadline (defense-in-depth)', () => {
-    beforeEach(() => {
-      jest.useFakeTimers();
-    });
-    afterEach(() => {
-      jest.runOnlyPendingTimers();
-      jest.useRealTimers();
-    });
-
-    /**
-     * A step whose `run()` promise NEVER settles (e.g. an async call that
-     * ignores 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;
-      let releaseHang: (() => void) | undefined;
-
-      const outcomePromise = runColdBoot<TestSession>({
-        steps: [
-          {
-            id: 'never-settles',
-            // Never resolves or rejects until the test tears down — models a hung async call.
-            run: () =>
-              new Promise<ColdBootStepResult<TestSession>>((resolve) => {
-                releaseHang = () => resolve({ kind: 'skip' });
-              }),
-          },
-          {
-            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();
-
-      // Tear down the intentional hang so Jest workers can exit cleanly.
-      releaseHang?.();
-      await outcomePromise;
-    });
-
-    /**
-     * With `overallDeadlineMs` set, the non-settling step is abandoned at the
-     * deadline, the runner CONTINUES to the terminal step, 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' });
-    });
-
-    /**
-     * A terminal step may run a synchronous side effect before its first
-     * `await`; that side effect must still execute when the deadline trips on
-     * an earlier step — the terminal fallback is preserved.
-     */
-    it('lets the terminal step fire its synchronous side effect after the deadline trips', async () => {
-      const terminalSideEffect = jest.fn();
-
-      const outcomePromise = runColdBoot<TestSession>({
-        overallDeadlineMs: 3000,
-        steps: [
-          {
-            id: 'never-settles',
-            run: () => new Promise<ColdBootStepResult<TestSession>>(() => {}),
-          },
-          {
-            id: 'terminal',
-            run: async (): Promise<ColdBootStepResult<TestSession>> => {
-              // Synchronous side effect that fires before the first await.
-              terminalSideEffect();
-              return { kind: 'skip' };
-            },
-          },
-        ],
-      });
-
-      await jest.advanceTimersByTimeAsync(3000);
-      await outcomePromise;
-
-      expect(terminalSideEffect).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();
-    });
-  });
-
-  /**
-   * End-to-end deadline semantics over a longer chain at the real overall
-   * deadline a consumer arms (the runner itself has no default). Models a chain
-   * whose FIRST step never settles — its `run()` promise ignores the abort
-   * signal and stays pending — followed by several no-op steps and a terminal
-   * step. Asserts the runner (a) abandons the hung step at the deadline,
-   * (b) still fires the terminal step's synchronous side effect, and
-   * (c) always settles within the bounded budget — it never hangs.
-   */
-  describe('long-chain overall-deadline semantics', () => {
-    /**
-     * Mirror of the overall-deadline value a consumer arms (e.g. `@oxy.so/services`
-     * cold boot — the only consumer that arms the deadline). Kept as a local
-     * literal because core does not — and must not — import a consumer package;
-     * if the consumer's value changes, update this to match.
-     */
-    const OVERALL_DEADLINE = 20000;
-
-    beforeEach(() => {
-      jest.useFakeTimers();
-    });
-    afterEach(() => {
-      jest.runOnlyPendingTimers();
-      jest.useRealTimers();
-    });
-
-    /** A step whose `run()` never settles — models a hung async call. */
-    const neverSettlingStep = (): ColdBootStep<TestSession> => ({
-      id: 'never-settles',
-      run: () => new Promise<ColdBootStepResult<TestSession>>(() => {}),
-    });
-
-    it('abandons the hung step at the deadline and fires the terminal step', async () => {
-      const terminalRan = jest.fn();
-      const onStepDeadline = jest.fn();
-
-      const outcomePromise = runColdBoot<TestSession>({
-        overallDeadlineMs: OVERALL_DEADLINE,
-        onStepDeadline,
-        steps: [
-          neverSettlingStep(),
-          // Every intermediate step has nothing to contribute on this load.
-          skipStep('intermediate-1'),
-          skipStep('intermediate-2'),
-          skipStep('intermediate-3'),
-          {
-            id: 'terminal',
-            // Runs a synchronous side effect before its first await.
-            run: async (): Promise<ColdBootStepResult<TestSession>> => {
-              terminalRan();
-              return { kind: 'skip' };
-            },
-          },
-        ],
-      });
-
-      // Nothing settles before the deadline — the chain is stuck on the first step.
-      await jest.advanceTimersByTimeAsync(OVERALL_DEADLINE - 1);
-      expect(terminalRan).not.toHaveBeenCalled();
-
-      // At the deadline the hung step is abandoned and the chain proceeds.
-      await jest.advanceTimersByTimeAsync(1);
-      const outcome = await outcomePromise;
-
-      expect(onStepDeadline).toHaveBeenCalledWith('never-settles');
-      expect(terminalRan).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: OVERALL_DEADLINE,
-        steps: [neverSettlingStep(), 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(OVERALL_DEADLINE - 1);
-      expect(settled).toBe(false);
-
-      await jest.advanceTimersByTimeAsync(1);
-      await outcomePromise;
-      expect(settled).toBe(true);
-    });
-
-    it('does not penalize a fast first-step success — it wins well before the deadline', async () => {
-      const laterRan = jest.fn();
-      const outcomePromise = runColdBoot<TestSession>({
-        overallDeadlineMs: OVERALL_DEADLINE,
-        steps: [
-          {
-            id: 'first',
-            run: async (): Promise<ColdBootStepResult<TestSession>> => {
-              await Promise.resolve();
-              return { kind: 'session', session: { userId: 'u-fast' } };
-            },
-          },
-          sessionStep('terminal', 'u-should-not-run', laterRan),
-        ],
-      });
-
-      await jest.advanceTimersByTimeAsync(0);
-      const outcome = await outcomePromise;
-
-      expect(outcome).toEqual({
-        kind: 'session',
-        via: 'first',
-        session: { userId: 'u-fast' },
-      });
-      expect(laterRan).not.toHaveBeenCalled();
-    });
-  });
-});

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

@@ -1,60 +0,0 @@
-import {
-  getCommonsApprovalBlockingReason,
-  parseCommonsApprovalExpiresAt,
-} from '../commonsApproval';
-
-describe('commonsApproval validation', () => {
-  const application = {
-    id: 'app1',
-    name: 'Mention',
-    type: 'first_party' as const,
-    isOfficial: true,
-    isInternal: false,
-    scopes: ['profile'],
-  };
-
-  it('blocks when the application is missing', () => {
-    expect(
-      getCommonsApprovalBlockingReason({
-        application: null,
-        status: 'pending',
-        expiresAt: Date.now() + 60_000,
-      }),
-    ).toMatch(/could not be resolved/i);
-  });
-
-  it('blocks non-pending sessions', () => {
-    expect(
-      getCommonsApprovalBlockingReason({
-        application,
-        status: 'expired',
-        expiresAt: Date.now() + 60_000,
-      }),
-    ).toMatch(/invalid, already used, or expired/i);
-  });
-
-  it('blocks expired pending sessions (ISO expiresAt)', () => {
-    expect(
-      getCommonsApprovalBlockingReason({
-        application,
-        status: 'pending',
-        expiresAt: new Date(Date.now() - 60_000).toISOString(),
-      }),
-    ).toMatch(/expired/i);
-  });
-
-  it('allows a pending, unexpired session', () => {
-    expect(
-      getCommonsApprovalBlockingReason({
-        application,
-        status: 'pending',
-        expiresAt: Date.now() + 60_000,
-      }),
-    ).toBeNull();
-  });
-
-  it('parses ISO expiresAt strings', () => {
-    const iso = '2026-07-19T12:00:00.000Z';
-    expect(parseCommonsApprovalExpiresAt(iso)).toBe(Date.parse(iso));
-  });
-});

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

@@ -1,151 +0,0 @@
-/**
- * The identity cache-key enumeration, checked against the keys REAL reads
- * produce.
- *
- * A list-equality assertion on `OXY_IDENTITY_CACHE_PREFIXES` alone would be
- * satisfied forever by a typo (`GET:/profile/username/`) — it pins the list's
- * shape, not its correctness. So the load-bearing test here drives each prefix
- * from the SDK method that actually reads under it, over the real
- * `HttpService` cache, and asserts the sweep evicts every one. A prefix that
- * stops matching its read fails here rather than in production.
- *
- * The list is shared by every profile writer (`updateProfile`,
- * `updatePrivacySettings`, `updateAccount`) and by the Node-only
- * `oxy:user:invalidate` subscriber in `@oxy.so/core/server`, precisely because
- * two hand-written copies of it had already drifted apart.
- */
-
-import { OxyServices } from '../../OxyServices';
-import {
-  OXY_IDENTITY_CACHE_PREFIXES,
-  evictOxyIdentityCache,
-  oxyUserByIdCacheKey,
-  type OxyIdentityCacheEvictor,
-} from '../identityCacheSweep';
-
-function makeJwt(payload: Record<string, unknown>): string {
-  const b64url = (obj: Record<string, unknown>): string =>
-    Buffer.from(JSON.stringify(obj)).toString('base64url');
-  return `${b64url({ alg: 'none', typ: 'JWT' })}.${b64url({
-    exp: Math.floor(Date.now() / 1000) + 3600,
-    ...payload,
-  })}.sig`;
-}
-
-function jsonResponse(data: unknown): Response {
-  return new Response(JSON.stringify({ data }), {
-    status: 200,
-    headers: { 'content-type': 'application/json' },
-  });
-}
-
-function makeRecordingEvictor() {
-  const entries: string[] = [];
-  const prefixes: string[] = [];
-  const evictor: OxyIdentityCacheEvictor = {
-    clearCacheEntry: (key) => {
-      entries.push(key);
-    },
-    clearCacheByPrefix: (prefix) => {
-      prefixes.push(prefix);
-      return 0;
-    },
-  };
-  return { evictor, entries, prefixes };
-}
-
-describe('evictOxyIdentityCache — the key list', () => {
-  it('sweeps every identity prefix and the exact by-id entry', () => {
-    const { evictor, entries, prefixes } = makeRecordingEvictor();
-    evictOxyIdentityCache(evictor, 'abc123');
-
-    expect(prefixes).toEqual([
-      'GET:/session/user/',
-      'GET:/users/me',
-      'GET:/auth/lookup/',
-      'GET:/profiles/username/',
-      'GET:/profiles/resolve',
-    ]);
-    expect(prefixes).toEqual([...OXY_IDENTITY_CACHE_PREFIXES]);
-    expect(entries).toEqual([oxyUserByIdCacheKey('abc123')]);
-  });
-
-  it('sweeps the prefixes but writes no by-id entry when the id is unknown', () => {
-    const { evictor, entries, prefixes } = makeRecordingEvictor();
-    evictOxyIdentityCache(evictor);
-
-    expect(prefixes).toEqual([...OXY_IDENTITY_CACHE_PREFIXES]);
-    expect(entries).toEqual([]);
-  });
-
-  it('treats an empty-string id as unknown rather than building `GET:/users/`', () => {
-    // `GET:/users/` would be a prefix-shaped key handed to an EXACT-match
-    // deleter, so it evicts nothing while looking like it evicted something.
-    const { evictor, entries } = makeRecordingEvictor();
-    evictOxyIdentityCache(evictor, '');
-    expect(entries).toEqual([]);
-  });
-});
-
-describe('evictOxyIdentityCache — every prefix matches a real read', () => {
-  let originalFetch: typeof globalThis.fetch;
-  let fetchMock: jest.Mock<Promise<Response>, [RequestInfo | URL, RequestInit?]>;
-  let oxy: OxyServices;
-
-  const USER_ID = 'user-77';
-
-  beforeEach(() => {
-    originalFetch = globalThis.fetch;
-    fetchMock = jest.fn();
-    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
-    oxy = new OxyServices({
-      baseURL: 'http://test.invalid',
-      enableRetry: false,
-      requestTimeout: 1000,
-    });
-    oxy.httpService.setTokens(makeJwt({ userId: USER_ID }));
-  });
-
-  afterEach(() => {
-    globalThis.fetch = originalFetch;
-    jest.clearAllMocks();
-  });
-
-  /** One real read per swept key, each warmed into the real response cache. */
-  const reads: ReadonlyArray<{
-    key: string;
-    warm: (client: OxyServices) => Promise<unknown>;
-  }> = [
-    { key: 'GET:/session/user/', warm: (c) => c.getUserBySession('sess-1') },
-    { key: 'GET:/users/me', warm: (c) => c.getCurrentUser() },
-    { key: 'GET:/auth/lookup/', warm: (c) => c.lookupUsername('alice') },
-    { key: 'GET:/profiles/username/', warm: (c) => c.getProfileByUsername('alice') },
-    { key: 'GET:/profiles/resolve', warm: (c) => c.resolveProfile('@alice@test.invalid') },
-    { key: 'GET:/users/<id>', warm: (c) => c.getUserById(USER_ID) },
-  ];
-
-  it('covers every prefix in the list with a read (no prefix goes unexercised)', () => {
-    // Vacuity floor: adding a prefix to the list without adding the read that
-    // exercises it fails HERE, rather than silently shrinking the test below.
-    expect(reads).toHaveLength(OXY_IDENTITY_CACHE_PREFIXES.length + 1);
-    for (const prefix of OXY_IDENTITY_CACHE_PREFIXES) {
-      expect(reads.some((read) => read.key === prefix)).toBe(true);
-    }
-  });
-
-  it.each(reads)('evicts the entry warmed by $key', async ({ warm }) => {
-    fetchMock.mockResolvedValueOnce(jsonResponse({ id: USER_ID, username: 'alice' }));
-    await warm(oxy);
-    expect(fetchMock).toHaveBeenCalledTimes(1);
-
-    // Control: the entry really is warm (a miss would call the un-queued mock).
-    await warm(oxy);
-    expect(fetchMock).toHaveBeenCalledTimes(1);
-
-    evictOxyIdentityCache(oxy, USER_ID);
-
-    fetchMock.mockResolvedValueOnce(jsonResponse({ id: USER_ID, username: 'alice-2' }));
-    await warm(oxy);
-    expect(fetchMock).toHaveBeenCalledTimes(2);
-  });
-});