@antasphere/chassis-server 1.0.0

package/test/unit/hub-subject.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it, vi } from 'vitest';
+import { hubSubjectCache } from '../../src/entitlements/hub-subject.js';
+
+/**
+ * The hub-subject cache (PRDCT-2654): a per-user TTL cache over the SSO link
+ * lookup, a miss cached too, and bounded on a long-lived replica by a sweep
+ * of the expired entries once it holds more than `sweepAbove` users.
+ */
+
+function setup(opts: { ttlMs?: number; sweepAbove?: number } = {}) {
+  let clock = 1_000_000;
+  const subs = new Map<string, string>([
+    ['u1', 'sub-1'],
+    ['u2', 'sub-2']
+  ]);
+  const lookup = vi.fn(async (userId: string) => subs.get(userId) ?? null);
+  const cache = hubSubjectCache(lookup, { ttlMs: 1_000, ...opts, now: () => clock });
+  return {
+    cache,
+    lookup,
+    subs,
+    advance: (ms: number) => {
+      clock += ms;
+    }
+  };
+}
+
+describe('hubSubjectCache', () => {
+  it('serves a hit within the TTL without calling the lookup', async () => {
+    const { cache, lookup, advance } = setup();
+    expect(await cache.resolve('u1')).toBe('sub-1');
+    advance(999);
+    expect(await cache.resolve('u1')).toBe('sub-1');
+    expect(lookup).toHaveBeenCalledTimes(1);
+  });
+
+  it('caches a miss too', async () => {
+    const { cache, lookup } = setup();
+    expect(await cache.resolve('local-operator')).toBeNull();
+    expect(await cache.resolve('local-operator')).toBeNull();
+    expect(lookup).toHaveBeenCalledTimes(1);
+    expect(cache.size).toBe(1);
+  });
+
+  it('overwrites an expired entry on the next read', async () => {
+    const { cache, lookup, subs, advance } = setup();
+    expect(await cache.resolve('u1')).toBe('sub-1');
+    subs.set('u1', 'sub-1-relinked');
+    advance(1_000);
+    expect(await cache.resolve('u1')).toBe('sub-1-relinked');
+    expect(lookup).toHaveBeenCalledTimes(2);
+    expect(cache.size).toBe(1);
+  });
+
+  it('sweeps the expired entries once it holds more than sweepAbove users, keeping the live ones', async () => {
+    const { cache, advance } = setup({ sweepAbove: 3 });
+    for (const u of ['a', 'b', 'c']) await cache.resolve(u);
+    advance(600);
+    await cache.resolve('live'); // written at +600, lives until +1600
+    expect(cache.size).toBe(4);
+    advance(500); // a, b, c expired (until +1000); 'live' has 500 ms left
+    await cache.resolve('d');
+    expect(cache.size).toBe(2);
+    advance(1);
+    const before = cache.size;
+    await cache.resolve('live');
+    expect(cache.size).toBe(before);
+  });
+
+  it('does not sweep at or below the threshold, even with expired entries to drop; one entry above, it does', async () => {
+    const { cache, advance } = setup({ sweepAbove: 3, ttlMs: 1_000 });
+    for (const u of ['a', 'b']) await cache.resolve(u);
+    advance(2_000); // a and b are expired now
+    await cache.resolve('c'); // size 2 → not above 3: no sweep, the expired stay
+    expect(cache.size).toBe(3);
+    await cache.resolve('d'); // size 3 → still not above 3: no sweep (the boundary, verifier round 1)
+    expect(cache.size).toBe(4);
+    await cache.resolve('e'); // size 4 → above 3: a and b swept, c, d live
+    expect(cache.size).toBe(3);
+    cache.clear();
+    expect(cache.size).toBe(0);
+  });
+});

