@antasphere/chassis-server 1.0.0

package/test/unit/entitlement-profiles.test.ts

@@ -0,0 +1,289 @@
+import { describe, expect, it } from 'vitest';
+import type { ToolEntitlements } from '@antasphere/chassis-contract';
+import { EntitlementProfiles, HubMachineToken } from '@antasphere/chassis-server';
+import type { Logger } from '@antasphere/chassis-server/logger';
+
+/**
+ * The per-account plan cache of the cloud edition (the billing rail, §7):
+ * one hub read per account per TTL, the hub's overrides winning over the
+ * tool's tier values, the last known plan kept through an outage for the
+ * stale window and then `free`, a never-answered account `free` from the
+ * start, and a failure cached like an answer so a storm stays one read.
+ * The read is off the request path (PRDCT-2633): a stale entry is served at
+ * once while the refresh runs behind it, a cold account waits at most the
+ * cold budget. The hub's answer shape is the contract's copy (checked
+ * against the hub's wire snapshot, PRDCT-2677), a boolean limit included
+ * (PRDCT-2636), and since phase 2 the hub's upgrade page and its
+ * features list as the truth once it serves limit rows (PRDCT-2664).
+ */
+
+const logger = { error: () => {}, warn: () => {}, info: () => {}, debug: () => {} } as unknown as Logger;
+const ISSUER = 'https://hub.test';
+const TOOL: ToolEntitlements = {
+  actions: [],
+  limits: { 'files.maxBytes': { oss: 10, free: 100, pro: 500 }, seats: { oss: null, free: 3, pro: null } },
+  features: { sso: { free: false, pro: true }, basic: { free: true, pro: true } }
+};
+
+/** The hub's whole answer (the shape the contract mirrors verbatim), with the test's fields over it. */
+const answerOf = (over: Record<string, unknown>) =>
+  Response.json({
+    accountRef: '77777777-aaaa-4bbb-8ccc-000000000001',
+    plan: 'free',
+    planUntil: null,
+    limits: {},
+    features: [],
+    // Required on the wire since PRDCT-2677: every hub since 0.11.0 sends it.
+    upgradeUrl: `${ISSUER}/billing/upgrade?org=acct&tool=things&plan=free`,
+    ...over
+  });
+
+function profiles(
+  answer: () => Response | Promise<Response>,
+  clock: { now: number },
+  dials: { coldWaitMs?: number } = {}
+) {
+  let reads = 0;
+  const fetchImpl = (async (input: string | URL | Request) => {
+    const url = String(input);
+    if (url.endsWith('/api/v1/auth/oauth2/token')) {
+      return Response.json({ access_token: 'mach_1', expires_in: 3600 });
+    }
+    reads += 1;
+    return answer();
+  }) as typeof fetch;
+  const token = new HubMachineToken({
+    issuerUrl: ISSUER,
+    clientId: 'tool-things',
+    clientSecret: 's'.repeat(20),
+    resource: `${ISSUER}/mcp`,
+    logger,
+    fetchImpl,
+    now: () => clock.now
+  });
+  const p = new EntitlementProfiles({
+    issuerUrl: ISSUER,
+    token,
+    logger,
+    fetchImpl,
+    now: () => clock.now,
+    dials: { ttlMs: 30_000, staleMs: 15 * 60_000, ...dials }
+  });
+  return { p, reads: () => reads };
+}
+
+describe('EntitlementProfiles', () => {
+  it('reads once per account per TTL, single-flight, and resolves the tier values', async () => {
+    const clock = { now: 1_000_000 };
+    const { p, reads } = profiles(() => answerOf({ plan: 'pro' }), clock);
+    const [a, b] = await Promise.all([p.get('acct', TOOL), p.get('acct', TOOL)]);
+    expect(reads()).toBe(1);
+    expect(a).toEqual(b);
+    expect(a.plan).toBe('pro');
+    expect(a.source).toBe('hub');
+    expect(a.limits).toEqual({ 'files.maxBytes': 500, seats: null });
+    expect([...a.features].sort()).toEqual(['basic', 'sso']);
+    clock.now += 29_000;
+    await p.get('acct', TOOL);
+    expect(reads()).toBe(1);
+    clock.now += 2_000;
+    // Past the TTL: served at once from the last answer, the refresh behind it.
+    const served = await p.get('acct', TOOL);
+    expect(served.plan).toBe('pro');
+    expect(served.source).toBe('stale');
+    await p.settle();
+    expect(reads()).toBe(2);
+    expect((await p.get('acct', TOOL)).source).toBe('hub');
+  });
+
+  it('the hub’s overrides win over the tier’s values, features included', async () => {
+    const clock = { now: 1_000_000 };
+    const { p } = profiles(
+      () => answerOf({ plan: 'free', limits: { 'files.maxBytes': 250 }, features: ['sso'] }),
+      clock
+    );
+    const profile = await p.get('acct', TOOL);
+    expect(profile.plan).toBe('free');
+    expect(profile.limits).toEqual({ 'files.maxBytes': 250, seats: 3 });
+    expect([...profile.features]).toEqual(['sso']);
+  });
+
+  it('an account the hub never answered for is free, and the miss is cached for the TTL', async () => {
+    const clock = { now: 1_000_000 };
+    const { p, reads } = profiles(
+      () => Response.json({ error: { code: 'not_found' } }, { status: 404 }),
+      clock
+    );
+    const a = await p.get('acct', TOOL);
+    expect(a.plan).toBe('free');
+    expect(a.source).toBe('default');
+    expect(a.limits['files.maxBytes']).toBe(100);
+    await p.get('acct', TOOL);
+    expect(reads()).toBe(1);
+  });
+
+  it('keeps the last known plan through an outage for the stale window, then falls to free', async () => {
+    const clock = { now: 1_000_000 };
+    let mode: 'ok' | 'down' = 'ok';
+    const { p, reads } = profiles(
+      () => (mode === 'ok' ? answerOf({ plan: 'pro' }) : Response.json({ error: {} }, { status: 500 })),
+      clock
+    );
+    expect((await p.get('acct', TOOL)).plan).toBe('pro');
+    mode = 'down';
+    clock.now += 31_000;
+    const stale = await p.get('acct', TOOL);
+    expect(stale.plan).toBe('pro');
+    expect(stale.source).toBe('stale'); // served now, the refresh behind it
+    await p.settle();
+    expect(reads()).toBe(2);
+    expect((await p.get('acct', TOOL)).source).toBe('hub'); // re-cached from the last answer for another TTL
+    clock.now += 14 * 60_000; // 14.5 min after the answer: still inside the window
+    expect((await p.get('acct', TOOL)).plan).toBe('pro');
+    await p.settle();
+    clock.now += 61_000; // past 15 min
+    const fallen = await p.get('acct', TOOL);
+    expect(fallen.plan).toBe('free');
+    expect(fallen.source).toBe('default');
+    expect(fallen.limits['files.maxBytes']).toBe(100);
+    await p.settle(); // the miss the fallen read started, behind the request
+    mode = 'ok';
+    clock.now += 31_000;
+    await p.get('acct', TOOL);
+    await p.settle();
+    expect((await p.get('acct', TOOL)).plan).toBe('pro');
+  });
+
+  it('a slow hub costs a warm request nothing (PRDCT-2633): the stale plan is served at once, the refresh lands behind it', async () => {
+    const clock = { now: 1_000_000 };
+    let release: (() => void) | null = null;
+    let slow = false;
+    const { p, reads } = profiles(async () => {
+      if (slow) await new Promise<void>((r) => (release = r));
+      return answerOf({ plan: 'pro' });
+    }, clock);
+    expect((await p.get('acct', TOOL)).plan).toBe('pro');
+    slow = true;
+    clock.now += 31_000;
+    const started = Date.now();
+    const served = await p.get('acct', TOOL);
+    expect(Date.now() - started).toBeLessThan(200);
+    expect(served.plan).toBe('pro');
+    expect(served.source).toBe('stale');
+    expect(reads()).toBe(2); // the refresh is in flight, single-flight
+    await p.get('acct', TOOL);
+    expect(reads()).toBe(2);
+    release!();
+    await p.settle();
+    expect((await p.get('acct', TOOL)).source).toBe('hub');
+  });
+
+  it('a cold account waits for its first read up to the cold budget, then is served the default while the read finishes', async () => {
+    const clock = { now: 1_000_000 };
+    let release: (() => void) | null = null;
+    const { p, reads } = profiles(
+      async () => {
+        await new Promise<void>((r) => (release = r));
+        return answerOf({ plan: 'pro' });
+      },
+      clock,
+      { coldWaitMs: 50 }
+    );
+    const started = Date.now();
+    const cold = await p.get('acct', TOOL);
+    expect(Date.now() - started).toBeGreaterThanOrEqual(45);
+    expect(cold.plan).toBe('free');
+    expect(cold.source).toBe('default');
+    expect(reads()).toBe(1);
+    release!();
+    await p.settle();
+    const warm = await p.get('acct', TOOL);
+    expect(warm.plan).toBe('pro');
+    expect(warm.source).toBe('hub');
+    expect(reads()).toBe(1);
+  });
+
+  it('a cold read that answers within the budget is judged right on the first request', async () => {
+    const clock = { now: 1_000_000 };
+    const { p } = profiles(() => answerOf({ plan: 'pro' }), clock, { coldWaitMs: 1_000 });
+    expect((await p.get('acct', TOOL)).plan).toBe('pro');
+  });
+
+  it('every shape the hub’s contract allows parses, a boolean limit included (PRDCT-2636)', async () => {
+    const clock = { now: 1_000_000 };
+    const shapes: Array<[Record<string, unknown>, Record<string, number | null>]> = [
+      [
+        { plan: 'pro', planUntil: '2026-12-31T00:00:00.000Z', limits: {}, features: [] },
+        { 'files.maxBytes': 500, seats: null }
+      ],
+      [
+        { plan: 'free', limits: { 'files.maxBytes': true }, features: [] },
+        { 'files.maxBytes': null, seats: 3 }
+      ],
+      [
+        { plan: 'pro', limits: { seats: false, 'files.maxBytes': 42 }, features: ['sso'] },
+        { 'files.maxBytes': 42, seats: 0 }
+      ],
+      [
+        { plan: 'free', limits: { unknown: true }, features: ['sso', 'basic'] },
+        { 'files.maxBytes': 100, seats: 3 }
+      ]
+    ];
+    for (const [over, limits] of shapes) {
+      const { p } = profiles(() => answerOf(over), clock);
+      const profile = await p.get('acct', TOOL);
+      expect(profile.source, JSON.stringify(over)).toBe('hub');
+      expect(profile.plan).toBe(over.plan);
+      expect(profile.limits, JSON.stringify(over)).toEqual(limits);
+    }
+    // A shape the hub's contract does NOT allow reads as a miss: the mirror is verbatim.
+    for (const bad of [
+      { plan: 'pro', limits: { seats: 'many' } },
+      { plan: 'pro', limits: undefined },
+      { plan: 'pro', accountRef: 'not-a-uuid' }
+    ]) {
+      const { p } = profiles(() => answerOf(bad as Record<string, unknown>), clock);
+      expect((await p.get('acct', TOOL)).source, JSON.stringify(bad)).toBe('default');
+    }
+  });
+
+  it('carries the hub’s upgrade page through resolve, and none when the plan is the default (an answer without the page no longer parses, PRDCT-2677)', async () => {
+    const clock = { now: 1_000_000 };
+    const page = `${ISSUER}/billing/upgrade?org=acct&tool=things&plan=pro`;
+    const { p } = profiles(() => answerOf({ plan: 'pro', upgradeUrl: page }), clock);
+    expect((await p.get('acct', TOOL)).upgradeUrl).toBe(page);
+    const older = profiles(() => answerOf({ plan: 'pro', upgradeUrl: undefined }), clock);
+    const olderProfile = await older.p.get('acct', TOOL);
+    expect(olderProfile.upgradeUrl).toBeNull();
+    expect(olderProfile.source).toBe('default');
+    const missing = profiles(() => Response.json({ error: {} }, { status: 500 }), clock);
+    expect((await missing.p.get('acct', TOOL)).upgradeUrl).toBeNull();
+  });
+
+  it('a hub that answers limits is authoritative on features, an empty list included; one that answers none leaves the tier’s features', async () => {
+    const clock = { now: 1_000_000 };
+    // Phase 2: the hub serves its rows, and switches every feature off for this pro account.
+    const phase2 = profiles(() => answerOf({ plan: 'pro', limits: { seats: 10 }, features: [] }), clock);
+    const off = await phase2.p.get('acct', TOOL);
+    expect(off.plan).toBe('pro');
+    expect([...off.features]).toEqual([]);
+    // Phase 1 (no limit key): an empty list means "the declared tier values apply".
+    const phase1 = profiles(() => answerOf({ plan: 'pro', limits: {}, features: [] }), clock);
+    expect([...(await phase1.p.get('acct', TOOL)).features].sort()).toEqual(['basic', 'sso']);
+    // And a non-empty list still overrides there.
+    const listed = profiles(() => answerOf({ plan: 'pro', limits: {}, features: ['basic'] }), clock);
+    expect([...(await listed.p.get('acct', TOOL)).features]).toEqual(['basic']);
+  });
+
+  it('a malformed profile and an unreachable hub read as a miss', async () => {
+    const clock = { now: 1_000_000 };
+    let kind: 'malformed' | 'network' = 'malformed';
+    const { p } = profiles(() => {
+      if (kind === 'network') throw new TypeError('fetch failed');
+      return answerOf({ plan: 'platinum' });
+    }, clock);
+    expect((await p.get('a', TOOL)).plan).toBe('free');
+    kind = 'network';
+    expect((await p.get('b', TOOL)).plan).toBe('free');
+  });
+});

