@antasphere/chassis-server 1.1.0 → 1.3.0

package/test/unit/secret-box.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from 'vitest';
+import { createSecretBox, SecretBoxError } from '../../src/secret-box.js';
+
+/**
+ * The readable-secret box: AES-256-GCM under an HKDF key per (auth secret,
+ * info). Every refusal is a SecretBoxError, a malformed string included, and
+ * nothing that was changed ever opens to garbage.
+ */
+
+const AUTH_SECRET = 'unit-test-secret-0123456789abcdef0123456789abcdef';
+const INFO = 'webhooks:signing-secret';
+const PLAIN = 'whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw';
+
+const box = createSecretBox(AUTH_SECRET, INFO);
+
+/** Flip one bit of the decoded bytes of part `index` (1 = iv, 2 = tag, 3 = ciphertext). */
+function flipByte(sealed: string, index: 1 | 2 | 3): string {
+  const parts = sealed.split('.');
+  const bytes = Buffer.from(parts[index]!, 'base64url');
+  bytes[0] = bytes[0]! ^ 0x01;
+  parts[index] = bytes.toString('base64url');
+  return parts.join('.');
+}
+
+function expectRefused(open: () => string): void {
+  let thrown: unknown;
+  try {
+    open();
+  } catch (error) {
+    thrown = error;
+  }
+  expect(thrown).toBeInstanceOf(SecretBoxError);
+}
+
+describe('createSecretBox', () => {
+  it('round-trips a value', () => {
+    expect(box.open(box.seal(PLAIN))).toBe(PLAIN);
+  });
+
+  it('round-trips the empty string', () => {
+    expect(box.open(box.seal(''))).toBe('');
+  });
+
+  it('spells v1.<iv>.<tag>.<ciphertext> in base64url without the plaintext', () => {
+    const sealed = box.seal(PLAIN);
+    const parts = sealed.split('.');
+    expect(parts).toHaveLength(4);
+    expect(parts[0]).toBe('v1');
+    expect(Buffer.from(parts[1]!, 'base64url')).toHaveLength(12);
+    expect(Buffer.from(parts[2]!, 'base64url')).toHaveLength(16);
+    for (const part of parts.slice(1)) expect(part).toMatch(/^[A-Za-z0-9_-]+$/);
+    expect(sealed).not.toContain('MfKQ9r8');
+  });
+
+  it('seals one value twice to two different strings, both of which open', () => {
+    const first = box.seal(PLAIN);
+    const second = box.seal(PLAIN);
+    expect(first).not.toBe(second);
+    expect(first.split('.')[1]).not.toBe(second.split('.')[1]);
+    expect(box.open(first)).toBe(PLAIN);
+    expect(box.open(second)).toBe(PLAIN);
+  });
+
+  it.each([
+    ['the iv', 1],
+    ['the tag', 2],
+    ['the ciphertext', 3]
+  ] as const)('refuses a flipped byte in %s', (_name, index) => {
+    const sealed = box.seal(PLAIN);
+    expectRefused(() => box.open(flipByte(sealed, index)));
+  });
+
+  it('refuses a value sealed under another info', () => {
+    const other = createSecretBox(AUTH_SECRET, 'webhooks:other-purpose');
+    expectRefused(() => other.open(box.seal(PLAIN)));
+    expectRefused(() => box.open(other.seal(PLAIN)));
+  });
+
+  it('refuses a value sealed under another auth secret', () => {
+    const other = createSecretBox('another-auth-secret-0123456789abcdef0123456789', INFO);
+    expectRefused(() => other.open(box.seal(PLAIN)));
+  });
+
+  it('opens a value sealed by another box of the same auth secret and info', () => {
+    const twin = createSecretBox(AUTH_SECRET, INFO);
+    expect(twin.open(box.seal(PLAIN))).toBe(PLAIN);
+  });
+
+  it('keeps unicode plaintext intact', () => {
+    const unicode = 'clé secrète: 🔐 — 秘密 — Ωμέγα\u0000end';
+    expect(box.open(box.seal(unicode))).toBe(unicode);
+  });
+
+  describe('a malformed string is a SecretBoxError and nothing else', () => {
+    const sealed = box.seal(PLAIN);
+    const [, iv, tag, ciphertext] = sealed.split('.') as [string, string, string, string];
+    const cases: Array<[string, unknown]> = [
+      ['the empty string', ''],
+      ['no separators', 'garbage'],
+      ['three parts', `v1.${iv}.${tag}`],
+      ['five parts', `${sealed}.extra`],
+      ['an unknown version', `v2.${iv}.${tag}.${ciphertext}`],
+      ['an empty version', `.${iv}.${tag}.${ciphertext}`],
+      ['a short iv', `v1.${iv.slice(0, 8)}.${tag}.${ciphertext}`],
+      ['a long iv', `v1.${iv}AAAA.${tag}.${ciphertext}`],
+      ['an empty iv', `v1..${tag}.${ciphertext}`],
+      ['a short tag', `v1.${iv}.${tag.slice(0, 10)}.${ciphertext}`],
+      ['an empty tag', `v1.${iv}..${ciphertext}`],
+      ['an empty ciphertext', `v1.${iv}.${tag}.`],
+      ['a character outside base64url', `v1.${iv}.${tag}.${ciphertext}*`],
+      ['standard base64 characters', `v1.${iv}.${tag}.+/${ciphertext}`],
+      ['a non-string', null],
+      ['a number', 42]
+    ];
+    it.each(cases)('refuses %s', (_name, input) => {
+      expectRefused(() => box.open(input as string));
+    });
+  });
+
+  it('refuses an empty auth secret or an empty info', () => {
+    expect(() => createSecretBox('', INFO)).toThrow(SecretBoxError);
+    expect(() => createSecretBox(AUTH_SECRET, '')).toThrow(SecretBoxError);
+  });
+});

