@antasphere/chassis-contract 1.0.2 → 1.2.0

package/src/routes/index.ts

@@ -38,6 +38,7 @@ import {
 } from '../schemas/cli-auth.js';
 import { ssoCliConnectSchema } from '../schemas/sso-connect.js';
 import { ssoLogoutResponseSchema } from '../schemas/sso-logout.js';
+import { cliPackageRequestSchema } from '../schemas/cli-package.js';
 import {
   breakGlassClaimOwnershipRequestSchema,
   breakGlassClaimOwnershipSchema,
@@ -77,6 +78,22 @@ import {
   teamsListSchema,
   teamUpdateSchema
 } from '../schemas/teams.js';
+import {
+  webhookCatalogSchema,
+  webhookDeliveriesListQuerySchema,
+  webhookDeliveriesListSchema,
+  webhookDeliveryParamsSchema,
+  webhookDeliverySchema,
+  webhookEndpointCreatedSchema,
+  webhookEndpointCreateSchema,
+  webhookEndpointSchema,
+  webhookEndpointUpdateSchema,
+  webhookParamsSchema,
+  webhookSecretRotatedSchema,
+  webhooksListQuerySchema,
+  webhooksListSchema,
+  webhookTestResultSchema
+} from '../schemas/webhooks.js';
 
 /**
  * Server-only entry: route contracts for @hono/zod-openapi. Importing this
@@ -135,6 +152,55 @@ export const instanceRoute = createRoute({
   }
 });
 
+// ── The tool's own CLI package (cloud edition only, PRDCT-3312) ─────────────
+// Reached with NO credential but the hub exchange token in the body (the
+// `/sso/cli-connect` token, burned in the same one-time ledger). NOT in
+// PUBLIC_API_PATHS and unlisted in the machine scope allowlist on purpose: a
+// request without a credential reaches the handler, a key or an OAuth bearer
+// meets 403 endpoint_not_allowed before it. The route exists ONLY on
+// EDITION=cloud; oss answers the plain 404 terminator. Rate-limited on the
+// CLI-connect wall, per client address.
+export const cliPackageRoute = createRoute({
+  method: 'post',
+  path: '/cli/package',
+  tags: ['cli'],
+  summary: "Download the tool's own CLI package (cloud edition) on a hub-minted exchange token",
+  description:
+    'Answers the gzipped tarball the release packed (the output of `pnpm pack` of the tool CLI), named ' +
+    "as npm names it, to a member the hub lets into the tool. The client first asks the hub's " +
+    '`POST /api/v1/sso/tool-token` for an exchange token for this instance, then posts it here as ' +
+    '`{ token }`. The refusals a client meets, and what each one means: ' +
+    "the hub's 403 `tool_access_denied` on the tool-token step (this person has no access to this tool " +
+    'on the hub); 401 `invalid_token` here (bad signature, issuer, audience or purpose, expired, or ' +
+    'already used: run the exchange again, each token works once, here or at `/sso/cli-connect`); ' +
+    '404 `cli_not_packaged` (the instance was released without its CLI package); a plain 404 ' +
+    '`not_found` (a self-hosted instance, or a chassis from before this route: the path is not ' +
+    'registered); 403 `endpoint_not_allowed` (an API key or an OAuth bearer was sent: this route takes ' +
+    'the exchange token in its body and never a machine credential).',
+  request: { body: jsonRequestBody(cliPackageRequestSchema, 'The hub exchange token') },
+  responses: {
+    200: {
+      description: 'The CLI package, a gzipped tarball (application/gzip)',
+      content: { 'application/gzip': { schema: { type: 'string', format: 'binary' } } }
+    },
+    400: jsonBody(apiErrorSchema, 'Validation error'),
+    401: jsonBody(
+      apiErrorSchema,
+      'invalid_token: bad signature/iss/aud/purpose, expired, or an already used jti (here or at /sso/cli-connect)'
+    ),
+    403: jsonBody(
+      apiErrorSchema,
+      'endpoint_not_allowed: a machine credential (API key or OAuth bearer) was sent'
+    ),
+    404: jsonBody(
+      apiErrorSchema,
+      'cli_not_packaged: the instance was released without its CLI package (a plain not_found: not a cloud instance, or a chassis without the route)'
+    ),
+    429: errorResponses[429],
+    500: errorResponses[500]
+  }
+});
+
 export const setupRoute = createRoute({
   method: 'post',
   path: '/setup',
@@ -630,6 +696,173 @@ export const teamMemberRemoveRoute = createRoute({
   responses: { 200: jsonBody(teamMemberSchema, 'The removed team member'), ...teamErrors }
 });
 
+// ── Webhooks ─────────────────────────────────────────────────────────────────
+// Outbound webhooks (PRDCT-3482): URLs a workspace registers to be told, by a
+// signed POST, when one of the tool's events happens. Owners and admins only,
+// on both editions; a guest gets 403 `guest_forbidden`, a session a demo pass
+// opened 403 `demo_session`. The signing secret appears in two answers only,
+// the create and the rotation, and never again.
+
+/** The refusals every webhook route shares (the writes add their own). */
+const webhookErrors = {
+  401: errorResponses[401],
+  403: jsonBody(apiErrorSchema, 'guest_forbidden, forbidden (not an owner or admin), or demo_session'),
+  404: errorResponses[404]
+};
+const urlRefused400 = jsonBody(
+  apiErrorSchema,
+  'Validation error, url_refused (the address is not one this instance may deliver to: a private network, a port, the scheme), unknown_event (a type or family the catalog does not declare) or unknown_subject (a filter key the catalog does not declare)'
+);
+
+export const webhooksListRoute = createRoute({
+  method: 'get',
+  path: '/webhooks',
+  tags: ['webhooks'],
+  summary: "List the workspace's webhook endpoints (owner or admin; cursor-paginated)",
+  request: { query: webhooksListQuerySchema },
+  responses: {
+    200: jsonBody(webhooksListSchema, 'Webhook endpoints, newest first'),
+    400: errorResponses[400],
+    401: errorResponses[401],
+    403: webhookErrors[403]
+  }
+});
+
+export const webhookCatalogRoute = createRoute({
+  method: 'get',
+  path: '/webhooks/events',
+  tags: ['webhooks'],
+  summary:
+    'The event catalog: every event type this instance can deliver, its subjects and the JSON Schema of its data',
+  responses: {
+    200: jsonBody(webhookCatalogSchema, 'The subjects and the event types'),
+    401: errorResponses[401],
+    403: jsonBody(apiErrorSchema, 'guest_forbidden (every other member reads the catalog)')
+  }
+});
+
+export const webhookCreateRoute = createRoute({
+  method: 'post',
+  path: '/webhooks',
+  tags: ['webhooks'],
+  summary: 'Register a webhook endpoint (owner or admin); its signing secret is shown once, here',
+  description:
+    'An endpoint subscribes to `events`: exact types (`thing.created`), families (`thing.*`) or everything (`*`), ' +
+    'checked against the catalog (`GET /webhooks/events`). `filters` narrows the subscription by subject: a ' +
+    'subject key mapped to the ids it accepts, AND across keys, OR within a key; an event that does not carry a ' +
+    "filtered subject does not match. Every delivery is signed with the endpoint's secret (`whsec_…`), returned " +
+    'in this answer only: store it now, it is never shown again (`POST /webhooks/{id}/rotate-secret` makes a new one).',
+  request: {
+    body: jsonRequestBody(webhookEndpointCreateSchema, 'The URL, what it subscribes to, its filters')
+  },
+  responses: {
+    201: jsonBody(webhookEndpointCreatedSchema, 'The created endpoint, with its signing secret (shown once)'),
+    400: urlRefused400,
+    ...webhookErrors,
+    403: jsonBody(
+      apiErrorSchema,
+      'guest_forbidden, forbidden (not an owner or admin), demo_session, or plan_required'
+    )
+  }
+});
+
+export const webhookGetRoute = createRoute({
+  method: 'get',
+  path: '/webhooks/{id}',
+  tags: ['webhooks'],
+  summary: 'Read one webhook endpoint (owner or admin)',
+  request: { params: webhookParamsSchema },
+  responses: { 200: jsonBody(webhookEndpointSchema, 'The endpoint'), ...webhookErrors }
+});
+
+export const webhookUpdateRoute = createRoute({
+  method: 'patch',
+  path: '/webhooks/{id}',
+  tags: ['webhooks'],
+  summary: "Change an endpoint's URL, description, events, filters or enabled switch (owner or admin)",
+  description: 'Only the fields named change; at least one is required.',
+  request: {
+    params: webhookParamsSchema,
+    body: jsonRequestBody(webhookEndpointUpdateSchema, 'Fields to change')
+  },
+  responses: {
+    200: jsonBody(webhookEndpointSchema, 'The endpoint as it now is'),
+    400: urlRefused400,
+    ...webhookErrors
+  }
+});
+
+export const webhookDeleteRoute = createRoute({
+  method: 'delete',
+  path: '/webhooks/{id}',
+  tags: ['webhooks'],
+  summary: 'Delete a webhook endpoint and its delivery history (owner or admin)',
+  request: { params: webhookParamsSchema },
+  responses: {
+    200: jsonBody(webhookEndpointSchema, 'The deleted endpoint (final snapshot)'),
+    ...webhookErrors
+  }
+});
+
+export const webhookRotateSecretRoute = createRoute({
+  method: 'post',
+  path: '/webhooks/{id}/rotate-secret',
+  tags: ['webhooks'],
+  summary: "Replace an endpoint's signing secret (owner or admin); the new one is shown once, here",
+  description:
+    'The previous secret keeps signing until `previousSecretExpiresAt`, so a receiver can switch keys without a gap.',
+  request: { params: webhookParamsSchema },
+  responses: {
+    200: jsonBody(webhookSecretRotatedSchema, 'The endpoint, with its new signing secret (shown once)'),
+    ...webhookErrors
+  }
+});
+
+export const webhookTestRoute = createRoute({
+  method: 'post',
+  path: '/webhooks/{id}/test',
+  tags: ['webhooks'],
+  summary: 'Send a signed webhook.ping to the endpoint now and report the outcome',
+  request: { params: webhookParamsSchema },
+  responses: {
+    200: jsonBody(webhookTestResultSchema, 'The ping, attempted inline: its outcome is on the delivery'),
+    ...webhookErrors
+  }
+});
+
+export const webhookDeliveriesListRoute = createRoute({
+  method: 'get',
+  path: '/webhooks/{id}/deliveries',
+  tags: ['webhooks'],
+  summary: "List an endpoint's deliveries, optionally by status (owner or admin; cursor-paginated)",
+  request: { params: webhookParamsSchema, query: webhookDeliveriesListQuerySchema },
+  responses: {
+    200: jsonBody(webhookDeliveriesListSchema, 'Deliveries, newest first'),
+    400: errorResponses[400],
+    ...webhookErrors
+  }
+});
+
+export const webhookDeliveryGetRoute = createRoute({
+  method: 'get',
+  path: '/webhooks/{id}/deliveries/{deliveryId}',
+  tags: ['webhooks'],
+  summary: 'Read one delivery, with the payload as sent and its latest attempt (owner or admin)',
+  request: { params: webhookDeliveryParamsSchema },
+  responses: { 200: jsonBody(webhookDeliverySchema, 'The delivery'), ...webhookErrors }
+});
+
+export const webhookRedeliverRoute = createRoute({
+  method: 'post',
+  path: '/webhooks/{id}/deliveries/{deliveryId}/redeliver',
+  tags: ['webhooks'],
+  summary: 'Queue the same event again for this endpoint, as a new delivery',
+  description:
+    "The new delivery carries the same `eventId`, the receiver's dedupe key, and the same payload.",
+  request: { params: webhookDeliveryParamsSchema },
+  responses: { 201: jsonBody(webhookDeliverySchema, 'The new delivery, queued'), ...webhookErrors }
+});
+
 // ── Demo passes ──────────────────────────────────────────────────────────────
 // A link an owner mints so that one member is signed in without a password,
 // for a demonstration (the demo pass spec). The three routes are registered

package/src/schemas/cli-package.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+
+/**
+ * The tool's own CLI package (cloud edition only, PRDCT-3312):
+ *
+ *   POST /cli/package — download the CLI package the release packed, on a
+ *   hub-minted 120 s exchange JWT
+ *
+ * The same token the hub's `POST /sso/tool-token` mints for
+ * `/sso/cli-connect` (`aud` = THIS instance's resource URL,
+ * `purpose: 'sso-connect'`, unique `jti`), consumed one-time-use in the same
+ * ledger: a token spent here mints no key at `/sso/cli-connect`, and the
+ * other way round. The hub mints it only for a member it lets into the
+ * tool, which is what this route rests on. The token rides in the BODY and
+ * never in `Authorization`: a machine credential on the path meets the
+ * scope gate's 403 `endpoint_not_allowed`.
+ */
+export const cliPackageRequestSchema = z.object({
+  /** The hub-minted exchange JWT (compact JWS — three base64url segments). */
+  token: z.string().min(1)
+});
+export type CliPackageRequest = z.infer<typeof cliPackageRequestSchema>;

package/src/schemas/instance.ts

@@ -58,6 +58,14 @@ export const instanceInfoSchema = z.object({
    * false, so the self-hosted discovery bytes are unchanged.
    */
   restricted: z.boolean().optional(),
+  /**
+   * The tool's own CLI package (cloud edition, PRDCT-3312): present only when
+   * the instance was released with it (`CLI_PACKAGE_DIR`), naming the npm
+   * package `POST /cli/package` serves and its version. The `team` command
+   * reads it to know what it installs and whether to update. ABSENT
+   * otherwise, so older discovery bytes are unchanged.
+   */
+  cli: z.object({ name: z.string(), version: z.string() }).optional(),
   /**
    * What this version of the tool declares for the billing rail (its priced
    * actions with their default credits, its limits and features per tier):

package/src/schemas/webhooks.ts

@@ -0,0 +1,226 @@
+import { z } from 'zod';
+import { cursorPageQuerySchema, hasControlChars, plainText } from './common.js';
+
+/**
+ * Outbound webhooks (PRDCT-3482): a URL a workspace registers to be told, by a
+ * signed POST, when something happens to the tool's own subjects. The tool
+ * declares the event types and the subjects they carry (the catalog); the
+ * chassis stores the endpoints, matches the events against them, signs and
+ * delivers, and keeps each delivery's history. Owners and admins manage them.
+ *
+ * The signing secret is NEVER part of an endpoint's shape: it is shown once,
+ * at creation and at each rotation, and stored sealed.
+ */
+
+/**
+ * What an endpoint subscribes to: an exact event type (`thing.created`), a
+ * family (`thing.*`) or everything (`*`).
+ */
+export const webhookEventPatternSchema = z
+  .string()
+  .max(80)
+  .regex(
+    /^(\*|[a-z][a-z0-9_]*\.(\*|[a-z][a-z0-9_]*))$/,
+    'an event type (thing.created), a family (thing.*) or everything (*)'
+  );
+
+/** A subject key of the catalog (`thing`, `project`): lowercase, digits and underscores. */
+export const webhookSubjectKeySchema = z
+  .string()
+  .max(40)
+  .regex(/^[a-z][a-z0-9_]*$/, 'lowercase letters, digits and underscores, starting with a letter');
+
+/**
+ * Narrows a subscription by subject: a subject key mapped to the ids it
+ * accepts. AND across keys, OR within a key; an event that does not carry a
+ * filtered subject does not match. An empty object filters nothing.
+ */
+export const webhookFiltersSchema = z
+  .record(webhookSubjectKeySchema, z.array(plainText(1, 200)).min(1).max(100))
+  .refine((v) => Object.keys(v).length <= 10, { error: 'at most 10 subject keys' })
+  .describe(
+    'Subject key → ids; AND across keys, OR within a key; an event that does not carry a filtered subject does not match'
+  );
+export type WebhookFilters = z.infer<typeof webhookFiltersSchema>;
+
+/**
+ * The WHATWG URL parser, present in every runtime this contract runs in (Node,
+ * the browser); typed here because the package compiles without DOM or Node
+ * types, to stay runtime-neutral.
+ */
+type UrlParts = { protocol: string; username: string; password: string };
+const UrlParser = (globalThis as unknown as { URL: new (input: string) => UrlParts }).URL;
+
+function isHttpUrlWithoutCredentials(value: string): boolean {
+  let parsed: UrlParts;
+  try {
+    parsed = new UrlParser(value);
+  } catch {
+    return false;
+  }
+  return (
+    (parsed.protocol === 'http:' || parsed.protocol === 'https:') &&
+    parsed.username === '' &&
+    parsed.password === ''
+  );
+}
+
+/**
+ * Where the deliveries go: an http or https URL without credentials. Whitespace
+ * and control characters are refused outright, because the URL parser silently
+ * strips tabs and newlines, so the stored string would not be the address
+ * delivered to. The address rules (ports, private networks, https on the cloud
+ * edition) are the server's, answered `url_refused`.
+ */
+export const webhookUrlSchema = z
+  .string()
+  .max(2048)
+  .refine((v) => !/\s/.test(v) && !hasControlChars(v), {
+    error: 'must not contain whitespace or control characters',
+    abort: true
+  })
+  .refine(isHttpUrlWithoutCredentials, { error: 'an http or https URL without credentials' });
+
+export const webhookDeliveryStatusSchema = z.enum(['pending', 'delivered', 'failed', 'held']);
+export type WebhookDeliveryStatus = z.infer<typeof webhookDeliveryStatusSchema>;
+
+export const webhookEndpointSchema = z.object({
+  id: z.string(),
+  url: z.string(),
+  description: z.string(),
+  events: z.array(z.string()),
+  filters: z.record(z.string(), z.array(z.string())),
+  enabled: z.boolean(),
+  createdBy: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  /** Set with `disabledReason` when the endpoint was switched off after failing too long. */
+  disabledAt: z.string().nullable(),
+  disabledReason: z.string().nullable(),
+  consecutiveFailures: z.number().int(),
+  lastDeliveryAt: z.string().nullable(),
+  lastDeliveryStatus: z.enum(['delivered', 'failed']).nullable(),
+  /** During a rotation, the previous secret keeps signing until this date. */
+  previousSecretExpiresAt: z.string().nullable()
+});
+export type WebhookEndpoint = z.infer<typeof webhookEndpointSchema>;
+
+/** The endpoint as created, with its signing secret (`whsec_…`), shown ONCE. */
+export const webhookEndpointCreatedSchema = webhookEndpointSchema.extend({
+  secret: z.string()
+});
+export type WebhookEndpointCreated = z.infer<typeof webhookEndpointCreatedSchema>;
+
+/**
+ * The endpoint after a rotation, with its new secret, shown ONCE; the previous
+ * secret keeps signing until `previousSecretExpiresAt`.
+ */
+export const webhookSecretRotatedSchema = webhookEndpointSchema.extend({
+  secret: z.string(),
+  previousSecretExpiresAt: z.string()
+});
+export type WebhookSecretRotated = z.infer<typeof webhookSecretRotatedSchema>;
+
+const webhookDescriptionSchema = plainText(0, 200);
+const webhookEventsSchema = z.array(webhookEventPatternSchema).min(1).max(50);
+
+export const webhookEndpointCreateSchema = z.object({
+  url: webhookUrlSchema,
+  description: webhookDescriptionSchema.default(''),
+  events: webhookEventsSchema,
+  filters: webhookFiltersSchema.default({}),
+  enabled: z.boolean().default(true)
+});
+/** The INPUT shape: `description`, `filters` and `enabled` may be left out. */
+export type WebhookEndpointCreate = z.input<typeof webhookEndpointCreateSchema>;
+
+/** Every field optional, none defaulted (a PATCH never resets what it does not name). */
+export const webhookEndpointUpdateSchema = z
+  .object({
+    url: webhookUrlSchema.optional(),
+    description: webhookDescriptionSchema.optional(),
+    events: webhookEventsSchema.optional(),
+    filters: webhookFiltersSchema.optional(),
+    enabled: z.boolean().optional()
+  })
+  .refine((b) => Object.values(b).some((v) => v !== undefined), { error: 'nothing to change' });
+export type WebhookEndpointUpdate = z.infer<typeof webhookEndpointUpdateSchema>;
+
+export const webhooksListSchema = z.object({
+  webhooks: z.array(webhookEndpointSchema),
+  nextCursor: z.string().nullable()
+});
+export type WebhooksList = z.infer<typeof webhooksListSchema>;
+
+export const webhooksListQuerySchema = cursorPageQuerySchema;
+
+/**
+ * One event sent to one endpoint, with its attempts. `eventId` is the
+ * receiver's dedupe key, the same on every attempt and on a redelivery;
+ * `lastStatusCode` and `lastError` describe the latest attempt only;
+ * `payload` is the envelope as sent.
+ */
+export const webhookDeliverySchema = z.object({
+  id: z.string(),
+  endpointId: z.string(),
+  eventId: z.string(),
+  eventType: z.string(),
+  status: webhookDeliveryStatusSchema,
+  attempt: z.number().int(),
+  lastStatusCode: z.number().int().nullable(),
+  lastError: z.string().nullable(),
+  nextAttemptAt: z.string().nullable(),
+  deliveredAt: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  payload: z.record(z.string(), z.unknown())
+});
+export type WebhookDelivery = z.infer<typeof webhookDeliverySchema>;
+
+export const webhookDeliveriesListSchema = z.object({
+  deliveries: z.array(webhookDeliverySchema),
+  nextCursor: z.string().nullable()
+});
+export type WebhookDeliveriesList = z.infer<typeof webhookDeliveriesListSchema>;
+
+export const webhookDeliveriesListQuerySchema = cursorPageQuerySchema.extend({
+  status: webhookDeliveryStatusSchema.optional()
+});
+
+/** The `webhook.ping` attempted inline: its outcome is on the delivery row. */
+export const webhookTestResultSchema = z.object({
+  delivery: webhookDeliverySchema
+});
+export type WebhookTestResult = z.infer<typeof webhookTestResultSchema>;
+
+/** A subject events can carry and endpoints can filter on: its key (what a filter names), the field of the envelope's `subjects` its value is written under (one id or a list of ids). */
+export const webhookCatalogSubjectSchema = z.object({
+  key: z.string(),
+  field: z.string(),
+  description: z.string(),
+  /** The value under `field` is always a list of ids (`projectIds`); else always one id. */
+  list: z.boolean()
+});
+export type WebhookCatalogSubject = z.infer<typeof webhookCatalogSubjectSchema>;
+
+export const webhookCatalogEventSchema = z.object({
+  type: z.string(),
+  description: z.string(),
+  /** The subject keys this event carries (what a filter can match it on). */
+  subjects: z.array(z.string()),
+  /** The JSON Schema of the event's `data`. */
+  schema: z.record(z.string(), z.unknown())
+});
+export type WebhookCatalogEvent = z.infer<typeof webhookCatalogEventSchema>;
+
+export const webhookCatalogSchema = z.object({
+  subjects: z.array(webhookCatalogSubjectSchema),
+  events: z.array(webhookCatalogEventSchema)
+});
+export type WebhookCatalog = z.infer<typeof webhookCatalogSchema>;
+
+/** `{id}` the endpoint (a uuid, as every `{id}` path param). */
+export const webhookParamsSchema = z.object({ id: z.uuid() });
+
+/** `{id}` the endpoint, `{deliveryId}` one of its deliveries: both uuids. */
+export const webhookDeliveryParamsSchema = webhookParamsSchema.extend({ deliveryId: z.uuid() });

package/test/webhooks.test.ts

@@ -0,0 +1,141 @@
+import { describe, expect, it } from 'vitest';
+import {
+  webhookDeliveriesListQuerySchema,
+  webhookDeliveryParamsSchema,
+  webhookEndpointCreateSchema,
+  webhookEndpointCreatedSchema,
+  webhookEndpointSchema,
+  webhookEndpointUpdateSchema,
+  webhookEventPatternSchema,
+  webhookFiltersSchema,
+  webhookUrlSchema
+} from '../src/index.js';
+import {
+  webhookCatalogRoute,
+  webhookCreateRoute,
+  webhookDeliveryGetRoute,
+  webhookRedeliverRoute
+} from '../src/routes/index.js';
+
+const ok = (schema: { safeParse: (v: unknown) => { success: boolean } }, v: unknown) =>
+  schema.safeParse(v).success;
+
+describe('webhook event patterns', () => {
+  it('takes an exact type, a family or everything', () => {
+    for (const v of ['thing.created', 'thing.*', '*', 'some_thing.status_changed', 'a1.b2']) {
+      expect(ok(webhookEventPatternSchema, v), v).toBe(true);
+    }
+  });
+
+  it('refuses anything else', () => {
+    for (const v of [
+      '',
+      'thing',
+      '*.created',
+      'thing.created.extra',
+      'Thing.created',
+      '1thing.x',
+      'thing.',
+      '**',
+      `a.${'b'.repeat(80)}`
+    ]) {
+      expect(ok(webhookEventPatternSchema, v), v).toBe(false);
+    }
+  });
+});
+
+describe('webhook filters', () => {
+  it('maps subject keys to non-empty id lists', () => {
+    expect(ok(webhookFiltersSchema, {})).toBe(true);
+    expect(ok(webhookFiltersSchema, { thing: ['a', 'b'], project: ['p'] })).toBe(true);
+  });
+
+  it('refuses a bad key, an empty list, an empty id, a control character and more than 10 keys', () => {
+    expect(ok(webhookFiltersSchema, { Thing: ['a'] })).toBe(false);
+    expect(ok(webhookFiltersSchema, { thing: [] })).toBe(false);
+    expect(ok(webhookFiltersSchema, { thing: [''] })).toBe(false);
+    expect(ok(webhookFiltersSchema, { thing: ['a\u0000'] })).toBe(false);
+    expect(ok(webhookFiltersSchema, { thing: Array.from({ length: 101 }, (_, i) => `id${i}`) })).toBe(false);
+    const eleven = Object.fromEntries(Array.from({ length: 11 }, (_, i) => [`k${i}`, ['x']]));
+    expect(ok(webhookFiltersSchema, eleven)).toBe(false);
+    const ten = Object.fromEntries(Array.from({ length: 10 }, (_, i) => [`k${i}`, ['x']]));
+    expect(ok(webhookFiltersSchema, ten)).toBe(true);
+  });
+});
+
+describe('webhook URL', () => {
+  it('takes http and https URLs', () => {
+    expect(ok(webhookUrlSchema, 'https://example.com/hooks')).toBe(true);
+    expect(ok(webhookUrlSchema, 'http://example.com:8080/x?y=1')).toBe(true);
+  });
+
+  it('refuses another scheme, credentials, whitespace and a non-URL', () => {
+    for (const v of [
+      'ftp://example.com',
+      'javascript:alert(1)',
+      'https://user:pass@example.com',
+      'https://user@example.com',
+      'https://example.com/a\nb',
+      ' https://example.com',
+      'example.com',
+      `https://example.com/${'a'.repeat(2048)}`
+    ]) {
+      expect(ok(webhookUrlSchema, v), v).toBe(false);
+    }
+  });
+});
+
+describe('webhook endpoint create and update', () => {
+  it('fills the defaults on create', () => {
+    const parsed = webhookEndpointCreateSchema.parse({ url: 'https://example.com', events: ['thing.*'] });
+    expect(parsed).toEqual({
+      url: 'https://example.com',
+      description: '',
+      events: ['thing.*'],
+      filters: {},
+      enabled: true
+    });
+  });
+
+  it('needs at least one event, at most 50', () => {
+    expect(ok(webhookEndpointCreateSchema, { url: 'https://example.com', events: [] })).toBe(false);
+    expect(
+      ok(webhookEndpointCreateSchema, { url: 'https://example.com', events: Array(51).fill('thing.created') })
+    ).toBe(false);
+  });
+
+  it('defaults nothing on update and refuses an empty change', () => {
+    expect(webhookEndpointUpdateSchema.parse({ enabled: false })).toEqual({ enabled: false });
+    expect(ok(webhookEndpointUpdateSchema, {})).toBe(false);
+  });
+});
+
+describe('the signing secret', () => {
+  it('is never part of an endpoint, only of the created answer', () => {
+    expect('secret' in webhookEndpointSchema.shape).toBe(false);
+    expect('secret' in webhookEndpointCreatedSchema.shape).toBe(true);
+  });
+});
+
+describe('webhook params and queries', () => {
+  it('takes uuids only', () => {
+    const id = '00000000-0000-4000-8000-000000000000';
+    expect(ok(webhookDeliveryParamsSchema, { id, deliveryId: id })).toBe(true);
+    expect(ok(webhookDeliveryParamsSchema, { id, deliveryId: 'nope' })).toBe(false);
+  });
+
+  it('filters deliveries by a known status', () => {
+    expect(ok(webhookDeliveriesListQuerySchema, { status: 'held' })).toBe(true);
+    expect(ok(webhookDeliveriesListQuerySchema, { status: 'lost' })).toBe(false);
+  });
+});
+
+describe('webhook routes', () => {
+  it('declares the paths and the answers the server registers', () => {
+    expect(webhookCatalogRoute.path).toBe('/webhooks/events');
+    expect(Object.keys(webhookCreateRoute.responses)).toContain('201');
+    expect(webhookDeliveryGetRoute.path).toBe('/webhooks/{id}/deliveries/{deliveryId}');
+    expect(webhookRedeliverRoute.method).toBe('post');
+    expect(Object.keys(webhookRedeliverRoute.responses)).toContain('201');
+  });
+});