@acid-cat/cli 0.9.0 → 0.10.1

package/dist/conform/webhook.js

@@ -0,0 +1,474 @@
+import { isObject, memberOf, parseJson } from "../json.js";
+import { expect, expectEqual, expectOccurrence, until } from "./check.js";
+import { count, eventRequests, httpChannel } from "./mcp.js";
+import { MCP_WEBHOOK_DEFAULTS, isOccurrence, webhookSignature, webhookSubscriptionId } from "@acid-cat/spec-ts";
+import { randomBytes, randomUUID } from "node:crypto";
+import { createServer } from "node:https";
+// src/conform/webhook.ts
+/**
+* Conformance checks for webhook delivery of the MCP events extension (spec/bindings/mcp.md#webhook), through HTTP.
+* conform runs an HTTPS receiver on 127.0.0.1 with the certificate that it gets. The deployment under test must trust
+* that certificate, allow deliveries to 127.0.0.1, and give the principal of `WebhookSettings` to each request with the
+* header `Authorization: Bearer <principal>`.
+*
+* Each check uses its own path on the receiver, so its URL is new: the server verifies it again, and the subscriptions
+* of one check, or of an earlier run of conform, never have the key of another check.
+*/
+const RULE = "spec/bindings/mcp.md#webhook";
+/** True if the body of a request is the control message `verification`. */
+const isVerification = (request) => memberOf(request.body, "type") === "verification";
+/**
+* Start the receiver. By default, it answers a verification with its challenge, and each other request with 200. A
+* check can choose other answers for its path.
+*/
+async function startReceiver(settings) {
+	const received = /* @__PURE__ */ new Map();
+	const answerers = /* @__PURE__ */ new Map();
+	const server = createServer({
+		cert: settings.cert,
+		key: settings.key
+	}, (request, response) => {
+		const chunks = [];
+		request.on("data", (chunk) => chunks.push(chunk));
+		request.on("end", () => {
+			const path = request.url ?? "/";
+			const text = Buffer.concat(chunks).toString("utf8");
+			let body;
+			try {
+				body = parseJson(text);
+			} catch {
+				body = void 0;
+			}
+			const each = {
+				headers: request.headers,
+				text,
+				body
+			};
+			const list = received.get(path) ?? [];
+			list.push(each);
+			received.set(path, list);
+			const index = list.filter((one) => !isVerification(one)).length - 1;
+			const verification = {
+				status: 200,
+				body: JSON.stringify({ challenge: memberOf(body, "challenge") })
+			};
+			const chosen = answerers.get(path)?.(each, index) ?? (isVerification(each) ? verification : { status: 200 });
+			response.writeHead(chosen.status, { "Content-Type": "application/json" }).end(chosen.body ?? "");
+		});
+	});
+	await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+	const address = server.address();
+	const port = typeof address === "object" && address !== null ? address.port : 0;
+	return {
+		/** A new URL on the receiver, for one check. */
+		url: (answer) => {
+			const path = `/hook/${randomUUID()}`;
+			if (answer !== void 0) answerers.set(path, answer);
+			return {
+				url: `https://127.0.0.1:${port}${path}`,
+				received: () => received.get(path) ?? []
+			};
+		},
+		close: () => new Promise((resolve) => {
+			server.closeAllConnections();
+			server.close(() => resolve());
+		})
+	};
+}
+/** A new Standard Webhooks secret. */
+const newSecret = () => `whsec_${randomBytes(32).toString("base64")}`;
+/** One header of a request, as text. */
+function header(request, name) {
+	const value = request.headers[name];
+	expect(typeof value === "string", `the request must have the header ${name}, got ${JSON.stringify(request.headers)}`);
+	return value;
+}
+/**
+* Check the headers of a request of the server: the media type, the id, the timestamp, the subscription id, and a
+* signature with each secret. `type` is the type of a control message; with none, the request is an occurrence.
+*/
+async function expectSigned(request, subscription, secrets, type) {
+	expect(header(request, "content-type").startsWith("application/json"), `Content-Type must be application/json, got ${header(request, "content-type")}`);
+	const id = header(request, "webhook-id");
+	const pattern = type === void 0 ? /^msg_[A-Za-z0-9]+$/ : new RegExp(`^msg_${type}_[A-Za-z0-9]+$`);
+	expect(pattern.test(id), `webhook-id must match ${pattern}, got ${JSON.stringify(id)}`);
+	const timestampText = header(request, "webhook-timestamp");
+	const timestamp = Number(timestampText);
+	expect(/^\d+$/.test(timestampText) && Math.abs(timestamp - Date.now() / 1e3) <= 300, `webhook-timestamp must be the time in seconds, got ${JSON.stringify(timestampText)}`);
+	expectEqual(header(request, "x-mcp-subscription-id"), subscription, "X-MCP-Subscription-Id");
+	const signatures = header(request, "webhook-signature").split(" ");
+	for (const secret of secrets) {
+		const expected = await webhookSignature([secret], id, timestamp, request.text);
+		expect(signatures.includes(expected), `webhook-signature must have the signature ${expected} of a secret, got ${JSON.stringify(signatures)}`);
+	}
+	return id;
+}
+/** The body of a delivery of an occurrence: the occurrence without `truncated`. */
+function expectDelivered(request, name) {
+	expect(isObject(request.body) && !("truncated" in request.body), `the body must be an occurrence without truncated, got ${request.text}`);
+	return expectOccurrence(request.body, name);
+}
+/** The checks of webhook delivery through the MCP server at `url`. */
+async function checkWebhook(checks, url, settings) {
+	let receiver;
+	try {
+		receiver = await startReceiver(settings);
+	} catch (error) {
+		await checks.run("conform starts an HTTPS receiver with the certificate and the key", RULE, () => {
+			throw error instanceof Error ? error : new Error(String(error));
+		});
+		return;
+	}
+	try {
+		await checkWithReceiver(checks, url, settings, receiver);
+	} finally {
+		await receiver.close();
+	}
+}
+async function checkWithReceiver(checks, url, settings, receiver) {
+	const principal = settings.principal;
+	const channel = httpChannel(url, { Authorization: `Bearer ${principal}` });
+	const anonymous = httpChannel(url);
+	const { errorOf, watching, signalKey } = eventRequests(channel);
+	const subscribeParams = (name, input, hook, secret, extra = {}) => ({
+		name,
+		arguments: input,
+		delivery: {
+			mode: "webhook",
+			url: hook,
+			secret
+		},
+		...extra
+	});
+	const unsubscribeParams = (name, input, hook) => ({
+		name,
+		arguments: input,
+		delivery: { url: hook }
+	});
+	const resultOf = (message, method) => {
+		const result = memberOf(message, "result");
+		expect(isObject(result), `${method} must give a result, got ${JSON.stringify(message)}`);
+		return result;
+	};
+	const main = {
+		channel,
+		principal
+	};
+	const subscribe = async (name, input, hook, secret, signal, extra = {}, client = main) => {
+		const result = resultOf(await client.channel.request("events/subscribe", subscribeParams(name, input, hook, secret, extra), signal), "events/subscribe");
+		expectEqual(result.resultType, "complete", "resultType");
+		expectEqual(result.id, await webhookSubscriptionId(client.principal, hook, name, input), "the subscription id");
+		const refreshBefore = result.refreshBefore;
+		expect(typeof refreshBefore === "string" && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/.test(refreshBefore), `refreshBefore must be an RFC 3339 date and time, got ${JSON.stringify(refreshBefore)}`);
+		expect(Date.parse(refreshBefore) > Date.now(), `refreshBefore must be in the future, got ${refreshBefore}`);
+		expect(result.cursor === null || typeof result.cursor === "string", `cursor must be the watermark or null, got ${JSON.stringify(result.cursor)}`);
+		expectEqual(result.truncated, false, "truncated");
+		const status = result.deliveryStatus;
+		expectEqual(memberOf(status, "active"), true, "deliveryStatus.active");
+		const last = memberOf(status, "lastDeliveryAt");
+		expect(last === null || typeof last === "string", `deliveryStatus.lastDeliveryAt must be a date or null, got ${JSON.stringify(last)}`);
+		expect(isObject(status) && "lastError" in status, `deliveryStatus must have lastError, got ${JSON.stringify(status)}`);
+		return {
+			id: String(result.id),
+			refreshBefore: Date.parse(refreshBefore)
+		};
+	};
+	const unsubscribe = (name, input, hook, signal, client = main) => client.channel.request("events/unsubscribe", unsubscribeParams(name, input, hook), signal);
+	/** End a subscription at the end of a check. It can be gone already. */
+	const cleanup = (name, input, hook, client = main) => unsubscribe(name, input, hook, AbortSignal.timeout(checks.deadline), client).catch(() => void 0);
+	/** The requests of a URL that are not verifications. */
+	const deliveries = (hook) => hook.received().filter((each) => !isVerification(each));
+	const atLeast = (hook, number, signal) => until(`the receiver gets ${number} deliveries`, async () => deliveries(hook), (list) => list.length >= number, signal);
+	const watchedKey = (key) => (keys) => keys.includes(key);
+	const minTtlMs = settings.minTtlMs ?? MCP_WEBHOOK_DEFAULTS.minTtlMs;
+	const maxTtlMs = settings.maxTtlMs ?? MCP_WEBHOOK_DEFAULTS.maxTtlMs;
+	await checks.run("events/subscribe and events/unsubscribe with no principal are Forbidden", RULE, async (signal) => {
+		const hook = receiver.url();
+		const input = { key: randomUUID() };
+		const subscribed = errorOf(await anonymous.request("events/subscribe", subscribeParams("fixture.watch", input, hook.url, newSecret()), signal));
+		expectEqual(subscribed.code, -32024, "the JSON-RPC error code of events/subscribe");
+		const unsubscribed = errorOf(await anonymous.request("events/unsubscribe", unsubscribeParams("fixture.watch", input, hook.url), signal));
+		expectEqual(unsubscribed.code, -32024, "the JSON-RPC error code of events/unsubscribe");
+		expectEqual(hook.received().length, 0, "the requests that the receiver got");
+	});
+	await checks.run("a URL that is not https, or a secret that is not valid, is the error -32602", RULE, async (signal) => {
+		const hook = receiver.url();
+		const http = hook.url.replace(/^https:/, "http:");
+		for (const [what, params] of [
+			["a URL that is not https", subscribeParams("fixture.watch", { key: randomUUID() }, http, newSecret())],
+			["a secret of 16 bytes", subscribeParams("fixture.watch", { key: randomUUID() }, hook.url, `whsec_${randomBytes(16).toString("base64")}`)],
+			["a secret with no prefix", subscribeParams("fixture.watch", { key: randomUUID() }, hook.url, randomBytes(32).toString("base64"))]
+		]) expectEqual(errorOf(await channel.request("events/subscribe", params, signal)).code, -32602, `the JSON-RPC error code for ${what}`);
+		expectEqual(hook.received().length, 0, "the requests that the receiver got");
+	});
+	await checks.run("the server verifies a new URL with a challenge, then answers with the subscription", RULE, async (signal) => {
+		const hook = receiver.url();
+		const input = {
+			count: 0,
+			key: randomUUID()
+		};
+		const secret = newSecret();
+		try {
+			const { id } = await subscribe("fixture.ticks", input, hook.url, secret, signal);
+			const [verification] = hook.received();
+			expect(verification !== void 0 && isVerification(verification), `the first request must be the verification, got ${JSON.stringify(verification?.body)}`);
+			expect(typeof memberOf(verification.body, "challenge") === "string", `the verification must have a challenge, got ${verification.text}`);
+			await expectSigned(verification, id, [secret], "verification");
+		} finally {
+			await cleanup("fixture.ticks", input, hook.url);
+		}
+	});
+	await checks.run("an endpoint that does not answer the challenge is CallbackEndpointError, and the subscription does not start", RULE, async (signal) => {
+		const hook = receiver.url((request) => isVerification(request) ? {
+			status: 200,
+			body: JSON.stringify({ challenge: "wrong" })
+		} : void 0);
+		const input = { key: randomUUID() };
+		const error = errorOf(await channel.request("events/subscribe", subscribeParams("fixture.watch", input, hook.url, newSecret()), signal));
+		expectEqual(error.code, -32027, "the JSON-RPC error code");
+		expectEqual(memberOf(error.data, "reason"), "challenge_failed", "data.reason");
+		await until("the key is not in fixture.watching", () => watching(signal), (keys) => !keys.includes(input.key), signal);
+		expectEqual(hook.received().length, 1, "the requests that the receiver got: only the verification");
+	});
+	await checks.run("each occurrence is one signed POST, in order, whose cursor is the watermark", RULE, async (signal) => {
+		const hook = receiver.url();
+		const input = {
+			count: 3,
+			key: randomUUID()
+		};
+		const secret = newSecret();
+		try {
+			const { id } = await subscribe("fixture.ticks", input, hook.url, secret, signal);
+			const list = await atLeast(hook, 3, signal);
+			const ids = /* @__PURE__ */ new Set();
+			for (const [index, request] of list.entries()) {
+				const n = index + 1;
+				ids.add(await expectSigned(request, id, [secret]));
+				const occurrence = expectDelivered(request, "fixture.ticks");
+				expectEqual([
+					occurrence.data,
+					occurrence.eventId,
+					occurrence.cursor
+				], [
+					{ n },
+					String(n),
+					String(n)
+				], "the data, the eventId and the cursor");
+			}
+			expectEqual(ids.size, 3, "the number of different webhook-id headers");
+		} finally {
+			await cleanup("fixture.ticks", input, hook.url);
+		}
+	});
+	await checks.run("a subscription gets the things that happen; a renewal grants a new lifetime and signs with both secrets; events/unsubscribe ends it", RULE, async (signal) => {
+		const hook = receiver.url();
+		const input = { key: randomUUID() };
+		const [first, second] = [newSecret(), newSecret()];
+		try {
+			const started = await subscribe("fixture.watch", input, hook.url, first, signal, { ttlMs: minTtlMs });
+			await until("fixture.watching gives the key", () => watching(signal), watchedKey(input.key), signal);
+			expectEqual(await signalKey(input.key, "a", signal), 1, "the subscriptions that fixture.signal reached");
+			const [a] = await atLeast(hook, 1, signal);
+			if (a === void 0) throw new Error("the receiver got no delivery");
+			await expectSigned(a, started.id, [first]);
+			const occurrence = expectDelivered(a, "fixture.watch");
+			expectEqual(occurrence.data, {
+				...input,
+				value: "a"
+			}, "the data");
+			expect(!("cursor" in occurrence), `with no cursor of the provider, the delivery has no cursor, got ${a.text}`);
+			const renewed = await subscribe("fixture.watch", input, hook.url, second, signal);
+			expectEqual(renewed.id, started.id, "the subscription id of the renewal");
+			expect(renewed.refreshBefore >= started.refreshBefore, "a renewal with no ttlMs, which grants the maximum lifetime, must not grant a shorter lifetime than the first grant of the minimum lifetime");
+			expectEqual(count(await watching(signal), input.key), 1, "the subscriptions of the key after the renewal");
+			expectEqual(await signalKey(input.key, "b", signal), 1, "the subscriptions that fixture.signal reached after the renewal");
+			const [, b] = await atLeast(hook, 2, signal);
+			if (b === void 0) throw new Error("the receiver got no second delivery");
+			await expectSigned(b, started.id, [second, first]);
+			expectEqual(memberOf(resultOf(await unsubscribe("fixture.watch", input, hook.url, signal), "events/unsubscribe"), "resultType"), "complete", "the resultType of events/unsubscribe");
+			await until("the key leaves fixture.watching", () => watching(signal), (keys) => !keys.includes(input.key), signal);
+			const again = errorOf(await unsubscribe("fixture.watch", input, hook.url, signal));
+			expectEqual(again.code, -32023, "the JSON-RPC error code of a second events/unsubscribe");
+			expectEqual(memberOf(again.data, "kind"), "subscription", "data.kind");
+		} finally {
+			await cleanup("fixture.watch", input, hook.url);
+		}
+	});
+	await checks.run("a delivery that gets a status that is not 2xx is sent again, with the same webhook-id", RULE, async (signal) => {
+		const hook = receiver.url((request, index) => !isVerification(request) && index === 0 ? { status: 500 } : void 0);
+		const input = { key: randomUUID() };
+		const secret = newSecret();
+		try {
+			const { id } = await subscribe("fixture.watch", input, hook.url, secret, signal);
+			await until("fixture.watching gives the key", () => watching(signal), watchedKey(input.key), signal);
+			await signalKey(input.key, "again", signal);
+			const [failed, retried] = await atLeast(hook, 2, signal);
+			if (failed === void 0 || retried === void 0) throw new Error("the receiver got no retry");
+			const firstId = await expectSigned(failed, id, [secret]);
+			expectEqual(await expectSigned(retried, id, [secret]), firstId, "the webhook-id of the second attempt");
+			expectEqual(retried.text, failed.text, "the body of the second attempt");
+		} finally {
+			await cleanup("fixture.watch", input, hook.url);
+		}
+	});
+	await checks.run("a 410 abandons the delivery at once, and the next occurrence follows", RULE, async (signal) => {
+		const hook = receiver.url((request, index) => !isVerification(request) && index === 0 ? { status: 410 } : void 0);
+		const input = { key: randomUUID() };
+		try {
+			await subscribe("fixture.watch", input, hook.url, newSecret(), signal);
+			await until("fixture.watching gives the key", () => watching(signal), watchedKey(input.key), signal);
+			await signalKey(input.key, "gone", signal);
+			await atLeast(hook, 1, signal);
+			await signalKey(input.key, "next", signal);
+			const [gone, next] = await atLeast(hook, 2, signal);
+			if (gone === void 0 || next === void 0) throw new Error("the receiver got no second delivery");
+			expectEqual(expectDelivered(gone, "fixture.watch").data, {
+				...input,
+				value: "gone"
+			}, "the data of the first delivery");
+			expectEqual(expectDelivered(next, "fixture.watch").data, {
+				...input,
+				value: "next"
+			}, "the data of the second delivery");
+		} finally {
+			await cleanup("fixture.watch", input, hook.url);
+		}
+	});
+	await checks.run("a defect after an occurrence sends the control message terminated", RULE, async (signal) => {
+		const hook = receiver.url();
+		const secret = newSecret();
+		try {
+			const { id } = await subscribe("fixture.broken", {}, hook.url, secret, signal);
+			const [occurrence, terminated] = await atLeast(hook, 2, signal);
+			if (occurrence === void 0 || terminated === void 0) throw new Error("the receiver got no control message");
+			expectEqual(expectDelivered(occurrence, "fixture.broken").data, { n: 1 }, "the data of the occurrence");
+			expect(!isOccurrence(terminated.body), `the second request must be a control message, got ${terminated.text}`);
+			expectEqual(memberOf(terminated.body, "type"), "terminated", "the type of the control message");
+			const error = memberOf(terminated.body, "error");
+			expectEqual(memberOf(error, "code"), -32603, "the error code of the control message");
+			expect(typeof memberOf(error, "message") === "string" && !/\n\s+at /.test(String(memberOf(error, "message"))), "the message must be text with no stack trace");
+			await expectSigned(terminated, id, [secret], "terminated");
+		} finally {
+			await cleanup("fixture.broken", {}, hook.url);
+		}
+	});
+	await checks.run("before an occurrence after a gap, the server sends the control message gap with the watermark", RULE, async (signal) => {
+		const hook = receiver.url();
+		const input = {
+			count: 3,
+			gap: 2,
+			key: randomUUID()
+		};
+		const secret = newSecret();
+		try {
+			const { id } = await subscribe("fixture.ticks", input, hook.url, secret, signal);
+			const [first, gap, second, third] = await atLeast(hook, 4, signal);
+			if (first === void 0 || gap === void 0 || second === void 0 || third === void 0) throw new Error("the receiver got less than four requests");
+			expectEqual(expectDelivered(first, "fixture.ticks").data, { n: 1 }, "the data of the first delivery");
+			expectEqual(gap.body, {
+				type: "gap",
+				cursor: "1"
+			}, "the control message gap, with the watermark after the first delivery");
+			await expectSigned(gap, id, [secret], "gap");
+			const after = expectDelivered(second, "fixture.ticks");
+			expectEqual([after.data, after.cursor], [{ n: 2 }, "2"], "the data and the cursor of the delivery after the gap");
+			expectEqual(expectDelivered(third, "fixture.ticks").data, { n: 3 }, "the data of the last delivery");
+		} finally {
+			await cleanup("fixture.ticks", input, hook.url);
+		}
+	});
+	await checks.run("the server grants ttlMs between the minimum and the maximum lifetime, and the maximum with no ttlMs", RULE, async (signal) => {
+		const hook = receiver.url();
+		const cases = [
+			[
+				"a ttlMs below the minimum",
+				{ ttlMs: Math.floor(minTtlMs / 2) },
+				minTtlMs
+			],
+			[
+				"a ttlMs above the maximum",
+				{ ttlMs: maxTtlMs * 2 },
+				maxTtlMs
+			],
+			[
+				"ttlMs: null",
+				{ ttlMs: null },
+				maxTtlMs
+			],
+			[
+				"no ttlMs",
+				{},
+				maxTtlMs
+			]
+		];
+		for (const [what, extra, granted] of cases) {
+			const input = { key: randomUUID() };
+			try {
+				const before = Date.now();
+				const { refreshBefore } = await subscribe("fixture.watch", input, hook.url, newSecret(), signal, extra);
+				const after = Date.now();
+				expect(refreshBefore >= before + granted - 1 && refreshBefore <= after + granted + 1, `for ${what}, refreshBefore must be ${granted} ms after the request, got ${refreshBefore - before} ms after its start`);
+			} finally {
+				await cleanup("fixture.watch", input, hook.url);
+			}
+		}
+	});
+	if (settings.minTtlMs !== void 0) await checks.run("a subscription with no renewal ends at the end of its lifetime, and gets no more deliveries", RULE, async (signal) => {
+		const hook = receiver.url();
+		const input = { key: randomUUID() };
+		try {
+			const before = Date.now();
+			await subscribe("fixture.watch", input, hook.url, newSecret(), signal, { ttlMs: minTtlMs });
+			await until("fixture.watching gives the key", () => watching(signal), watchedKey(input.key), signal);
+			await until("the lifetime ends, and the key leaves fixture.watching", () => watching(signal), (keys) => !keys.includes(input.key), signal);
+			const elapsed = Date.now() - before;
+			expect(elapsed >= minTtlMs, `the subscription ended ${elapsed} ms after the request, before its lifetime of ${minTtlMs} ms`);
+			expectEqual(await signalKey(input.key, "late", signal), 0, "the subscriptions that fixture.signal reached after the end");
+			expectEqual(deliveries(hook).length, 0, "the deliveries that the receiver got");
+			const ended = errorOf(await unsubscribe("fixture.watch", input, hook.url, signal));
+			expectEqual([ended.code, memberOf(ended.data, "kind")], [-32023, "subscription"], "the error of events/unsubscribe after the end");
+		} finally {
+			await cleanup("fixture.watch", input, hook.url);
+		}
+	});
+	if (settings.maxSubscriptions !== void 0) {
+		const max = settings.maxSubscriptions;
+		const other = settings.otherPrincipal;
+		const name = `a new subscription over the limit of a principal is ResourceExhausted, and a renewal still works${other === void 0 ? "" : ", and another principal can still subscribe"}`;
+		await checks.run(name, RULE, async (signal) => {
+			const client = other === void 0 ? main : {
+				channel: httpChannel(url, { Authorization: `Bearer ${other}` }),
+				principal: other
+			};
+			const hook = receiver.url();
+			const created = [];
+			const extra = { key: randomUUID() };
+			try {
+				let refused;
+				while (refused === void 0 && created.length <= max) {
+					const input = { key: randomUUID() };
+					const message = await client.channel.request("events/subscribe", subscribeParams("fixture.watch", input, hook.url, newSecret()), signal);
+					if (memberOf(message, "error") === void 0) {
+						resultOf(message, "events/subscribe");
+						created.push(input);
+					} else refused = errorOf(message);
+				}
+				if (refused === void 0) throw new Error(`the server granted ${created.length} subscriptions to one principal, over the limit of ${max}`);
+				expectEqual(refused.code, -32025, "the JSON-RPC error code");
+				expectEqual(refused.data, {
+					limit: "subscriptions",
+					max
+				}, "data");
+				if (other !== void 0) expectEqual(created.length, max, "the subscriptions that the server granted before the limit");
+				const [first] = created;
+				if (first === void 0) throw new Error("the principal had no free subscription, so the check cannot renew one");
+				await subscribe("fixture.watch", first, hook.url, newSecret(), signal, {}, client);
+				if (other !== void 0) await subscribe("fixture.watch", extra, hook.url, newSecret(), signal);
+			} finally {
+				for (const input of created) await cleanup("fixture.watch", input, hook.url, client);
+				await cleanup("fixture.watch", extra, hook.url);
+			}
+		});
+	}
+}
+export { checkWebhook };