package/test/unit/static-assets.test.ts

@@ -0,0 +1,227 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { Hono } from 'hono';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { brotliCompressSync, gzipSync } from 'node:zlib';
+import {
+  IMMUTABLE_CACHE_CONTROL,
+  REVALIDATE_CACHE_CONTROL,
+  acceptedEncodings,
+  loadSpaFallback,
+  staticAssets,
+  staticCacheControl
+} from '@antasphere/chassis-server/middleware';
+
+/**
+ * PRDCT-3584. The dashboard build went out with no cache policy and no
+ * compression, so every visit re-downloaded it. Three properties:
+ *
+ * 1. a content-hashed asset (`/_app/immutable/*`) is cached for a year and
+ *    marked immutable; nothing else ever is;
+ * 2. a precompressed sibling is served when the request accepts its
+ *    encoding, with `Content-Encoding` and `Vary`, and the plain file when
+ *    it does not;
+ * 3. a path that is not a file falls through to the SPA fallback, which is
+ *    revalidated on every use.
+ */
+
+const CHUNK = 'export const answer = 42; '.repeat(40);
+let publicDir: string;
+let app: Hono;
+
+beforeAll(() => {
+  publicDir = mkdtempSync(join(tmpdir(), 'chassis-static-'));
+  mkdirSync(join(publicDir, '_app', 'immutable', 'chunks'), { recursive: true });
+  const chunk = join(publicDir, '_app', 'immutable', 'chunks', 'abc123.js');
+  writeFileSync(chunk, CHUNK);
+  writeFileSync(`${chunk}.br`, brotliCompressSync(Buffer.from(CHUNK)));
+  writeFileSync(`${chunk}.gz`, gzipSync(Buffer.from(CHUNK)));
+  // a hashed asset with no compressed sibling
+  writeFileSync(join(publicDir, '_app', 'immutable', 'chunks', 'plain.js'), CHUNK);
+  writeFileSync(join(publicDir, 'index.html'), '<!doctype html><title>t</title>');
+  writeFileSync(join(publicDir, 'favicon.png'), Buffer.from([0x89, 0x50, 0x4e, 0x47]));
+
+  app = new Hono();
+  app.use('*', staticAssets({ publicDir }));
+  app.get('*', (c) => {
+    c.header('Cache-Control', REVALIDATE_CACHE_CONTROL);
+    return c.html('<!doctype html><title>fallback</title>');
+  });
+});
+
+afterAll(() => {
+  rmSync(publicDir, { recursive: true, force: true });
+});
+
+describe('staticCacheControl', () => {
+  it('marks only the content-hashed prefix immutable', () => {
+    expect(staticCacheControl('/_app/immutable/chunks/abc123.js')).toBe(IMMUTABLE_CACHE_CONTROL);
+    expect(staticCacheControl('/_app/immutable/entry/start.js')).toBe(IMMUTABLE_CACHE_CONTROL);
+    expect(staticCacheControl('/_app/version.json')).toBe(REVALIDATE_CACHE_CONTROL);
+    expect(staticCacheControl('/index.html')).toBe(REVALIDATE_CACHE_CONTROL);
+    expect(staticCacheControl('/favicon.png')).toBe(REVALIDATE_CACHE_CONTROL);
+    expect(staticCacheControl('/')).toBe(REVALIDATE_CACHE_CONTROL);
+  });
+});
+
+describe('staticAssets', () => {
+  it('serves a hashed asset immutable for a year', async () => {
+    const res = await app.request('/_app/immutable/chunks/plain.js');
+    expect(res.status).toBe(200);
+    expect(res.headers.get('cache-control')).toBe(IMMUTABLE_CACHE_CONTROL);
+    expect(res.headers.get('content-encoding')).toBeNull();
+    expect(res.headers.get('vary')).toBe('Accept-Encoding');
+    expect(await res.text()).toBe(CHUNK);
+  });
+
+  it('serves the brotli sibling when the request accepts br', async () => {
+    const res = await app.request('/_app/immutable/chunks/abc123.js', {
+      headers: { 'accept-encoding': 'gzip, deflate, br, zstd' }
+    });
+    expect(res.status).toBe(200);
+    expect(res.headers.get('content-encoding')).toBe('br');
+    expect(res.headers.get('vary')).toContain('Accept-Encoding');
+    expect(res.headers.get('cache-control')).toBe(IMMUTABLE_CACHE_CONTROL);
+    expect(res.headers.get('content-type')).toContain('javascript');
+    const body = Buffer.from(await res.arrayBuffer());
+    expect(body.equals(brotliCompressSync(Buffer.from(CHUNK)))).toBe(true);
+  });
+
+  it('serves the gzip sibling when only gzip is accepted', async () => {
+    const res = await app.request('/_app/immutable/chunks/abc123.js', {
+      headers: { 'accept-encoding': 'gzip' }
+    });
+    expect(res.headers.get('content-encoding')).toBe('gzip');
+    const body = Buffer.from(await res.arrayBuffer());
+    expect(body.equals(gzipSync(Buffer.from(CHUNK)))).toBe(true);
+  });
+
+  it('serves the plain file when no encoding is accepted', async () => {
+    const res = await app.request('/_app/immutable/chunks/abc123.js');
+    expect(res.headers.get('content-encoding')).toBeNull();
+    expect(await res.text()).toBe(CHUNK);
+  });
+
+  it('revalidates every static file outside the hashed prefix', async () => {
+    const icon = await app.request('/favicon.png');
+    expect(icon.status).toBe(200);
+    expect(icon.headers.get('cache-control')).toBe(REVALIDATE_CACHE_CONTROL);
+  });
+
+  it('leaves the application HTML itself to the fallback', async () => {
+    for (const path of ['/', '/index.html']) {
+      const res = await app.request(path);
+      expect(res.status, path).toBe(200);
+      expect(res.headers.get('cache-control'), path).toBe(REVALIDATE_CACHE_CONTROL);
+      expect(await res.text(), path).toContain('fallback');
+    }
+  });
+
+  it('falls through to the SPA fallback on an application route, revalidated', async () => {
+    const res = await app.request('/login');
+    expect(res.status).toBe(200);
+    expect(res.headers.get('cache-control')).toBe(REVALIDATE_CACHE_CONTROL);
+    expect(await res.text()).toContain('fallback');
+  });
+
+  it('never marks a non-hashed response immutable', async () => {
+    for (const path of ['/', '/index.html', '/favicon.png', '/login', '/_app/version.json']) {
+      const res = await app.request(path);
+      expect(res.headers.get('cache-control'), path).not.toContain('immutable');
+    }
+  });
+});
+
+describe('the SPA fallback', () => {
+  const html = '<!doctype html><title>app</title><script>1</script>';
+  let dir: string;
+  let fallbackApp: Hono;
+  let etag: string;
+
+  beforeAll(async () => {
+    dir = mkdtempSync(join(tmpdir(), 'chassis-fallback-'));
+    writeFileSync(join(dir, 'index.html'), html);
+    writeFileSync(join(dir, 'index.html.br'), brotliCompressSync(Buffer.from(html)));
+    // no .gz sibling on purpose: a gzip-only client gets the plain HTML
+    const fallback = await loadSpaFallback(dir, html);
+    etag = fallback.etag;
+    fallbackApp = new Hono();
+    fallbackApp.use('*', staticAssets({ publicDir: dir }));
+    fallbackApp.get('*', (c) => fallback.respond(c));
+  });
+
+  afterAll(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('answers a deep link with the plain HTML, a strong ETag and no-cache', async () => {
+    const res = await fallbackApp.request('/settings/members');
+    expect(res.status).toBe(200);
+    expect(res.headers.get('content-type')).toContain('text/html');
+    expect(res.headers.get('cache-control')).toBe(REVALIDATE_CACHE_CONTROL);
+    expect(res.headers.get('etag')).toBe(etag);
+    expect(res.headers.get('content-encoding')).toBeNull();
+    expect(res.headers.get('vary')).toBe('Accept-Encoding');
+    expect(await res.text()).toBe(html);
+  });
+
+  it('answers 304 to a matching If-None-Match, with no body and the HTML type', async () => {
+    const res = await fallbackApp.request('/settings/members', { headers: { 'if-none-match': etag } });
+    expect(res.status).toBe(304);
+    expect(await res.text()).toBe('');
+    expect(res.headers.get('etag')).toBe(etag);
+    expect(res.headers.get('cache-control')).toBe(REVALIDATE_CACHE_CONTROL);
+    expect(res.headers.get('content-type')).toContain('text/html');
+  });
+
+  it('answers the root and /index.html with the validator too', async () => {
+    for (const path of ['/', '/index.html']) {
+      const res = await fallbackApp.request(path);
+      expect(res.status, path).toBe(200);
+      expect(res.headers.get('etag'), path).toBe(etag);
+      const again = await fallbackApp.request(path, { headers: { 'if-none-match': etag } });
+      expect(again.status, path).toBe(304);
+    }
+  });
+
+  it('serves the brotli sibling to a client that accepts br, under its own validator', async () => {
+    const res = await fallbackApp.request('/login', {
+      headers: { 'accept-encoding': 'gzip, deflate, br;q=1.0' }
+    });
+    expect(res.status).toBe(200);
+    expect(res.headers.get('content-encoding')).toBe('br');
+    const variant = res.headers.get('etag')!;
+    expect(variant).not.toBe(etag);
+    expect(variant.endsWith('-br"')).toBe(true);
+    const body = Buffer.from(await res.arrayBuffer());
+    expect(body.equals(brotliCompressSync(Buffer.from(html)))).toBe(true);
+    const again = await fallbackApp.request('/login', {
+      headers: { 'accept-encoding': 'br', 'if-none-match': variant }
+    });
+    expect(again.status).toBe(304);
+    // the plain validator never confirms the compressed body
+    const cross = await fallbackApp.request('/login', {
+      headers: { 'accept-encoding': 'br', 'if-none-match': etag }
+    });
+    expect(cross.status).toBe(200);
+  });
+
+  it('falls back to the plain HTML when the accepted encoding has no sibling', async () => {
+    const res = await fallbackApp.request('/login', { headers: { 'accept-encoding': 'gzip' } });
+    expect(res.status).toBe(200);
+    expect(res.headers.get('content-encoding')).toBeNull();
+    expect(await res.text()).toBe(html);
+  });
+
+  it('reads Accept-Encoding tokens with their weights stripped', () => {
+    expect([...acceptedEncodings('gzip, deflate, br;q=1.0, zstd')]).toEqual([
+      'gzip',
+      'deflate',
+      'br',
+      'zstd'
+    ]);
+    expect([...acceptedEncodings(undefined)]).toEqual([]);
+    expect(acceptedEncodings(' BR ').has('br')).toBe(true);
+  });
+});

package/test/unit/tx-send.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest';
+import pg from 'pg';
+import { drizzle } from 'drizzle-orm/node-postgres';
+import { connectionOf } from '../../src/webhooks/tx-send.js';
+
+/**
+ * The transactional send reaches the connection behind a drizzle handle
+ * through the driver binding's session (`session.client`): this pins the
+ * shape against the installed drizzle, so a bump that moves it fails here
+ * and not in a delivery.
+ */
+describe('tx-send: the connection behind a drizzle handle', () => {
+  it('a plain handle exposes its pool, with query', () => {
+    const pool = new pg.Pool({ connectionString: 'postgres://nobody@127.0.0.1:1/none' });
+    const db = drizzle(pool);
+    expect(connectionOf(db)).toBe(pool);
+    expect(typeof connectionOf(db).query).toBe('function');
+  });
+
+  it('something that is not a drizzle handle is refused, naming the shape', () => {
+    expect(() => connectionOf({} as never)).toThrow(/session\.client/);
+  });
+});

package/test/unit/webhook-catalog.test.ts

@@ -0,0 +1,151 @@
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import {
+  buildWebhookCatalog,
+  catalogToWire,
+  CHASSIS_WEBHOOK_EVENTS,
+  type WebhookCatalogDeclaration,
+  type WebhookEventDeclaration
+} from '../../src/webhooks/catalog.js';
+
+/**
+ * The boot check of the webhooks catalog (PRDCT-3482, verifier round 1, G7):
+ * the chassis's events merged with the tool's, every fault named at boot, and
+ * the wire form `GET /webhooks/events` answers.
+ */
+
+const thingCreated: WebhookEventDeclaration = {
+  type: 'thing.created',
+  description: 'A thing was created.',
+  subjects: ['thing', 'project'],
+  data: z.object({ thingId: z.string(), name: z.string() })
+};
+
+const tool = (over: Partial<WebhookCatalogDeclaration> = {}): WebhookCatalogDeclaration => ({
+  subjects: { thing: { field: 'thingId', description: 'A thing, by id' } },
+  events: [thingCreated],
+  ...over
+});
+
+describe('buildWebhookCatalog', () => {
+  it('merges the chassis events with the tool events', () => {
+    const catalog = buildWebhookCatalog(tool());
+    for (const e of CHASSIS_WEBHOOK_EVENTS) expect(catalog.events.has(e.type), e.type).toBe(true);
+    expect(catalog.events.get('thing.created')).toBe(thingCreated);
+    expect(Object.keys(catalog.subjects).sort()).toEqual(['project', 'thing']);
+  });
+
+  it('a tool with no webhooks slot gets the chassis catalog alone', () => {
+    const catalog = buildWebhookCatalog(undefined);
+    expect([...catalog.events.keys()].sort()).toEqual(CHASSIS_WEBHOOK_EVENTS.map((e) => e.type).sort());
+    expect(catalog.subjects.project).toMatchObject({ field: 'projectId' });
+  });
+
+  it('refuses a type declared twice', () => {
+    expect(() => buildWebhookCatalog(tool({ events: [thingCreated, { ...thingCreated }] }))).toThrow(
+      /"thing\.created" is declared twice/
+    );
+  });
+
+  it('refuses a tool re-declaring a chassis type', () => {
+    expect(() =>
+      buildWebhookCatalog(tool({ events: [{ ...thingCreated, type: 'project.created' }] }))
+    ).toThrow(/"project\.created" is declared twice/);
+  });
+
+  it('refuses an event carrying a subject nobody declared', () => {
+    expect(() =>
+      buildWebhookCatalog(tool({ events: [{ ...thingCreated, subjects: ['thing', 'widget'] }] }))
+    ).toThrow(/carries the subject "widget", which webhooks\.subjects does not declare/);
+  });
+
+  it.each(['Thing.created', 'thing', 'thing.created.now', 'thing-x.created', '1thing.created', 'thing.'])(
+    'refuses the malformed type %s',
+    (type) => {
+      expect(() => buildWebhookCatalog(tool({ events: [{ ...thingCreated, type }] }))).toThrow(
+        /must be family\.verb/
+      );
+    }
+  );
+
+  it.each(['*', 'thing.*'])('refuses the pattern %s as a type', (type) => {
+    expect(() => buildWebhookCatalog(tool({ events: [{ ...thingCreated, type }] }))).toThrow(
+      new RegExp(`"${type.replace(/[.*]/g, '\\$&')}"`)
+    );
+  });
+
+  it('refuses an event without a description', () => {
+    expect(() => buildWebhookCatalog(tool({ events: [{ ...thingCreated, description: '' }] }))).toThrow(
+      /"thing\.created" needs a description/
+    );
+  });
+
+  it('refuses a malformed subject key and a subject without a field', () => {
+    expect(() =>
+      buildWebhookCatalog(tool({ subjects: { 'Bad-Key': { field: 'x', description: 'x' } } }))
+    ).toThrow(/webhooks\.subjects key "Bad-Key"/);
+    expect(() => buildWebhookCatalog(tool({ subjects: { thing: { field: '', description: 'x' } } }))).toThrow(
+      /webhooks\.subjects\.thing\.field is required/
+    );
+  });
+
+  it('accepts a tool renaming the project subject’s field (a list under projectIds)', () => {
+    const catalog = buildWebhookCatalog(
+      tool({
+        subjects: {
+          thing: { field: 'thingId', description: 'A thing, by id' },
+          project: { field: 'projectIds', description: 'The projects of a thing', list: true }
+        }
+      })
+    );
+    expect(catalog.subjects.project).toEqual({
+      field: 'projectIds',
+      description: 'The projects of a thing',
+      list: true
+    });
+    // The chassis's own project events now carry the tool's declaration.
+    expect(catalog.events.get('project.created')?.subjects).toEqual(['project']);
+  });
+});
+
+describe('catalogToWire', () => {
+  it('carries list: true for a list subject and false otherwise, and the JSON Schema of every event', () => {
+    const wire = catalogToWire(
+      buildWebhookCatalog(
+        tool({
+          subjects: {
+            thing: { field: 'thingId', description: 'A thing, by id' },
+            project: { field: 'projectIds', description: 'The projects of a thing', list: true }
+          }
+        })
+      )
+    );
+    expect(wire.subjects).toEqual(
+      expect.arrayContaining([
+        { key: 'thing', field: 'thingId', description: 'A thing, by id', list: false },
+        { key: 'project', field: 'projectIds', description: 'The projects of a thing', list: true }
+      ])
+    );
+    expect(wire.subjects).toHaveLength(2);
+    const created = wire.events.find((e) => e.type === 'thing.created');
+    expect(created).toMatchObject({
+      description: 'A thing was created.',
+      subjects: ['thing', 'project'],
+      schema: {
+        type: 'object',
+        properties: { thingId: { type: 'string' }, name: { type: 'string' } },
+        required: ['thingId', 'name']
+      }
+    });
+    expect(wire.events.map((e) => e.type)).toEqual(
+      expect.arrayContaining(['webhook.ping', 'project.created', 'thing.created'])
+    );
+  });
+
+  it('the chassis’s own project subject reads list: false', () => {
+    const wire = catalogToWire(buildWebhookCatalog(undefined));
+    expect(wire.subjects).toEqual([
+      { key: 'project', field: 'projectId', description: expect.any(String), list: false }
+    ]);
+  });
+});

package/test/unit/webhook-env.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest';
+import { buildEnvSchema } from '../../src/env.js';
+
+/**
+ * The webhooks' environment (PRDCT-3482, verifier round 1, G8): the switch
+ * that opens private networks is refused on the cloud edition, by name, and
+ * the delivery log's retention defaults to thirty days.
+ */
+
+const schema = buildEnvSchema({ version: '0.0.0-test' });
+const BASE = { DATABASE_URL: 'postgres://u:p@localhost:5432/db' };
+const CLOUD = {
+  ...BASE,
+  EDITION: 'cloud',
+  HUB_ISSUER_URL: 'https://account.example.com',
+  HUB_CLIENT_ID: 'tool-client',
+  HUB_CLIENT_SECRET: 'a-hub-client-secret-of-length'
+};
+
+const issuesOf = (source: Record<string, string>) => {
+  const result = schema.safeParse(source);
+  return result.success
+    ? []
+    : result.error.issues.map((i) => ({ key: i.path.join('.'), message: i.message }));
+};
+
+describe('WEBHOOKS_ALLOW_PRIVATE_NETWORKS', () => {
+  it('is refused on EDITION=cloud, naming the key', () => {
+    const issues = issuesOf({ ...CLOUD, WEBHOOKS_ALLOW_PRIVATE_NETWORKS: 'true' });
+    expect(issues).toEqual([
+      { key: 'WEBHOOKS_ALLOW_PRIVATE_NETWORKS', message: expect.stringMatching(/never on EDITION=cloud/) }
+    ]);
+  });
+
+  it('a cloud env without it parses (the refusal is the switch, not the edition)', () => {
+    expect(issuesOf(CLOUD)).toEqual([]);
+    expect(
+      schema.parse({ ...CLOUD, WEBHOOKS_ALLOW_PRIVATE_NETWORKS: 'false' }).WEBHOOKS_ALLOW_PRIVATE_NETWORKS
+    ).toBe(false);
+  });
+
+  it('parses true on oss, and defaults to false', () => {
+    expect(
+      schema.parse({ ...BASE, WEBHOOKS_ALLOW_PRIVATE_NETWORKS: 'true' }).WEBHOOKS_ALLOW_PRIVATE_NETWORKS
+    ).toBe(true);
+    expect(schema.parse(BASE).WEBHOOKS_ALLOW_PRIVATE_NETWORKS).toBe(false);
+  });
+});
+
+describe('WEBHOOK_DELIVERY_RETENTION_DAYS', () => {
+  it('defaults to 30, takes 0 (keep forever), refuses a negative', () => {
+    expect(schema.parse(BASE).WEBHOOK_DELIVERY_RETENTION_DAYS).toBe(30);
+    expect(
+      schema.parse({ ...BASE, WEBHOOK_DELIVERY_RETENTION_DAYS: '0' }).WEBHOOK_DELIVERY_RETENTION_DAYS
+    ).toBe(0);
+    expect(issuesOf({ ...BASE, WEBHOOK_DELIVERY_RETENTION_DAYS: '-1' }).map((i) => i.key)).toEqual([
+      'WEBHOOK_DELIVERY_RETENTION_DAYS'
+    ]);
+  });
+});

package/test/unit/webhook-jobs.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { Logger } from '../../src/logger.js';
+import { webhookJobs } from '../../src/webhooks/jobs.js';
+import {
+  MAX_IN_FLIGHT_PER_ENDPOINT,
+  WEBHOOK_DELIVERIES_HELD_QUEUE,
+  WEBHOOK_DELIVERIES_QUEUE,
+  WEBHOOK_EVENTS_QUEUE,
+  WEBHOOK_PURGE_QUEUE,
+  WebhookDeliveryDeferred,
+  WebhookDeliveryFailed,
+  type WebhookService
+} from '../../src/webhooks/service.js';
+
+/**
+ * The webhooks' queue declarations (verifier round 2, MJ-R2-1): the two
+ * queues that must drain a burst poll every half second, the delivery queue
+ * runs eight pollers, and an attempt the per-endpoint bound defers goes back
+ * in the queue with its retry budget untouched (the job completes), while a
+ * failed attempt still throws so pg-boss retries it.
+ */
+
+const logger = { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() } as unknown as Logger;
+
+function fakeService(attempt: (id: string) => Promise<unknown>) {
+  const requeue = vi.fn(async (_id: string, _inSeconds: number) => undefined);
+  const service = {
+    dials: { retryLimit: 2, retryDelaySeconds: 1 },
+    attempt: vi.fn(async (id: string) => attempt(id)),
+    requeue,
+    fanOut: vi.fn(async () => 0),
+    hold: vi.fn(async () => undefined),
+    purge: vi.fn(async () => 0)
+  } as unknown as WebhookService;
+  return { service, requeue };
+}
+
+const jobOf = (service: WebhookService, queue: string) => {
+  const job = webhookJobs(service, logger, 30).find((j) => j.queue === queue);
+  expect(job, `no declaration for ${queue}`).toBeDefined();
+  return job!;
+};
+
+const META = { id: 'job-1', queue: WEBHOOK_DELIVERIES_QUEUE, key: null };
+
+describe('webhookJobs', () => {
+  it('the fan-out and the delivery queues poll every half second; the held queue and the purge keep the default', () => {
+    const { service } = fakeService(async () => null);
+    const byQueue = new Map(webhookJobs(service, logger, 30).map((j) => [j.queue, j]));
+    expect(byQueue.get(WEBHOOK_EVENTS_QUEUE)).toMatchObject({ concurrency: 2, pollingIntervalSeconds: 0.5 });
+    expect(byQueue.get(WEBHOOK_DELIVERIES_QUEUE)).toMatchObject({
+      concurrency: 8,
+      pollingIntervalSeconds: 0.5
+    });
+    expect(byQueue.get(WEBHOOK_DELIVERIES_HELD_QUEUE)?.pollingIntervalSeconds).toBeUndefined();
+    expect(byQueue.get(WEBHOOK_PURGE_QUEUE)?.pollingIntervalSeconds).toBeUndefined();
+  });
+
+  it('the bound leaves room for other endpoints: two per endpoint of the eight pollers', () => {
+    expect(MAX_IN_FLIGHT_PER_ENDPOINT).toBe(2);
+    const { service } = fakeService(async () => null);
+    expect(jobOf(service, WEBHOOK_DELIVERIES_QUEUE).concurrency).toBeGreaterThan(MAX_IN_FLIGHT_PER_ENDPOINT);
+  });
+
+  it('a deferred attempt is put back in the queue two seconds later and the job completes', async () => {
+    const { service, requeue } = fakeService(async (id) => {
+      throw new WebhookDeliveryDeferred(id);
+    });
+    const job = jobOf(service, WEBHOOK_DELIVERIES_QUEUE);
+    vi.mocked(logger.warn).mockClear();
+    await expect(job.handler({ deliveryId: 'd-1' }, META)).resolves.toBeUndefined();
+    expect(requeue).toHaveBeenCalledTimes(1);
+    expect(requeue).toHaveBeenCalledWith('d-1', 2);
+    expect(logger.warn).not.toHaveBeenCalled();
+  });
+
+  it('a failed attempt throws so pg-boss retries it, and is never requeued by hand', async () => {
+    const { service, requeue } = fakeService(async (id) => {
+      throw new WebhookDeliveryFailed(id, 'HTTP 500');
+    });
+    const job = jobOf(service, WEBHOOK_DELIVERIES_QUEUE);
+    await expect(job.handler({ deliveryId: 'd-2' }, META)).rejects.toBeInstanceOf(WebhookDeliveryFailed);
+    expect(requeue).not.toHaveBeenCalled();
+  });
+
+  it('a delivered attempt neither throws nor requeues', async () => {
+    const { service, requeue } = fakeService(async () => ({ status: 'delivered' }));
+    const job = jobOf(service, WEBHOOK_DELIVERIES_QUEUE);
+    await expect(job.handler({ deliveryId: 'd-3' }, META)).resolves.toBeUndefined();
+    expect(requeue).not.toHaveBeenCalled();
+  });
+});