@antasphere/chassis-server 1.1.0 → 1.2.0

package/src/mcp/webhooks.ts

@@ -0,0 +1,370 @@
+import { z } from 'zod';
+import {
+  webhookDeliveryStatusSchema,
+  webhookEventPatternSchema,
+  webhookFiltersSchema,
+  webhookUrlSchema
+} from '@antasphere/chassis-contract';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { mcpInputs } from './inputs.js';
+import { deny, jsonText, wrapToolErrors, type ErrorHints, type ToolTextResult } from './errors.js';
+import {
+  callApi,
+  forWorkspace,
+  pageQuery,
+  type McpScopes,
+  type McpToolContext,
+  type ScopeCheck
+} from './tool-kit.js';
+import type { McpIdentity } from './server.js';
+
+/**
+ * The eleven WEBHOOK tools (PRDCT-3482), registered by the chassis right after
+ * the team reads and only when the tool declares a webhooks scope: a webhook
+ * is a chassis concept (a URL a workspace registers to be told, by a signed
+ * POST, when one of the tool's events happens), so the tools over it are the
+ * chassis'. Thin shims over the instance's own /api/v1/webhooks called
+ * IN-PROCESS with the caller's bearer forwarded verbatim: the API's
+ * fail-closed scope allowlist, its owner-or-admin rule and its 404 for an
+ * endpoint of another workspace apply unchanged.
+ *
+ * Every tool pre-checks the tool's webhooks scope, except the catalog, which
+ * is a read (every non-guest member's, under the read scope). Nothing here
+ * names a tool, a brand or a domain: the prefix arrives as
+ * `identity.toolPrefix`, the event types as the instance's catalog.
+ */
+
+/** What a webhook IS, opening the descriptions. */
+const WHAT_IS_A_WEBHOOK =
+  'A webhook is a URL an organization registers to be told, by a signed HTTP POST, when something ' +
+  'happens (for example `thing.created`).';
+
+/** Who manages them. */
+const WHO_MANAGES = 'Only an owner or an admin of the organization manages webhooks, reads included.';
+
+/** How the `events` list of an endpoint reads. */
+const EVENT_PATTERNS =
+  'Each entry of `events` is an exact event type (`thing.created`), a family (`thing.*`) or ' +
+  'everything (`*`).';
+
+/**
+ * The webhook code only the webhook routes answer, merged into the instance's
+ * hint table by `composeErrorHints` like the project hints. The codes the
+ * webhook routes SHARE with the rest of the instance (`forbidden`,
+ * `demo_session`, `plan_required`) are worded for webhooks on the webhook
+ * tools alone ({@link webhookToolHints}): in the instance's table they would
+ * misread every other route's refusal.
+ */
+export function webhookErrorHints(toolPrefix: string): ErrorHints {
+  return {
+    url_refused:
+      'This instance does not deliver to that address. Refused: a scheme other than http or https ' +
+      '(https only on the cloud), a URL carrying a user name or password, a port other than the ' +
+      'scheme’s default, and an address that is not on the public internet (localhost, a private or ' +
+      'link-local network), unless the operator of a self-hosted instance opened private networks. ' +
+      `Use a public address of the receiver, then call ${toolPrefix}create_webhook or ` +
+      `${toolPrefix}update_webhook again.`,
+    unknown_event:
+      'One of the `events` entries is not an event type or family this instance delivers. ' +
+      `Read ${toolPrefix}webhook_events for the exact types; a family is its first word plus \`.*\`.`,
+    unknown_subject:
+      'One of the `filters` keys is not a subject this instance declares. ' +
+      `The subject keys are in ${toolPrefix}webhook_events (for example \`project\`).`
+  };
+}
+
+/** The shared codes, worded for the webhook tools only (layered over the instance's table there). */
+function webhookToolHints(toolPrefix: string): ErrorHints {
+  return {
+    forbidden:
+      'Only an owner or an admin of the organization manages webhooks, reads included. Ask one of ' +
+      `them to make the change, or to read the endpoints (${toolPrefix}webhook_events stays open to ` +
+      'every member).',
+    demo_session:
+      'This connection was opened by a demonstration link, which may not set up webhooks. A person ' +
+      'signed in with their own account must do it.',
+    plan_required:
+      'The organization’s plan does not include this — the upgrade link in this message is where a ' +
+      'human raises it; nothing was created.'
+  };
+}
+
+const webhookIdInput = z
+  .uuid()
+  .describe('The webhook id, from the webhook list or the create answer (never its URL).');
+
+const deliveryIdInput = z.uuid().describe('The delivery id, from the delivery list of this webhook.');
+
+const urlInput = webhookUrlSchema.describe(
+  'Where the deliveries go: a public http or https URL without credentials (https only on the cloud).'
+);
+
+const eventsInput = z
+  .array(webhookEventPatternSchema)
+  .min(1)
+  .max(50)
+  .describe(`What the endpoint subscribes to. ${EVENT_PATTERNS}`);
+
+const descriptionInput = z.string().max(200).describe('A short note on what the endpoint is for.');
+
+const filtersInput = webhookFiltersSchema.describe(
+  'Narrows the subscription by subject: a subject key of the catalog (its `subjects[].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.'
+);
+
+const enabledInput = z.boolean().describe('false pauses the deliveries without deleting the endpoint.');
+
+/** Register the eleven webhook tools on a server, after the team reads. */
+export function registerWebhookTools(
+  server: McpServer,
+  ctx: McpToolContext,
+  identity: McpIdentity,
+  scopes: McpScopes,
+  checkScope: ScopeCheck<string>,
+  hints: ErrorHints
+): void {
+  const webhooksScope = scopes.webhooks;
+  if (!webhooksScope) return;
+  const { workspaceInput, cursorInput, limitInput } = mcpInputs(identity);
+  const prefix = identity.toolPrefix;
+  const t = (name: string) => `${prefix}${name}`;
+  const toolHints: ErrorHints = { ...hints, ...webhookToolHints(prefix) };
+
+  const run = (
+    scope: string,
+    workspace: string | undefined,
+    body: (c: McpToolContext) => Promise<unknown>
+  ): Promise<ToolTextResult> => {
+    const denied = checkScope(ctx.principal, scope);
+    if (denied) return Promise.resolve(denied);
+    const c = forWorkspace(ctx, workspace);
+    return wrapToolErrors(async () => jsonText(await body(c)), toolHints);
+  };
+
+  const send = (method: string, value?: unknown): RequestInit =>
+    value === undefined
+      ? { method }
+      : { method, headers: { 'content-type': 'application/json' }, body: JSON.stringify(value) };
+
+  const base = '/api/v1/webhooks';
+
+  // ── The catalog: a read ──────────────────────────────────────────────────
+
+  server.registerTool(
+    t('webhook_events'),
+    {
+      description:
+        `The event catalog of this instance: every event type it delivers to webhooks. ${WHAT_IS_A_WEBHOOK} ` +
+        'Returns { subjects: [{ key, field, description }], events: [{ type, description, subjects, ' +
+        'schema }] } — `subjects` are what an event is about (the key a filter uses, and the field of ' +
+        'the envelope’s `subjects` its value is written under: one id or a list of ids), `schema` is ' +
+        'the JSON Schema of the event’s `data`. ' +
+        `${EVENT_PATTERNS} Read this before ${t('create_webhook')}. Every member may read it.`,
+      inputSchema: { workspace: workspaceInput },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ workspace }) => run(scopes.read, workspace, (c) => callApi(c, `${base}/events`))
+  );
+
+  // ── Endpoints ────────────────────────────────────────────────────────────
+
+  server.registerTool(
+    t('list_webhooks'),
+    {
+      description:
+        `List the organization’s webhooks, newest first. ${WHAT_IS_A_WEBHOOK} ${WHO_MANAGES} Returns ` +
+        '{ webhooks: [{ id, url, description, events, filters, enabled, createdBy, createdAt, ' +
+        'updatedAt, disabledAt, disabledReason, consecutiveFailures, lastDeliveryAt, ' +
+        'lastDeliveryStatus, previousSecretExpiresAt }], nextCursor } — never a signing secret. ' +
+        '`disabledAt` is set when the instance switched the endpoint off after failing too long. When ' +
+        'nextCursor is non-null, call again with cursor set to it.',
+      inputSchema: { workspace: workspaceInput, limit: limitInput, cursor: cursorInput },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ workspace, limit, cursor }) =>
+      run(webhooksScope, workspace, (c) => callApi(c, pageQuery(base, { cursor, limit })))
+  );
+
+  server.registerTool(
+    t('create_webhook'),
+    {
+      description:
+        `Register a webhook — confirm with the user first (URL and events included). ${WHAT_IS_A_WEBHOOK} ` +
+        `${WHO_MANAGES} ${EVENT_PATTERNS} The types are checked against ${t('webhook_events')}, and ` +
+        'the keys of `filters` are the catalog’s subject keys. The answer is the endpoint plus its ' +
+        'signing `secret` (`whsec_…`), shown ONCE and never again: give it to the receiver, which ' +
+        'verifies every delivery’s Standard Webhooks signature with it, and never store it anywhere ' +
+        `else. A lost secret is replaced by ${t('rotate_webhook_secret')}.`,
+      inputSchema: {
+        workspace: workspaceInput,
+        url: urlInput,
+        events: eventsInput,
+        description: descriptionInput.optional(),
+        filters: filtersInput.optional(),
+        enabled: enabledInput.optional()
+      }
+    },
+    async ({ workspace, url, events, description, filters, enabled }) =>
+      run(webhooksScope, workspace, (c) =>
+        callApi(
+          c,
+          base,
+          send('POST', {
+            url,
+            events,
+            ...(description !== undefined ? { description } : {}),
+            ...(filters !== undefined ? { filters } : {}),
+            ...(enabled !== undefined ? { enabled } : {})
+          })
+        )
+      )
+  );
+
+  server.registerTool(
+    t('get_webhook'),
+    {
+      description:
+        `Read one webhook, without its secret. ${WHO_MANAGES} Returns the endpoint as ` +
+        `${t('list_webhooks')} shows it. A webhook of another organization answers not found.`,
+      inputSchema: { workspace: workspaceInput, webhookId: webhookIdInput },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ workspace, webhookId }) =>
+      run(webhooksScope, workspace, (c) => callApi(c, `${base}/${webhookId}`))
+  );
+
+  server.registerTool(
+    t('update_webhook'),
+    {
+      description:
+        'Change a webhook’s URL, description, events, filters or enabled switch — confirm with the ' +
+        `user first. ${WHO_MANAGES} Send only the fields you are changing; \`events\` and \`filters\` ` +
+        `REPLACE the whole list or object. ${EVENT_PATTERNS} Setting enabled back to true resumes an ` +
+        'endpoint the instance switched off. The secret is unchanged. Returns the endpoint as it now is.',
+      inputSchema: {
+        workspace: workspaceInput,
+        webhookId: webhookIdInput,
+        url: urlInput.optional(),
+        description: descriptionInput.optional(),
+        events: eventsInput.optional(),
+        filters: filtersInput.optional(),
+        enabled: enabledInput.optional()
+      }
+    },
+    async ({ workspace, webhookId, url, description, events, filters, enabled }) => {
+      const patch = { url, description, events, filters, enabled };
+      if (Object.values(patch).every((v) => v === undefined)) {
+        return deny(
+          'Nothing to change: pass at least one of url, description, events, filters or enabled. ' +
+            `Read the webhook first (${t('get_webhook')}) if you need its current values.`
+        );
+      }
+      const body = Object.fromEntries(Object.entries(patch).filter(([, v]) => v !== undefined));
+      return run(webhooksScope, workspace, (c) => callApi(c, `${base}/${webhookId}`, send('PATCH', body)));
+    }
+  );
+
+  server.registerTool(
+    t('delete_webhook'),
+    {
+      description:
+        'Delete a webhook and its whole delivery history — confirm with the user first; nothing more ' +
+        `is sent to it and this cannot be undone. ${WHO_MANAGES} To pause it instead, call ` +
+        `${t('update_webhook')} with enabled set to false. Returns a last snapshot of the deleted endpoint.`,
+      inputSchema: { workspace: workspaceInput, webhookId: webhookIdInput },
+      annotations: { destructiveHint: true }
+    },
+    async ({ workspace, webhookId }) =>
+      run(webhooksScope, workspace, (c) => callApi(c, `${base}/${webhookId}`, send('DELETE')))
+  );
+
+  server.registerTool(
+    t('rotate_webhook_secret'),
+    {
+      description:
+        'Replace a webhook’s signing secret — confirm with the user first. ' +
+        `${WHO_MANAGES} The answer is the endpoint plus its new \`secret\` (\`whsec_…\`), shown ONCE: ` +
+        'give it to the receiver and never store it anywhere else. The previous secret keeps signing ' +
+        'until `previousSecretExpiresAt`, so the receiver can switch without a gap.',
+      inputSchema: { workspace: workspaceInput, webhookId: webhookIdInput }
+    },
+    async ({ workspace, webhookId }) =>
+      run(webhooksScope, workspace, (c) => callApi(c, `${base}/${webhookId}/rotate-secret`, send('POST')))
+  );
+
+  server.registerTool(
+    t('test_webhook'),
+    {
+      description:
+        'Send a signed `webhook.ping` to a webhook now, once, and answer how it went. ' +
+        `${WHO_MANAGES} Returns { delivery: { id, eventId, eventType, status, attempt, ` +
+        'lastStatusCode, lastError, … } } — `status` is `delivered` when the receiver answered 2xx, ' +
+        '`failed` otherwise, with `lastStatusCode` and `lastError` saying why. A ping is never retried.',
+      inputSchema: { workspace: workspaceInput, webhookId: webhookIdInput }
+    },
+    async ({ workspace, webhookId }) =>
+      run(webhooksScope, workspace, (c) => callApi(c, `${base}/${webhookId}/test`, send('POST')))
+  );
+
+  // ── Deliveries ───────────────────────────────────────────────────────────
+
+  server.registerTool(
+    t('list_webhook_deliveries'),
+    {
+      description:
+        `List a webhook’s deliveries, newest first, optionally by status. ${WHO_MANAGES} A delivery ` +
+        'is one event sent to this endpoint, with its attempts. Returns { deliveries: [{ id, ' +
+        'endpointId, eventId, eventType, status, attempt, lastStatusCode, lastError, nextAttemptAt, ' +
+        'deliveredAt, createdAt, updatedAt, payload }], nextCursor } — `eventId` is the receiver’s ' +
+        'dedupe key, `lastStatusCode` and `lastError` describe the latest attempt only. When ' +
+        'nextCursor is non-null, call again with cursor set to it.',
+      inputSchema: {
+        workspace: workspaceInput,
+        webhookId: webhookIdInput,
+        status: webhookDeliveryStatusSchema
+          .optional()
+          .describe(
+            '`pending` (waiting for an attempt or a retry), `delivered`, `failed`, or `held` (out of ' +
+              'retries, kept for a redelivery).'
+          ),
+        limit: limitInput,
+        cursor: cursorInput
+      },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ workspace, webhookId, status, limit, cursor }) =>
+      run(webhooksScope, workspace, (c) =>
+        callApi(c, pageQuery(`${base}/${webhookId}/deliveries`, { cursor, limit }, { status }))
+      )
+  );
+
+  server.registerTool(
+    t('get_webhook_delivery'),
+    {
+      description:
+        `Read one delivery of a webhook, with the payload as sent and its latest attempt. ${WHO_MANAGES} ` +
+        `Returns the delivery as ${t('list_webhook_deliveries')} shows it.`,
+      inputSchema: { workspace: workspaceInput, webhookId: webhookIdInput, deliveryId: deliveryIdInput },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ workspace, webhookId, deliveryId }) =>
+      run(webhooksScope, workspace, (c) => callApi(c, `${base}/${webhookId}/deliveries/${deliveryId}`))
+  );
+
+  server.registerTool(
+    t('redeliver_webhook'),
+    {
+      description:
+        'Send one delivery’s event to its webhook again, as a new delivery — confirm with the user ' +
+        `first. ${WHO_MANAGES} The new delivery carries the same \`eventId\` (the receiver’s dedupe key) ` +
+        'and the same payload, and is queued: read its outcome later with ' +
+        `${t('get_webhook_delivery')}. Returns the new delivery.`,
+      inputSchema: { workspace: workspaceInput, webhookId: webhookIdInput, deliveryId: deliveryIdInput }
+    },
+    async ({ workspace, webhookId, deliveryId }) =>
+      run(webhooksScope, workspace, (c) =>
+        callApi(c, `${base}/${webhookId}/deliveries/${deliveryId}/redeliver`, send('POST'))
+      )
+  );
+}

