@acid-cat/core-ts 0.9.0 → 0.10.1

package/dist/webhook.js

@@ -0,0 +1,384 @@
+import { sleep, systemClock } from "./clock.js";
+import { endMessage, invalidParams, subscriptionParams } from "./mcp-events.js";
+import { isMaxAgeMs } from "./session.js";
+import { MCP_EVENT_ERRORS, MCP_WEBHOOK_DEFAULTS, canonicalJson, isGloballyRoutable, isJsonObject, mcpSubscribeError, webhookGrantMs, webhookSecretBytes, webhookSignature, webhookSubscriptionId } from "@acid-cat/spec-ts";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { lookup } from "node:dns";
+import { request } from "node:https";
+import { isIP } from "node:net";
+import { rootCertificates } from "node:tls";
+// src/webhook.ts
+/**
+* Webhook delivery through MCP (spec/bindings/mcp.md#webhook), on Node.js. The server sends the occurrences of each
+* webhook subscription in HTTP `POST` requests to a URL of the client, signed as Standard Webhooks specifies.
+*
+* This module uses `node:https`, `node:dns` and `node:crypto`. `@acid-cat/core-ts/node` exports it.
+*/
+/** Make webhook delivery for `mcpHandler` (option `webhooks`). */
+function webhookDelivery(options = {}) {
+	const settings = {
+		maxTtlMs: options.maxTtlMs ?? MCP_WEBHOOK_DEFAULTS.maxTtlMs,
+		minTtlMs: options.minTtlMs ?? MCP_WEBHOOK_DEFAULTS.minTtlMs,
+		maxSubscriptions: options.maxSubscriptions ?? MCP_WEBHOOK_DEFAULTS.maxSubscriptions,
+		attempts: options.attempts ?? MCP_WEBHOOK_DEFAULTS.attempts,
+		retryWindowMs: options.retryWindowMs ?? MCP_WEBHOOK_DEFAULTS.retryWindowMs,
+		timeoutMs: options.timeoutMs ?? MCP_WEBHOOK_DEFAULTS.timeoutMs,
+		rotationGraceMs: options.rotationGraceMs ?? MCP_WEBHOOK_DEFAULTS.rotationGraceMs,
+		retryDelayMs: options.retryDelayMs ?? ((attempt) => 1e4 * 3 ** (attempt - 1))
+	};
+	const clock = options.clock ?? systemClock;
+	const network = {
+		allowPrivateNetworks: options.allowPrivateNetworks === true,
+		ca: options.ca === void 0 ? void 0 : [...rootCertificates, ...typeof options.ca === "string" || Buffer.isBuffer(options.ca) ? [options.ca] : options.ca],
+		timeoutMs: settings.timeoutMs
+	};
+	const subscriptions = /* @__PURE__ */ new Map();
+	/** The subscriptions that start, by key. A second request with the same key waits for the first. */
+	const starting = /* @__PURE__ */ new Map();
+	/** The pairs of principal and URL that agreed to get deliveries, while the process runs. */
+	const verified = /* @__PURE__ */ new Set();
+	const pumps = /* @__PURE__ */ new Set();
+	let closed = false;
+	/** The headers of a delivery, with a new timestamp and signature. */
+	async function headersOf(subscription, webhookId, body) {
+		const timestamp = Math.floor(clock.now() / 1e3);
+		return {
+			"Content-Type": "application/json",
+			"webhook-id": webhookId,
+			"webhook-timestamp": String(timestamp),
+			"webhook-signature": await webhookSignature(subscription.secrets, webhookId, timestamp, body),
+			"X-MCP-Subscription-Id": subscription.id
+		};
+	}
+	/** The secrets that sign a delivery now: the new secret, and the old secret during the grace time. */
+	const secretsOf = (subscription) => subscription.previous !== void 0 && clock.now() < subscription.previous.until ? [subscription.secret, subscription.previous.secret] : [subscription.secret];
+	/**
+	* Send one delivery, with retries. The result is `delivered`, `abandoned`, or `stopped` when the subscription ended
+	* before the end of the attempts.
+	*/
+	async function deliver(subscription, webhookId, body) {
+		const start = clock.now();
+		for (let attempt = 1;; attempt += 1) {
+			if (subscription.ended.signal.aborted) return "stopped";
+			const posted = await post(subscription.url, await headersOf({
+				id: subscription.id,
+				secrets: secretsOf(subscription)
+			}, webhookId, body), body, network);
+			if ("status" in posted && posted.status >= 200 && posted.status < 300) {
+				subscription.lastDeliveryAt = new Date(clock.now()).toISOString();
+				subscription.lastError = null;
+				return "delivered";
+			}
+			subscription.lastError = "failure" in posted ? posted.failure : statusError(posted.status);
+			if ("status" in posted && (posted.status === 410 || posted.status === 413)) return "abandoned";
+			const delay = settings.retryDelayMs(attempt);
+			if (attempt >= settings.attempts || clock.now() - start + delay > settings.retryWindowMs) return "abandoned";
+			if (!await sleep(clock, delay, subscription.ended.signal)) return "stopped";
+		}
+	}
+	/** Send the occurrences of a subscription one at a time, in order, until the subscription ends. */
+	async function pump(subscription) {
+		for (;;) {
+			let step;
+			try {
+				step = await subscription.occurrences.next();
+			} catch (error) {
+				if (subscription.ended.signal.aborted) return;
+				const body = JSON.stringify({
+					type: "terminated",
+					error: {
+						code: MCP_EVENT_ERRORS.internal,
+						message: endMessage(error)
+					}
+				});
+				await deliver(subscription, webhookIdOf("terminated"), body);
+				return end(subscription);
+			}
+			if (step.done === true) return end(subscription);
+			const { truncated, cursor: own, ...rest } = step.value;
+			if (truncated === true) {
+				if (await deliver(subscription, webhookIdOf("gap"), JSON.stringify({
+					type: "gap",
+					cursor: subscription.watermark
+				})) === "stopped") return;
+			}
+			const cursor = own ?? subscription.watermark;
+			if (await deliver(subscription, webhookIdOf(), JSON.stringify(cursor === null ? rest : {
+				...rest,
+				cursor
+			})) === "stopped") return;
+			subscription.watermark = cursor;
+		}
+	}
+	/** End a subscription: cancel it, close its session, and forget it. */
+	async function end(subscription) {
+		if (subscription.ended.signal.aborted) return;
+		subscription.ended.abort();
+		subscription.cancelExpiry();
+		if (subscriptions.get(subscription.key) === subscription) subscriptions.delete(subscription.key);
+		await subscription.occurrences.return();
+		await subscription.own.close();
+	}
+	/** Grant a lifetime. When it ends with no renewal, the subscription is cancelled. */
+	function grant(subscription, ttlMs) {
+		const lifetime = webhookGrantMs(ttlMs, settings);
+		subscription.expiresAt = clock.now() + lifetime;
+		subscription.cancelExpiry();
+		subscription.cancelExpiry = clock.schedule(() => void end(subscription), lifetime);
+	}
+	/** Verify that the endpoint agrees to get deliveries for this principal. The result is the reason of a failure. */
+	async function verify(principal, url, id, secret) {
+		const pair = canonicalJson([principal, url.href]);
+		if (verified.has(pair) || options.allow?.(url) === true) return void 0;
+		const challenge = randomBytes(24).toString("base64url");
+		const body = JSON.stringify({
+			type: "verification",
+			challenge
+		});
+		const posted = await post(url, await headersOf({
+			id,
+			secrets: [secret]
+		}, webhookIdOf("verification"), body), body, network);
+		if ("failure" in posted) return posted.failure;
+		if (posted.status >= 300 && posted.status < 400) return "challenge_failed";
+		if (posted.status < 200 || posted.status >= 300) return statusError(posted.status);
+		if (!sameText(challengeOf(posted.text), challenge)) return "challenge_failed";
+		verified.add(pair);
+	}
+	const resultOf = (subscription) => ({ result: {
+		id: subscription.id,
+		refreshBefore: new Date(subscription.expiresAt).toISOString(),
+		cursor: subscription.watermark,
+		truncated: false,
+		deliveryStatus: {
+			active: true,
+			lastDeliveryAt: subscription.lastDeliveryAt,
+			lastError: subscription.lastError
+		}
+	} });
+	/** Start a new subscription: subscribe in a session of its own, verify the endpoint, then send the occurrences. */
+	async function start(principal, key, url, secret, request, open) {
+		if ([...subscriptions.values()].filter((each) => each.principal === principal).length >= settings.maxSubscriptions) return { error: {
+			code: MCP_EVENT_ERRORS.resourceExhausted,
+			message: "Too many webhook subscriptions.",
+			data: {
+				limit: "subscriptions",
+				max: settings.maxSubscriptions
+			}
+		} };
+		const id = await webhookSubscriptionId(principal, request.rawUrl, request.name, request.input);
+		const own = await open();
+		const subscribed = await own.session.subscribe(request.name, request.input, {
+			...request.cursor === void 0 ? {} : { cursor: request.cursor },
+			...request.maxAgeMs === void 0 ? {} : { maxAgeMs: request.maxAgeMs }
+		});
+		if ("kind" in subscribed) {
+			await own.close();
+			return { error: mcpSubscribeError(subscribed) };
+		}
+		const reason = closed ? "connection_refused" : await verify(principal, url, id, secret);
+		if (reason !== void 0 || closed) {
+			await subscribed.return();
+			await own.close();
+			return { error: callbackError(reason ?? "connection_refused") };
+		}
+		const subscription = {
+			id,
+			key,
+			principal,
+			url,
+			own,
+			occurrences: subscribed,
+			ended: new AbortController(),
+			secret,
+			previous: void 0,
+			expiresAt: 0,
+			cancelExpiry: () => {},
+			watermark: null,
+			lastDeliveryAt: null,
+			lastError: null
+		};
+		subscriptions.set(key, subscription);
+		grant(subscription, request.ttlMs);
+		const work = pump(subscription).finally(() => pumps.delete(work));
+		pumps.add(work);
+		return resultOf(subscription);
+	}
+	return {
+		async subscribe(principal, params, open) {
+			const read = readSubscribe(params);
+			if ("error" in read) return read;
+			const { url, secret } = read;
+			const key = subscriptionKey(principal, read.rawUrl, read.name, read.input);
+			await starting.get(key);
+			const existing = subscriptions.get(key);
+			if (existing !== void 0) {
+				if (!isMaxAgeMs(read.maxAgeMs)) return invalidParams("maxAgeMs must be an integer that is 0 or more.");
+				if (existing.secret !== secret) {
+					existing.previous = {
+						secret: existing.secret,
+						until: clock.now() + settings.rotationGraceMs
+					};
+					existing.secret = secret;
+				}
+				grant(existing, read.ttlMs);
+				return resultOf(existing);
+			}
+			const started = start(principal, key, url, secret, read, open);
+			starting.set(key, started);
+			return started.finally(() => starting.delete(key));
+		},
+		unsubscribe(principal, params) {
+			const { name, arguments: input = {}, delivery } = params;
+			const url = isJsonObject(delivery) ? delivery["url"] : void 0;
+			if (typeof name !== "string" || typeof url !== "string") return Promise.resolve(invalidParams("events/unsubscribe needs name and delivery.url."));
+			const subscription = subscriptions.get(subscriptionKey(principal, url, name, input));
+			if (subscription === void 0) return Promise.resolve({ error: {
+				code: MCP_EVENT_ERRORS.notFound,
+				message: "There is no such subscription.",
+				data: { kind: "subscription" }
+			} });
+			return end(subscription).then(() => ({ result: {} }));
+		},
+		async close() {
+			closed = true;
+			await Promise.allSettled(starting.values());
+			await Promise.allSettled([...subscriptions.values()].map(end));
+			await Promise.allSettled(pumps);
+		}
+	};
+}
+/** The key of a webhook subscription: the principal, `delivery.url` as the client sent it, the id, and the input. */
+const subscriptionKey = (principal, rawUrl, name, input) => canonicalJson([
+	principal,
+	rawUrl,
+	name,
+	input
+]);
+/** Read and check the parameters of `events/subscribe`. */
+function readSubscribe(params) {
+	const read = subscriptionParams(params);
+	if ("error" in read) return read;
+	const { delivery, ttlMs } = params;
+	if (!isJsonObject(delivery) || delivery["mode"] !== "webhook") return invalidParams("delivery must be { mode: \"webhook\", url, secret }.");
+	const { url, secret } = delivery;
+	if (typeof url !== "string" || !URL.canParse(url) || new URL(url).protocol !== "https:") return invalidParams("delivery.url must be an https URL.");
+	if (typeof secret !== "string" || webhookSecretBytes(secret) === void 0) return invalidParams("delivery.secret must be whsec_ and the base64 of 24 to 64 bytes.");
+	if (ttlMs !== void 0 && ttlMs !== null && (typeof ttlMs !== "number" || !Number.isFinite(ttlMs) || ttlMs < 0)) return invalidParams("ttlMs must be a number of milliseconds or null.");
+	return {
+		...read,
+		ttlMs,
+		url: new URL(url),
+		rawUrl: url,
+		secret
+	};
+}
+/** The error `CallbackEndpointError`. */
+const callbackError = (reason) => ({
+	code: MCP_EVENT_ERRORS.callbackEndpoint,
+	message: "The callback endpoint did not agree to get deliveries.",
+	data: { reason }
+});
+/** The category of a status that is not `2xx`. */
+const statusError = (status) => status >= 500 ? "http_5xx" : "http_4xx";
+const ALPHANUMERIC = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+/** A new `webhook-id`: `msg_` and random letters and digits, or `msg_<type>_` and random letters and digits for a control message. */
+function webhookIdOf(type) {
+	const characters = [...randomBytes(48)].filter((byte) => byte < 248).slice(0, 24).map((byte) => ALPHANUMERIC.charAt(byte % 62));
+	return `msg_${type === void 0 ? "" : `${type}_`}${characters.join("")}`;
+}
+/** The `challenge` of the JSON answer to a verification, or `undefined`. */
+function challengeOf(text) {
+	try {
+		const value = JSON.parse(text);
+		return isJsonObject(value) && typeof value["challenge"] === "string" ? value["challenge"] : void 0;
+	} catch {
+		return;
+	}
+}
+/** Compare two texts in constant time. */
+function sameText(received, expected) {
+	if (received === void 0) return false;
+	const a = Buffer.from(received);
+	const b = Buffer.from(expected);
+	return a.length === b.length && timingSafeEqual(a, b);
+}
+/** The largest answer that the server reads, in bytes. The server reads only the answer to a verification. */
+const MAXIMUM_ANSWER_BYTES = 65536;
+/** An error of the lookup: the host name has no address that the server can connect to. */
+var BlockedAddressError = class extends Error {
+	code = "EBLOCKEDADDRESS";
+};
+/**
+* Send one `POST` request. The server resolves the host name, and connects only to an address that it accepts. It
+* connects to that address, with the host name in the `Host` header and in TLS. It does not follow redirects.
+*/
+function post(url, headers, body, network) {
+	const host = url.hostname.startsWith("[") ? url.hostname.slice(1, -1) : url.hostname;
+	const accepts = (address) => network.allowPrivateNetworks || isGloballyRoutable(address);
+	if (isIP(host) !== 0 && !accepts(host)) return Promise.resolve({ failure: "connection_refused" });
+	return new Promise((resolve) => {
+		let settled = false;
+		const settle = (posted) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			resolve(posted);
+		};
+		const request$1 = request({
+			method: "POST",
+			host,
+			port: url.port === "" ? 443 : Number(url.port),
+			path: `${url.pathname}${url.search}`,
+			headers: {
+				...headers,
+				"Content-Length": String(Buffer.byteLength(body))
+			},
+			agent: false,
+			...isIP(host) === 0 ? { servername: host } : {},
+			...network.ca === void 0 ? {} : { ca: [...network.ca] },
+			lookup: (hostname, lookupOptions, callback) => {
+				lookup(hostname, {
+					all: true,
+					family: lookupOptions.family ?? 0
+				}, (error, addresses) => {
+					if (error !== null) return callback(error, "", 0);
+					const address = addresses.find((each) => accepts(each.address));
+					if (address === void 0) return callback(new BlockedAddressError(`${hostname} has no address that the server accepts.`), "", 0);
+					if (lookupOptions.all === true) return callback(null, [address]);
+					callback(null, address.address, address.family);
+				});
+			}
+		}, (response) => {
+			const chunks = [];
+			let length = 0;
+			response.on("data", (chunk) => {
+				if (!(chunk instanceof Buffer)) return;
+				length += chunk.length;
+				if (length <= MAXIMUM_ANSWER_BYTES) chunks.push(chunk);
+			});
+			response.on("end", () => settle({
+				status: response.statusCode ?? 0,
+				text: Buffer.concat(chunks).toString("utf8")
+			}));
+			response.on("error", () => settle({
+				status: response.statusCode ?? 0,
+				text: ""
+			}));
+		});
+		const timer = setTimeout(() => {
+			settle({ failure: "timeout" });
+			request$1.destroy();
+		}, network.timeoutMs);
+		request$1.on("error", (error) => settle({ failure: failureOf(error) }));
+		request$1.end(body);
+	});
+}
+/** The category of an error of the network. */
+function failureOf(error) {
+	const code = "code" in error && typeof error.code === "string" ? error.code : "";
+	if (code === "ETIMEDOUT" || code === "ESOCKETTIMEDOUT") return "timeout";
+	if (/^(ERR_TLS|ERR_SSL|CERT_|UNABLE_TO_|DEPTH_ZERO|SELF_SIGNED|HOSTNAME_MISMATCH)/.test(code) || /certificate|SSL|TLS/i.test(error.message)) return "tls_error";
+	return "connection_refused";
+}
+export { webhookDelivery };