package/test/unit/idempotency-crypto.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest';
+import { open, seal } from '@antasphere/chassis-server/middleware';
+
+/**
+ * The replay cache stores response bodies AES-256-GCM encrypted because they
+ * carry one-shot secrets. seal/open must round-trip, and open must fail
+ * CLOSED (null, never throw or return garbage) on tamper or a wrong key —
+ * that null is what turns an AUTH_SECRET rotation into a clean re-execute.
+ */
+
+const SECRET = 'unit-test-secret-0123456789abcdef0123456789abcdef';
+const BODY = JSON.stringify({ apiKey: { id: 'x' }, key: 'key_abcd1234_supersecret' });
+
+describe('idempotency seal/open (AES-256-GCM)', () => {
+  it('round-trips a response body', () => {
+    const sealed = seal(BODY, SECRET);
+    expect(open(sealed, SECRET)).toBe(BODY);
+  });
+
+  it('produces the iv.ciphertext.tag shape without leaking the plaintext', () => {
+    const sealed = seal(BODY, SECRET);
+    expect(sealed.split('.')).toHaveLength(3);
+    expect(sealed).not.toContain('supersecret');
+    // Fresh iv per seal: the same plaintext never encrypts to the same blob.
+    expect(seal(BODY, SECRET)).not.toBe(sealed);
+  });
+
+  it('returns null on tampered ciphertext', () => {
+    const sealed = seal(BODY, SECRET);
+    const [iv, ciphertext, tag] = sealed.split('.') as [string, string, string];
+    const flipped = ciphertext.startsWith('A') ? `B${ciphertext.slice(1)}` : `A${ciphertext.slice(1)}`;
+    expect(open(`${iv}.${flipped}.${tag}`, SECRET)).toBeNull();
+  });
+
+  it('returns null under a different key (rotated AUTH_SECRET)', () => {
+    const sealed = seal(BODY, SECRET);
+    expect(open(sealed, 'another-secret-entirely-9876543210')).toBeNull();
+  });
+
+  it('returns null on malformed input', () => {
+    expect(open('not-a-sealed-payload', SECRET)).toBeNull();
+    expect(open('a.b', SECRET)).toBeNull();
+    expect(open('', SECRET)).toBeNull();
+  });
+});

package/test/unit/json-depth.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest';
+import { Hono } from 'hono';
+import { exceedsJsonDepth, jsonDepthLimit, MAX_JSON_DEPTH } from '@antasphere/chassis-server/middleware';
+
+const nest = (depth: number) => '['.repeat(depth) + '1' + ']'.repeat(depth);
+
+describe('exceedsJsonDepth', () => {
+  it('measures nesting', () => {
+    expect(exceedsJsonDepth(nest(10), 100)).toBe(false);
+    expect(exceedsJsonDepth(nest(101), 100)).toBe(true);
+    expect(exceedsJsonDepth(nest(100), 100)).toBe(false);
+  });
+
+  it('counts objects and arrays together', () => {
+    expect(exceedsJsonDepth('{"a":{"b":{"c":[1]}}}', 3)).toBe(true);
+    expect(exceedsJsonDepth('{"a":{"b":{"c":[1]}}}', 4)).toBe(false);
+  });
+
+  it('ignores brackets inside string literals, escapes included', () => {
+    const payload = `{"a":"${'['.repeat(500)}"}`;
+    expect(exceedsJsonDepth(payload, 5)).toBe(false);
+    expect(exceedsJsonDepth('{"a":"\\"[[[[[[[[[[","b":1}', 5)).toBe(false);
+  });
+
+  it('does not fire on flat, wide payloads', () => {
+    expect(exceedsJsonDepth(JSON.stringify(Array.from({ length: 5000 }, (_, i) => i)), 100)).toBe(false);
+  });
+});
+
+describe('jsonDepthLimit middleware', () => {
+  function app() {
+    const a = new Hono();
+    a.use('*', jsonDepthLimit());
+    a.post('/echo', async (c) => c.json({ ok: true, body: await c.req.json() }));
+    a.post('/raw', async (c) => c.text(await c.req.text()));
+    return a;
+  }
+
+  it('rejects an over-deep JSON body with a 400 before the handler', async () => {
+    const res = await app().request('/echo', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: nest(MAX_JSON_DEPTH + 1)
+    });
+    expect(res.status).toBe(400);
+    expect(await res.json()).toMatchObject({ error: { code: 'payload_too_deep' } });
+  });
+
+  it('rejects the depth that breaks JSON.stringify inside the shipped image', async () => {
+    // node:22-alpine throws RangeError from JSON.stringify past ~5000 levels;
+    // a newer host Node does not, which is exactly why the guard is at the
+    // edge and not a try/catch around some stringify call.
+    const res = await app().request('/echo', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: nest(6000)
+    });
+    expect(res.status).toBe(400);
+  });
+
+  it('passes ordinary bodies through untouched', async () => {
+    const res = await app().request('/echo', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ name: 'acme', nested: { a: { b: [1, 2, 3] } } })
+    });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toMatchObject({ ok: true, body: { name: 'acme' } });
+  });
+
+  it('ignores non-JSON bodies (streamed uploads, form-encoded token calls)', async () => {
+    const res = await app().request('/raw', {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      body: nest(6000)
+    });
+    expect(res.status).toBe(200);
+  });
+
+  it('ignores bodyless requests', async () => {
+    const res = await app().request('/echo', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' }
+    });
+    // No body: the handler's own parse decides, the guard does not interfere.
+    expect(res.status).not.toBe(400);
+  });
+});

