@antasphere/chassis-server 1.0.0

package/test/unit/security-headers.test.ts

@@ -0,0 +1,131 @@
+import { describe, expect, it } from 'vitest';
+import { Hono } from 'hono';
+import { buildCsp, hstsValue, securityHeaders } from '@antasphere/chassis-server/middleware';
+import { createRuntimeState } from '@antasphere/chassis-server/util';
+
+/**
+ * Two properties, and on this repo the first one is the one with scar tissue.
+ *
+ * 1. The baseline header middleware is a DEFAULT, never an override. The
+ *    viewer serves USER-AUTHORED HTML under its own `CSP: sandbox` +
+ *    `Referrer-Policy: no-referrer`; an unconditional overwrite here silently
+ *    replaces that sandbox with the dashboard CSP, which is the
+ *    fail-dangerous class the viewer spike caught live. HSTS is added
+ *    set-if-absent for the same reason.
+ * 2. PLT-28: no HSTS was sent at all. It rides EVERY response, not just HTML —
+ *    the session cookie goes out on XHR too, so an http downgrade on /api/v1
+ *    is the same theft.
+ */
+
+const DASHBOARD_CSP = "default-src 'self'";
+
+function appWith(hsts: string | null = null): Hono {
+  const app = new Hono();
+  app.use('*', securityHeaders({ csp: DASHBOARD_CSP, state: createRuntimeState(), hsts }));
+  app.get('/dashboard', (c) => c.html('<h1>app</h1>'));
+  app.get('/v/abc', (c) =>
+    c.body('<h1>user content</h1>', 200, {
+      'content-type': 'text/html; charset=utf-8',
+      'content-security-policy': 'sandbox allow-scripts',
+      'referrer-policy': 'no-referrer'
+    })
+  );
+  return app;
+}
+
+describe('securityHeaders set-if-absent guards', () => {
+  it('applies the dashboard CSP to app HTML', async () => {
+    const res = await appWith().request('/dashboard');
+    expect(res.headers.get('content-security-policy')).toBe(DASHBOARD_CSP);
+    expect(res.headers.get('x-content-type-options')).toBe('nosniff');
+  });
+
+  it('never clobbers the viewer sandbox CSP or its referrer policy', async () => {
+    const res = await appWith().request('/v/abc');
+    expect(res.headers.get('content-security-policy')).toBe('sandbox allow-scripts');
+    expect(res.headers.get('referrer-policy')).toBe('no-referrer');
+  });
+});
+
+/**
+ * PLT-28. The tool issues a session cookie for the dashboard AND a scoped
+ * viewer cookie on share links; one plain-http navigation is one stolen
+ * session or one stolen share unlock.
+ */
+describe('HSTS', () => {
+  it('is absent when the instance declares an http public origin', () => {
+    expect(hstsValue({ PUBLIC_BASE_URL: 'http://localhost:3000', HSTS_MAX_AGE: 15552000 })).toBeNull();
+  });
+
+  it('is armed by an https public origin', () => {
+    expect(hstsValue({ PUBLIC_BASE_URL: 'https://app.example.com', HSTS_MAX_AGE: 15552000 })).toBe(
+      'max-age=15552000; includeSubDomains'
+    );
+  });
+
+  it('honours HSTS_MAX_AGE=0 as the operator opt-out', () => {
+    expect(hstsValue({ PUBLIC_BASE_URL: 'https://app.example.com', HSTS_MAX_AGE: 0 })).toBeNull();
+  });
+
+  it('rides EVERY response, not just HTML — the cookie goes out on XHR too', async () => {
+    const app = appWith('max-age=15552000; includeSubDomains');
+    app.get('/api/v1/me', (c) => c.json({ ok: true }));
+    const html = await app.request('/dashboard');
+    expect(html.headers.get('strict-transport-security')).toBe('max-age=15552000; includeSubDomains');
+    const json = await app.request('/api/v1/me');
+    expect(json.headers.get('strict-transport-security')).toBe('max-age=15552000; includeSubDomains');
+  });
+
+  it('rides the viewer too, without touching its sandbox CSP', async () => {
+    const res = await appWith('max-age=15552000; includeSubDomains').request('/v/abc');
+    expect(res.headers.get('strict-transport-security')).toBe('max-age=15552000; includeSubDomains');
+    expect(res.headers.get('content-security-policy')).toBe('sandbox allow-scripts');
+  });
+
+  it('sends none when the instance is not https', async () => {
+    const res = await appWith(null).request('/dashboard');
+    expect(res.headers.get('strict-transport-security')).toBeNull();
+  });
+
+  describe('buildCsp frame-src (PRDCT-1352, DASH-4)', () => {
+    it("frames only 'self' by default — the single-origin preview", () => {
+      expect(buildCsp([])).toContain("frame-src 'self';");
+      expect(buildCsp([])).not.toContain('decks.example.net');
+    });
+
+    it('adds the viewer origin so the dashboard preview can frame decks from it', () => {
+      const csp = buildCsp(["'sha256-abc'"], { frameSrc: ['https://decks.example.net'] });
+      expect(csp).toContain("frame-src 'self' https://decks.example.net;");
+      // Nothing else widens: the viewer origin gets frames, not scripts or connects.
+      expect(csp).toContain("script-src 'self' 'sha256-abc';");
+      expect(csp).toContain("connect-src 'self';");
+      expect(csp).toContain("frame-ancestors 'none';");
+    });
+  });
+
+  describe('buildCsp style-src and font-src (PRDCT-2308, the two font CDNs)', () => {
+    it('allows exactly the two stylesheet API hosts and the two font file hosts, nothing wider', () => {
+      const csp = buildCsp([]);
+      expect(csp).toContain(
+        "style-src 'self' 'unsafe-inline' https://api.fontshare.com https://fonts.googleapis.com;"
+      );
+      expect(csp).toContain("font-src 'self' https://cdn.fontshare.com https://fonts.gstatic.com;");
+      // No scheme-wide source anywhere: `https:` or `data:` on styles or fonts
+      // would let any host in (verifier round 1, M12/M13).
+      for (const directive of csp.split('; ')) {
+        if (directive.startsWith('style-src') || directive.startsWith('font-src')) {
+          expect(directive).not.toMatch(/\bhttps:(\s|$)/);
+          expect(directive).not.toContain('data:');
+        }
+      }
+      expect(csp).toContain("img-src 'self' data:;");
+      // A tool's declaration widens img-src by exactly what it names (PRDCT-2725: `blob:`
+      // for an image fetched through the API and shown from an object URL); the chassis
+      // default carries no scheme source but data:.
+      expect(buildCsp([], { imgSrc: ['blob:'] })).toContain("img-src 'self' data: blob:;");
+      expect(buildCsp([], { imgSrc: ['blob:'] })).not.toMatch(/img-src[^;]*https:/);
+      expect(csp).toContain("connect-src 'self';");
+      expect(csp).toContain("default-src 'self';");
+    });
+  });
+});

