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

package/dist/tools/get-document.mjs

@@ -6,6 +6,7 @@ import { SchemaError } from "../schema/errors.mjs";
 import { lexicalOutline } from "../schema/outline.mjs";
 import { resolveDataPointer } from "../schema/pointer.mjs";
 import "../schema/index.mjs";
+import { downloadHandoff, downloadSlugs } from "../upload/file.mjs";
 import { READ_LOCALE_DESCRIPTION, depthShape, entityShape, idSchema, idShape, localeOf, localeShape, slugsFor, widen } from "./shared.mjs";
 import { identityOf, resolveDocument } from "./document.mjs";
 import { diffDocuments, loadPublished, loadVersion, readLive } from "./versions.mjs";
@@ -46,6 +47,18 @@ const versionShape = (scope) => {
 		diffFrom: idSchema.optional().describe("Version id, or \"published\" for the newest version published in any locale. Returns {from, to, patch}, the JSON Patch from that version to what is read.")
 	});
 };
+const downloadShape = (scope) => {
+	const slugs = downloadSlugs(scope);
+	return widen(slugs.length === 0 ? {} : { download: z.literal(true).optional().describe(`Only for ${slugs.join(", ")}. Adds "download": GET its "url" with its "headers" once, within 5 minutes, for the file. Not with "path", "versionId" or "diffFrom".`) });
+};
+const assertDownloadArgs = (scope, target, args) => {
+	if (target.kind === "global" || !downloadSlugs(scope).includes(target.slug)) throw new APIError(`"${target.slug}" has no file to download.`, 400);
+	if (args.path !== void 0 || args.versionId !== void 0 || args.diffFrom !== void 0) throw new APIError("\"download\" cannot be combined with \"path\", \"versionId\" or \"diffFrom\".", 400);
+};
+const withDownload = async (scope, doc, target) => typeof doc["filename"] === "string" ? jsonResult({
+	...doc,
+	download: await downloadHandoff(scope, target)
+}) : errorResult("This document has no file to download.");
 /**
 * With `path` the handler returns the subtree plus the `id`, `_status` and
 * `updatedAt` a client needs to write back, so reading one branch still gives
@@ -69,11 +82,13 @@ const versionShape = (scope) => {
 		}),
 		draft: z.boolean().optional().describe("Default true. false reads the published version."),
 		outline: z.boolean().optional().describe("With \"path\" at a rich text field: list each node's pointer, type, \"version\" and text."),
-		...versionShape(scope)
+		...versionShape(scope),
+		...downloadShape(scope)
 	}),
 	handler: async ({ args, scope }) => {
 		const target = resolveDocument(scope, args, "read");
 		assertVersionArgs(scope, target, args);
+		if (args.download) assertDownloadArgs(scope, target, args);
 		const prototyped = args.path ? prototypeSegmentProblem(args.path) : void 0;
 		if (prototyped !== void 0) return errorResult(prototyped);
 		let pointer;
@@ -96,7 +111,12 @@ const versionShape = (scope) => {
 		}, doc);
 		if (pointer === void 0) {
 			if (args.outline) return errorResult(OUTLINE_ERROR);
-			return jsonResult(doc);
+			return args.download && args.id !== void 0 ? await withDownload(scope, doc, {
+				collection: target.slug,
+				id: args.id,
+				draft: args.draft ?? true,
+				locale: read.locale ?? null
+			}) : jsonResult(doc);
 		}
 		const path = pointer.toString();
 		const value = pointer.get(doc);

package/dist/tools/list-capabilities.mjs

@@ -1,10 +1,12 @@
 import { defineMcpxTool } from "../define-tool.mjs";
-import { canCreate } from "../capabilities.mjs";
 import { jsonResult } from "../result.mjs";
 import { translateStatic, translatorFor } from "../i18n.mjs";
+import { slugsFor } from "./shared.mjs";
+import { MCPX_ISSUES_URL, MCPX_REPOSITORY_URL } from "../version.mjs";
 import { hasDraftValidationEnabled } from "payload/shared";
 //#region src/tools/list-capabilities.ts
 const DESCRIPTION = `Lists what this key may do. Call it first. Returns each collection and global the key can read or write, with whether it can create, publish, has drafts and exposes versions to findVersions, and a collection's "idType". Also returns the locales, the "limits" on page size and depth, and the enabled custom tools.`;
+const DIAGNOSTICS = ` Its "server" block holds the server version with repository and issue links, for a bug report.`;
 const translateLabel = (scope, label, fallback) => {
 	const { i18n, t } = scope.req;
 	const resolved = typeof label === "function" ? label({
@@ -21,7 +23,7 @@ const translateLabel = (scope, label, fallback) => {
 * grows.
 */ const listCapabilities = defineMcpxTool({
 	name: "listCapabilities",
-	description: DESCRIPTION,
+	description: (scope) => scope.diagnostics ? `${DESCRIPTION}${DIAGNOSTICS}` : DESCRIPTION,
 	annotations: {
 		readOnlyHint: true,
 		openWorldHint: false
@@ -31,6 +33,7 @@ const translateLabel = (scope, label, fallback) => {
 	handler: ({ scope }) => {
 		const { payload } = scope.req;
 		const translate = translatorFor(scope.req.i18n);
+		const creatable = slugsFor(scope, "create").collections;
 		const collections = scope.exposure.collections.flatMap((entry) => {
 			const capability = scope.capabilities.collections[entry.slug];
 			const collection = payload.collections[entry.slug];
@@ -46,7 +49,7 @@ const translateLabel = (scope, label, fallback) => {
 				...description === void 0 ? {} : { description },
 				read: capability.read,
 				write: capability.write,
-				create: capability.write && canCreate(entry),
+				create: creatable.includes(entry.slug),
 				publish: capability.publish,
 				drafts: entry.hasDrafts,
 				versions: entry.hasVersions,
@@ -79,7 +82,13 @@ const translateLabel = (scope, label, fallback) => {
 				default: scope.localization.defaultLocale
 			} : null,
 			limits: scope.limits,
-			tools: Object.entries(scope.capabilities.tools).filter(([, enabled]) => enabled).map(([name]) => name)
+			tools: Object.entries(scope.capabilities.tools).filter(([, enabled]) => enabled).map(([name]) => name),
+			...scope.diagnostics ? { server: {
+				name: scope.diagnostics.name,
+				version: scope.diagnostics.version,
+				repository: MCPX_REPOSITORY_URL,
+				issues: MCPX_ISSUES_URL
+			} } : {}
 		});
 	}
 });

package/dist/tools/patch-document.mjs

@@ -3,13 +3,14 @@ import { isPlainObject } from "../guards.mjs";
 import { errorResult, jsonResult } from "../result.mjs";
 import { JSON_POINTER_PATTERN } from "../schema/path.mjs";
 import "../schema/index.mjs";
-import { entityShape, idShape, liveWriteSentence, localeOf, localeShape } from "./shared.mjs";
 import { collectPublishBlockers } from "../write/publish-blockers.mjs";
+import { assertAcceptsFile, fileShape, fileSlugs, fileWriteRefusal, uploadHandoff, uploadedFile } from "../upload/file.mjs";
+import { entityShape, idShape, liveWriteSentence, localeOf, localeShape } from "./shared.mjs";
 import { identityOf, readDraft, resolveDocument, staleReadResult } from "./document.mjs";
 import { applyPatchOperations, isElementPointer } from "../write/patch.mjs";
 import { withTransaction } from "../write/transaction.mjs";
 import { buildWriteData } from "../write/write-data.mjs";
-import { Forbidden, NotFound } from "payload";
+import { APIError, Forbidden, NotFound } from "payload";
 import { z } from "zod";
 import { Pointer } from "rfc6902";
 //#region src/tools/patch-document.ts
@@ -75,7 +76,8 @@ const notAppliedPointers = (patches, intended, saved) => patches.flatMap((operat
 * document before writing anything, runs the write in a transaction, then
 * re-reads the saved document to report which pointers survived and what still
 * blocks publishing. The draft guard, not this tool, decides where the write
-* lands.
+* lands. With `file`, the patches and the file land as one update, and the
+* transaction commits right after it because Payload has moved files by then.
 */ const patchDocument = defineMcpxTool({
 	name: "patchDocument",
 	description: DESCRIPTION,
@@ -93,27 +95,72 @@ const notAppliedPointers = (patches, intended, saved) => patches.flatMap((operat
 			required: true,
 			description: "Localized fields are written in this locale only."
 		}),
-		patches: z.array(PATCH_OPERATION_SCHEMA).min(1).max(PATCHES_LIMIT),
-		expectedUpdatedAt: z.string().optional().describe("\"updatedAt\" from your last read. Refused if the document changed since.")
+		patches: fileSlugs(scope).length === 0 ? z.array(PATCH_OPERATION_SCHEMA).min(1).max(PATCHES_LIMIT) : z.array(PATCH_OPERATION_SCHEMA).max(PATCHES_LIMIT).describe("May be empty when \"file\" is given."),
+		expectedUpdatedAt: z.string().optional().describe("\"updatedAt\" from your last read. Refused if the document changed since."),
+		...fileShape(scope, (slugs) => `Replaces the file of a document in ${slugs}. The call returns an "upload" for the bytes instead of writing.`)
 	}),
 	handler: async ({ args, scope }) => {
 		const target = resolveDocument(scope, args, "write");
 		const { payload } = scope.req;
 		const locale = localeOf(scope, args.locale);
 		const patches = args.patches;
-		return await withTransaction(scope.req, async () => {
+		const { file } = args;
+		const bytes = uploadedFile(scope.req);
+		if (file !== void 0) assertAcceptsFile(scope, target, file);
+		if (patches.length === 0 && file === void 0) throw new APIError("\"patches\" may be empty only when \"file\" is given.", 400);
+		const report = async (next) => {
+			const saved = await readDraft(scope, {
+				target,
+				locale,
+				privileged: true
+			});
+			const readable = await readDraft(scope, {
+				target,
+				locale
+			}).catch((error) => {
+				if (error instanceof NotFound || error instanceof Forbidden) return;
+				throw error;
+			});
+			const notApplied = readable ? notAppliedPointers(patches, next, readable) : [];
+			const validation = await collectPublishBlockers(scope.req, {
+				doc: saved,
+				entity: target
+			});
+			return jsonResult({
+				...identityOf(target, saved["id"]),
+				status: saved["_status"],
+				updatedAt: saved["updatedAt"],
+				...validation.blockers.length > 0 ? { publishBlockers: validation.blockers } : {},
+				...validation.unavailable ? { publishBlockersUnavailable: true } : {},
+				...notApplied.length > 0 ? { notApplied } : {}
+			});
+		};
+		const outcome = await withTransaction(scope.req, async () => {
 			const doc = await readDraft(scope, {
 				target,
 				locale
 			});
 			const stale = staleReadResult(doc, args.expectedUpdatedAt, "The document changed since you read it. Read it again and re-apply the patch.");
-			if (stale) return stale;
+			if (stale) return { done: stale };
 			const applied = applyPatchOperations(payload.config, {
 				doc,
 				patches,
 				ref: target
 			});
-			if ("problems" in applied) return errorResult("No operation was applied.", { problems: applied.problems });
+			if ("problems" in applied) return { done: errorResult("No operation was applied.", { problems: applied.problems }) };
+			if (file !== void 0 && target.kind === "collection") {
+				const refusal = await fileWriteRefusal(scope, {
+					entity: target,
+					id: target.id,
+					data: applied.next
+				});
+				if (refusal) return { done: refusal };
+				if (!bytes) return { handoff: {
+					...args,
+					file,
+					expectedUpdatedAt: doc["updatedAt"]
+				} };
+			}
 			const write = {
 				data: buildWriteData(payload.config, target.config, applied.next),
 				depth: 0,
@@ -125,39 +172,22 @@ const notAppliedPointers = (patches, intended, saved) => patches.flatMap((operat
 			if (target.kind === "collection") await payload.update({
 				...write,
 				collection: target.slug,
-				id: target.id
+				id: target.id,
+				...bytes === void 0 ? {} : { file: bytes }
 			});
 			else await payload.updateGlobal({
 				...write,
 				fallbackLocale: false,
 				slug: target.slug
 			});
-			const saved = await readDraft(scope, {
-				target,
-				locale,
-				privileged: true
-			});
-			const readable = await readDraft(scope, {
-				target,
-				locale
-			}).catch((error) => {
-				if (error instanceof NotFound || error instanceof Forbidden) return;
-				throw error;
-			});
-			const notApplied = readable ? notAppliedPointers(patches, applied.next, readable) : [];
-			const validation = await collectPublishBlockers(scope.req, {
-				doc: saved,
-				entity: target
-			});
-			return jsonResult({
-				...identityOf(target, saved["id"]),
-				status: saved["_status"],
-				updatedAt: saved["updatedAt"],
-				...validation.blockers.length > 0 ? { publishBlockers: validation.blockers } : {},
-				...validation.unavailable ? { publishBlockersUnavailable: true } : {},
-				...notApplied.length > 0 ? { notApplied } : {}
-			});
+			return bytes === void 0 ? { done: await report(applied.next) } : { written: applied.next };
+		});
+		if ("done" in outcome) return outcome.done;
+		if ("handoff" in outcome) return await uploadHandoff(scope, {
+			tool: "patchDocument",
+			args: outcome.handoff
 		});
+		return await report(outcome.written);
 	}
 });
 //#endregion

package/dist/tools/shared.mjs

@@ -1,4 +1,5 @@
 import { canCreate, isLiveWrite } from "../capabilities.mjs";
+import { acceptsFiles } from "../upload/file.mjs";
 import { z } from "zod";
 //#region src/tools/shared.ts
 /**
@@ -17,19 +18,19 @@ const slugsWhere = (scope, predicate, allowed) => {
 	return [...pick(scope.exposure.collections, allowed.collections), ...pick(scope.exposure.globals, allowed.globals)];
 };
 /**
-* Slugs this key may write but never create in, because their documents are
-* files. Collection-only, since nothing creates a global either way.
-*/ const patchOnlySlugs = (scope) => slugsWhere(scope, (entity) => !canCreate(entity), {
-	collections: scope.collections.writable,
-	globals: []
-});
+* Collections this key may write but not create in: upload collections whose
+* files MCP does not accept. Nothing creates a global either way.
+*/ const patchOnlySlugs = (scope) => {
+	const creatable = slugsFor(scope, "create").collections;
+	return scope.collections.writable.filter((slug) => !creatable.includes(slug));
+};
 const widen = (branch) => branch;
 /**
 * The one list the shape helpers and {@link resolveEntity} both read.
 */ const slugsFor = (scope, operation) => {
 	switch (operation) {
 		case "create": return {
-			collections: slugsWhere(scope, canCreate, {
+			collections: slugsWhere(scope, (entity) => canCreate(entity) && (!entity.isUpload || acceptsFiles(scope, entity.slug)), {
 				collections: scope.collections.writable,
 				globals: []
 			}),

package/dist/tools/validate-document.mjs

@@ -1,7 +1,7 @@
 import { defineMcpxTool } from "../define-tool.mjs";
 import { jsonResult } from "../result.mjs";
-import { entityShape, idShape, localeOf, localeShape } from "./shared.mjs";
 import { collectPublishBlockers } from "../write/publish-blockers.mjs";
+import { entityShape, idShape, localeOf, localeShape } from "./shared.mjs";
 import { collectLocaleBlockers, identityOf, readDraft, resolveDocument } from "./document.mjs";
 /**
 * Gated on write rather than read, because publish blockers only mean something

package/dist/types.d.mts

@@ -34,9 +34,9 @@ export interface McpxCollectionOptions {
    */
   read?: boolean;
   /**
-   * Expose `patchDocument`, `validateDocument` and, unless this is an upload
-   * collection, `createDocument`. Without drafts a write changes live
-   * content. Default `true`.
+   * Expose `patchDocument`, `validateDocument` and `createDocument`. An upload
+   * collection is created in only where MCP accepts its files. Without drafts
+   * a write changes live content. Default `true`.
    */
   write?: boolean;
   /**
@@ -66,7 +66,7 @@ export interface McpxExposedEntity {
    */
   hasVersions: boolean;
   /**
-   * An upload document is a file, and no tool here can supply one.
+   * An upload document is a file, which only an upload grant can supply.
    */
   isUpload: boolean;
   /**
@@ -101,6 +101,18 @@ export interface McpxToolScope {
     maxLimit: number;
     maxDepth: number;
   };
+  /**
+   * Whether files can be uploaded at all: the KV is database-backed and no
+   * custom `auth.resolve` is configured.
+   */
+  uploads: boolean;
+  /**
+   * `null` when `diagnostics` is off.
+   */
+  diagnostics: null | {
+    name: string;
+    version: string;
+  };
   exposure: {
     collections: McpxExposedEntity[];
     globals: McpxExposedEntity[];
@@ -224,6 +236,10 @@ export type McpxPluginOptions = {
     name?: string;
     version?: string;
   };
+  /**
+   * Expose the server version plus repository and issue links to clients. Default `true`.
+   */
+  diagnostics?: boolean;
 };
 /**
  * What a key may do with one entity. Globals reuse this shape.

package/dist/upload/file.mjs

@@ -0,0 +1,185 @@
+import { errorResult, jsonResult } from "../result.mjs";
+import { SchemaError } from "../schema/errors.mjs";
+import { resolveDataPointer } from "../schema/pointer.mjs";
+import "../schema/index.mjs";
+import { issueGrant, uploadKvSlug } from "./grant.mjs";
+import { collectPublishBlockers } from "../write/publish-blockers.mjs";
+import { APIError } from "payload";
+import { hasDraftValidationEnabled, hasDraftsEnabled, validateMimeType } from "payload/shared";
+import { z } from "zod";
+//#region src/upload/file.ts
+const MAX_BYTES = 26214400;
+const FILENAME = /^[^/\\\p{Cc}]+$/u;
+const MIME_TYPE = /^[\w.+-]+\/[\w.+-]+$/;
+const uploadedFiles = /* @__PURE__ */ new WeakMap();
+const fileSchema = (maxBytes) => z.strictObject({
+	filename: z.string().max(255).regex(FILENAME),
+	mimeType: z.string().max(255).regex(MIME_TYPE),
+	size: z.number().int().min(1).max(maxBytes)
+});
+/**
+* The largest file accepted: Payload's `upload.limits.fileSize` if set, and
+* never more than 25 MB, since the body is buffered.
+*/ const uploadMaxBytes = (config) => Math.min(config.upload.limits?.fileSize ?? MAX_BYTES, MAX_BYTES);
+const allowedMimeTypes = (scope, slug) => {
+	if (!scope.uploads || !scope.collections.writable.includes(slug)) return [];
+	const entity = scope.exposure.collections.find((candidate) => candidate.slug === slug);
+	const config = scope.req.payload.config.collections.find((candidate) => candidate.slug === slug);
+	return entity?.isUpload === true && Array.isArray(config?.upload.mimeTypes) ? config.upload.mimeTypes : [];
+};
+/**
+* Whether this key may send a file to `slug`: a writable upload collection
+* that sets `upload.mimeTypes`.
+*/ const acceptsFiles = (scope, slug) => allowedMimeTypes(scope, slug).length > 0;
+/**
+* The collections this key may send files to.
+*/ const fileSlugs = (scope) => scope.collections.writable.filter((slug) => acceptsFiles(scope, slug));
+/**
+* The `file` argument, present only when the key may send a file somewhere.
+*/ const fileShape = (scope, description) => {
+	const slugs = fileSlugs(scope);
+	return slugs.length === 0 ? {} : { file: fileSchema(uploadMaxBytes(scope.req.payload.config)).optional().describe(description(slugs.join(", "))) };
+};
+/**
+* Throws for a `file` sent to an entity that does not accept one, or declared
+* with a type outside its `upload.mimeTypes`. Payload stores the declared
+* type, so it is held to the same list as the content.
+*/ const assertAcceptsFile = (scope, target, file) => {
+	const mimeTypes = target.kind === "global" ? [] : allowedMimeTypes(scope, target.slug);
+	if (mimeTypes.length === 0) throw new APIError(`"${target.slug}" does not accept files through MCP: it is not an upload collection, or it sets no upload.mimeTypes.`, 400);
+	if (!validateMimeType(file.mimeType, mimeTypes)) throw new APIError(`"${target.slug}" accepts only ${mimeTypes.join(", ")}, not "${file.mimeType}".`, 400);
+};
+/**
+* Attaches the claimed bytes to the request the tool runs on.
+*/ const setUploadedFile = (req, file) => {
+	uploadedFiles.set(req, file);
+};
+/**
+* The bytes for this call, or `undefined` before they were sent.
+*/ const uploadedFile = (req) => uploadedFiles.get(req);
+const sharesPublishedFile = async (req, entity, id) => {
+	if (!hasDraftsEnabled(entity.config)) return false;
+	const read = {
+		collection: entity.slug,
+		id,
+		depth: 0,
+		overrideAccess: true,
+		disableErrors: true,
+		select: {
+			filename: true,
+			_status: true
+		},
+		req
+	};
+	const [latest, published] = await Promise.all([req.payload.findByID({
+		...read,
+		draft: true
+	}), req.payload.findByID({
+		...read,
+		draft: false
+	})]);
+	return latest?.["_status"] === "draft" && published?.["_status"] === "published" && latest["filename"] === published["filename"];
+};
+const isClientWritable = (scope, target, path) => {
+	try {
+		const resolution = resolveDataPointer(scope.req.payload.config, {
+			ref: target.entity,
+			doc: target.data,
+			pointer: path
+		});
+		return resolution.readOnly !== true && resolution.descriptor?.readOnly !== true;
+	} catch (error) {
+		if (error instanceof SchemaError) return false;
+		throw error;
+	}
+};
+/**
+* Refuses a file write Payload would turn into data loss: a replace that
+* deletes the published file, or a write that fails validation after the old
+* file is gone. Payload validates only after it moves files, so the merged
+* data is validated here first wherever Payload will validate it, keeping only
+* failures the client can fix. Once the bytes are attached, Payload validates
+* with every hook and the file.
+*/ const fileWriteRefusal = async (scope, target) => {
+	const { entity, id } = target;
+	if (id !== void 0 && await sharesPublishedFile(scope.req, entity, id)) return errorResult("The file was not replaced: the latest draft still uses the published file, which the replace would delete. Publish or discard the draft first.");
+	if (uploadedFile(scope.req) !== void 0 || hasDraftsEnabled(entity.config) && !hasDraftValidationEnabled(entity.config)) return;
+	const { blockers: found } = await collectPublishBlockers(scope.req, {
+		doc: {
+			...target.data,
+			...id === void 0 ? {} : { id }
+		},
+		entity
+	});
+	const blockers = found.filter((blocker) => isClientWritable(scope, target, blocker.path));
+	return blockers.length === 0 ? void 0 : errorResult("Nothing was written: the document fails validation.", { validationErrors: blockers });
+};
+const handoffUrl = (req, path) => {
+	const request = new URL(req.url ?? "");
+	const url = new URL(req.payload.config.serverURL || request.origin);
+	url.pathname = `${request.pathname.replace(/\/+$/, "")}/${path}`;
+	return url.toString();
+};
+const grantContext = (req) => {
+	const slug = uploadKvSlug(req.payload.config);
+	const apiKeyId = req.context.mcpx?.apiKeyId;
+	if (slug === void 0 || apiKeyId === void 0) throw new Error("A handoff was offered without a database KV or key.");
+	return {
+		slug,
+		apiKeyId
+	};
+};
+/**
+* Stores the call as a grant and returns where to PUT its file. Nothing else
+* is written: the PUT runs the same call again with the bytes attached.
+*/ const uploadHandoff = async (scope, call) => {
+	const { req } = scope;
+	const { payload } = req;
+	const { slug, apiKeyId } = grantContext(req);
+	const url = handoffUrl(req, "upload");
+	const { grantId, exp } = await issueGrant(payload, slug, {
+		kind: "upload",
+		apiKeyId,
+		tool: call.tool,
+		args: call.args,
+		locale: req.locale ?? null,
+		fallbackLocale: req.fallbackLocale ?? null
+	});
+	return jsonResult({ upload: {
+		url,
+		method: "PUT",
+		headers: {
+			"content-type": call.args.file.mimeType,
+			"x-mcpx-grant": grantId
+		},
+		expiresAt: new Date(exp).toISOString(),
+		maxBytes: uploadMaxBytes(payload.config)
+	} });
+};
+/**
+* The upload collections whose files this key may download. A collection
+* with its own top-level `download` field is left out, since the handoff
+* would overwrite it in the result.
+*/ const downloadSlugs = (scope) => scope.uploads ? scope.collections.readable.filter((slug) => scope.exposure.collections.find((candidate) => candidate.slug === slug)?.isUpload === true && !scope.req.payload.collections[slug]?.config.flattenedFields.some((field) => field.name === "download")) : [];
+/**
+* Stores a grant for the file of a document just read and returns where to
+* GET it.
+*/ const downloadHandoff = async (scope, target) => {
+	const { req } = scope;
+	const { slug, apiKeyId } = grantContext(req);
+	const url = handoffUrl(req, "file");
+	const { grantId, exp } = await issueGrant(req.payload, slug, {
+		kind: "download",
+		apiKeyId,
+		...target,
+		fallbackLocale: req.fallbackLocale ?? null
+	});
+	return {
+		url,
+		method: "GET",
+		headers: { "x-mcpx-grant": grantId },
+		expiresAt: new Date(exp).toISOString()
+	};
+};
+//#endregion
+export { acceptsFiles, assertAcceptsFile, downloadHandoff, downloadSlugs, fileShape, fileSlugs, fileWriteRefusal, setUploadedFile, uploadHandoff, uploadMaxBytes, uploadedFile };

package/dist/upload/grant.mjs

@@ -0,0 +1,96 @@
+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
+const GRANT_TTL_MS = 3e5;
+const GRANTS_PER_KEY = 10;
+const GRANT_ID = /^[\w-]{43}$/;
+const NO_REQ = {};
+const grantPrefix = (apiKeyId) => `mcpx-grant:${String(apiKeyId)}:`;
+const usedPrefix = (apiKeyId) => `mcpx-grant-used:${String(apiKeyId)}:`;
+const expOf = (data) => isPlainObject(data) && typeof data["exp"] === "number" ? data["exp"] : 0;
+/**
+* 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 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) => {
+	const { docs } = await payload.db.find({
+		collection: slug,
+		where: { or: fragments.map((fragment) => ({ key: { like: fragment } })) },
+		limit: 0,
+		pagination: false,
+		req: NO_REQ
+	});
+	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) => {
+	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 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;
+	await payload.db.create({
+		collection: slug,
+		data: {
+			key: `${grantPrefix(grant.apiKeyId)}${hashApiKey(payload.secret, grantId)}`,
+			data: {
+				...grant,
+				exp
+			}
+		},
+		req: NO_REQ
+	});
+	return {
+		grantId,
+		exp
+	};
+};
+/**
+* Loads the grant for `grantId` and marks it used, or returns `undefined` for
+* a malformed, unknown, expired or used one. The marker is a unique-key
+* insert, so of two concurrent claims exactly one succeeds. A malformed id
+* is refused before any database read.
+*/ const claimGrant = async (payload, slug, grantId) => {
+	if (!GRANT_ID.test(grantId)) return;
+	const hash = hashApiKey(payload.secret, grantId);
+	const row = (await findRows(payload, slug, [hash])).find((candidate) => candidate.key.startsWith("mcpx-grant:") && candidate.key.endsWith(`:${hash}`));
+	const grant = row?.data;
+	if (!row || !isPlainObject(grant) || row.key !== `${grantPrefix(grant.apiKeyId)}${hash}` || expOf(grant) <= Date.now()) return;
+	try {
+		await payload.db.create({
+			collection: slug,
+			data: {
+				key: `${usedPrefix(grant.apiKeyId)}${hash}`,
+				data: { exp: grant.exp }
+			},
+			req: NO_REQ
+		});
+	} catch (error) {
+		if (error instanceof ValidationError) return;
+		throw error;
+	}
+	await payload.db.deleteOne({
+		collection: slug,
+		where: { key: { equals: row.key } },
+		req: NO_REQ
+	});
+	return grant;
+};
+//#endregion
+export { claimGrant, issueGrant, uploadKvSlug };

package/dist/version.mjs

@@ -2,5 +2,7 @@
 /**
 * Package version injected at build time; sources under Vitest report "dev".
 */ const MCPX_VERSION = "1.0.0";
+const MCPX_REPOSITORY_URL = "https://github.com/abinnovision/payloadcms-commons/tree/main/packages/mcpx";
+const MCPX_ISSUES_URL = "https://github.com/abinnovision/payloadcms-commons/issues";
 //#endregion
-export { MCPX_VERSION };
+export { MCPX_ISSUES_URL, MCPX_REPOSITORY_URL, MCPX_VERSION };