@protobase/server 0.68.5 → 0.69.0

package/dist/workflows/hooks/hook-event.js

@@ -0,0 +1,51 @@
+import { limits } from "@protobase/workflows";
+//#region src/workflows/hooks/hook-event.ts
+/**
+* Whether the call as its run sees it is over a run input's limit as JSON, which escaping makes larger than the body
+* itself: its body is then kept as a file of the run instead.
+*/
+const overInputLimit = (event) => new TextEncoder().encode(JSON.stringify(event)).length > limits.inputBytes;
+const dropped = (name, signatureHeader) => name === "authorization" || name === "proxy-authorization" || name === "cookie" || name.startsWith("webhook-") || name.startsWith("x-forwarded-") || name === "forwarded" || name === signatureHeader;
+/** The call's headers without its credentials, lower-cased as `Headers` keeps them, so no case of a name gets through. */
+const keptHeaders = (headers, signatureHeader) => {
+	const signature = signatureHeader?.toLowerCase();
+	return Object.fromEntries([...headers].filter(([name]) => !dropped(name, signature)));
+};
+const formFields = (params) => Object.fromEntries([...new Set(params.keys())].map((name) => {
+	const values = params.getAll(name);
+	return [name, values.length === 1 ? values[0] : values];
+}));
+const isJson = (type) => /^application\/([\w.+-]+\+)?json\b/i.test(type);
+const parsedBody = (bytes, type) => {
+	const text = new TextDecoder().decode(bytes);
+	if (isJson(type)) try {
+		return JSON.parse(text);
+	} catch (error) {
+		if (!(error instanceof SyntaxError)) throw error;
+		return text;
+	}
+	if (/^application\/x-www-form-urlencoded\b/i.test(type)) return formFields(new URLSearchParams(text));
+	return text;
+};
+/**
+* The call as its run sees it: method, query, headers without credentials, the body, or `file` when the caller kept the
+* body as a file of the run, as for a call over the run input's 1 MiB, and when it came. The address is left out: it holds the key.
+*/
+const hookEvent = (request, bytes, signatureHeader, file) => ({
+	method: request.method,
+	query: Object.fromEntries(new URL(request.url).searchParams),
+	headers: keptHeaders(request.headers, signatureHeader),
+	body: file ?? parsedBody(bytes, request.headers.get("content-type") ?? ""),
+	received_at: (/* @__PURE__ */ new Date()).toISOString()
+});
+/** The same call for a plugin's `receive`: the headers without credentials, the bytes read, and no key in its address. */
+const receivedRequest = (request, bytes, signatureHeader) => {
+	const url = new URL(request.url);
+	return new Request(`${url.origin}/?${url.searchParams}`, {
+		method: request.method,
+		headers: keptHeaders(request.headers, signatureHeader),
+		body: bytes
+	});
+};
+//#endregion
+export { hookEvent, keptHeaders, overInputLimit, receivedRequest };

package/dist/workflows/hooks/hook-paths.d.ts

@@ -0,0 +1,16 @@
+//#region src/workflows/hooks/hook-paths.d.ts
+/** The names of the parameters in the webhook addresses. */
+export declare const webhookParams: {
+  readonly workflow: "workflow";
+  readonly key: "key";
+};
+/** Where a workflow's webhook URL is issued, `POST <systemPath>/workflows/<id>/webhook`; the route's pattern without an id. */
+export declare const webhookIssuePath: (systemPath: string, workflow?: string) => string;
+/** The public address a webhook trigger is called at, `<systemPath>/workflows/hooks/<key>`; the route's pattern without a key. */
+export declare const hookPath: (systemPath: string, key?: string) => string;
+/**
+ * `text` with the key of every webhook address in it replaced by `[key]`, for a request log: the key opens the URL. A
+ * word of the line is read decoded as the router reads it, so an address written with escapes is redacted too.
+ */
+export declare const redactHookKeys: (text: string) => string;
+//#endregion

package/dist/workflows/hooks/hook-paths.js