package/test/unit/logger-redaction.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'vitest';
+import { pino } from 'pino';
+import { REDACT_PATHS } from '@antasphere/chassis-server/logger';
+
+/**
+ * The redaction list is the last line between a config payload and the log
+ * stream. Two gaps this pins shut:
+ *  - `*.secret` is an EXACT key match, so `clientSecret` sailed straight
+ *    through it (PLT-33);
+ *  - GOOGLE_CLIENT_SECRET and, on this repo, HUB_CLIENT_SECRET (this tool's
+ *    own identity at the Antasphere hub) are read in env.ts but were absent
+ *    from the list, so any "parsed env" line carried them.
+ */
+type Log = ReturnType<typeof pino>;
+
+function capture(fn: (log: Log) => void): string {
+  const chunks: string[] = [];
+  const log: Log = pino(
+    { redact: { paths: REDACT_PATHS, censor: '[redacted]' } },
+    { write: (chunk: string) => chunks.push(chunk) }
+  ) as Log;
+  fn(log);
+  return chunks.join('');
+}
+
+describe('log redaction', () => {
+  it('redacts the env-level credentials', () => {
+    const out = capture((log) =>
+      log.info({
+        DATABASE_URL: 'postgres://u:p@h/db',
+        AUTH_SECRET: 'auth-secret-value',
+        GOOGLE_CLIENT_SECRET: 'google-secret-value',
+        HUB_CLIENT_SECRET: 'hub-client-secret-value'
+      })
+    );
+    expect(out).not.toContain('google-secret-value');
+    expect(out).not.toContain('hub-client-secret-value');
+    expect(out).not.toContain('auth-secret-value');
+    expect(out).not.toContain('postgres://u:p@h/db');
+  });
+
+  it('redacts camelCase and snake_case secret keys the `*.secret` glob misses', () => {
+    const out = capture((log) =>
+      log.info({
+        client: {
+          clientId: 'visible-id',
+          clientSecret: 'camel-secret-value',
+          client_secret: 'snake-secret-value',
+          accessToken: 'access-token-value',
+          refresh_token: 'refresh-token-value',
+          apiKey: 'api-key-value'
+        }
+      })
+    );
+    expect(out).toContain('visible-id');
+    for (const leaked of [
+      'camel-secret-value',
+      'snake-secret-value',
+      'access-token-value',
+      'refresh-token-value',
+      'api-key-value'
+    ]) {
+      expect(out).not.toContain(leaked);
+    }
+  });
+});