package/test/unit/serve-content-type.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from 'vitest';
+import { Readable } from 'node:stream';
+import { Hono } from 'hono';
+import { serveBlob } from '@antasphere/chassis-server/files';
+import type { StorageDriver } from '@antasphere/chassis-server/storage';
+import type { Logger } from '@antasphere/chassis-server/logger';
+
+/**
+ * PLT-5 backstop: versions are immutable, so a manifest `contentType`
+ * committed before the contract's media-type gate (or through any path that
+ * skips it) lives forever. Serving it verbatim made the `Headers` constructor
+ * throw — a permanent anonymous 500 on that asset. The serve helper degrades
+ * an invalid stored value to application/octet-stream instead.
+ */
+
+const noopLogger = {
+  error: () => {},
+  warn: () => {},
+  info: () => {},
+  debug: () => {}
+} as unknown as Logger;
+
+function storageWith(bytes: Buffer): StorageDriver {
+  return {
+    name: 'test',
+    exists: async () => true,
+    getStream: async () => Readable.from([bytes]),
+    put: async () => {
+      throw new Error('unused');
+    },
+    delete: async () => {
+      throw new Error('unused');
+    }
+  } as unknown as StorageDriver;
+}
+
+async function serve(contentType: string): Promise<Response> {
+  const bytes = Buffer.from('hello');
+  const app = new Hono();
+  app.get('/blob', (c) =>
+    serveBlob(c, {
+      storage: storageWith(bytes),
+      logger: noopLogger,
+      workspaceId: '00000000-0000-4000-8000-000000000000',
+      sha256: 'a'.repeat(64),
+      sizeBytes: bytes.length,
+      contentType,
+      filename: 'file.bin',
+      headOnly: false
+    })
+  );
+  return app.request('/blob');
+}
+
+describe('serveBlob content-type sanitization (PLT-5)', () => {
+  it('serves a valid stored media type verbatim', async () => {
+    const res = await serve('text/plain; charset=utf-8');
+    expect(res.status).toBe(200);
+    expect(res.headers.get('content-type')).toBe('text/plain; charset=utf-8');
+  });
+
+  it('degrades an invalid stored value to octet-stream instead of throwing', async () => {
+    // Includes a value that passes the RFC 7231 grammar but carries a code
+    // point above Latin-1 in a quoted parameter (charset="€") — the real
+    // ByteString trap the serve backstop must also catch, not just the
+    // grammar violations (PLT-5, verifier round-2 coverage note).
+    for (const bad of ['text/html; charset="€"', 'text/héml', 'not a type', 'text/html\r\nx-evil: 1']) {
+      const res = await serve(bad);
+      expect(res.status, bad).toBe(200);
+      expect(res.headers.get('content-type'), bad).toBe('application/octet-stream');
+      expect(res.headers.get('x-evil')).toBeNull();
+    }
+  });
+});