package/test/unit/erasure-log.test.ts

@@ -0,0 +1,72 @@
+import { createHash } from 'node:crypto';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { emailHash, ErasureLog } from '@antasphere/chassis-server/accounts';
+
+/**
+ * PRDCT-1811: the tombstone's email fingerprint is KEYED. `erasures.jsonl`
+ * rides in the unencrypted data tarball of every backup, and a plain
+ * sha256 of an address is a dictionary lookup away from the address — an
+ * off-site backup would list who asked to be forgotten. The key is the
+ * instance's auth secret, which travels only in the encrypted config
+ * archive.
+ *
+ * PRDCT-1809: a replay whose delete fails reports the tombstone as REFUSED
+ * instead of swallowing it — the boot turns that into a fail-closed verdict.
+ */
+const silent = { warn() {}, error() {}, info() {}, debug() {} } as unknown as ConstructorParameters<
+  typeof ErasureLog
+>[1];
+
+const KEY = 'unit-test-auth-secret-0123456789abcdef0123456789abcdef';
+
+describe('emailHash (PRDCT-1811)', () => {
+  it('is an HMAC under the key: 64 hex, key-dependent, and never the plain sha256 of the address', () => {
+    const fp = emailHash('Alice@Example.com', KEY);
+    expect(fp).toMatch(/^[0-9a-f]{64}$/);
+    expect(fp).not.toBe(createHash('sha256').update('alice@example.com').digest('hex'));
+    expect(emailHash('alice@example.com', 'another-key-0123456789abcdef0123456789abcdef')).not.toBe(fp);
+  });
+
+  it('normalizes the address (trim + lowercase) so the operator correlation survives casing', () => {
+    expect(emailHash('  ALICE@example.COM ', KEY)).toBe(emailHash('alice@example.com', KEY));
+  });
+});
+
+describe('ErasureLog', () => {
+  let dir: string;
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'erasure-log-'));
+  });
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('append writes the keyed fingerprint, never the address', async () => {
+    const log = new ErasureLog(dir, silent, KEY);
+    await log.append({ id: 'u1', email: 'Alice@Example.com' });
+    const raw = readFileSync(join(dir, 'erasures.jsonl'), 'utf8');
+    expect(raw).not.toContain('example.com');
+    const line = JSON.parse(raw.trim()) as { userId: string; emailHash: string };
+    expect(line.userId).toBe('u1');
+    expect(line.emailHash).toBe(emailHash('alice@example.com', KEY));
+  });
+
+  it('replay reports a tombstone whose delete throws as REFUSED, with its cause (PRDCT-1809)', async () => {
+    const log = new ErasureLog(dir, silent, KEY);
+    await log.append({ id: 'gone', email: 'gone@example.com' });
+    await log.append({ id: 'owner', email: 'owner@example.com' });
+    await log.append({ id: 'absent', email: 'absent@example.com' });
+    const boom = new Error('last owner');
+    const result = await log.replay(
+      async (id) => id !== 'absent',
+      async (id) => {
+        if (id === 'owner') throw boom;
+      }
+    );
+    expect(result.replayed).toEqual(['gone']);
+    expect(result.refused).toEqual([{ userId: 'owner', erasedAt: expect.any(String), cause: boom }]);
+  });
+});