package/test/unit/mcp-errors.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, it } from 'vitest';
+import { ApiToolError, jsonText, wrapToolErrors } from '@antasphere/chassis-server/mcp';
+import { isPublicOauthPath } from '@antasphere/chassis-server/middleware';
+
+describe('mcp error → hint mapping', () => {
+  it('attaches an actionable hint for known API codes', () => {
+    const err = new ApiToolError(403, 'insufficient_scope', 'This credential was not granted "things:write"');
+    const text = err.toUserFacingText();
+    expect(text).toContain('HTTP 403');
+    expect(text).toContain('insufficient_scope');
+    expect(text).toContain('consent screen');
+  });
+
+  it('a 402 entitlement_denied carries the top-up hint, the price, the balance and the link, as text', () => {
+    const err = new ApiToolError(402, 'entitlement_denied', 'Not enough credits', {
+      credits: 1500,
+      balance: 20,
+      topUpUrl: 'https://account.antasphere.com/orgs/acme/billing'
+    });
+    const text = err.toUserFacingText();
+    expect(text).toContain('HTTP 402');
+    expect(text).toContain('lacks the credits');
+    expect(text).toContain(
+      'Top up: https://account.antasphere.com/orgs/acme/billing (this needs 1500 credits, the organization holds 20).'
+    );
+  });
+
+  it('the gate’s own 402 message already carries the link: no second top-up sentence (verifier round 1)', () => {
+    const url = 'https://account.antasphere.com/orgs/acme/billing';
+    const err = new ApiToolError(
+      402,
+      'entitlement_denied',
+      `This needs 1500 credits and the organization holds 20; top up at ${url}`,
+      { credits: 1500, balance: 20, topUpUrl: url }
+    );
+    const text = err.toUserFacingText();
+    expect(text).not.toContain('Top up:');
+    expect(text.split(url).length - 1).toBe(1);
+  });
+
+  it('a 413 entitlement_denied without details (the self-hosted cap) has no top-up sentence', () => {
+    const err = new ApiToolError(413, 'entitlement_denied', 'File exceeds the 100 MB limit');
+    const text = err.toUserFacingText();
+    expect(text).toContain('HTTP 413');
+    expect(text).toContain('File exceeds the 100 MB limit');
+    expect(text).not.toContain('Top up:');
+    expect(text).not.toContain('undefined');
+  });
+
+  it('a 413 entitlement_denied with the price and the balance but no link (an unpriceable quantity, PRDCT-2677) has no top-up sentence and its hint says so', () => {
+    const err = new ApiToolError(
+      413,
+      'entitlement_denied',
+      'This quantity cannot be priced (9007199254740991 credits or more, the organization holds 3); nothing was charged',
+      { credits: 9007199254740991, balance: 3 }
+    );
+    const text = err.toUserFacingText();
+    expect(text).toContain('HTTP 413');
+    expect(text).not.toContain('Top up:');
+    expect(text).toContain('beyond what can be priced');
+    expect(text).not.toContain('undefined');
+  });
+
+  it('degrades gracefully for unknown codes', () => {
+    const err = new ApiToolError(422, 'weird_domain_thing', 'nope');
+    const text = err.toUserFacingText();
+    expect(text).toContain('weird_domain_thing');
+    expect(text).not.toContain('undefined');
+  });
+
+  it('wrapToolErrors turns ApiToolError into an isError tool result', async () => {
+    const result = await wrapToolErrors(async () => {
+      throw new ApiToolError(401, 'invalid_token', 'expired');
+    });
+    expect(result.isError).toBe(true);
+    expect(result.content[0]?.text).toContain('invalid_token');
+  });
+
+  it('wrapToolErrors passes successes through untouched', async () => {
+    const result = await wrapToolErrors(async () => jsonText({ ok: true }));
+    expect(result.isError).toBeUndefined();
+    expect(JSON.parse(result.content[0]?.text ?? '')).toEqual({ ok: true });
+  });
+
+  it('wrapToolErrors lets non-API errors propagate to the SDK', async () => {
+    await expect(
+      wrapToolErrors(async () => {
+        throw new Error('bug');
+      })
+    ).rejects.toThrow('bug');
+  });
+});
+
+describe('public OAuth path matcher', () => {
+  it('covers exactly the cookie-less endpoints', () => {
+    expect(isPublicOauthPath('/api/v1/auth/oauth2/token')).toBe(true);
+    expect(isPublicOauthPath('/api/v1/auth/oauth2/register')).toBe(true);
+    expect(isPublicOauthPath('/api/v1/auth/oauth2/introspect')).toBe(true);
+    expect(isPublicOauthPath('/api/v1/auth/oauth2/revoke')).toBe(true);
+    expect(isPublicOauthPath('/api/v1/auth/jwks')).toBe(true);
+    expect(isPublicOauthPath('/api/v1/auth/.well-known/openid-configuration')).toBe(true);
+  });
+
+  it('never exempts cookie-bearing endpoints', () => {
+    expect(isPublicOauthPath('/api/v1/auth/oauth2/authorize')).toBe(false);
+    expect(isPublicOauthPath('/api/v1/auth/oauth2/consent')).toBe(false);
+    expect(isPublicOauthPath('/api/v1/auth/sign-in/email')).toBe(false);
+    expect(isPublicOauthPath('/api/v1/auth/get-session')).toBe(false);
+  });
+});