package/test/unit/setup-transport.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+import { isSecureSetupOrigin } from '@antasphere/chassis-server/util';
+import { INSECURE_SETUP_ORIGINS, SECURE_SETUP_ORIGINS } from '@antasphere/chassis-server/testing';
+
+/**
+ * PLT-10: the documented no-domain install path used to open port 3000 to the
+ * world and tell the operator to complete the first-boot wizard over
+ * plaintext HTTP. That request carries the owner password and the setup
+ * token, and it is the one request that decides who owns the instance.
+ *
+ * The URL table lives in src/testing/setup-origins.ts because the shell
+ * twin of this rule (dr_origin_is_secure, which setup.sh uses to warn the
+ * operator up front) is driven from the same list — see
+ * apps/server/test/unit/dr-lib.test.ts. One table, two implementations, no drift.
+ */
+describe('isSecureSetupOrigin', () => {
+  it.each(SECURE_SETUP_ORIGINS)('accepts %s', (url) => {
+    expect(isSecureSetupOrigin(url)).toBe(true);
+  });
+
+  it.each(INSECURE_SETUP_ORIGINS)('REFUSES %s', (url) => {
+    expect(isSecureSetupOrigin(url)).toBe(false);
+  });
+
+  it('fails closed on anything it cannot parse', () => {
+    expect(isSecureSetupOrigin('not a url')).toBe(false);
+    expect(isSecureSetupOrigin('')).toBe(false);
+  });
+});

package/test/unit/storage-local.test.ts

