@abinnovision/payloadcms-mcpx 2.0.0-beta.9 → 2.0.0

package/dist/endpoint/confirmations.mjs

@@ -0,0 +1,124 @@
+import { isPlainObject } from "../guards.mjs";
+import { grantContext, grantKvSlug, rowHandle } from "../grants/grant.mjs";
+import { respond } from "./http.mjs";
+import { CONFIRMATIONS_PATH, DECISIONS } from "../api-keys/confirmation-view.mjs";
+import { relationId } from "../auth/resolve.mjs";
+import { decideConfirmations, issueConfirmation, listConfirmations } from "../grants/confirmation.mjs";
+import { publicOrigin } from "../request.mjs";
+import { jsonResult } from "../result.mjs";
+import { BUILTIN_TOOLS } from "../tools/builtin.mjs";
+import { formatAdminURL } from "payload/shared";
+//#region src/endpoint/confirmations.ts
+const confirmableTool = (name) => BUILTIN_TOOLS.find((tool) => tool.name === name && tool.confirm);
+const keyViewUrl = (req, options, apiKeyId) => {
+	return formatAdminURL({
+		adminRoute: req.payload.config.routes.admin,
+		path: `/collections/${options.apiKeysSlug}/${String(apiKeyId)}`,
+		serverURL: publicOrigin(req)
+	});
+};
+/**
+* The `confirmation` a confirmable tool's handler gets on an MCP call. Its
+* `request` stores the call for the key's user to approve and answers with
+* the confirmation the client passes to `runConfirmed`.
+*/ const confirmationFor = (tool, scope, options) => ({
+	confirmed: false,
+	request: async (args) => {
+		const { req } = scope;
+		const { slug, apiKeyId } = grantContext(req);
+		const view = keyViewUrl(req, options, apiKeyId);
+		const { id, exp } = await issueConfirmation(req.payload, slug, {
+			apiKeyId,
+			tool,
+			args,
+			locale: req.locale ?? null,
+			fallbackLocale: req.fallbackLocale ?? null
+		});
+		return jsonResult({ confirmation: {
+			id,
+			url: `${view}?confirmation=${encodeURIComponent(id)}`,
+			expiresAt: new Date(exp).toISOString()
+		} });
+	}
+});
+const authorize = async (req, options, keyId) => {
+	const slug = grantKvSlug(req.payload.config);
+	if (slug === void 0) return respond(404, { error: "Confirmations are not available." });
+	if (req.user?.collection !== options.userCollection) return respond(401, { error: "Sign in as the user of this key." });
+	const key = typeof keyId === "string" || typeof keyId === "number" ? await req.payload.findByID({
+		collection: options.apiKeysSlug,
+		id: keyId,
+		depth: 0,
+		overrideAccess: true,
+		disableErrors: true,
+		select: { user: true }
+	}).catch(() => null) : null;
+	const user = relationId(key?.user);
+	if (!key || user === void 0 || String(user) !== String(req.user.id)) return respond(403, { error: "Only the user of this key may decide on its calls." });
+	return {
+		slug,
+		apiKeyId: key.id
+	};
+};
+const viewOf = async (req, entry, highlight) => {
+	const { tool: name, args } = entry.confirmation;
+	const tool = confirmableTool(name);
+	const summary = await tool?.confirm?.summarize({ args }, req).catch((error) => {
+		req.payload.logger.warn({
+			err: error,
+			msg: "[payloadcms-mcpx] Could not summarize a confirmation."
+		});
+	});
+	return {
+		handle: entry.handle,
+		tool: name,
+		group: tool?.confirm?.label ?? name,
+		highlighted: entry.handle === highlight,
+		summary: summary ?? {
+			label: name,
+			permanent: true
+		}
+	};
+};
+/**
+* Lists the pending calls of `?key=`, for its user's admin session. A
+* `?confirmation=` id marks its call as highlighted.
+*/ const listHandler = (options) => async (req) => {
+	const allowed = await authorize(req, options, req.searchParams.get("key"));
+	if (allowed instanceof Response) return allowed;
+	const { payload } = req;
+	const highlighted = req.searchParams.get("confirmation");
+	const highlight = highlighted === null ? void 0 : rowHandle(payload, highlighted);
+	const entries = (await listConfirmations(payload, allowed.slug, allowed.apiKeyId)).filter((entry) => entry.confirmation.state === "pending");
+	const confirmations = [];
+	for (const entry of entries) confirmations.push(await viewOf(req, entry, highlight));
+	return respond(200, { confirmations });
+};
+/**
+* Approves or rejects pending calls of a key, for its user's admin session.
+* The body is `{ key, handles, decision }`. Answers with the handles it
+* changed; a call already decided, run or expired is left out.
+*/ const decideHandler = (options) => async (req) => {
+	const body = await req.json?.().catch(() => void 0);
+	const allowed = await authorize(req, options, isPlainObject(body) ? body["key"] : void 0);
+	if (allowed instanceof Response) return allowed;
+	const handles = isPlainObject(body) ? body["handles"] : void 0;
+	const decision = isPlainObject(body) ? body["decision"] : void 0;
+	const isDecision = (value) => DECISIONS.some((candidate) => candidate === value);
+	if (!Array.isArray(handles) || handles.length > 50 || !handles.every((handle) => typeof handle === "string") || !isDecision(decision)) return respond(400, { error: `Send "handles", at most ${String(50)}, and a "decision" of "approved" or "rejected".` });
+	const decided = await decideConfirmations(req.payload, allowed.slug, allowed.apiKeyId, handles, decision);
+	return respond(200, { decided });
+};
+/**
+* The endpoints the API key's edit view reads and decides through.
+*/ const confirmationEndpoints = (options) => [{
+	path: `${options.endpointPath}${CONFIRMATIONS_PATH}`,
+	method: "get",
+	handler: listHandler(options)
+}, {
+	path: `${options.endpointPath}${CONFIRMATIONS_PATH}`,
+	method: "post",
+	handler: decideHandler(options)
+}];
+//#endregion
+export { confirmationEndpoints, confirmationFor };

