@abinnovision/payloadcms-mcpx 2.0.0-beta.13 → 2.0.0-beta.15

package/dist/api-keys/fields.mjs

@@ -1,5 +1,5 @@
 import { CAPABILITIES_FIELD } from "../capabilities.mjs";
-import { CAPABILITIES_DESCRIPTION, CAPABILITY_OPERATIONS, createCapabilityMatrix } from "./capability-matrix.mjs";
+import { CAPABILITIES_DESCRIPTION, STORED_OPERATIONS, createCapabilityMatrix } from "./capability-matrix.mjs";
 //#region src/api-keys/fields.ts
 const encryptKey = ({ req, value }) => typeof value === "string" ? req.payload.encrypt(value) : value;
 const decryptKey = ({ req, value }) => {
@@ -79,6 +79,23 @@ const SETUP_GUIDE_FIELD = "setupGuide";
 	}
 ];
 /**
+* The pending calls of the key, above everything else on its edit view, where
+* a collection exposes `delete`. The component renders nothing while none is
+* pending and never touches the form, so deciding does not mark the key
+* modified.
+*/ const createConfirmationFields = (options) => options.confirmations ? [{
+	name: "confirmations",
+	type: "ui",
+	admin: {
+		disableListColumn: true,
+		components: { Field: {
+			path: "@abinnovision/payloadcms-mcpx/admin",
+			exportName: "McpxConfirmations",
+			clientProps: { endpointPath: options.endpointPath }
+		} }
+	}
+}] : [];
+/**
 * Wraps the key fields and the setup guide in unnamed tabs, so wide snippets
 * get the full form width. Named tabs would nest the data and move
 * `capabilities` off the document root, which capability resolution reads.
@@ -124,7 +141,7 @@ const SETUP_GUIDE_FIELD = "setupGuide";
 		name: row.fieldName,
 		type: "group",
 		label: row.label,
-		fields: CAPABILITY_OPERATIONS.filter((operation) => row[operation.id]).map((operation) => checkbox(operation.id, operation.description))
+		fields: STORED_OPERATIONS.filter((operation) => row[operation.id]).map((operation) => checkbox(operation.id, operation.description))
 	}));
 	const collectionGroups = entityGroups(matrix.collections);
 	const globalGroups = entityGroups(matrix.globals);
@@ -165,4 +182,4 @@ const SETUP_GUIDE_FIELD = "setupGuide";
 	}];
 };
 //#endregion
-export { createCapabilityFields, createKeyFields, withSetupGuideTab };
+export { createCapabilityFields, createConfirmationFields, createKeyFields, withSetupGuideTab };

package/dist/builtin-tool-names.mjs

@@ -10,7 +10,9 @@
 	"patchDocument",
 	"createDocument",
 	"validateDocument",
-	"publishDocument"
+	"publishDocument",
+	"deleteDocument",
+	"runConfirmed"
 ];
 //#endregion
 export { BUILTIN_TOOL_NAMES };

package/dist/capabilities.mjs

@@ -17,7 +17,8 @@ import { isPlainObject } from "./guards.mjs";
 * Without drafts there is no draft stage, so every write is live.
 */ const isLiveWrite = (entity) => entity.write === "live" && !entity.hasDrafts;
 const flag = (group, name) => isPlainObject(group) && group[name] === true;