@@ -0,0 +1,53 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Readable } from 'node:stream';
+import { text } from 'node:stream/consumers';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { LocalStorageDriver } from '@antasphere/chassis-server/storage';
+
+/**
+ * The local driver must fail a missing blob at the getStream() await — never
+ * as a late 'error' event on an already-returned stream. The content route
+ * commits its status line right after that await, so a lazy open turned a
+ * missing blob into a 200 + truncated body (scale drill, I2).
+ */
+describe('LocalStorageDriver.getStream', () => {
+  let root: string;
+  let driver: LocalStorageDriver;
+  const KEY = 'ws/ab/cd/blob';
+  const PAYLOAD = 'The quick brown fox jumps over the lazy dog';
+
+  beforeAll(async () => {
+    root = await mkdtemp(join(tmpdir(), 'storage-local-test-'));
+    driver = new LocalStorageDriver(root);
+  });
+
+  afterAll(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  it('rejects at the await (ENOENT) when the blob is missing', async () => {
+    await expect(driver.getStream('ws/ab/cd/missing')).rejects.toMatchObject({ code: 'ENOENT' });
+  });
+
+  it('streams a stored blob back, in full and by range', async () => {
+    await driver.put(KEY, Readable.from(PAYLOAD), {
+      contentType: 'text/plain',
+      sizeBytes: PAYLOAD.length
+    });
+    expect(await driver.exists(KEY)).toBe(true);
+
+    const full = await driver.getStream(KEY);
+    expect(await text(full)).toBe(PAYLOAD);
+
+    const slice = await driver.getStream(KEY, { start: 4, end: 8 });
+    expect(await text(slice)).toBe('quick');
+  });
+
+  it('rejects at the await after the blob is deleted underneath a live key', async () => {
+    await driver.delete(KEY);
+    expect(await driver.exists(KEY)).toBe(false);
+    await expect(driver.getStream(KEY)).rejects.toMatchObject({ code: 'ENOENT' });
+  });
+});

package/test/unit/superadmin.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+import { parseSuperadminEmails } from '@antasphere/chassis-server/accounts';
+
+describe('parseSuperadminEmails', () => {
+  it('returns an empty set (dormant) for undefined and blank input', () => {
+    expect(parseSuperadminEmails(undefined).size).toBe(0);
+    expect(parseSuperadminEmails('').size).toBe(0);
+    expect(parseSuperadminEmails('   ').size).toBe(0);
+  });
+
+  it('parses a comma-separated list, trimming and lowercasing entries', () => {
+    const set = parseSuperadminEmails(' Ops@Example.com ,root@host.io ');
+    expect(set.size).toBe(2);
+    expect(set.has('ops@example.com')).toBe(true);
+    expect(set.has('root@host.io')).toBe(true);
+    // Matching is on the lowercased form only.
+    expect(set.has('Ops@Example.com')).toBe(false);
+  });
+
+  it('dedupes case-variant duplicates', () => {
+    const set = parseSuperadminEmails('a@b.co,A@B.CO');
+    expect(set.size).toBe(1);
+  });
+
+  it('throws LOUDLY on malformed entries (a typo must never silently disarm)', () => {
+    expect(() => parseSuperadminEmails('not-an-email')).toThrow(/not a valid email/);
+    expect(() => parseSuperadminEmails('ok@example.com,broken')).toThrow(/broken/);
+    expect(() => parseSuperadminEmails('a b@example.com')).toThrow(/not a valid email/);
+    // Only separators, no entries: refuse rather than arm an empty list.
+    expect(() => parseSuperadminEmails(',,')).toThrow(/at least one email/);
+  });
+});

package/test/unit/timers.test.ts

@@ -0,0 +1,287 @@
+import { describe, expect, it, vi } from 'vitest';
+import type PgBoss from 'pg-boss';
+import type pg from 'pg';
+import type { Logger } from '@antasphere/chassis-server/logger';
+import {
+  MAX_IN_SECONDS,
+  PgBossTimers,
+  TIMER_KEY_LOCK_CLASS,
+  TimerError,
+  startAfterOf,
+  type TimerOptions,
+  type TimerRef
+} from '../../src/jobs/timers.js';
+
+/**
+ * The one-off timers' validation and their mapping onto pg-boss (PRDCT-3254),
+ * with no database: a fake boss records `send`, a fake pool records
+ * `connect` and `query`. A malformed call is refused before ANY of them is
+ * touched. The statements themselves run against a real pg-boss in
+ * `test/integration/timers.test.ts`.
+ */
+
+const JOB_ID = '0b9a3c8e-1f2d-4e5a-9b6c-7d8e9f0a1b2c';
+
+const logger = { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() } as unknown as Logger;
+
+interface FakeClient {
+  query: ReturnType<typeof vi.fn>;
+  release: ReturnType<typeof vi.fn>;
+}
+
+function fakes(sendAnswer: string | null = JOB_ID) {
+  const send = vi.fn(async (_queue: string, _data: object, _options: PgBoss.SendOptions) => sendAnswer);
+  const client: FakeClient = {
+    query: vi.fn(async (_text: string, _values?: unknown[]) => ({ rowCount: 0, rows: [] })),
+    release: vi.fn()
+  };
+  const pool = {
+    connect: vi.fn(async () => client),
+    query: vi.fn(async (_text: string, _values?: unknown[]) => ({ rowCount: 0 as number | null, rows: [] }))
+  };
+  const timers = new PgBossTimers({ send } as unknown as PgBoss, pool as unknown as pg.Pool, logger);
+  return { send, pool, client, timers };
+}
+
+async function expectInvalid(promise: Promise<unknown>): Promise<void> {
+  const err = await promise.then(
+    () => null,
+    (e: unknown) => e
+  );
+  expect(err).toBeInstanceOf(TimerError);
+  expect((err as TimerError).code).toBe('invalid_argument');
+}
+
+function expectInvalidSync(fn: () => unknown): void {
+  let caught: unknown = null;
+  try {
+    fn();
+  } catch (e) {
+    caught = e;
+  }
+  expect(caught).toBeInstanceOf(TimerError);
+  expect((caught as TimerError).code).toBe('invalid_argument');
+}
+
+describe('startAfterOf', () => {
+  it('answers the same Date for `at`', () => {
+    const at = new Date('2030-01-02T03:04:05.000Z');
+    expect(startAfterOf({ at })).toBe(at);
+  });
+
+  it('answers the seconds for `inSeconds`', () => {
+    expect(startAfterOf({ inSeconds: 30 })).toBe(30);
+    expect(startAfterOf({ inSeconds: 0 })).toBe(0);
+  });
+
+  it('refuses neither and both', () => {
+    expectInvalidSync(() => startAfterOf({} as TimerOptions));
+    expectInvalidSync(() => startAfterOf({ at: new Date(), inSeconds: 3 } as unknown as TimerOptions));
+  });
+
+  it('refuses an invalid Date and a value that is not a Date', () => {
+    expectInvalidSync(() => startAfterOf({ at: new Date('not a date') }));
+    expectInvalidSync(() => startAfterOf({ at: '2030-01-01T00:00:00Z' } as unknown as TimerOptions));
+  });
+
+  it('refuses a negative, NaN, infinite or over-a-century delay; takes the cap itself', () => {
+    expectInvalidSync(() => startAfterOf({ inSeconds: -1 }));
+    expectInvalidSync(() => startAfterOf({ inSeconds: Number.NaN }));
+    expectInvalidSync(() => startAfterOf({ inSeconds: Number.POSITIVE_INFINITY }));
+    expectInvalidSync(() => startAfterOf({ inSeconds: MAX_IN_SECONDS + 1 }));
+    expect(startAfterOf({ inSeconds: MAX_IN_SECONDS })).toBe(MAX_IN_SECONDS);
+  });
+
+  it('takes a payload with a null prototype and nested Dates (JSON takes them)', async () => {
+    const { send, timers } = fakes();
+    await timers.schedule('things-timer', Object.create(null) as object, { inSeconds: 1 });
+    await timers.schedule('things-timer', { at: new Date() }, { inSeconds: 1 });
+    expect(send).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe('schedule refuses a malformed call before any IO', () => {
+  const cases: Array<[string, (t: PgBossTimers) => Promise<unknown>]> = [
+    ['a queue name with a space', (t) => t.schedule('things timer', {}, { inSeconds: 1 })],
+    ['an empty queue name', (t) => t.schedule('', {}, { inSeconds: 1 })],
+    ['a null payload', (t) => t.schedule('things-timer', null as unknown as object, { inSeconds: 1 })],
+    ['a string payload', (t) => t.schedule('things-timer', 'x' as unknown as object, { inSeconds: 1 })],
+    ['a number payload', (t) => t.schedule('things-timer', 42 as unknown as object, { inSeconds: 1 })],
+    ['an array payload', (t) => t.schedule('things-timer', [1, 2] as unknown as object, { inSeconds: 1 })],
+    ['a Date payload', (t) => t.schedule('things-timer', new Date(), { inSeconds: 1 })],
+    ['a bigint inside the payload', (t) => t.schedule('things-timer', { n: 1n }, { inSeconds: 1 })],
+    [
+      'a circular payload',
+      (t) => {
+        const data: Record<string, unknown> = {};
+        data.self = data;
+        return t.schedule('things-timer', data, { inSeconds: 1 });
+      }
+    ],
+    ['a delay over a hundred years', (t) => t.schedule('things-timer', {}, { inSeconds: 1e21 })],
+    ['no `at` and no `inSeconds`', (t) => t.schedule('things-timer', {}, {} as TimerOptions)],
+    ['an empty key', (t) => t.schedule('things-timer', {}, { inSeconds: 1, key: '' })],
+    [
+      'a key carrying the unit separator',
+      (t) => t.schedule('things-timer', {}, { inSeconds: 1, key: 'a\u001fb' })
+    ],
+    ['retry.limit -1', (t) => t.schedule('things-timer', {}, { inSeconds: 1, retry: { limit: -1 } })],
+    ['retry.limit 1.5', (t) => t.schedule('things-timer', {}, { inSeconds: 1, retry: { limit: 1.5 } })],
+    [
+      'retry.delaySeconds -1',
+      (t) => t.schedule('things-timer', {}, { inSeconds: 1, retry: { limit: 1, delaySeconds: -1 } })
+    ],
+    [
+      'retry.limit -1 on a keyed call',
+      (t) => t.schedule('things-timer', {}, { inSeconds: 1, key: 'k', retry: { limit: -1 } })
+    ]
+  ];
+
+  it.each(cases)('%s → invalid_argument, no send, no connect', async (_label, call) => {
+    const { send, pool, timers } = fakes();
+    await expectInvalid(call(timers));
+    expect(send).not.toHaveBeenCalled();
+    expect(pool.connect).not.toHaveBeenCalled();
+    expect(pool.query).not.toHaveBeenCalled();
+  });
+});
+
+describe('schedule without a key maps onto pg-boss send', () => {
+  it('`at` → startAfter the Date, no retry options, no singletonKey, no db', async () => {
+    const { send, pool, timers } = fakes();
+    const at = new Date(Date.now() + 60_000);
+    await expect(timers.schedule('things-timer', { n: 1 }, { at })).resolves.toBe(JOB_ID);
+    expect(send).toHaveBeenCalledTimes(1);
+    const [queue, data, options] = send.mock.calls[0] as unknown as [string, object, PgBoss.SendOptions];
+    expect(queue).toBe('things-timer');
+    expect(data).toEqual({ n: 1 });
+    expect(options).toEqual({ startAfter: at });
+    expect(options.startAfter).toBe(at);
+    for (const absent of ['retryLimit', 'retryDelay', 'retryBackoff', 'singletonKey', 'db']) {
+      expect(options).not.toHaveProperty(absent);
+    }
+    expect(pool.connect).not.toHaveBeenCalled();
+  });
+
+  it('`inSeconds` → startAfter the seconds', async () => {
+    const { send, timers } = fakes();
+    await timers.schedule('things-timer', { n: 2 }, { inSeconds: 30 });
+    expect(send.mock.calls[0]?.[2]).toEqual({ startAfter: 30 });
+  });
+
+  it('`retry` → retryLimit, retryDelay, retryBackoff', async () => {
+    const { send, timers } = fakes();
+    await timers.schedule(
+      'things-timer',
+      {},
+      { inSeconds: 5, retry: { limit: 3, delaySeconds: 10, backoff: true } }
+    );
+    expect(send.mock.calls[0]?.[2]).toEqual({
+      startAfter: 5,
+      retryLimit: 3,
+      retryDelay: 10,
+      retryBackoff: true
+    });
+  });
+
+  it('`retry` with the limit alone → delay 0, no backoff', async () => {
+    const { send, timers } = fakes();
+    await timers.schedule('things-timer', {}, { inSeconds: 5, retry: { limit: 0 } });
+    expect(send.mock.calls[0]?.[2]).toEqual({
+      startAfter: 5,
+      retryLimit: 0,
+      retryDelay: 0,
+      retryBackoff: false
+    });
+  });
+
+  it('a send that answers null is an unknown queue', async () => {
+    const { timers } = fakes(null);
+    const err = await timers.schedule('no-such-queue', {}, { inSeconds: 1 }).then(
+      () => null,
+      (e: unknown) => e
+    );
+    expect(err).toBeInstanceOf(TimerError);
+    expect((err as TimerError).code).toBe('unknown_queue');
+  });
+});
+
+describe('schedule with a key runs one transaction on a client of its own', () => {
+  it('BEGIN, the per-key lock, the withdraw, the insert on the same client, COMMIT, release', async () => {
+    const { send, pool, client, timers } = fakes();
+    await expect(timers.schedule('things-timer', { n: 3 }, { inSeconds: 7, key: 'k1' })).resolves.toBe(
+      JOB_ID
+    );
+    expect(pool.connect).toHaveBeenCalledTimes(1);
+    const statements = client.query.mock.calls.map((c) => String(c[0]).trim().split(/\s+/)[0]);
+    // The disarm of a running timer (its retries taken away) FIRST, then the withdraw of the pending one:
+    // in that order pg-boss's fail path cannot slip its retry row between the two (verifier round 2, F7).
+    expect(statements).toEqual(['BEGIN', 'SELECT', 'UPDATE', 'UPDATE', 'COMMIT']);
+    expect(client.query.mock.calls[1]?.[1]).toEqual([TIMER_KEY_LOCK_CLASS, 'things-timer\u001fk1']);
+    expect(client.query.mock.calls[2]?.[1]).toEqual(['things-timer', 'k1']);
+    expect(String(client.query.mock.calls[2]?.[0])).toContain('SET retry_limit = retry_count');
+    expect(String(client.query.mock.calls[2]?.[0])).toContain("state = 'active'");
+    expect(client.query.mock.calls[3]?.[1]).toEqual(['things-timer', 'k1']);
+    expect(String(client.query.mock.calls[3]?.[0])).toContain("state IN ('created', 'retry')");
+    const options = send.mock.calls[0]?.[2] as unknown as PgBoss.SendOptions & {
+      db: { executeSql: (t: string, v: unknown[]) => Promise<unknown> };
+    };
+    expect(options.singletonKey).toBe('k1');
+    expect(options.startAfter).toBe(7);
+    // The insert's executor is the transaction's client.
+    await options.db.executeSql('SELECT 1', []);
+    expect(client.query).toHaveBeenLastCalledWith('SELECT 1', []);
+    expect(client.release).toHaveBeenCalledTimes(1);
+    expect(pool.query).not.toHaveBeenCalled();
+  });
+
+  it('an unknown queue rolls the transaction back and releases the client', async () => {
+    const { client, timers } = fakes(null);
+    const err = await timers.schedule('no-such-queue', {}, { inSeconds: 1, key: 'k' }).then(
+      () => null,
+      (e: unknown) => e
+    );
+    expect((err as TimerError).code).toBe('unknown_queue');
+    const statements = client.query.mock.calls.map((c) => String(c[0]).trim().split(/\s+/)[0]);
+    expect(statements).toContain('ROLLBACK');
+    expect(statements).not.toContain('COMMIT');
+    expect(client.release).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('cancel refuses a malformed call before any IO', () => {
+  const cases: Array<[string, string, TimerRef]> = [
+    ['both id and key', 'things-timer', { id: JOB_ID, key: 'k' } as unknown as TimerRef],
+    ['neither id nor key', 'things-timer', {} as TimerRef],
+    ['an id that is not a UUID', 'things-timer', { id: 'not-a-uuid' }],
+    ['an id with SQL in it', 'things-timer', { id: `${JOB_ID}' OR '1'='1` }],
+    ['an empty key', 'things-timer', { key: '' }],
+    ['a queue name with a space', 'things timer', { id: JOB_ID }]
+  ];
+
+  it.each(cases)('%s → invalid_argument, no query', async (_label, queue, ref) => {
+    const { pool, timers } = fakes();
+    await expectInvalid(timers.cancel(queue, ref));
+    expect(pool.query).not.toHaveBeenCalled();
+    expect(pool.connect).not.toHaveBeenCalled();
+  });
+
+  it('a well-formed cancel disarms a running timer first, then answers the PENDING rows withdrawn', async () => {
+    const { pool, timers } = fakes();
+    pool.query
+      .mockResolvedValueOnce({ rowCount: 0, rows: [] })
+      .mockResolvedValueOnce({ rowCount: 1, rows: [] });
+    await expect(timers.cancel('things-timer', { id: JOB_ID })).resolves.toBe(1);
+    expect(pool.query.mock.calls[0]?.[1]).toEqual(['things-timer', JOB_ID]);
+    expect(String(pool.query.mock.calls[0]?.[0])).toContain('SET retry_limit = retry_count');
+    expect(pool.query.mock.calls[1]?.[1]).toEqual(['things-timer', JOB_ID]);
+    expect(String(pool.query.mock.calls[1]?.[0])).toContain("state IN ('created', 'retry')");
+    // The disarm's row count is not the answer: a running timer is not withdrawn.
+    pool.query
+      .mockResolvedValueOnce({ rowCount: 1, rows: [] })
+      .mockResolvedValueOnce({ rowCount: 0, rows: [] });
+    await expect(timers.cancel('things-timer', { key: 'k1' })).resolves.toBe(0);
+    expect(pool.query.mock.calls[2]?.[1]).toEqual(['things-timer', 'k1']);
+    expect(pool.query.mock.calls[3]?.[1]).toEqual(['things-timer', 'k1']);
+  });
+});