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

package/dist/endpoint/confirmations.mjs

@@ -0,0 +1,124 @@
+import { isPlainObject } from "../guards.mjs";
+import { leaseContext, leaseHandle, leaseKvSlug } from "../leases/lease.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 "../leases/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 } = leaseContext(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 = leaseKvSlug(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 : leaseHandle(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 { leasesAvailable, 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: leasesAvailable(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 { leaseKvSlug } from "../leases/lease.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 lease KV slug where uploads, downloads and confirmations are possible:
+* the KV is database-backed and no custom `auth.resolve` is set, since the
+* lease endpoints cannot replay what such a resolver authenticated by.
+*/ const leasesAvailable = (req, options) => options.auth?.resolve === void 0 ? leaseKvSlug(req.payload.config) : void 0;
+//#endregion
+export { leasesAvailable, 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 { leasesAvailable, readCapped, respond } from "./http.mjs";
+import { resolveApiKeyById } from "../auth/resolve.mjs";
+import { parseResult } from "../result.mjs";
+import { claimGrant } from "../leases/grant.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 = leasesAvailable(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/guards.mjs

@@ -1,7 +1,14 @@
 //#region src/guards.ts
 const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /**
+* A property of a plain object, `undefined` for any other value.
+*/ const propOf = (value, key) => isPlainObject(value) ? value[key] : void 0;
+/**
 * An own property only, so a client-chosen key never reads the prototype.
 */ const ownValue = (record, key) => record !== void 0 && Object.hasOwn(record, key) ? record[key] : void 0;
+/**
+* The entries whose value is not `undefined`, for spreading optional arguments
+* into a call.
+*/ const definedProps = (props) => Object.fromEntries(Object.entries(props).filter(([, value]) => value !== void 0));
 //#endregion
-export { isPlainObject, ownValue };
+export { definedProps, isPlainObject, ownValue, propOf };

package/dist/index.d.mts

@@ -1,8 +1,8 @@
 import { DocumentId } from "./entity.mjs";
-import { McpxAnyTool, McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxExposedEntity, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxScopeSlugs, McpxTool, McpxToolExtra, McpxToolScope, McpxWriteMode } from "./types.mjs";
+import { McpxAnyTool, McpxAuthResult, McpxCollectionOptions, McpxEntityCapabilities, McpxExposedEntity, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxScopeSlugs, McpxTool, McpxToolExtra, McpxToolScope } from "./types.mjs";
 import { defineMcpxTool } from "./define-tool.mjs";
 import { mcpxPlugin } from "./plugin.mjs";
 import { isMcpxRequest } from "./request.mjs";
 import { errorResult, jsonResult } from "./result.mjs";
 import { mcpxReadRequest } from "./tools/read-request.mjs";
-export { type McpxAnyTool, type McpxAuthResult, type McpxCollectionCapabilities, type McpxCollectionOptions, type DocumentId as McpxDocumentId, type McpxExposedEntity, type McpxGlobalOptions, type McpxPluginOptions, type McpxRequestContext, type McpxResolvedCapabilities, type McpxScopeSlugs, type McpxTool, type McpxToolExtra, type McpxToolScope, type McpxWriteMode, defineMcpxTool, errorResult, isMcpxRequest, jsonResult, mcpxPlugin, mcpxReadRequest };
+export { type McpxAnyTool, type McpxAuthResult, type McpxCollectionOptions, type DocumentId as McpxDocumentId, type McpxEntityCapabilities, type McpxExposedEntity, type McpxGlobalOptions, type McpxPluginOptions, type McpxRequestContext, type McpxResolvedCapabilities, type McpxScopeSlugs, type McpxTool, type McpxToolExtra, type McpxToolScope, defineMcpxTool, errorResult, isMcpxRequest, jsonResult, mcpxPlugin, mcpxReadRequest };

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { defineMcpxTool } from "./define-tool.mjs";
+import { isMcpxRequest } from "./request.mjs";
 import { errorResult, jsonResult } from "./result.mjs";
 import { mcpxReadRequest } from "./tools/read-request.mjs";
-import { isMcpxRequest } from "./request.mjs";
 import { mcpxPlugin } from "./plugin.mjs";
 export { defineMcpxTool, errorResult, isMcpxRequest, jsonResult, mcpxPlugin, mcpxReadRequest };

package/dist/leases/confirmation.mjs

@@ -0,0 +1,74 @@
+import { LEASE_ID, NO_REQ, claimLease, issueLease, leaseHandle, leasePrefixes, leasesWith, unexpired } from "./lease.mjs";
+//#region src/leases/confirmation.ts
+const CONFIRMATION_TTL_MS = 9e5;
+const HANDLE = /^[\da-f]{64}$/;
+/**
+* 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 issueLease(payload, slug, {
+		...leasePrefixes("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 (!LEASE_ID.test(id)) return;
+	const key = `${leasePrefixes("confirmation", apiKeyId).prefix}${leaseHandle(payload, id)}`;
+	const rows = await leasesWith(payload, slug, [key]);
+	return unexpired(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 claimLease(payload, slug, leasePrefixes("confirmation", apiKeyId), leaseHandle(payload, id), exp);
+/**
+* Every unexpired call of `apiKeyId` with its handle, oldest first.
+*/ const listConfirmations = async (payload, slug, apiKeyId) => {
+	const { prefix } = leasePrefixes("confirmation", apiKeyId);
+	const now = Date.now();
+	return (await leasesWith(payload, slug, [prefix])).flatMap((row) => {
+		const confirmation = unexpired(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 } = leasePrefixes("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 leasesWith(payload, slug, [prefix])) {
+		const confirmation = unexpired(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 };

package/dist/leases/grant.mjs

@@ -0,0 +1,29 @@
+import { LEASE_ID, claimLease, issueLease, leaseHandle, leasePrefixes, leasesMatching, unexpired } from "./lease.mjs";
+//#region src/leases/grant.ts
+const GRANT_TTL_MS = 3e5;
+const GRANTS_PER_KEY = 10;
+/**
+* Stores a grant and returns its id. A key may hold at most
+* {@link GRANTS_PER_KEY} grants.
+*/ const issueGrant = async (payload, slug, grant) => await issueLease(payload, slug, {
+	...leasePrefixes("grant", grant.apiKeyId),
+	cap: GRANTS_PER_KEY,
+	capMessage: `This key already has ${String(GRANTS_PER_KEY)} uploads or downloads waiting. Use or abandon them first; each expires 5 minutes after it was issued.`,
+	ttlMs: GRANT_TTL_MS,
+	data: grant
+});
+/**
+* Loads the grant for `grantId` and marks it used, or returns `undefined` for
+* a malformed, unknown, expired or used one. A malformed id is refused before
+* any database read.
+*/ const claimGrant = async (payload, slug, grantId) => {
+	if (!LEASE_ID.test(grantId)) return;
+	const handle = leaseHandle(payload, grantId);
+	const row = (await leasesMatching(payload, slug, [handle])).find((candidate) => candidate.key.startsWith("mcpx-grant:") && candidate.key.endsWith(`:${handle}`));
+	const grant = unexpired(row, Date.now());
+	if (!row || !grant) return;
+	const prefixes = leasePrefixes("grant", grant.apiKeyId);
+	return row.key === `${prefixes.prefix}${handle}` && await claimLease(payload, slug, prefixes, handle, grant.exp) ? grant : void 0;
+};
+//#endregion
+export { claimGrant, issueGrant };