package/src/members/removal.ts

@@ -12,6 +12,7 @@ import {
   workspaceTeamMembers,
   type DbConn
 } from '@antasphere/chassis-db';
+import type { WebhookEmitter } from '../webhooks/service.js';
 
 /**
  * The membership an ADD hangs a right on, re-read inside the add's own
@@ -67,10 +68,29 @@ export interface RemovedMembership {
  * audit record.
  */
 export type MembershipRemovalHook = (
+  tx: DbConn,
+  removed: readonly RemovedMembership[],
+  ctx: MembershipRemovalContext
+) => Promise<Record<string, number>>;
+
+/** What the tool's hook receives beside the rows: the webhooks' emitter, to report what it ended inside the same transaction (PRDCT-3483). */
+export interface MembershipRemovalContext {
+  webhooks: WebhookEmitter;
+}
+
+/** The hook as the chassis calls it, the context bound at boot (`bindMembershipRemoval`). */
+export type BoundMembershipRemoval = (
   tx: DbConn,
   removed: readonly RemovedMembership[]
 ) => Promise<Record<string, number>>;
 
+export function bindMembershipRemoval(
+  hook: MembershipRemovalHook | undefined,
+  ctx: MembershipRemovalContext
+): BoundMembershipRemoval | undefined {
+  return hook ? (tx, removed) => hook(tx, removed, ctx) : undefined;
+}
+
 export interface RemovalCounts {
   projectGrants: number;
   teamSeats: number;
@@ -127,7 +147,7 @@ export interface RemovalCounts {
 export async function deleteMembershipGrants(
   tx: DbConn,
   removed: readonly RemovedMembership[],
-  toolHook?: MembershipRemovalHook
+  toolHook?: BoundMembershipRemoval
 ): Promise<RemovalCounts> {
   if (removed.length === 0) {
     return { projectGrants: 0, teamSeats: 0, invitations: 0, demoPasses: 0, tool: {} };

package/src/middleware/idempotency.ts

@@ -69,7 +69,9 @@ const TARGET_PATHS = new Set([
   '/api/v1/api-keys',
   '/api/v1/invitations',
   '/api/v1/workspaces',
-  '/api/v1/projects'
+  '/api/v1/projects',
+  // A retried registration answers the first one's secret, never a second endpoint (PRDCT-3482).
+  '/api/v1/webhooks'
 ]);
 // The two member routes that MINT a credential for another user. Both are
 // covered (FUZZ-7): a replayed mint hands out a second live secret, and the

package/src/middleware/scopes.ts

@@ -30,6 +30,14 @@ export interface ScopeAllowlistOptions<S extends string> {
   write: S;
   /** The tool's dedicated opt-in scope for the full-workspace export. */
   dataExport: S;
+  /**
+   * The tool's dedicated opt-in scope for the webhooks family (PRDCT-3482):
+   * registering an endpoint is a standing read of the workspace to a URL of
+   * the caller's choice, so no read or write key opens it. Absent: no
+   * machine principal reaches `/webhooks` at all (the catalog read stays
+   * under the read scope).
+   */
+  webhooks?: S | undefined;
   /** The tool's own rules, asked in order AFTER the chassis rules. */
   rules: ReadonlyArray<ScopeRule<S>>;
 }
@@ -89,6 +97,7 @@ export function createScopeAllowlist<S extends string>({
   read,
   write,
   dataExport,
+  webhooks,
   rules
 }: ScopeAllowlistOptions<S>): (path: string, method: string) => S | null {
   return function requiredScopeFor(path: string, method: string): S | null {
@@ -130,6 +139,11 @@ export function createScopeAllowlist<S extends string>({
     // Teams: the same discipline (above).
     const team = teamAccess(path, method);
     if (team !== null) return team === 'read' ? read : write;
+    // Webhooks (PRDCT-3482): the catalog is a read any key may make; the
+    // family itself, reads included, needs the tool's dedicated scope, and
+    // closes entirely when the tool declares none.
+    if (path === '/api/v1/webhooks/events' && isRead) return read;
+    if (path === '/api/v1/webhooks' || path.startsWith('/api/v1/webhooks/')) return webhooks ?? null;
     for (const rule of rules) {
       const needed = rule(path, method, isRead);
       if (needed !== null) return needed;

package/src/secret-box.ts

@@ -0,0 +1,93 @@
+import { createCipheriv, createDecipheriv, hkdfSync, randomBytes } from 'node:crypto';
+
+/**
+ * A box for secrets the instance must read back (a signing secret it hands to
+ * a receiver, a refresh token it presents later): AES-256-GCM under a key
+ * derived from the instance's auth secret by HKDF-SHA256 with a caller-given
+ * `info`, so the database never holds them in the clear and a copy of the
+ * database alone opens nothing. A one-way secret (a password, an API key the
+ * instance only compares) never goes in here: it is hashed, not sealed.
+ *
+ * `info` separates the boxes: two boxes of one instance with different infos
+ * derive different keys, so a value sealed for one purpose never opens under
+ * another. Name it `<area>:<purpose>` and never change it once values are
+ * stored under it (they would no longer open).
+ *
+ * A sealed value reads `v1.<iv>.<tag>.<ciphertext>`, each part base64url: a
+ * fresh 12-byte IV per seal (two seals of one value differ), the 16-byte GCM
+ * tag, which `open` checks before it answers anything (a changed byte
+ * anywhere is refused, never decrypted to garbage). The version prefix lets a
+ * later key or cipher change read the old rows. Every refusal, a malformed
+ * string included, is a `SecretBoxError` and nothing else.
+ */
+const VERSION = 'v1';
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+const KEY_BYTES = 32;
+const BASE64URL = /^[A-Za-z0-9_-]*$/;
+
+export class SecretBoxError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'SecretBoxError';
+  }
+}
+
+export interface SecretBox {
+  seal(plain: string): string;
+  open(sealed: string): string;
+}
+
+/** `info` separates the boxes: two boxes of one instance with different infos never open each other's values. */
+export function createSecretBox(authSecret: string, info: string): SecretBox {
+  if (typeof authSecret !== 'string' || authSecret.length === 0) {
+    throw new SecretBoxError('the secret box needs the auth secret');
+  }
+  if (typeof info !== 'string' || info.length === 0) {
+    throw new SecretBoxError('the secret box needs an info string that names its purpose');
+  }
+  const key = Buffer.from(hkdfSync('sha256', authSecret, Buffer.alloc(0), info, KEY_BYTES));
+
+  return {
+    seal(plain: string): string {
+      if (typeof plain !== 'string') throw new SecretBoxError('the secret box seals strings only');
+      const iv = randomBytes(IV_BYTES);
+      const cipher = createCipheriv('aes-256-gcm', key, iv, { authTagLength: TAG_BYTES });
+      const ciphertext = Buffer.concat([cipher.update(plain, 'utf8'), cipher.final()]);
+      const tag = cipher.getAuthTag();
+      return [
+        VERSION,
+        iv.toString('base64url'),
+        tag.toString('base64url'),
+        ciphertext.toString('base64url')
+      ].join('.');
+    },
+
+    open(sealed: string): string {
+      if (typeof sealed !== 'string') throw new SecretBoxError('not a sealed value');
+      const parts = sealed.split('.');
+      if (parts.length !== 4 || parts[0] !== VERSION) {
+        throw new SecretBoxError('not a sealed value of this version');
+      }
+      const [, ivPart, tagPart, ciphertextPart] = parts as [string, string, string, string];
+      // Buffer.from skips characters outside the alphabet silently: refuse them
+      // here, so only the one spelling of a sealed value opens.
+      if (!BASE64URL.test(ivPart) || !BASE64URL.test(tagPart) || !BASE64URL.test(ciphertextPart)) {
+        throw new SecretBoxError('a sealed value with a part that is not base64url');
+      }
+      const iv = Buffer.from(ivPart, 'base64url');
+      const tag = Buffer.from(tagPart, 'base64url');
+      const ciphertext = Buffer.from(ciphertextPart, 'base64url');
+      if (iv.length !== IV_BYTES || tag.length !== TAG_BYTES) {
+        throw new SecretBoxError('a sealed value with a malformed iv or tag');
+      }
+      try {
+        const decipher = createDecipheriv('aes-256-gcm', key, iv, { authTagLength: TAG_BYTES });
+        decipher.setAuthTag(tag);
+        return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8');
+      } catch {
+        throw new SecretBoxError('the sealed value does not open under this key');
+      }
+    }
+  };
+}

package/src/testing/helpers.ts

@@ -93,6 +93,14 @@ export interface ChassisTestHost<TResult extends BootResultLike, TOverrides> {
    * scope) that answers 200 to any principal the gates let through.
    */
   probeRoute: string;
+  /**
+   * The host's tool is the chassis's minimal test tool, which declares the
+   * `thing` subject and the `thing.created` / `thing.deleted` events the
+   * webhooks suite emits (PRDCT-3482). A real tool leaves it unset: the
+   * suite's delivery scenarios skip under its host, and the tool proves its
+   * own events in its own suite.
+   */
+  webhooks?: boolean;
 }
 
 /** Postgres `admin_shutdown`: what a backend answers a still-connected client when the server stops. */

package/src/tool-definition.ts

@@ -29,6 +29,13 @@ import type { McpToolDefinition } from './mcp/server.js';
 import type { BucketDeclaration, ClientIpFn, RateLimiters } from './middleware/rate-limit.js';
 import type { Otel } from './observability/otel.js';
 import type { EventBus } from './platform/events.js';
+import type {
+  WebhookCatalogDeclaration,
+  WebhookDials,
+  WebhookEmitter,
+  WebhookService
+} from './webhooks/index.js';
+import type { SafeFetchOptions } from './webhooks/safe-fetch.js';
 import type { PlatformRegistry } from './platform/registry.js';
 import type { RuntimeState } from './state.js';
 import type { StorageDriver } from './storage/driver.js';
@@ -66,6 +73,13 @@ export interface ServiceCore<TEnvShape extends z.ZodRawShape, TEvents, TToolOver
   authSecret: string;
   /** One-off timers on the queues the `jobs` slot declared (`jobs/timers.ts`): a service arms and withdraws them. */
   timers: Timers;
+  /**
+   * The outbound webhooks' emitter (PRDCT-3482): a service calls
+   * `webhooks.emit(tx, …)` INSIDE the transaction of the write it reports,
+   * with a type the tool's `webhooks` slot declared. Costs one lookup when
+   * no endpoint of the workspace listens.
+   */
+  webhooks: WebhookEmitter;
   /** The tool's own test seams (`BootOverrides.tool`); undefined in production. */
   overrides: TToolOverrides | undefined;
 }
@@ -328,6 +342,15 @@ export interface ToolDefinition<
    * Absent = nothing declared: no route gated, empty lists in discovery.
    */
   entitlements?: (env: ToolEnv<TEnvShape>, ctx: EntitlementsContext<TDomain>) => ToolEntitlementDeclaration;
+  /**
+   * Slot 25: the tool's event catalog for outbound webhooks (PRDCT-3482):
+   * the subjects an endpoint may filter on (each with the envelope field it
+   * is written under) and the event types the tool emits, each with the zod
+   * schema of its `data`. Checked at boot (`buildWebhookCatalog`), merged
+   * with the chassis's own events, served on `GET /webhooks/events`. Absent
+   * = the chassis events alone; the routes exist on every instance.
+   */
+  webhooks?: WebhookCatalogDeclaration;
 }
 
 /**
@@ -393,6 +416,10 @@ export interface BootOverrides<TToolOverrides = never> {
   hubCreateOrg?: HubOrgCreator;
   /** The tool's own test seams, handed to its `services` slot as `core.overrides`. */
   tool?: TToolOverrides;
+  /** Shrinks the webhooks' retry budget, hold, auto-disable streak, listener cache and overlap for the tests. */
+  webhookDials?: Partial<WebhookDials> | undefined;
+  /** The guarded fetch's seams (a lookup, a transport) so a suite delivers to a loopback receiver. */
+  webhookFetch?: SafeFetchOptions | undefined;
 }
 
 export interface BootResult<
@@ -414,6 +441,8 @@ export interface BootResult<
   email: EmailDriver;
   otel: Otel;
   authSecret: string;
+  /** The outbound webhooks (PRDCT-3482): the emitter, the fan-out and the delivery, for a suite to drive directly. */
+  webhooks: WebhookService;
 }
 
 /**