-const publishFlag = (entity, group) => canPublish(entity) && flag(group, "write") && flag(group, "publish");
+const writeFlag = (entity, group) => canWrite(entity) && entity.read && flag(group, "read") && flag(group, "write");
+const publishFlag = (entity, group) => canPublish(entity) && writeFlag(entity, group) && flag(group, "publish");
 /**
 * Capabilities in force for a key: the plugin config decides what can exist,
 * the key's checkboxes decide what does. A missing checkbox is `false`, so keys
@@ -28,10 +29,13 @@ const publishFlag = (entity, group) => canPublish(entity) && flag(group, "write"
 		const resolved = {};
 		for (const entity of entities) {
 			const group = isPlainObject(namespaceGroup) ? namespaceGroup[entity.fieldName] : void 0;
+			const deleting = entity.delete && flag(group, "read") && flag(group, "delete");
 			resolved[entity.slug] = {
 				read: entity.read && flag(group, "read"),
-				write: canWrite(entity) && flag(group, "write"),
-				publish: publishFlag(entity, group)
+				write: writeFlag(entity, group),
+				publish: publishFlag(entity, group),
+				delete: deleting,
+				deleteUnattended: deleting && entity.deleteUnattended && flag(group, "deleteUnattended")
 			};
 		}
 		return resolved;
@@ -53,7 +57,8 @@ const publishFlag = (entity, group) => canPublish(entity) && flag(group, "write"
 	return {
 		readable: slugsWith("read"),
 		writable: slugsWith("write"),
-		publishable: slugsWith("publish")
+		publishable: slugsWith("publish"),
+		deletable: slugsWith("delete")
 	};
 };
 //#endregion

package/dist/define-tool.d.mts

@@ -1,23 +1,23 @@
-import { McpxAnyTool, McpxTool, McpxToolScope } from "./types.mjs";
+import { McpxAnyTool, McpxTool, McpxToolConfirm, McpxToolDefinition, McpxToolScope } from "./types.mjs";
 import { z } from "zod";
 //#region src/define-tool.d.ts
 /**
  * Fixed shape; arguments inferred from it.
  */
-export declare function defineMcpxTool<Shape extends z.ZodRawShape>(tool: McpxTool<Shape> & {
+export declare function defineMcpxTool<Shape extends z.ZodRawShape, Confirm extends McpxToolConfirm | undefined = undefined>(tool: McpxToolDefinition<Shape, z.infer<z.ZodObject<Shape>>, Confirm> & {
   inputSchema?: Shape;
 }): McpxTool<Shape>;
 /**
  * Per-request shape returned as an object literal; arguments inferred from it.
  */
-export declare function defineMcpxTool<Shape extends z.ZodRawShape>(tool: McpxTool<Shape> & {
+export declare function defineMcpxTool<Shape extends z.ZodRawShape, Confirm extends McpxToolConfirm | undefined = undefined>(tool: McpxToolDefinition<Shape, z.infer<z.ZodObject<Shape>>, Confirm> & {
   inputSchema: (scope: McpxToolScope) => Shape;
 }): McpxAnyTool;
 /**
  * Per-request shape built from helpers that erase to `z.ZodRawShape`, as the
  * builtins do. Nothing to infer from, so state the arguments instead.
  */
-export declare function defineMcpxTool<Args>(tool: McpxTool<z.ZodRawShape, Args> & {
+export declare function defineMcpxTool<Args, Confirm extends McpxToolConfirm | undefined = undefined>(tool: McpxToolDefinition<z.ZodRawShape, Args, Confirm> & {
   inputSchema: (scope: McpxToolScope) => z.ZodRawShape;
 }): McpxAnyTool;
 //#endregion

package/dist/define-tool.mjs

@@ -1,6 +1,13 @@
+import { z } from "zod";
 //#region src/define-tool.ts
 function defineMcpxTool(tool) {
 	return tool;
 }
+/**
+* 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 ?? {});
+/**
+* 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;
 //#endregion
-export { defineMcpxTool };
+export { defineMcpxTool, isToolEnabled, toolInputSchema };

package/dist/endpoint/confirmations.mjs

@@ -0,0 +1,124 @@
+import { isPlainObject } from "../guards.mjs";
+import { CONFIRMATIONS_PATH } from "../api-keys/confirmation-view.mjs";
+import { grantKvSlug } from "../grants/grant.mjs";
+import { confirmationHandle, decideConfirmations, issueConfirmation, listConfirmations } from "../grants/confirmation.mjs";
+import { jsonResult } from "../result.mjs";
+import { BUILTIN_TOOLS } from "../tools/builtin.mjs";
+import { formatAdminURL } from "payload/shared";
+//#region src/endpoint/confirmations.ts
+const respond = (status, body) => Response.json(body, { status });
+const confirmableTool = (name) => BUILTIN_TOOLS.find((tool) => tool.name === name && tool.confirm);
+const keyViewUrl = (req, options, apiKeyId) => {
+	const { config } = req.payload;
+	return formatAdminURL({
+		adminRoute: config.routes.admin,
+		path: `/collections/${options.apiKeysSlug}/${String(apiKeyId)}`,
+		serverURL: config.serverURL || new URL(req.url ?? "").origin
+	});
+};
+/**
+* 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 = grantKvSlug(req.payload.config);
+		const apiKeyId = req.context.mcpx?.apiKeyId;
+		if (slug === void 0 || apiKeyId === void 0) throw new Error("A confirmation was requested without a database KV.");
+		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 = isPlainObject(key?.user) ? key.user["id"] : key?.user;
+	if (!key || typeof user !== "string" && typeof user !== "number" || 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 : confirmationHandle(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;
+	if (!Array.isArray(handles) || handles.length > 50 || !handles.every((handle) => typeof handle === "string") || decision !== "approved" && decision !== "rejected") 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,7 +1,7 @@
 import { resolveCapabilities, scopeSlugs } from "../capabilities.mjs";
+import { grantKvSlug } from "../grants/grant.mjs";
 import { isValidAuthResult, resolveApiKeyAuth } from "../auth/resolve.mjs";
 import { jsonRpcError } from "./errors.mjs";
-import { uploadKvSlug } from "../upload/grant.mjs";
 import { createMcpServer } from "./server.mjs";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 //#region src/endpoint/handler.ts
@@ -35,7 +35,7 @@ const readBody = async (req) => {
 			defaultLocale: localization.defaultLocale
 		} : null,
 		limits: options.limits,
-		uploads: options.auth?.resolve === void 0 && uploadKvSlug(req.payload.config) !== void 0,
+		uploads: options.auth?.resolve === void 0 && grantKvSlug(req.payload.config) !== void 0,
 		diagnostics: options.diagnostics ? {
 			name: options.serverInfo.name,
 			version: options.serverInfo.version

package/dist/endpoint/server.mjs

@@ -1,29 +1,33 @@
-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;
-/**
-* 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;
+const NO_CONFIRMATION = {
+	confirmed: false,
+	request: () => Promise.reject(/* @__PURE__ */ new Error("No confirmation can be stored here."))
+};
 /**
 * Runs one tool call. Payload's public errors become error results; anything
-* else is logged and reported as an internal error.
-*/ const runTool = async (tool, args, scope, req, extra) => {
+* 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.handler({
-			args,
-			scope,
-			req,
-			extra
-		});
+		return await (tool.confirm ? tool.handler({
+			...ctx,
+			confirmation
+		}) : tool.handler(ctx));
 	} catch (error) {
 		return toToolError(error, req.payload.logger);
 	}
@@ -96,7 +100,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 () => await runTool(tool, args, scope, req, extra));
+			const result = queue.then(async () => await runTool(tool, args, scope, req, extra, confirmationFor(tool.name, scope, options)));
 			queue = result.catch(() => void 0);
 			return result;
 		});
@@ -104,4 +108,4 @@ const DRAFTS_ONLY = "Every write is saved as a draft.";
 	return server;
 };
 //#endregion