package/dist/conform/webmcp.js

@@ -1,7 +1,7 @@
 import { isArrayOf, isObject, isStringArray, memberOf, parseJson } from "../json.js";
 import { Checks, abortable, expect, expectEqual, fixture, idsOf, sorted, until } from "./check.js";
 import { REFERENCE, visitObjects } from "@acid-cat/spec-ts";
-//#region src/conform/webmcp.ts
+// src/conform/webmcp.ts
 /**
 * Conformance checks for the WebMCP binding (spec/bindings/webmcp.md).
 *
@@ -152,7 +152,7 @@ function isBundled(schema) {
 	visitObjects(schema, (node) => {
 		if (typeof node.$ref !== "string") return;
 		const name = REFERENCE.exec(node.$ref)?.[1];
-		if (name === void 0 || !(name in types)) bundled = false;
+		if (name === void 0 || !Object.hasOwn(types, name)) bundled = false;
 	});
 	return bundled;
 }
@@ -172,6 +172,11 @@ async function checkWebMcp(driver, options) {
 	await checks.run("each available capability of the view is a tool", `${RULE}#tools`, async (signal) => {
 		await until(`the tools are ${expected.join(", ")}`, () => names(driver, signal), (tools) => JSON.stringify(tools) === JSON.stringify(expected), signal);
 	});
+	await checks.run("an event is not a tool", `${RULE}#events`, async (signal) => {
+		const tools = await names(driver, signal);
+		const events = Object.keys(fixture.events ?? {}).filter((id) => tools.includes(id));
+		expectEqual(events, [], "the tools that have the id of an event");
+	});
 	await checks.run("a tool has the description and the bundled input schema of its capability", `${RULE}#tools`, async (signal) => {
 		for (const tool of await driver.tools(signal)) {
 			expectEqual(tool.description, view[tool.name]?.description, `description of ${tool.name}`);
@@ -244,5 +249,4 @@ async function checkWebMcp(driver, options) {
 	});
 	return checks;
 }
-//#endregion
 export { browserDriver, checkWebMcp, createTestHost, processDriver };

package/dist/index.d.ts

@@ -2,4 +2,4 @@
 export { bundle, check, viewOf } from "./catalog.js";
 export type { Catalog, Report } from "./catalog.js";
 export { conform, fixture, serve } from "./conform/index.js";
-export type { Check, ConformOptions, Routes, Served, WebHandler } from "./conform/index.js";
+export type { Check, ConformOptions, PollSettings, Routes, Served, WebHandler, WebhookSettings } from "./conform/index.js";

package/dist/json/catalog.schema.json.js

@@ -1,9 +1,9 @@
-//#region ../../schemas/catalog.schema.json
+// ../../schemas/catalog.schema.json
 var catalog_schema_default = {
 	$schema: "https://json-schema.org/draft/2020-12/schema",
 	$id: "https://acid-cat.dev/schemas/0.1/catalog.schema.json",
 	title: "AcidCat catalog",
-	description: "One document that states what an application can do and which targets see it. See spec/catalog.md.",
+	description: "One document that states what an application can do, which events it gives, and which targets see each one. See spec/catalog.md.",
 	type: "object",
 	required: [
 		"acidcat",
@@ -34,6 +34,12 @@ var catalog_schema_default = {
 			"type": "object",
 			"propertyNames": { "$ref": "#/$defs/id" },
 			"additionalProperties": { "$ref": "#/$defs/capability" }
+		},
+		"events": {
+			"description": "The events, keyed by id. See spec/events.md.",
+			"type": "object",
+			"propertyNames": { "$ref": "#/$defs/id" },
+			"additionalProperties": { "$ref": "#/$defs/event" }
 		}
 	},
 	$defs: {
@@ -73,7 +79,7 @@ var catalog_schema_default = {
 			"type": ["object", "boolean"]
 		},
 		"objectSchema": {
-			"description": "An input schema: it states that the input is an object, or it references a type.",
+			"description": "An input or payload schema: it states that the value is an object, or it references a type.",
 			"type": "object",
 			"anyOf": [{
 				"required": ["type"],
@@ -110,8 +116,25 @@ var catalog_schema_default = {
 				"readOnly": { "type": "boolean" },
 				"state": { "$ref": "#/$defs/schema" }
 			}
+		},
+		"event": {
+			"type": "object",
+			"required": ["description"],
+			"properties": {
+				"description": {
+					"type": "string",
+					"minLength": 1,
+					"pattern": "\\S"
+				},
+				"audience": {
+					"type": "array",
+					"items": { "$ref": "#/$defs/targetName" },
+					"uniqueItems": true
+				},
+				"input": { "$ref": "#/$defs/objectSchema" },
+				"payload": { "$ref": "#/$defs/objectSchema" }
+			}
 		}
 	}
 };
-//#endregion
 export { catalog_schema_default as default };