package/dist/endpoint/handler.mjs

@@ -1,4 +1,5 @@
 import { resolveCapabilities, scopeSlugs } from "../capabilities.mjs";
+import { grantsAvailable, readCapped } from "./http.mjs";
 import { isValidAuthResult, resolveApiKeyAuth } from "../auth/resolve.mjs";
 import { jsonRpcError } from "./errors.mjs";
 import { createMcpServer } from "./server.mjs";
@@ -6,19 +7,6 @@ import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/
 //#region src/endpoint/handler.ts
 const BODY_BYTES_LIMIT = 4194304;
 const BATCH_MESSAGES_LIMIT = 10;
-const readBody = async (req) => {
-	if (Number(req.headers.get("content-length")) > BODY_BYTES_LIMIT) return null;
-	if (!req.body) return;
-	const decoder = new TextDecoder();
-	let text = "";
-	let size = 0;
-	for await (const chunk of req.body) {
-		size += chunk.byteLength;
-		if (size > BODY_BYTES_LIMIT) return null;
-		text += decoder.decode(chunk, { stream: true });
-	}
-	return text + decoder.decode();
-};
 /**
 * The scope the tools of one request see: the key's resolved capabilities, the
 * slugs they reach, and the locales and limits of the config.
@@ -34,6 +22,8 @@ const readBody = async (req) => {
 			defaultLocale: localization.defaultLocale
 		} : null,
 		limits: options.limits,
+		uploads: grantsAvailable(req, options) !== void 0,
+		diagnostics: options.diagnostics ? options.serverInfo : null,
 		exposure: {
 			collections: options.collections,
 			globals: options.globals
@@ -41,6 +31,22 @@ const readBody = async (req) => {
 	};
 };
 /**
+* Makes `req` act as the key: sets `req.user`, replacing any user Payload
+* resolved from cookies, and the `req.context.mcpx` stamp the draft guard
+* reads. Returns the scope the tools see.
+*/ const authenticateAs = (req, options, auth) => {
+	const capabilities = resolveCapabilities(options, auth.capabilities);
+	req.user = auth.user;
+	req.context = {
+		...req.context,
+		mcpx: {
+			apiKeyId: auth.apiKeyId,
+			capabilities
+		}
+	};
+	return buildScope(req, options, capabilities);
+};
+/**
 * Answers GET and DELETE on the endpoint path. The server is stateless and
 * never streams, so only POST carries meaning.
 */ const methodNotAllowed = () => jsonRpcError({
@@ -69,24 +75,16 @@ const readBody = async (req) => {
 			headers: { "www-authenticate": "Bearer" }
 		});
 	}