-export { createMcpServer, isToolEnabled, runTool, toolInputSchema };
+export { createMcpServer, runTool };

package/dist/endpoint/upload.mjs

@@ -1,8 +1,9 @@
-import { checkApiKey } from "../auth/resolve.mjs";
-import { claimGrant, uploadKvSlug } from "../upload/grant.mjs";
+import { isToolEnabled, toolInputSchema } from "../define-tool.mjs";
+import { claimGrant, grantKvSlug } from "../grants/grant.mjs";
 import { downloadSlugs, setUploadedFile, uploadMaxBytes } from "../upload/file.mjs";
 import { BUILTIN_TOOLS } from "../tools/builtin.mjs";
-import { isToolEnabled, runTool, toolInputSchema } from "./server.mjs";
+import { checkApiKey } from "../auth/resolve.mjs";
+import { runTool } from "./server.mjs";
 import { authenticateAs } from "./handler.mjs";
 //#region src/endpoint/upload.ts
 const UPLOAD_TOOLS = /* @__PURE__ */ new Set(["createDocument", "patchDocument"]);
@@ -54,7 +55,7 @@ const reauthenticate = async (req, options, grant) => {
 	return await checkApiKey(req, options, keyDoc ?? void 0);
 };
 const claimAs = async (req, options, kind) => {
-	const slug = uploadKvSlug(req.payload.config);
+	const slug = grantKvSlug(req.payload.config);
 	const grantId = req.headers.get("x-mcpx-grant");
 	if (slug === void 0 || options.auth?.resolve || grantId === null) return;
 	const grant = await claimGrant(req.payload, slug, grantId);

package/dist/grants/confirmation.mjs

@@ -0,0 +1,106 @@
+import { isPlainObject } from "../guards.mjs";
+import { hashApiKey } from "../api-keys/key.mjs";
+import { GRANT_ID, NO_REQ, expOf, issueRow, rowsWith } from "./grant.mjs";
+import { ValidationError } from "payload";
+//#region src/grants/confirmation.ts
+const CONFIRMATION_TTL_MS = 9e5;
+const HANDLE = /^[\da-f]{64}$/;
+const entryPrefix = (apiKeyId) => `mcpx-confirmation:${String(apiKeyId)}:`;
+const usedPrefix = (apiKeyId) => `mcpx-confirmation-used:${String(apiKeyId)}:`;
+const asConfirmation = (row, now) => row && isPlainObject(row.data) && expOf(row.data) > now ? row.data : void 0;
+/**
+* The handle the admin panel uses for the entry of `id`: its HMAC, which is
+* also what the row key holds.
+*/ const confirmationHandle = (payload, id) => hashApiKey(payload.secret, id);
+/**
+* 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, {
+		prefix: entryPrefix(call.apiKeyId),
+		usedPrefix: usedPrefix(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 (!GRANT_ID.test(id)) return;
+	const key = `${entryPrefix(apiKeyId)}${confirmationHandle(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. The marker is a unique-key insert, so
+* of two concurrent claims exactly one returns `true`.
+*/ const claimConfirmation = async (payload, slug, apiKeyId, id, exp) => {
+	const handle = confirmationHandle(payload, id);
+	try {
+		await payload.db.create({
+			collection: slug,
+			data: {
+				key: `${usedPrefix(apiKeyId)}${handle}`,
+				data: { exp }
+			},
+			req: NO_REQ
+		});
+	} catch (error) {
+		if (error instanceof ValidationError) return false;
+		throw error;
+	}
+	await payload.db.deleteOne({
+		collection: slug,
+		where: { key: { equals: `${entryPrefix(apiKeyId)}${handle}` } },
+		req: NO_REQ
+	});
+	return true;
+};
+/**
+* Every unexpired call of `apiKeyId` with its handle, oldest first.
+*/ const listConfirmations = async (payload, slug, apiKeyId) => {
+	const prefix = entryPrefix(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 = entryPrefix(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, confirmationHandle, decideConfirmations, issueConfirmation, listConfirmations, readConfirmation };

package/dist/{upload → grants}/grant.mjs

@@ -2,7 +2,7 @@ import { isPlainObject } from "../guards.mjs";
 import { hashApiKey } from "../api-keys/key.mjs";
 import { APIError, ValidationError } from "payload";
 import crypto from "node:crypto";
-//#region src/upload/grant.ts
+//#region src/grants/grant.ts
 const GRANT_TTL_MS = 3e5;
 const GRANTS_PER_KEY = 10;
 const GRANT_ID = /^[\w-]{43}$/;
@@ -13,12 +13,14 @@ const expOf = (data) => isPlainObject(data) && typeof data["exp"] === "number" ?
 /**
 * The KV collection slug, when Payload's database KV adapter backs it with a
 * unique `key`, which the single-use claim relies on. `undefined` otherwise.
-*/ const uploadKvSlug = (config) => {
+*/ const grantKvSlug = (config) => {
 	const kv = config.kv;
 	const key = kv?.kvCollection?.fields.find((field) => "name" in field && field.name === "key");
 	return key && "unique" in key && key.unique ? kv?.kvCollection?.slug : void 0;
 };
-const findRows = async (payload, slug, fragments) => {
+/**
+* KV rows whose key contains one of `fragments`.
+*/ const findRows = async (payload, slug, fragments) => {
 	const { docs } = await payload.db.find({
 		collection: slug,
 		where: { or: fragments.map((fragment) => ({ key: { like: fragment } })) },
@@ -29,35 +31,56 @@ const findRows = async (payload, slug, fragments) => {
 	return docs;
 };
 /**
-* Stores a grant and returns its id, the only copy of which goes to the
-* client. The row key holds the HMAC of the id. Expired rows of the same key
-* are purged first, and a key may hold at most {@link GRANTS_PER_KEY} grants.
-*/ const issueGrant = async (payload, slug, grant) => {
+* KV rows whose key starts with one of `prefixes`. `like` matches a
+* substring, so the prefix is checked again here.
+*/ const rowsWith = async (payload, slug, prefixes) => (await findRows(payload, slug, prefixes)).filter((row) => prefixes.some((prefix) => row.key.startsWith(prefix)));
+/**
+* Stores `data` under `prefix` and the HMAC of a fresh id, and returns the id,
+* the only copy of which goes to the client. Expired rows under `prefix` and
+* `usedPrefix` are purged first, and at most `cap` unexpired rows may wait
+* under `prefix`; past that, `capMessage` is thrown with 429.
+*/ const issueRow = async (payload, slug, args) => {
 	const now = Date.now();
-	const prefixes = [grantPrefix(grant.apiKeyId), usedPrefix(grant.apiKeyId)];
-	const rows = (await findRows(payload, slug, prefixes)).filter((row) => prefixes.some((prefix) => row.key.startsWith(prefix)));
+	const rows = await rowsWith(payload, slug, [args.prefix, args.usedPrefix]);
 	const expired = rows.filter((row) => expOf(row.data) <= now);
 	if (expired.length > 0) await payload.db.deleteMany({
 		collection: slug,
 		where: { key: { in: expired.map((row) => row.key) } },
 		req: NO_REQ
 	});
-	if (rows.filter((row) => row.key.startsWith(prefixes[0]) && expOf(row.data) > now).length >= GRANTS_PER_KEY) throw new APIError(`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.`, 429);
-	const grantId = crypto.randomBytes(32).toString("base64url");
-	const exp = now + GRANT_TTL_MS;
+	if (rows.filter((row) => row.key.startsWith(args.prefix) && expOf(row.data) > now).length >= args.cap) throw new APIError(args.capMessage, 429);
+	const id = crypto.randomBytes(32).toString("base64url");
+	const exp = now + args.ttlMs;
 	await payload.db.create({
 		collection: slug,
 		data: {
-			key: `${grantPrefix(grant.apiKeyId)}${hashApiKey(payload.secret, grantId)}`,
+			key: `${args.prefix}${hashApiKey(payload.secret, id)}`,
 			data: {
-				...grant,
+				...args.data,
 				exp
 			}
 		},
 		req: NO_REQ
 	});
 	return {
-		grantId,
+		id,
+		exp
+	};
+};
+/**
+* Stores a grant and returns its id. A key may hold at most
+* {@link GRANTS_PER_KEY} grants.
+*/ const issueGrant = async (payload, slug, grant) => {
+	const { id, exp } = await issueRow(payload, slug, {
+		prefix: grantPrefix(grant.apiKeyId),
+		usedPrefix: usedPrefix(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
+	});
+	return {
+		grantId: id,
 		exp
 	};
 };
@@ -93,4 +116,4 @@ const findRows = async (payload, slug, fragments) => {
 	return grant;
 };
 //#endregion
-export { claimGrant, issueGrant, uploadKvSlug };
+export { GRANT_ID, NO_REQ, claimGrant, expOf, grantKvSlug, issueGrant, issueRow, rowsWith };

package/dist/options.mjs

@@ -21,6 +21,12 @@ const assertExposable = (collection, apiKeysSlug) => {
 	if (collection.auth) fail(`Auth collection "${slug}" cannot be exposed. Its documents carry credentials.`);
 };
 const OPTION_NAMES = [
+	"read",
+	"write",
+	"publish",
+	"delete"
+];
+const GLOBAL_OPTION_NAMES = [
 	"read",
 	"write",
 	"publish"
@@ -37,26 +43,42 @@ const readFlag = (kind, slug, name, value) => {
 const assertWritable = (kind, config, write) => {
 	if (write === "live" && hasLocalizeStatusEnabled(config)) fail(`${kind} "${config.slug}" has versions.drafts.localizeStatus enabled, which live writes do not support yet. Set publish: false or write: false.`);
 };
+const normalizeDelete = (kind, config, value) => {
+	if (value !== "unattended") return {
+		delete: readFlag(kind, config.slug, "delete", value) ?? false,
+		deleteUnattended: false
+	};
+	if (!("trash" in config) || !config.trash) fail(`${kind} "${config.slug}" has delete: "unattended" but no trash, so a delete without approval would be permanent. Enable trash or set delete: true.`);
+	return {
+		delete: true,
+		deleteUnattended: true
+	};
+};
 const normalizeCapabilities = (kind, config, raw) => {
 	const { slug } = config;
+	const names = kind === "Global" ? GLOBAL_OPTION_NAMES : OPTION_NAMES;
 	if (raw === false) fail(`${kind} "${slug}" is set to false. Remove the entry to hide the ${kind.toLowerCase()}.`);
-	if (raw !== true && !isPlainObject(raw)) fail(`${kind} "${slug}" has ${JSON.stringify(raw)}. Use true or an object of ${OPTION_NAMES.join(", ")}.`);
+	if (raw !== true && !isPlainObject(raw)) fail(`${kind} "${slug}" has ${JSON.stringify(raw)}. Use true or an object of ${names.join(", ")}.`);
 	const settings = isPlainObject(raw) ? raw : {};
-	const unknownKey = Object.keys(settings).find((key) => !OPTION_NAMES.includes(key));
-	if (unknownKey !== void 0) fail(`${kind} "${slug}" has the unknown option "${unknownKey}". The options are ${OPTION_NAMES.join(", ")}.`);
+	const unknownKey = Object.keys(settings).find((key) => !names.includes(key));
+	if (unknownKey !== void 0) fail(`${kind} "${slug}" has the unknown option "${unknownKey}". The options are ${names.join(", ")}.`);
 	const flag = (name) => readFlag(kind, slug, name, settings[name]);
 	const read = flag("read") ?? true;
-	const write = flag("write") ?? true;
+	const write = flag("write") ?? read;
 	const publish = flag("publish");
 	const hasDrafts = hasDraftsEnabled(config);
 	if (publish === false && write && !hasDrafts) fail(`${kind} "${slug}" has no drafts, so every write goes live. Set write: false or remove publish: false.`);
 	if (publish === true && !hasDrafts) fail(`${kind} "${slug}" has no drafts, so there is nothing to publish. Enable versions.drafts or remove publish: true.`);
+	if (!read && (flag("write") === true || publish === true)) fail(`${kind} "${slug}" has read: false but write or publish on. Writing and publishing need read.`);
 	if (publish === true && !write) fail(`${kind} "${slug}" has publish: true but write: false. Publishing follows write.`);
+	const deleting = normalizeDelete(kind, config, settings["delete"]);
+	if (!read && deleting.delete) fail(`${kind} "${slug}" has read: false but delete on. Deleting needs read.`);
 	return {
 		read,
 		write: write ? publish === false ? "draft" : "live" : false,
 		hasDrafts,
-		hasVersions: read && Boolean(config.versions)
+		hasVersions: read && Boolean(config.versions),
+		...deleting
 	};
 };
 const assertGlobalExposable = (global) => {
@@ -138,8 +160,11 @@ const normalizeLimits = (limits) => {
 	assertUserCollection(config, userCollection);
 	const tools = options.tools ?? [];
 	assertTools(tools);
+	const collections = normalizeCollections(config, options, apiKeysSlug);
+	const confirmations = collections.some((entity) => entity.delete);
+	if (confirmations && options.auth?.resolve) fail("delete needs approval on the API key document, which a custom auth.resolve does not support. Remove delete: true or auth.resolve.");
 	return {
-		collections: normalizeCollections(config, options, apiKeysSlug),
+		collections,
 		globals: normalizeGlobals(config, options),
 		userCollection,
 		apiKeysSlug,
@@ -147,6 +172,7 @@ const normalizeLimits = (limits) => {
 		setupGuide: options.apiKeys?.setupGuide ?? true,
 		limits: normalizeLimits(options.limits),
 		tools,
+		confirmations,
 		auth: options.auth,
 		serverInfo: {
 			name: options.serverInfo?.name ?? "payloadcms-mcpx",