package/test/unit/mcp-inputs.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it } from 'vitest';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { z } from 'zod';
+import { buildMcpServer, mcpInputs, type McpToolContext } from '@antasphere/chassis-server/mcp';
+
+/**
+ * The shared MCP inputs (`mcpInputs`) are the ones the chassis's own three
+ * tools are declared with: a tool that builds its set from the same factory
+ * shows the same `workspace`, `cursor` and `limit` in `tools/list`.
+ */
+
+const identity = { serverName: 'things', toolPrefix: 'things_' };
+
+async function listedTools() {
+  const server = buildMcpServer(
+    {} as McpToolContext, // read at call time only; nothing is called here
+    { version: '0.0.0-test', instanceName: 'Inputs' },
+    {
+      registerTools: () => {},
+      instructions: () => 'test',
+      errorHints: {},
+      scopes: { read: 'things:read', write: 'things:write' }
+    },
+    identity
+  );
+  const [clientSide, serverSide] = InMemoryTransport.createLinkedPair();
+  const client = new Client({ name: 'inputs-test', version: '0.0.0' });
+  await Promise.all([server.connect(serverSide), client.connect(clientSide)]);
+  const { tools } = await client.listTools();
+  await client.close();
+  return tools;
+}
+
+/** The JSON schema a zod input is listed as, the way the MCP SDK lists it. */
+const listed = (input: z.ZodType) => {
+  const schema = z.toJSONSchema(z.object({ v: input }), { io: 'input' }) as unknown as {
+    properties: { v: Record<string, unknown> };
+  };
+  return schema.properties.v;
+};
+
+describe('mcpInputs, the shared MCP inputs', () => {
+  const inputs = mcpInputs(identity);
+
+  it('names `<toolPrefix>whoami` in the workspace input, and nothing of a tool elsewhere', () => {
+    expect(inputs.workspaceInput.description).toBe(
+      'Target organization (workspace id). Omit to use your default org — see things_whoami.'
+    );
+    expect(inputs.cursorInput.description).toBe('nextCursor from a previous page.');
+    expect(inputs.limitInput.description).toBe('Page size (server max 100). Default 50.');
+    expect(mcpInputs({ toolPrefix: 'other_' }).workspaceInput.description).toContain('see other_whoami.');
+  });
+
+  it('are the inputs every chassis tool is listed with, projects included', async () => {
+    const tools = await listedTools();
+    // The order `tools/list` keeps: the two examples, whoami, then the eleven
+    // project tools and the two team reads the chassis registers before a tool's own set.
+    expect(tools.map((t) => t.name)).toEqual([
+      'get_me',
+      'list_files',
+      'things_whoami',
+      'things_list_projects',
+      'things_get_project',
+      'things_list_project_members',
+      'things_create_project',
+      'things_update_project',
+      'things_archive_project',
+      'things_add_project_member',
+      'things_set_project_member_role',
+      'things_remove_project_member',
+      'things_set_project_team_role',
+      'things_remove_project_team',
+      'things_list_teams',
+      'things_list_team_members'
+    ]);
+    const props = (name: string) =>
+      tools.find((t) => t.name === name)!.inputSchema.properties as Record<string, Record<string, unknown>>;
+
+    for (const name of tools.map((t) => t.name)) {
+      expect(props(name).workspace).toEqual(listed(inputs.workspaceInput));
+      expect(props(name).workspace!.description).toBe(inputs.workspaceInput.description);
+    }
+    expect(props('list_files').cursor).toEqual(listed(inputs.cursorInput));
+    expect(props('list_files').limit).toEqual(listed(inputs.limitInput));
+    expect(props('list_files').cursor!.description).toBe(inputs.cursorInput.description);
+    expect(props('list_files').limit!.description).toBe(inputs.limitInput.description);
+    expect(Object.keys(props('list_files')).sort()).toEqual(['cursor', 'limit', 'workspace']);
+
+    // The paginated project lists take the same two, from the same factory.
+    for (const name of ['things_list_projects', 'things_list_project_members']) {
+      expect(props(name).cursor).toEqual(listed(inputs.cursorInput));
+      expect(props(name).limit).toEqual(listed(inputs.limitInput));
+    }
+  });
+
+  it('validate as the API expects: a uuid, a string, an integer from 1 to 100, all optional', () => {
+    expect(inputs.workspaceInput.safeParse(undefined).success).toBe(true);
+    expect(inputs.workspaceInput.safeParse('not-a-uuid').success).toBe(false);
+    expect(inputs.limitInput.safeParse(100).success).toBe(true);
+    expect(inputs.limitInput.safeParse(101).success).toBe(false);
+    expect(inputs.limitInput.safeParse(0).success).toBe(false);
+    expect(inputs.limitInput.safeParse(1.5).success).toBe(false);
+    expect(inputs.cursorInput.safeParse(undefined).success).toBe(true);
+  });
+});