package/test/unit/error-mapping.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from 'vitest';
+import { OpenAPIHono } from '@hono/zod-openapi';
+import { pino } from 'pino';
+import { createApp, postgresErrorCode } from '@antasphere/chassis-server';
+import { createRuntimeState } from '@antasphere/chassis-server/util';
+
+/**
+ * SL-B4 / SL-B5: a NUL byte reaching Postgres (SQLSTATE 22021) and a
+ * stringify-breaking payload (RangeError) both surfaced as anonymous 500s —
+ * and the 22021 path logged the failing statement together with its bound
+ * parameters. Both are client input; both must answer 4xx, quietly.
+ */
+class PgError extends Error {
+  constructor(
+    public code: string,
+    message: string
+  ) {
+    super(message);
+  }
+}
+
+async function appThrowing(error: unknown) {
+  const lines: string[] = [];
+  const logger = pino({ level: 'error' }, { write: (chunk: string) => lines.push(chunk) });
+  const api = new OpenAPIHono();
+  api.get('/boom', () => {
+    throw error;
+  });
+  const app = await createApp({
+    logger,
+    state: createRuntimeState(),
+    publicDir: '/nonexistent-public-dir',
+    displayName: 'Things',
+    api
+  });
+  return { app, lines };
+}
+
+describe('postgresErrorCode', () => {
+  it('reads the SQLSTATE off a driver error and nothing else', () => {
+    expect(postgresErrorCode(new PgError('22021', 'invalid byte sequence'))).toBe('22021');
+    expect(postgresErrorCode(new Error('plain'))).toBeUndefined();
+    expect(postgresErrorCode(null)).toBeUndefined();
+    expect(postgresErrorCode({ code: 42 })).toBeUndefined();
+  });
+});
+
+describe('app.onError client-input mappings', () => {
+  it('maps Postgres 22021 (NUL byte in text) to a quiet 400', async () => {
+    const { app, lines } = await appThrowing(
+      new PgError('22021', 'invalid byte sequence for encoding "UTF8": 0x00')
+    );
+    const res = await app.request('/api/v1/boom');
+    expect(res.status).toBe(400);
+    expect(await res.json()).toMatchObject({ error: { code: 'invalid_characters' } });
+    // The pg error object carries the statement AND its bound parameters.
+    expect(lines.join('')).toBe('');
+  });
+
+  it('maps 22P05 (untranslatable character) the same way', async () => {
+    const { app } = await appThrowing(new PgError('22P05', 'untranslatable character'));
+    expect((await app.request('/api/v1/boom')).status).toBe(400);
+  });
+
+  it('maps a stringify stack overflow to 400, not 500', async () => {
+    const { app } = await appThrowing(new RangeError('Maximum call stack size exceeded'));
+    const res = await app.request('/api/v1/boom');
+    expect(res.status).toBe(400);
+    expect(await res.json()).toMatchObject({ error: { code: 'payload_too_deep' } });
+  });
+
+  it('maps "Invalid string length" the same way', async () => {
+    const { app } = await appThrowing(new RangeError('Invalid string length'));
+    expect((await app.request('/api/v1/boom')).status).toBe(400);
+  });
+
+  it('keeps a genuine server fault a logged 500', async () => {
+    const { app, lines } = await appThrowing(new Error('database is on fire'));
+    const res = await app.request('/api/v1/boom');
+    expect(res.status).toBe(500);
+    expect(await res.json()).toMatchObject({ error: { code: 'internal' } });
+    expect(lines.join('')).toContain('unhandled error');
+  });
+
+  it('keeps an unrelated RangeError a 500 — narrow on the two known messages', async () => {
+    const { app } = await appThrowing(new RangeError('toFixed() digits argument must be between 0 and 100'));
+    expect((await app.request('/api/v1/boom')).status).toBe(500);
+  });
+});