-	const capabilities = resolveCapabilities(options, auth.capabilities);
-	req.user = auth.user;
-	req.context = {
-		...req.context,
-		mcpx: {
-			apiKeyId: auth.apiKeyId,
-			capabilities
-		}
-	};
+	const scope = authenticateAs(req, options, auth);
 	let parsedBody;
 	try {
-		const text = await readBody(req);
-		if (text === null) return jsonRpcError({
+		const body = await readCapped(req, BODY_BYTES_LIMIT);
+		if (body === null) return jsonRpcError({
 			status: 413,
 			code: -32e3,
 			message: `Request body too large: the limit is ${String(BODY_BYTES_LIMIT / 1024 / 1024)} MB.`
 		});
-		parsedBody = text === void 0 ? void 0 : JSON.parse(text);
+		parsedBody = body === void 0 ? void 0 : JSON.parse(new TextDecoder().decode(body));
 	} catch {
 		return jsonRpcError({
 			status: 400,
@@ -104,7 +102,7 @@ const readBody = async (req) => {
 		code: -32600,
 		message: `Invalid request: a batch may hold at most ${String(BATCH_MESSAGES_LIMIT)} messages.`
 	});
-	const server = createMcpServer(buildScope(req, options, capabilities), options);
+	const server = createMcpServer(scope, options);
 	const transport = new WebStandardStreamableHTTPServerTransport({ enableJsonResponse: true });
 	await server.connect(transport);
 	const headers = new Headers(req.headers);
@@ -119,4 +117,4 @@ const readBody = async (req) => {
 	}
 };
 //#endregion
-export { buildScope, createMcpxHandler, methodNotAllowed };
+export { authenticateAs, buildScope, createMcpxHandler, methodNotAllowed };

package/dist/endpoint/http.mjs

@@ -0,0 +1,27 @@
+import { grantKvSlug } from "../grants/grant.mjs";
+//#region src/endpoint/http.ts
+const respond = (status, body) => Response.json(body, { status });
+/**
+* The body, `null` once it passes `max` bytes, or `undefined` when there is
+* none. A declared length over `max` is refused unread. A chunked body
+* declares none, so bytes are counted as they arrive and reading stops at
+* `max`.
+*/ const readCapped = async (req, max) => {
+	if (Number(req.headers.get("content-length")) > max) return null;
+	if (!req.body) return;
+	const chunks = [];
+	let size = 0;
+	for await (const chunk of req.body) {
+		size += chunk.byteLength;
+		if (size > max) return null;
+		chunks.push(chunk);
+	}
+	return Buffer.concat(chunks);
+};
+/**
+* The grant KV slug where uploads, downloads and confirmations are possible:
+* the KV is database-backed and no custom `auth.resolve` is set, since the
+* grant endpoints cannot replay what such a resolver authenticated by.
+*/ const grantsAvailable = (req, options) => options.auth?.resolve === void 0 ? grantKvSlug(req.payload.config) : void 0;
+//#endregion
+export { grantsAvailable, readCapped, respond };

package/dist/endpoint/server.mjs

@@ -1,16 +1,45 @@
-import { toToolError } from "./errors.mjs";
+import { isToolEnabled, toolInputSchema } from "../define-tool.mjs";
+import { fileSlugs } from "../upload/file.mjs";
 import { liveWriteSlugs } from "../tools/shared.mjs";
+import { MCPX_REPOSITORY_URL } from "../version.mjs";
 import { BUILTIN_TOOLS } from "../tools/builtin.mjs";
+import { confirmationFor } from "./confirmations.mjs";
+import { toToolError } from "./errors.mjs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
 //#region src/endpoint/server.ts
-/**
-* Strict, so an unknown argument is rejected by name instead of stripped.
-*/ const toolInputSchema = (tool, scope) => z.strictObject(typeof tool.inputSchema === "function" ? tool.inputSchema(scope) : tool.inputSchema ?? {});
 const toolDescription = (tool, scope) => typeof tool.description === "function" ? tool.description(scope) : tool.description;
+const NO_CONFIRMATION = {
+	confirmed: false,
+	request: () => Promise.reject(/* @__PURE__ */ new Error("No confirmation can be stored here."))
+};
 /**
-* A tool that does not decide for itself is gated by its own checkbox.
-*/ const isToolEnabled = (tool, scope) => tool.isEnabled ? tool.isEnabled(scope) : scope.capabilities.tools[tool.name] === true;
+* Runs one tool call. Payload's public errors become error results; anything
+* else is logged and reported as an internal error. A tool with `confirm`
+* gets `confirmation`.
+*/ const runTool = async (tool, args, scope, req, extra, confirmation = NO_CONFIRMATION) => {
+	const ctx = {
+		args,
+		scope,
+		req,
+		extra
+	};
+	try {
+		return await (tool.confirm ? tool.handler({
+			...ctx,
+			confirmation
+		}) : tool.handler(ctx));
+	} catch (error) {
+		return toToolError(error, req.payload.logger);
+	}
+};
+const WRITE_STEP = {
+	tools: [
+		"patchDocument",
+		"createDocument",
+		"duplicateDocument"
+	],
+	does: "the write"
+};
 const WORKFLOW = [
 	{
 		tools: ["listCapabilities"],
@@ -24,10 +53,7 @@ const WORKFLOW = [
 		tools: ["findDocuments", "getDocument"],
 		does: "the content and its \"updatedAt\""
 	},
-	{
-		tools: ["patchDocument", "createDocument"],
-		does: "the write"
-	},
+	WRITE_STEP,
 	{
 		tools: ["validateDocument"],
 		does: "what blocks publishing"
@@ -37,6 +63,7 @@ const WORKFLOW = [
 		does: "make the draft public"
 	}
 ];
+const UPLOAD_STEP = "A write that returns \"upload\": PUT the file bytes to its \"url\" with its \"headers\". The response is the result of the write.";
 const PATHS = `describeSchema takes and returns schema paths. Every other "path", and "from" in a patch operation, is a pointer into a document, with a 0-based index where a schema path has "*" for an array element or a block slug: "/layout/sections/sectionWrapper/identifier" is "/layout/sections/0/identifier". In rich text a pointer enters the rich text state: "/content/block/callout/tone" is "/content/root/children/3/fields/tone". getDocument "outline" gives the index.`;
 const DRAFTS = "Writes are saved as drafts, except in collections and globals without drafts, which patchDocument names: those go live immediately.";
 const DRAFTS_ONLY = "Every write is saved as a draft.";
@@ -44,9 +71,12 @@ const DRAFTS_ONLY = "Every write is saved as a draft.";
 * The workflow for the tools this key has, and what its writes reach.
 */ const serverInstructions = (scope) => {
 	const enabled = new Set(BUILTIN_TOOLS.filter((tool) => isToolEnabled(tool, scope)).map((tool) => tool.name));
-	const steps = WORKFLOW.flatMap(({ tools, does }) => {
-		const present = tools.filter((name) => enabled.has(name));
-		return present.length === 0 ? [] : [`${present.join(" or ")}: ${does}.`];
+	const uploads = fileSlugs(scope).length > 0;
+	const steps = WORKFLOW.flatMap((step) => {
+		const present = step.tools.filter((name) => enabled.has(name));
+		if (present.length === 0) return [];
+		const line = `${present.join(" or ")}: ${step.does}.`;
+		return step === WRITE_STEP && uploads ? [line, UPLOAD_STEP] : [line];
 	}).map((step, index) => `${String(index + 1)}. ${step}`);
 	const publishing = enabled.has("publishDocument") ? "" : " This key cannot publish. A person publishes drafts in the admin panel.";
 	const drafts = liveWriteSlugs(scope, "write").length === 0 ? DRAFTS_ONLY : DRAFTS;
@@ -61,11 +91,11 @@ const DRAFTS_ONLY = "Every write is saved as a draft.";
 * so a failed call cannot roll back a write another call reported as done.
 */ const createMcpServer = (scope, options) => {
 	const { req } = scope;
-	const { logger } = req.payload;
 	let queue = Promise.resolve();
 	const server = new McpServer({
 		name: options.serverInfo.name,
-		version: options.serverInfo.version
+		version: options.serverInfo.version,
+		...options.diagnostics ? { websiteUrl: MCPX_REPOSITORY_URL } : {}
 	}, { instructions: serverInstructions(scope) });
 	for (const tool of [...BUILTIN_TOOLS, ...options.tools]) {
 		if (!isToolEnabled(tool, scope)) continue;
@@ -74,18 +104,7 @@ const DRAFTS_ONLY = "Every write is saved as a draft.";
 			inputSchema: toolInputSchema(tool, scope),
 			...tool.annotations ? { annotations: tool.annotations } : {}
 		}, (args, extra) => {
-			const result = queue.then(async () => {
-				try {
-					return await tool.handler({
-						args,
-						scope,
-						req,
-						extra
-					});
-				} catch (error) {
-					return toToolError(error, logger);
-				}
-			});
+			const result = queue.then(async () => await runTool(tool, args, scope, req, extra, confirmationFor(tool.name, scope, options)));
 			queue = result.catch(() => void 0);
 			return result;
 		});
@@ -93,4 +112,4 @@ const DRAFTS_ONLY = "Every write is saved as a draft.";
 	return server;
 };
 //#endregion
-export { createMcpServer, isToolEnabled, toolInputSchema };
+export { createMcpServer, runTool };

package/dist/endpoint/upload.mjs

@@ -0,0 +1,104 @@
+import { isToolEnabled, toolInputSchema } from "../define-tool.mjs";
+import { claimGrant } from "../grants/grant.mjs";
+import { grantsAvailable, readCapped, respond } from "./http.mjs";
+import { resolveApiKeyById } from "../auth/resolve.mjs";
+import { parseResult } from "../result.mjs";
+import { downloadSlugs, setUploadedFile, uploadMaxBytes } from "../upload/file.mjs";
+import { BUILTIN_TOOLS } from "../tools/builtin.mjs";
+import { runTool } from "./server.mjs";
+import { authenticateAs } from "./handler.mjs";
+//#region src/endpoint/upload.ts
+const UPLOAD_TOOLS = /* @__PURE__ */ new Set(["createDocument", "patchDocument"]);
+const refused = () => respond(403, { error: "The request was refused: the grant is unknown, expired or used, or the key no longer allows it. Call the tool again for a new one." });
+const statusOf = (result, data) => {
+	if (result.isError !== true) return 200;
+	if ("updatedAt" in data || data["status"] === 423) return 409;
+	if (data["status"] === 401 || data["status"] === 403) return 403;
+	return data["error"] === "Internal error" ? 500 : 422;
+};
+const NO_SESSION = {
+	signal: new AbortController().signal,
+	requestId: "upload",
+	sendNotification: () => Promise.resolve(),
+	sendRequest: () => Promise.reject(/* @__PURE__ */ new Error("No MCP session."))
+};
+const claimAs = async (req, options, kind) => {
+	const slug = grantsAvailable(req, options);
+	const grantId = req.headers.get("x-mcpx-grant");
+	if (slug === void 0 || grantId === null) return;
+	const grant = await claimGrant(req.payload, slug, grantId);
+	if (grant?.kind !== kind) return;
+	const auth = await resolveApiKeyById(req, options, grant.apiKeyId);
+	if (!auth) return;
+	const scope = authenticateAs(req, options, auth);
+	req.query = {};
+	for (const name of [...req.searchParams.keys()]) req.searchParams.delete(name);
+	req.locale = grant.locale;
+	req.fallbackLocale = grant.fallbackLocale;
+	return {
+		grant,
+		scope
+	};
+};
+/**
+* Completes a call that returned an `upload`: claims the grant, acts as its
+* key again, then runs the same tool with the same arguments and the body as
+* the file. The response body is the tool's result. The grant header is never
+* logged.
+*/ const createUploadHandler = (options) => async (req) => {
+	const { payload } = req;
+	const claimed = await claimAs(req, options, "upload");
+	if (!claimed || !UPLOAD_TOOLS.has(claimed.grant.tool) || !claimed.grant.file) return refused();
+	const { grant, scope } = claimed;
+	const { file } = grant;
+	const tool = BUILTIN_TOOLS.find((candidate) => candidate.name === grant.tool);
+	if (!tool || !isToolEnabled(tool, scope)) return refused();
+	const args = toolInputSchema(tool, scope).safeParse(grant.args);
+	if (!args.success) return refused();
+	if (file.size > uploadMaxBytes(payload.config)) return respond(413, { error: "The file is larger than allowed." });
+	const data = await readCapped(req, file.size);
+	if (data?.length !== file.size) return respond(400, { error: `The body must be exactly ${String(file.size)} bytes, the size the tool call declared.` });
+	setUploadedFile(req, {
+		data,
+		mimetype: file.mimeType,
+		name: file.filename,
+		size: data.length
+	});
+	const result = await runTool(tool, args.data, scope, req, NO_SESSION);
+	const body = parseResult(result);
+	return respond(statusOf(result, body), body);
+};
+/**
+* Serves the file of a `getDocument` call that returned a `download`: claims
+* the grant, acts as its key again, reloads the document as its user and
+* hands the request to the collection's own `/file/:filename` endpoint, so
+* Payload's file access, storage handlers and response headers apply.
+*/ const createDownloadHandler = (options) => async (req) => {
+	const claimed = await claimAs(req, options, "download");
+	if (!claimed || !downloadSlugs(claimed.scope).includes(claimed.grant.collection)) return refused();
+	const { collection, id, draft } = claimed.grant;
+	const doc = await req.payload.findByID({
+		collection,
+		id,
+		depth: 0,
+		draft,
+		overrideAccess: false,
+		disableErrors: true,
+		select: {
+			filename: true,
+			prefix: true
+		},
+		req
+	});
+	const { endpoints } = req.payload.collections[collection]?.config ?? {};
+	const endpoint = Array.isArray(endpoints) ? endpoints.find((candidate) => candidate.method === "get" && candidate.path === "/file/:filename") : void 0;
+	if (typeof doc?.filename !== "string" || !endpoint) return refused();
+	if (typeof doc.prefix === "string") req.searchParams.set("prefix", doc.prefix);
+	req.routeParams = {
+		collection,
+		filename: doc.filename
+	};
+	return await endpoint.handler(req);
+};
+//#endregion
+export { createDownloadHandler, createUploadHandler };

package/dist/grants/confirmation.mjs

@@ -0,0 +1,75 @@
+import { NO_REQ, ROW_ID, claimRow, expOf, issueRow, rowHandle, rowPrefixes, rowsWith } from "./grant.mjs";
+//#region src/grants/confirmation.ts
+const CONFIRMATION_TTL_MS = 9e5;
+const HANDLE = /^[\da-f]{64}$/;
+const asConfirmation = (row, now) => row && expOf(row.data) > now ? row.data : void 0;
+/**
+* Stores a pending call and returns its id. A key may hold at most
+* {@link CONFIRMATIONS_PER_KEY} calls.
+*/ const issueConfirmation = async (payload, slug, call) => {
+	const entry = {
+		...call,
+		state: "pending"
+	};
+	return await issueRow(payload, slug, {
+		...rowPrefixes("confirmation", call.apiKeyId),
+		cap: 50,
+		capMessage: `This key already has ${String(50)} calls waiting for approval. Run or abandon them first; each expires 15 minutes after it was requested.`,
+		ttlMs: CONFIRMATION_TTL_MS,
+		data: entry
+	});
+};
+/**
+* The unexpired call of `apiKeyId` with `id`, without claiming it. A call of
+* another key is `undefined`, as is a malformed id, before any database read.
+*/ const readConfirmation = async (payload, slug, apiKeyId, id) => {
+	if (!ROW_ID.test(id)) return;
+	const key = `${rowPrefixes("confirmation", apiKeyId).prefix}${rowHandle(payload, id)}`;
+	const rows = await rowsWith(payload, slug, [key]);
+	return asConfirmation(rows.find((row) => row.key === key), Date.now());
+};
+/**
+* Marks the call used and removes it. Of two concurrent claims exactly one
+* returns `true`.
+*/ const claimConfirmation = async (payload, slug, apiKeyId, id, exp) => await claimRow(payload, slug, rowPrefixes("confirmation", apiKeyId), rowHandle(payload, id), exp);
+/**
+* Every unexpired call of `apiKeyId` with its handle, oldest first.
+*/ const listConfirmations = async (payload, slug, apiKeyId) => {
+	const { prefix } = rowPrefixes("confirmation", apiKeyId);
+	const now = Date.now();
+	return (await rowsWith(payload, slug, [prefix])).flatMap((row) => {
+		const confirmation = asConfirmation(row, now);
+		return confirmation ? [{
+			handle: row.key.slice(prefix.length),
+			confirmation
+		}] : [];
+	}).sort((left, right) => left.confirmation.exp - right.confirmation.exp);
+};
+/**
+* Approves or rejects the pending calls of `apiKeyId` among `handles`, and
+* returns the handles it changed. A call that was decided, run or expired is
+* left alone and not returned.
+*/ const decideConfirmations = async (payload, slug, apiKeyId, handles, state) => {
+	const { prefix } = rowPrefixes("confirmation", apiKeyId);
+	const keys = new Set(handles.filter((handle) => HANDLE.test(handle)).map((handle) => `${prefix}${handle}`));
+	if (keys.size === 0) return [];
+	const now = Date.now();
+	const decided = [];
+	for (const row of await rowsWith(payload, slug, [prefix])) {
+		const confirmation = asConfirmation(row, now);
+		if (!keys.has(row.key) || confirmation?.state !== "pending") continue;
+		const updated = await payload.db.updateMany({
+			collection: slug,
+			where: { and: [{ key: { equals: row.key } }, { "data.state": { equals: "pending" } }] },
+			data: { data: {
+				...confirmation,
+				state
+			} },
+			req: NO_REQ
+		});
+		if (updated !== null && updated.length > 0) decided.push(row.key.slice(prefix.length));
+	}
+	return decided;
+};
+//#endregion
+export { claimConfirmation, decideConfirmations, issueConfirmation, listConfirmations, readConfirmation };