package/test/unit/mcp-project-hints.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { projectErrorHints } from '@antasphere/chassis-server/mcp';
+
+/**
+ * The project hints are composed per tool: a hint that names a tool names it
+ * as it is registered, under the tool's prefix, or a model follows it to a
+ * tool that does not exist.
+ */
+describe('projectErrorHints', () => {
+  it('names the member tools under the prefix given, never bare', () => {
+    const hints = projectErrorHints('acme_');
+    for (const name of [
+      'add_project_member',
+      'set_project_member_role',
+      'remove_project_member',
+      'list_project_members'
+    ]) {
+      expect(hints.member_not_found).toContain(`acme_${name}`);
+      expect(hints.member_not_found).not.toMatch(new RegExp(`(^|[^_a-z])${name}`));
+    }
+  });
+
+  it('words guest_forbidden, the answer of every project route to a guest', () => {
+    expect(projectErrorHints('x_').guest_forbidden).toContain('guests take no part in projects');
+  });
+});

package/test/unit/no-store.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+import { Hono } from 'hono';
+import type { Principal } from '@antasphere/chassis-contract';
+import { noStoreAuthenticated } from '@antasphere/chassis-server/middleware';
+
+/**
+ * DASH-5: authenticated JSON went out with no Cache-Control at all, leaving
+ * the decision to heuristic caching in whatever proxy or bfcache sits in the
+ * path — one member's roster served to the next.
+ */
+const principal = { userId: 'u1', via: 'session' } as unknown as Principal;
+
+function app(withPrincipal: boolean) {
+  const a = new Hono();
+  a.use('*', noStoreAuthenticated());
+  a.use('*', async (c, next) => {
+    c.set('principal', withPrincipal ? principal : null);
+    return next();
+  });
+  a.get('/me', (c) => c.json({ user: 'u1' }));
+  a.get('/instance', (c) => {
+    c.header('Cache-Control', 'public, max-age=60');
+    return c.json({ name: 'demo' });
+  });
+  a.get('/files/1/content', (c) => c.body('bytes', 200, { 'content-type': 'application/octet-stream' }));
+  return a;
+}
+
+describe('noStoreAuthenticated', () => {
+  it('marks authenticated JSON no-store', async () => {
+    const res = await app(true).request('/me');
+    expect(res.headers.get('cache-control')).toBe('no-store');
+  });
+
+  it('leaves anonymous responses cacheable', async () => {
+    const res = await app(false).request('/me');
+    expect(res.headers.get('cache-control')).toBeNull();
+  });
+
+  it('never clobbers a Cache-Control the route chose', async () => {
+    const res = await app(true).request('/instance');
+    expect(res.headers.get('cache-control')).toBe('public, max-age=60');
+  });
+
+  it('leaves streamed byte responses alone (Range/ETag surfaces own their headers)', async () => {
+    const res = await app(true).request('/files/1/content');
+    expect(res.headers.get('cache-control')).toBeNull();
+  });
+});