package/test/unit/export-entries.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from 'vitest';
+import { RESERVED_EXPORT_ENTRY_NAMES, resolveExportEntries } from '@antasphere/chassis-server/api';
+
+/**
+ * The tool's export entries, resolved before the zip stream starts: a name is
+ * sanitized like every other entry name, the rows are the JSON the bundle
+ * carries, and a name that lands on another entry is an error.
+ */
+describe('resolveExportEntries (the `api.exportEntries` slot)', () => {
+  it('writes each entry as <name>.json, rows as indented JSON, in the order given', () => {
+    const resolved = resolveExportEntries([
+      { name: 'things', rows: [{ id: 't1' }] },
+      { name: 'gadgets', rows: [] }
+    ]);
+    expect(resolved.map((e) => e.entryName)).toEqual(['things.json', 'gadgets.json']);
+    expect(resolved[0]!.buffer.toString('utf8')).toBe(JSON.stringify([{ id: 't1' }], null, 2) + '\n');
+    expect(resolved[1]!.buffer.toString('utf8')).toBe('[]\n');
+  });
+
+  it('an empty list resolves to nothing', () => {
+    expect(resolveExportEntries([])).toEqual([]);
+  });
+
+  it('sanitizes a hostile name: no separator, no control character, bounded, never empty', () => {
+    const names = resolveExportEntries([
+      { name: '../../etc/cron.d/x', rows: [] },
+      { name: 'a\u0000b\u001fc\u007fd\\e', rows: [] },
+      { name: 'x'.repeat(500), rows: [] },
+      { name: '', rows: [] }
+    ]).map((e) => e.entryName);
+    expect(names).toEqual([
+      '.._.._etc_cron.d_x.json',
+      'a_b_c_d_e.json',
+      `${'x'.repeat(150)}.json`,
+      'file.json'
+    ]);
+  });
+
+  it('the reserved list is the chassis entries of the bundle', () => {
+    expect([...RESERVED_EXPORT_ENTRY_NAMES]).toEqual([
+      'manifest',
+      'workspace',
+      'members',
+      'invitations',
+      'api-keys',
+      'projects',
+      'project_members',
+      'teams',
+      'team_members',
+      'project_teams',
+      'audit-log',
+      'files',
+      'skipped-blobs'
+    ]);
+  });
+
+  it.each([...RESERVED_EXPORT_ENTRY_NAMES])('refuses the chassis entry name %s', (name) => {
+    expect(() => resolveExportEntries([{ name, rows: [] }])).toThrow(/already an entry of the bundle/);
+  });
+
+  it('refuses a collision that only differs by case, or that appears through sanitizing', () => {
+    expect(() => resolveExportEntries([{ name: 'Files', rows: [] }])).toThrow(/already an entry/);
+    expect(() =>
+      resolveExportEntries([
+        { name: 'a/b', rows: [] },
+        { name: 'a_b', rows: [] }
+      ])
+    ).toThrow(/"a_b" is already an entry/);
+  });
+
+  it('refuses the same tool name twice', () => {
+    expect(() =>
+      resolveExportEntries([
+        { name: 'things', rows: [] },
+        { name: 'things', rows: [] }
+      ])
+    ).toThrow(/"things" is already an entry/);
+  });
+
+  it('refuses a shape that is not { name, rows[] }, and rows that do not serialize', () => {
+    expect(() => resolveExportEntries([{ name: 'things', rows: 'nope' } as never])).toThrow(/every entry is/);
+    expect(() => resolveExportEntries({} as never)).toThrow(/must return an array/);
+    expect(() => resolveExportEntries([{ name: 'things', rows: [{ n: 1n }] }])).toThrow();
+  });
+});

package/test/unit/export-sanitize.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest';
+import { sanitizeEntryName } from '@antasphere/chassis-server/api';
+
+/**
+ * Zip-slip guard: export entry names embed the user-supplied originalName.
+ * A hostile name must never yield a path separator (entry escaping the
+ * extraction directory) or control characters, and must stay bounded.
+ */
+describe('export sanitizeEntryName (zip-slip guard)', () => {
+  it('neutralizes path traversal and separators', () => {
+    expect(sanitizeEntryName('../../etc/passwd')).toBe('.._.._etc_passwd');
+    expect(sanitizeEntryName('..\\..\\windows\\system32')).toBe('.._.._windows_system32');
+    expect(sanitizeEntryName('a/b\\c')).toBe('a_b_c');
+  });
+
+  it('strips control characters', () => {
+    expect(sanitizeEntryName('a\u0000b\u001fc\u007fd')).toBe('a_b_c_d');
+  });
+
+  it('never returns an empty name', () => {
+    expect(sanitizeEntryName('')).toBe('file');
+  });
+
+  it('caps the length at 150', () => {
+    expect(sanitizeEntryName('x'.repeat(500))).toHaveLength(150);
+  });
+});