package/dist/webmcp.js

@@ -1,5 +1,5 @@
 import { CallFailureError, bundle, isCallFailure } from "@acid-cat/spec-ts";
-//#region src/webmcp.ts
+// src/webmcp.ts
 /**
 * The WebMCP binding (spec/bindings/webmcp.md): register capabilities as WebMCP tools in a web page.
 */
@@ -136,5 +136,4 @@ function installWebMcp(session, options = {}) {
 		}
 	};
 }
-//#endregion
 export { findHost, installWebMcp };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@acid-cat/core-ts",
-  "version": "0.9.0",
-  "description": "Serve AcidCat capabilities in plain TypeScript, with no Effect dependency.",
+  "version": "0.10.1",
+  "description": "Serve AcidCat capabilities and events in plain TypeScript, with no Effect dependency.",
   "keywords": [
     "acidcat",
     "mcp",
@@ -36,14 +36,16 @@
     "access": "public"
   },
   "dependencies": {
-    "@acid-cat/catalog": "0.9.0",
-    "@acid-cat/spec-ts": "0.9.0"
+    "@acid-cat/catalog": "0.10.1",
+    "@acid-cat/mcp-handshake": "0.10.1",
+    "@acid-cat/spec-ts": "0.10.1"
   },
   "devDependencies": {
-    "@acid-cat/cli": "0.9.0",
-    "@types/node": "26.6.5",
+    "@acid-cat/cli": "0.10.1",
+    "@types/node": "26.6.6",
     "esbuild": "0.28.2",
-    "playwright": "1.64.0",
+    "graphql": "17.1.0",
+    "playwright": "1.65.0",
     "typescript": "7.0.2",
     "zod": "4.6.7"
   }