@@ -0,0 +1,32 @@
+//#region src/workflows/hooks/hook-paths.ts
+/** The names of the parameters in the webhook addresses. */
+const webhookParams = {
+	workflow: "workflow",
+	key: "key"
+};
+/** Where a workflow's webhook URL is issued, `POST <systemPath>/workflows/<id>/webhook`; the route's pattern without an id. */
+const webhookIssuePath = (systemPath, workflow = `:${webhookParams.workflow}`) => `${systemPath}/workflows/${workflow}/webhook`;
+/** Where the webhook addresses live, the route the public address is mounted at. */
+const hooksBase = (systemPath) => `${systemPath}/workflows/hooks`;
+/** The public address a webhook trigger is called at, `<systemPath>/workflows/hooks/<key>`; the route's pattern without a key. */
+const hookPath = (systemPath, key = `:${webhookParams.key}`) => `${hooksBase(systemPath)}/${key}`;
+const hookAddress = /\/workflows\/hooks\/[^/?#]+/g;
+const decodedEscapes = (part) => part.replace(/(?:%[0-9A-Fa-f]{2})+/g, (escapes) => {
+	try {
+		return decodeURI(escapes);
+	} catch (error) {
+		if (!(error instanceof URIError)) throw error;
+		return escapes;
+	}
+});
+/**
+* `text` with the key of every webhook address in it replaced by `[key]`, for a request log: the key opens the URL. A
+* word of the line is read decoded as the router reads it, so an address written with escapes is redacted too.
+*/
+const redactHookKeys = (text) => text.replace(/\S+/g, (part) => {
+	const decoded = decodedEscapes(part);
+	const redacted = decoded.replace(hookAddress, "/workflows/hooks/[key]");
+	return redacted === decoded ? part : redacted;
+});
+//#endregion
+export { hookPath, hooksBase, redactHookKeys, webhookIssuePath, webhookParams };

package/dist/workflows/hooks/hook-route.js

@@ -0,0 +1,99 @@
+import { HttpProblem, badRequest, notFound, problemResponse, unauthorized } from "../../problem.js";
+import { clientAddress, createRateLimit } from "../../forms/rate-limit.js";
+import { callPlugin } from "../triggers/plugin-call.js";
+import { itemsProblem } from "../triggers/poll-result.js";
+import { removeRunFile, storeRunFile } from "../run-files.js";
+import { hookMode } from "./hook-secrets.js";
+import { authenticated, hmacOptions, idempotencyKey } from "./hook-auth.js";
+import { hookEvent, overInputLimit, receivedRequest } from "./hook-event.js";
+import { webhookParams } from "./hook-paths.js";
+import { findHook } from "./hook-store.js";
+import { startHookRuns } from "./hook-runs.js";
+import { readBody } from "./read-body.js";
+import { Hono } from "hono";
+import { limits } from "@protobase/workflows";
+import { webhookBodyCeiling, webhookBodyDefault } from "@protobase/workflows/plugin";
+//#region src/workflows/hooks/hook-route.ts
+/** Calls an address may have refused (401, 404 and, once a URL was found, 400 and 413) a minute before it waits. */
+const refusalsPerMinute = 30;
+/** Calls a minute that start runs, per trigger, when its input names no `per_minute`. */
+const callsPerMinute = 60;
+const tooMany = (seconds, detail) => new HttpProblem(429, "too-many-calls", "Too Many Requests", detail, {}, { "Retry-After": String(seconds) });
+const bodyLimit = (input) => Math.min(typeof input.body_limit === "number" ? input.body_limit : webhookBodyDefault, webhookBodyCeiling);
+/**
+* The public address a webhook trigger is called at, `POST .../workflows/hooks/<key>`, with no session: only POST; an
+* address that was refused 30 times this minute waits, before any lookup; the key must open a running webhook trigger
+* of an enabled version (404 for anything else, alike); the body is read up to the trigger's limit (413); the call
+* must prove it comes from the sender (401); then the trigger's own rate (429), spent only by calls that did; the run
+* starts once per signed id (202 `{ run_id }`). Each refusal starts no run. Its errors are its own: reported without
+* the request, answered with nothing of it.
+*/
+const hookRoute = (input) => {
+	const { db, schema } = input;
+	const refusals = createRateLimit();
+	const calls = createRateLimit();
+	const app = new Hono();
+	app.onError((error) => {
+		if (error instanceof HttpProblem) return problemResponse(error, "/workflows/hooks");
+		input.report(error);
+		return problemResponse(new HttpProblem(500, "internal-error", "Internal Server Error", "The call could not be taken; send it again"), "/workflows/hooks");
+	});
+	app.all(`/:${webhookParams.key}`, async (c) => {
+		if (c.req.method !== "POST") return c.body(null, 405, { Allow: "POST" });
+		const request = c.req.raw;
+		const address = clientAddress(request.headers);
+		const wait = refusals.spent(address, refusalsPerMinute);
+		if (wait > 0) throw tooMany(wait, "Too many refused calls from this address; wait a minute");
+		const refused = (problem) => {
+			refusals.take(address, refusalsPerMinute);
+			return problem;
+		};
+		const target = await findHook(db, schema, c.req.param(webhookParams.key), input.webhookTypes());
+		const type = target && input.webhooks(target.type);
+		if (!target || !type) throw refused(notFound("There is no webhook at this address"));
+		const bytes = await readBody(request, bodyLimit(target.input));
+		if (!bytes) throw refused(new HttpProblem(413, "body-too-large", "Payload Too Large", `The body is over ${bodyLimit(target.input)} bytes, the most this webhook takes`));
+		const mode = hookMode(target.input);
+		const signed = new Request(request.url, {
+			method: "POST",
+			headers: request.headers,
+			body: bytes
+		});
+		if (!mode || !await authenticated(signed, mode, target)) throw refused(unauthorized("The call does not carry this webhook's secret or signature"));
+		const perMinute = typeof target.input.per_minute === "number" ? target.input.per_minute : callsPerMinute;
+		const rate = calls.take(target.trigger_id, perMinute);
+		if (rate > 0) throw tooMany(rate, `This webhook takes ${perMinute} calls a minute`);
+		const key = idempotencyKey(request, mode, target.input);
+		if (key !== void 0 && key.length > 200) throw refused(badRequest("invalid-idempotency-key", `The call's id is over 200 characters`));
+		const runId = crypto.randomUUID();
+		const signatureHeader = mode === "hmac" ? hmacOptions(target.input).header : void 0;
+		const inline = hookEvent(request, bytes, signatureHeader);
+		const large = overInputLimit(inline);
+		if (large && !input.files()?.providers.private) throw refused(new HttpProblem(413, "body-too-large", "Payload Too Large", `The call is over a run input's ${limits.inputBytes} bytes as JSON, and this app keeps no files for larger ones`));
+		const file = large ? await storeRunFile(input.files(), runId, bytes, "body", request.headers.get("content-type") ?? "application/octet-stream") : void 0;
+		let started = false;
+		try {
+			const event = file ? hookEvent(request, bytes, signatureHeader, file) : inline;
+			const received = await callPlugin(() => type.receive({
+				request: receivedRequest(request, bytes, signatureHeader),
+				event,
+				idempotencyKey: key,
+				input: target.input
+			}), input.redact);
+			if (!("value" in received)) throw new Error(`The webhook trigger ${target.type} failed: ${"failed" in received ? received.failed : received.expired}`);
+			const { items, response } = received.value;
+			const problem = itemsProblem(items, file ? 1 : 100, false);
+			if (problem) throw new Error(`The webhook trigger ${target.type} ${problem}`);
+			const ids = await startHookRuns(db, schema, target, items, runId);
+			if (!ids) throw refused(notFound("There is no webhook at this address"));
+			started = ids[0] === runId;
+			if (response) return response;
+			return ids.length === 1 ? c.json({ run_id: ids[0] }, 202) : c.json({ run_ids: ids }, 202);
+		} finally {
+			if (file && !started) await removeRunFile(input.files(), file);
+		}
+	});
+	return app;
+};
+//#endregion
+export { hookRoute };

package/dist/workflows/hooks/hook-runs.js

@@ -0,0 +1,32 @@
+import { startWorkflow } from "../start-workflow.js";
+import { sql } from "kysely";
+//#region src/workflows/hooks/hook-runs.ts
+const stillLive = async (trx, schema, target) => {
+	const { rows } = await sql`select 1 from ${sql.id(schema, "triggers")} t
+    join ${sql.id(schema, "workflows")} w on w.id = t.workflow_id and w.enabled_version = t.version
+    where t.id = ${target.trigger_id} and t.version = ${target.version} and t.status in ('active', 'failing') for share`.execute(trx);
+	return rows.length > 0;
+};
+/**
+* Starts a run per item of a call, in one transaction: only while the trigger the call found still runs on the enabled
+* version, the version and tenant from the trigger row, never from the call, each item's key once per workflow. The
+* first run takes `firstId`, under which the call's large body was kept. The ids of the runs, a run already started
+* for a key included, or `undefined` when the workflow was turned off, changed or deleted since the call found it.
+*/
+const startHookRuns = (db, schema, target, items, firstId) => db.transaction().execute(async (trx) => {
+	if (!await stillLive(trx, schema, target)) return;
+	const ids = [];
+	for (const [index, item] of items.entries()) ids.push(await startWorkflow(trx, {
+		workflow: target.workflow_id,
+		version: target.version,
+		input: item.data,
+		...target.tenant_id !== null && { tenant: target.tenant_id },
+		startedBy: `trigger:${target.trigger_id}`,
+		...item.key !== void 0 && { key: item.key },
+		schema,
+		...index === 0 && { id: firstId }
+	}));
+	return ids;
+});
+//#endregion
+export { startHookRuns };

package/dist/workflows/hooks/hook-secrets.js

@@ -0,0 +1,42 @@
+import { badRequest } from "../../problem.js";
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+//#region src/workflows/hooks/hook-secrets.ts
+const modes = [
+	"standard_webhooks",
+	"hmac",
+	"bearer"
+];
+/** The mode a webhook trigger's input names, `standard_webhooks` by default; `undefined` for one the route does not know. */
+const hookMode = (input) => {
+	const auth = input.auth;
+	if (auth === void 0) return "standard_webhooks";
+	return typeof auth?.mode === "string" && modes.includes(auth.mode) ? auth.mode : void 0;
+};
+const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+/**
+* Whether `secret` is one this mode can check signatures with: a Standard Webhooks secret is `whsec_` and 24+ bytes in
+* padded base64, as strict as the signature check decodes it.
+*/
+const usable = (mode, secret) => {
+	if (mode !== "standard_webhooks") return secret.length >= 32 && secret.length <= 512;
+	const match = /^whsec_((?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?)$/.exec(secret);
+	return Boolean(match) && Buffer.from(match[1], "base64").length >= 24 && secret.length <= 512;
+};
+/** The secret of a new URL: the caller's, checked for its mode, or a new one of 32 random bytes. */
+const hookSecret = (mode, given) => {
+	if (given === void 0) return mode === "standard_webhooks" ? `whsec_${randomBytes(32).toString("base64")}` : randomBytes(32).toString("base64url");
+	if (!usable(mode, given)) throw badRequest("invalid-secret", mode === "standard_webhooks" ? "A standard_webhooks secret is whsec_ followed by at least 24 bytes in base64" : "A secret is 32 to 512 characters");
+	return given;
+};
+/** Whether a stored secret is still one its mode can check with, as after the mode changed since the URL was issued. */
+const usableSecret = (mode, secret) => secret !== null && usable(mode, secret);
+/** A new URL key: 32 random bytes, which only the URL holds; the app keeps its SHA-256. */
+const hookKey = () => randomBytes(32).toString("base64url");
+/** Whether a bearer token's SHA-256 is the kept one, compared in constant time on two digests of one length. */
+const bearerMatches = (token, secretHash) => {
+	const given = createHash("sha256").update(token).digest();
+	const kept = Buffer.from(secretHash, "hex");
+	return kept.length === given.length && timingSafeEqual(given, kept);
+};
+//#endregion
+export { bearerMatches, hookKey, hookMode, hookSecret, sha256, usableSecret };

package/dist/workflows/hooks/hook-store.js

@@ -0,0 +1,35 @@
+import { hookKey, hookSecret, sha256 } from "./hook-secrets.js";
+import { sql } from "kysely";
+//#region src/workflows/hooks/hook-store.ts
+/**
+* Gives the workflow a new URL key and secret, replacing any it had, so its old URL stops at once: the key's SHA-256 is
+* kept, the secret itself only where checking a signature needs it (`standard_webhooks`, `hmac`), and its SHA-256
+* always. The key and secret come back once.
+*/
+const saveHook = async (db, schema, hook) => {
+	const key = hookKey();
+	const secret = hookSecret(hook.mode, hook.secret);
+	const kept = hook.mode === "bearer" ? null : secret;
+	await sql`insert into ${sql.id(schema, "hooks")} (workflow_id, key_hash, secret, secret_hash, tenant_id)
+    values (${hook.workflow}, ${sha256(key)}, ${kept}, ${sha256(secret)}, ${hook.tenant})
+    on conflict (workflow_id) do update set key_hash = excluded.key_hash, secret = excluded.secret, secret_hash = excluded.secret_hash, tenant_id = excluded.tenant_id, created_at = now()`.execute(db);
+	return {
+		key,
+		secret
+	};
+};
+/**
+* The webhook trigger a URL key opens, in one statement: the key's workflow in the same tenant, its enabled version's
+* trigger of a webhook type, running or failing. `undefined` for an unknown key, a workflow turned off, deleted or
+* moved to another trigger, and a trigger stopping or waiting for a sign-in, alike.
+*/
+const findHook = async (db, schema, key, webhookTypes) => {
+	const { rows } = await sql`select h.workflow_id, h.tenant_id, h.secret, h.secret_hash, t.id as trigger_id, t.version, t.type, t.input
+    from ${sql.id(schema, "hooks")} h
+    join ${sql.id(schema, "workflows")} w on w.id = h.workflow_id and w.tenant_id is not distinct from h.tenant_id
+    join ${sql.id(schema, "triggers")} t on t.workflow_id = w.id and t.version = w.enabled_version and t.status in ('active', 'failing') and t.type = any(${webhookTypes})
+    where h.key_hash = ${sha256(key)}`.execute(db);
+	return rows[0];
+};
+//#endregion
+export { findHook, saveHook };

package/dist/workflows/hooks/hooks-sql.js

@@ -0,0 +1,20 @@
+import { quoteIdent } from "../../changes/capture-sql.js";
+//#region src/workflows/hooks/hooks-sql.ts
+/**
+* The webhook URL each workflow has, at most one: the SHA-256 of its key, which only the URL holds, and its secret.
+* A `bearer` secret is kept as its SHA-256 alone; `standard_webhooks` and `hmac` keep the secret itself, which checking
+* a signature needs. No API resource reads it. A workflow's delete removes its row, so its URL stops at once.
+*/
+const hooksSql = (schema) => {
+	const s = quoteIdent(schema);
+	return `create table if not exists ${s}."hooks" (
+  "workflow_id" uuid primary key references ${s}."workflows" ("id") on delete cascade,
+  "key_hash" text not null unique,
+  "secret" text,
+  "secret_hash" text not null,
+  "tenant_id" text,
+  "created_at" timestamptz not null default now()
+)`;
+};
+//#endregion
+export { hooksSql };

package/dist/workflows/hooks/issue-body.js

@@ -0,0 +1,21 @@
+import { badRequest } from "../../problem.js";
+//#region src/workflows/hooks/issue-body.ts
+const invalidBody = () => badRequest("invalid-body", "Send nothing, or { \"secret\": \"<secret>\" } to keep a secret the sender gives");
+/** The issue request's body: nothing, or `{ secret }`; anything else, malformed JSON included, is a 400 `invalid-body`. */
+const parseIssueBody = (text) => {
+	if (text === "") return {};
+	let body;
+	try {
+		body = JSON.parse(text);
+	} catch (error) {
+		if (error instanceof SyntaxError) throw invalidBody();
+		throw error;
+	}
+	if (typeof body !== "object" || body === null || Array.isArray(body)) throw invalidBody();
+	const { secret } = body;
+	if (secret === void 0) return {};
+	if (typeof secret !== "string") throw invalidBody();
+	return { secret };
+};
+//#endregion
+export { parseIssueBody };

package/dist/workflows/hooks/issue-route.js

@@ -0,0 +1,23 @@
+import { webhookParams } from "./hook-paths.js";
+import { parseIssueBody } from "./issue-body.js";
+import { issueWebhook } from "./issue-webhook.js";
+import { Hono } from "hono";
+//#region src/workflows/hooks/issue-route.ts
+/**
+* `POST <systemPath>/workflows/<id>/webhook` with an optional `{ secret }`: a new URL and secret for the workflow's
+* webhook trigger, answered once and never stored by any cache.
+*/
+const issueRoute = (input) => {
+	const app = new Hono();
+	app.post(`/:${webhookParams.workflow}/webhook`, async (c) => {
+		const body = parseIssueBody(await c.req.text());
+		const issued = await issueWebhook(input, c.get("session"), c.req.param(webhookParams.workflow), {
+			...body,
+			origin: new URL(c.req.url).origin
+		});
+		return c.json(issued, 200, { "Cache-Control": "no-store" });
+	});
+	return app;
+};
+//#endregion
+export { issueRoute };

package/dist/workflows/hooks/issue-webhook.js

@@ -0,0 +1,46 @@
+import { badRequest, notFound } from "../../problem.js";
+import { requestAccess } from "../../request-access.js";
+import { deletedRows } from "../../params.js";
+import { fetchReadable } from "../../fetch-readable.js";
+import { hookMode } from "./hook-secrets.js";
+import { hookPath } from "./hook-paths.js";
+import { saveHook } from "./hook-store.js";
+import { mayUpdateWorkflow } from "../may-update-workflow.js";
+//#region src/workflows/hooks/issue-webhook.ts
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const missing = () => notFound("No workflows with this key that you may change");
+/**
+* Gives a workflow a new webhook URL and secret, as `POST .../workflows/<id>/webhook` and `new_webhook_url` do: only for
+* a caller who may change that workflow in their tenant, as its update access decides; 404 for anyone else, as for a
+* workflow that is not there. Its current definition must start from a webhook trigger that does not register its own
+* URL. The secret is the caller's, checked for the trigger's mode, or a new one. Both come back once; the old URL stops.
+*/
+const issueWebhook = async ({ deps, schema, webhooks, origin }, session, id, request) => {
+	if (!uuid.test(id)) throw missing();
+	const entry = deps().registry.find("workflows");
+	const access = await requestAccess(deps(), entry, session);
+	if (!access.resolved.operations.update) throw missing();
+	return deps().db.transaction().execute(async (trx) => {
+		const found = await fetchReadable(trx, access, [id], deletedRows(access.full, false), { lock: true });
+		if (!found || !await mayUpdateWorkflow(trx, access, id, found.record)) throw missing();
+		const record = found.record;
+		const [type, input] = Object.entries(record.definition.trigger)[0];
+		const trigger = webhooks(type);
+		if (!trigger) throw badRequest("not-a-webhook", "This workflow does not start from a webhook trigger, such as app:webhook");
+		if (trigger.subscribe) throw badRequest("not-a-webhook", `${type} registers its own URL with its service as the workflow is turned on`);
+		const mode = hookMode(input);
+		if (!mode) throw badRequest("invalid-workflow", "The webhook trigger names an auth mode this app does not know");
+		const { key, secret } = await saveHook(trx, schema, {
+			workflow: id,
+			tenant: record.tenant_id ?? null,
+			mode,
+			...request.secret !== void 0 && { secret: request.secret }
+		});
+		return {
+			url: `${origin() ?? request.origin}${hookPath(deps().systemPath, key)}`,
+			secret
+		};
+	});
+};
+//#endregion
+export { issueWebhook };

package/dist/workflows/hooks/read-body.js

@@ -0,0 +1,32 @@
+//#region src/workflows/hooks/read-body.ts
+/**
+* The request's body, at most `limit` bytes, counted as they come off the stream whether or not the request declares
+* its length; `undefined` past the limit, having kept no more than `limit` bytes and cancelled the rest.
+*/
+const readBody = async (request, limit) => {
+	const declared = request.headers.get("content-length");
+	if (declared !== null && Number(declared) > limit) return void 0;
+	if (!request.body) return /* @__PURE__ */ new Uint8Array();
+	const reader = request.body.getReader();
+	const chunks = [];
+	let size = 0;
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		size += value.length;
+		if (size > limit) {
+			await reader.cancel();
+			return;
+		}
+		chunks.push(value);
+	}
+	const bytes = new Uint8Array(size);
+	let at = 0;
+	for (const chunk of chunks) {
+		bytes.set(chunk, at);
+		at += chunk.length;
+	}
+	return bytes;
+};
+//#endregion
+export { readBody };

package/dist/workflows/may-update-workflow.js

@@ -0,0 +1,26 @@
+import { tenantScope } from "../tenant.js";
+import { recordDecision, targetFilter } from "../request-access.js";
+import { fetchRecord } from "../records.js";
+//#region src/workflows/may-update-workflow.ts
+/**
+* Whether the caller may change this workflow as the record update path decides it: the update row filter and the
+* record-level update rule, beside the read access `fetchReadable` checked.
+*/
+const mayUpdateWorkflow = async (trx, access, id, record) => {
+	const tenant = tenantScope(access.entry, access.session)?.tenantValue;
+	const key = [access.full.fields[access.full.primaryKey[0]]];
+	const filter = targetFilter(access, "update");
+	if (filter && !await fetchRecord(trx, access.entry, [id], tenant, {
+		filter,
+		fields: key
+	})) return false;
+	if (!access.resolved.recordChecks.includes("update")) return true;
+	const decision = await recordDecision(access, "update", record);
+	if (typeof decision === "boolean") return decision;
+	return Boolean(await fetchRecord(trx, access.entry, [id], tenant, {
+		filter: decision,
+		fields: key
+	}));
+};
+//#endregion
+export { mayUpdateWorkflow };

package/dist/workflows/mcp/webhook-tools.d.ts

@@ -0,0 +1,9 @@
+import { Session } from "../../types.js";
+import "../../index.js";
+//#region src/workflows/mcp/webhook-tools.d.ts
+/** Issues a workflow's webhook URL as the caller; the server answers 404 for a workflow they may not change. */
+export type IssueWebhook = (session: Session, id: string, secret: string | undefined) => Promise<{
+  url: string;
+  secret: string;
+}>;
+//#endregion

package/dist/workflows/mcp/webhook-tools.js

@@ -0,0 +1,103 @@
+import { HttpProblem, notFound, preconditionFailed } from "../../problem.js";
+import { defineTool } from "../../assistant/tools.js";
+import { refused } from "../../assistant/record-tool-args.js";
+import { recordName, updateApproval } from "../../assistant/write-prompts.js";
+import { approvalTexts, recordBefore } from "../../assistant/record-before.js";
+import { notApproved, onlyNote, outside } from "../../assistant/write-tool-limits.js";
+import { idOf, idParameter, textOf } from "./workflow-tool-args.js";
+//#region src/workflows/mcp/webhook-tools.ts
+/**
+* `enable_workflow` and `new_webhook_url`: turning a workflow's trigger on or off, and issuing its webhook URL, each as
+* the caller and after the user approves it in their client.
+*/
+const writes = {
+	readOnlyHint: false,
+	destructiveHint: false,
+	openWorldHint: false
+};
+const enableRefused = (error) => {
+	if (error instanceof HttpProblem && error.slug === "own-sign-in-only") return JSON.stringify({
+		error: "own-sign-in-only",
+		message: "This workflow signs in through a connected account, so it was not turned on: the account's owner turns it on in the admin app, on the workflow's page, signed in as themselves. Saving it stays open to you."
+	});
+	return refused(error);
+};
+/** Turns a workflow's trigger on, on its current version, or off, once the user approves it. */
+const enableWorkflowTool = (input = {}) => defineTool({
+	name: "enable_workflow",
+	description: `Turns a workflow's trigger on (enabled: true) on version, which must be its current version as create_workflow, update_workflow or get_workflow gave it, or off (enabled: false), and returns JSON { id, enabled_version }. A workflow saved since that version is refused; read it again. While on, its trigger starts runs: a webhook trigger whose sender you give a URL once it is issued with new_webhook_url, one that registers its own URL with its service as soon as it did, a polling trigger at its next poll. A later save keeps it on, on the new version. A workflow that signs in through a connected account (its connections) is turned on only by that account's owner in the admin app: here it is refused with error own-sign-in-only. The user approves it in their client first.${onlyNote(input)}`,
+	parameters: {
+		type: "object",
+		properties: {
+			id: idParameter,
+			enabled: {
+				type: "boolean",
+				description: "true to turn it on, false to turn it off."
+			},
+			version: {
+				type: "integer",
+				description: "With enabled: true, the version to turn on: the workflow's current version."
+			}
+		},
+		required: ["id", "enabled"]
+	},
+	annotations: writes,
+	run: async (args, context) => {
+		const id = idOf(args);
+		const version = args.version;
+		if (!id || typeof args.enabled !== "boolean" || args.enabled && !Number.isInteger(version)) return "Pass { \"id\": \"<id>\", \"enabled\": true, \"version\": <its current version> } or { \"id\": \"<id>\", \"enabled\": false }.";
+		const refusal = outside(input, "workflows");
+		if (refusal) return refusal;
+		const before = await recordBefore(context, "workflows", id, void 0);
+		if (typeof before === "string") return before;
+		if (!before) return refused(notFound("No workflows with this key that you may read"));
+		if (args.enabled && before.record.version !== version) return refused(preconditionFailed(`The workflow was saved since version ${version}; its current version is ${before.record.version}`));
+		const data = { enabled_version: args.enabled ? version : null };
+		const { text, described } = await approvalTexts(context, "workflows");
+		const answer = await context.approve(updateApproval(text, described, id, before.record, data));
+		if (answer !== "approved") return notApproved(answer);
+		return context.records.update("workflows", id, data, args.enabled ? { etag: before.etag } : {}).then(({ record }) => JSON.stringify({
+			id: record.id,
+			enabled_version: record.enabled_version
+		}), enableRefused);
+	}
+});
+/** Issues a new webhook URL and secret for a workflow, once the user approves it. */
+const newWebhookUrlTool = (issue, input = {}) => defineTool({
+	name: "new_webhook_url",
+	description: `Issues a new URL and secret for a workflow that starts from a webhook trigger whose sender you give a URL (such as app:webhook), and returns JSON { url, secret }, shown this once: the app keeps no way to show them again, and the workflow's old URL stops. Pass secret to keep one the sender makes itself (a Standard Webhooks sender's whsec_ secret); without it the app makes one. The sender then POSTs to the url, signed as the trigger's auth mode says. A trigger that registers its own URL with its service is refused: turning the workflow on is all it needs. The user approves it in their client first.${onlyNote(input)}`,
+	parameters: {
+		type: "object",
+		properties: {
+			id: idParameter,
+			secret: {
+				type: "string",
+				description: "The sender's own secret, when it makes one; omit it to have the app make one."
+			}
+		},
+		required: ["id"]
+	},
+	annotations: writes,
+	run: async (args, context) => {
+		const id = idOf(args);
+		if (!id) return "Pass { \"id\": \"<id>\" }, and a secret when the sender makes its own.";
+		const refusal = outside(input, "workflows");
+		if (refusal) return refusal;
+		const before = await recordBefore(context, "workflows", id, void 0);
+		if (typeof before === "string") return before;
+		if (!before) return refused(notFound("No workflows with this key that you may read"));
+		const { text, described } = await approvalTexts(context, "workflows");
+		const answer = await context.approve({
+			title: text("webhookTitle", { record: recordName(described, id, before.record) }),
+			body: text("webhookBody"),
+			approveLabel: text("issue"),
+			rejectLabel: text("reject")
+		});
+		if (answer !== "approved") return notApproved(answer);
+		return issue(context.session, id, textOf(args.secret) || void 0).then((issued) => JSON.stringify(issued), refused);
+	}
+});
+/** The tools that turn workflows on and issue their webhook URLs; `new_webhook_url` only where the app can issue them. */
+const webhookTools = (input = {}, issue) => [enableWorkflowTool(input), ...issue ? [newWebhookUrlTool(issue, input)] : []];
+//#endregion
+export { enableWorkflowTool, newWebhookUrlTool, webhookTools };

package/dist/workflows/mcp/workflow-instructions.js

@@ -4,7 +4,7 @@ import { limits } from "@protobase/workflows";
 * profile of the States Language with JSONata, and how the workflow tools find, make, change and test-run them.
 */
 const workflowInstructions = [
-	"Workflows: list_workflow_types names the step types and triggers with their arguments and inputs; list_workflows and get_workflow read workflows; validate_workflow checks a definition without saving it; create_workflow and update_workflow save one; run_workflow starts a run with an input, and get_workflow_run reads it with each step's input, output, logs and error. A run goes on in the background: read it again until its status is succeeded or failed, then fix the step that failed with update_workflow and run it again.",
+	"Workflows: list_workflow_types names the step types and triggers with their arguments and inputs; list_workflows and get_workflow read workflows; validate_workflow checks a definition without saving it; create_workflow and update_workflow save one; run_workflow starts a run with an input, and get_workflow_run reads it with each step's input, output, logs and error. A run goes on in the background: read it again until its status is succeeded or failed, then fix the step that failed with update_workflow and run it again. A trigger starts runs only once enable_workflow turned the workflow on. A webhook trigger whose sender you give a URL, such as app:webhook, gets its URL and secret from new_webhook_url, shown once; one that registers its own URL with its service as the workflow is turned on needs none, and new_webhook_url refuses it.",
 	"A definition is one JSON document: { \"trigger\": <trigger>, \"stateMachine\": { \"QueryLanguage\": \"JSONata\", \"StartAt\": \"<state>\", \"States\": { \"<state>\": <state>, ... } } }, the States Language with JSONata expressions, in a profile where every value is read by name. It holds no layout. <trigger> is an object with one key: { \"<trigger id>\": <its input> } for a trigger list_workflow_types names, or { \"manual\": {} } for a workflow that runs only when someone starts it.",
 	"States: Task { Resource: <step type>, Arguments, TimeoutSeconds, Retry, Catch }; Pass { Output, Assign }; Choice { Choices: [{ Condition, Next, Output?, Assign? }], Default }; Map { Items, ItemProcessor: { StartAt, States }, MaxConcurrency }; Wait { Seconds | Timestamp }; Succeed { Output }; Fail { Error, Cause }. Every state may have Comment, Output and Assign. Task, Pass, Map and Wait have exactly one of Next (a state name) and End: true. State names are unique across the document, Maps included, and every state must be reachable from StartAt. InputPath, Parameters, ResultPath and the other JSONPath fields, and Parallel, are not part of the profile.",
 	"Expressions: a string that is whole \"{% ... %}\" is a JSONata expression whose value, of any type, the field takes; any other string is literal text. Build text inside one expression with &: \"{% 'Order ' & $order.id %}\". Expressions sit at any depth in Arguments, Output and Assign, and in Items, Condition, Seconds, Timestamp, Error and Cause.",

package/dist/workflows/mcp/workflow-read-tools.d.ts

@@ -1,4 +1,5 @@
 import { AssistantTool, ToolContext } from "../../assistant/tools.js";
+import { IssueWebhook } from "./webhook-tools.js";
 import "../../index.js";
 import { ResourceModel } from "@protobase/schema";
 import { CheckOptions, TypeEntry } from "@protobase/workflows";
@@ -10,6 +11,8 @@ import { CheckOptions, TypeEntry } from "@protobase/workflows";
 export type WorkflowCatalog = {
   types: readonly TypeEntry[];
   checkWith: (models: (name: string) => ResourceModel | undefined) => CheckOptions;
+  /** Issues a workflow's webhook URL as the caller, for `new_webhook_url`. */
+  issueWebhook?: IssueWebhook;
 };
 /** The tools that read workflows, their types and runs, and check definitions. */
 export declare const workflowReadTools: (catalog: WorkflowCatalog) => AssistantTool<ToolContext>[];