package/test/unit/no-tool-migration-filename.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest';
+import { readdirSync, readFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * No chassis test names a tool's migration FILE (PRDCT-2544). A tool made from
+ * the chassis has its own migration history, so a file name of another tool's
+ * history is an ENOENT waiting inside a package that tool never edits. The
+ * statements a chassis test needs are fixtures the chassis owns
+ * (`test/fixtures`). Reading the migration FOLDER by path stays allowed: any
+ * coherent folder satisfies it.
+ *
+ * The pattern is assembled from pieces so that this file does not match itself.
+ */
+const FOUR_DIGITS = '\\d{4}';
+const MIGRATION_FILENAME = new RegExp(`${FOUR_DIGITS}_[a-z_]+\\.${'sql'}`);
+
+const packagesDir = resolve(dirname(fileURLToPath(import.meta.url)), '../../..');
+
+function walk(dir: string): string[] {
+  return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    if (entry.name === 'node_modules') return [];
+    const path = join(dir, entry.name);
+    return entry.isDirectory() ? walk(path) : [path];
+  });
+}
+
+const testDirs = readdirSync(packagesDir, { withFileTypes: true })
+  .filter((entry) => entry.isDirectory() && entry.name.startsWith('chassis-'))
+  .map((entry) => join(packagesDir, entry.name, 'test'));
+
+describe('no chassis test names a migration file', () => {
+  it('the pattern catches a migration file name', () => {
+    expect(MIGRATION_FILENAME.test(['0001', 'some_backfill.sql'].join('_'))).toBe(true);
+    expect(MIGRATION_FILENAME.test('fixtures/onboarding-backfill.sql')).toBe(false);
+    expect(MIGRATION_FILENAME.test('../../../db/drizzle')).toBe(false);
+  });
+
+  it('it looks where the chassis tests are', () => {
+    const names = testDirs.map((dir) => relative(packagesDir, dir));
+    expect(names).toContain(join('chassis-server', 'test'));
+    expect(names.length).toBeGreaterThanOrEqual(4);
+  });
+
+  it('no file under packages/chassis-*/test contains one', () => {
+    const files = testDirs.flatMap((dir) => {
+      try {
+        return walk(dir);
+      } catch {
+        return []; // a chassis package without a test folder
+      }
+    });
+    expect(files.length).toBeGreaterThan(50);
+    // The walk reaches the fixtures and this guard itself: a walk that skips a
+    // folder would leave the count above the floor and the guard blind there.
+    const walked = files.map((file) => relative(packagesDir, file));
+    expect(walked).toEqual(
+      expect.arrayContaining([
+        join('chassis-server', 'test', 'fixtures', 'onboarding-backfill.sql'),
+        join('chassis-server', 'test', 'fixtures', 'operator-user-id-backfill.sql'),
+        join('chassis-server', 'test', 'unit', 'no-tool-migration-filename.test.ts')
+      ])
+    );
+    const offenders = files
+      .filter((file) => MIGRATION_FILENAME.test(readFileSync(file, 'utf8')))
+      .map((file) => relative(packagesDir, file));
+    expect(offenders).toEqual([]);
+  });
+});