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

package/dist/endpoint/confirmations.mjs

@@ -1,9 +1,9 @@
 import { isPlainObject } from "../guards.mjs";
-import { grantContext, grantKvSlug, rowHandle } from "../grants/grant.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 "../grants/confirmation.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";
@@ -25,7 +25,7 @@ const keyViewUrl = (req, options, apiKeyId) => {
 	confirmed: false,
 	request: async (args) => {
 		const { req } = scope;
-		const { slug, apiKeyId } = grantContext(req);
+		const { slug, apiKeyId } = leaseContext(req);
 		const view = keyViewUrl(req, options, apiKeyId);
 		const { id, exp } = await issueConfirmation(req.payload, slug, {
 			apiKeyId,
@@ -42,7 +42,7 @@ const keyViewUrl = (req, options, apiKeyId) => {
 	}
 });
 const authorize = async (req, options, keyId) => {
-	const slug = grantKvSlug(req.payload.config);
+	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({
@@ -88,7 +88,7 @@ const viewOf = async (req, entry, highlight) => {
 	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 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));

package/dist/endpoint/handler.mjs

@@ -1,5 +1,5 @@
 import { resolveCapabilities, scopeSlugs } from "../capabilities.mjs";
-import { grantsAvailable, readCapped } from "./http.mjs";
+import { leasesAvailable, readCapped } from "./http.mjs";
 import { isValidAuthResult, resolveApiKeyAuth } from "../auth/resolve.mjs";
 import { jsonRpcError } from "./errors.mjs";
 import { createMcpServer } from "./server.mjs";
@@ -22,7 +22,7 @@ const BATCH_MESSAGES_LIMIT = 10;
 			defaultLocale: localization.defaultLocale
 		} : null,
 		limits: options.limits,
-		uploads: grantsAvailable(req, options) !== void 0,
+		uploads: leasesAvailable(req, options) !== void 0,
 		diagnostics: options.diagnostics ? options.serverInfo : null,
 		exposure: {
 			collections: options.collections,

package/dist/endpoint/http.mjs

@@ -1,4 +1,4 @@
-import { grantKvSlug } from "../grants/grant.mjs";
+import { leaseKvSlug } from "../leases/lease.mjs";
 //#region src/endpoint/http.ts
 const respond = (status, body) => Response.json(body, { status });
 /**
@@ -19,9 +19,9 @@ const respond = (status, body) => Response.json(body, { status });
 	return Buffer.concat(chunks);
 };
 /**
-* The grant KV slug where uploads, downloads and confirmations are possible:
+* 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
-* 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;
+* 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 { grantsAvailable, readCapped, respond };
+export { leasesAvailable, readCapped, respond };

package/dist/endpoint/upload.mjs

@@ -1,8 +1,8 @@
 import { isToolEnabled, toolInputSchema } from "../define-tool.mjs";
-import { claimGrant } from "../grants/grant.mjs";
-import { grantsAvailable, readCapped, respond } from "./http.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";
@@ -23,7 +23,7 @@ const NO_SESSION = {
 	sendRequest: () => Promise.reject(/* @__PURE__ */ new Error("No MCP session."))
 };
 const claimAs = async (req, options, kind) => {
-	const slug = grantsAvailable(req, options);
+	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);

package/dist/{grants → leases}/confirmation.mjs

@@ -1,8 +1,7 @@
-import { NO_REQ, ROW_ID, claimRow, expOf, issueRow, rowHandle, rowPrefixes, rowsWith } from "./grant.mjs";
-//#region src/grants/confirmation.ts
+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}$/;
-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.
@@ -11,8 +10,8 @@ const asConfirmation = (row, now) => row && expOf(row.data) > now ? row.data : v
 		...call,
 		state: "pending"
 	};
-	return await issueRow(payload, slug, {
-		...rowPrefixes("confirmation", call.apiKeyId),
+	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,
@@ -23,22 +22,22 @@ const asConfirmation = (row, now) => row && expOf(row.data) > now ? row.data : v
 * 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());
+	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 claimRow(payload, slug, rowPrefixes("confirmation", apiKeyId), rowHandle(payload, id), exp);
+*/ 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 } = rowPrefixes("confirmation", apiKeyId);
+	const { prefix } = leasePrefixes("confirmation", apiKeyId);
 	const now = Date.now();
-	return (await rowsWith(payload, slug, [prefix])).flatMap((row) => {
-		const confirmation = asConfirmation(row, now);
+	return (await leasesWith(payload, slug, [prefix])).flatMap((row) => {
+		const confirmation = unexpired(row, now);
 		return confirmation ? [{
 			handle: row.key.slice(prefix.length),
 			confirmation
@@ -50,13 +49,13 @@ const asConfirmation = (row, now) => row && expOf(row.data) > now ? row.data : v
 * 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 { 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 rowsWith(payload, slug, [prefix])) {
-		const confirmation = asConfirmation(row, now);
+	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,

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 };

package/dist/{grants/grant.mjs → leases/lease.mjs}

@@ -1,33 +1,31 @@
 import { isPlainObject } from "../guards.mjs";
 import { generateApiKey, hashApiKey } from "../api-keys/key.mjs";
 import { APIError, ValidationError } from "payload";
-//#region src/grants/grant.ts
-const GRANT_TTL_MS = 3e5;
-const GRANTS_PER_KEY = 10;
-const ROW_ID = /^[\w-]{43}$/;
+//#region src/leases/lease.ts
+const LEASE_ID = /^[\w-]{43}$/;
 const NO_REQ = {};
 /**
-* The key prefixes of a kind of row: waiting rows and the markers of used
+* The key prefixes of a kind of lease: waiting leases and the markers of used
 * ones.
-*/ const rowPrefixes = (kind, apiKeyId) => ({
+*/ const leasePrefixes = (kind, apiKeyId) => ({
 	prefix: `mcpx-${kind}:${String(apiKeyId)}:`,
 	usedPrefix: `mcpx-${kind}-used:${String(apiKeyId)}:`
 });
 /**
-* What a row is addressed by: the HMAC of its id, which the row key ends in.
-*/ const rowHandle = (payload, id) => hashApiKey(payload.secret, id);
+* What a lease is addressed by: the HMAC of its id, which the row key ends in.
+*/ const leaseHandle = (payload, id) => hashApiKey(payload.secret, id);
 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 grantKvSlug = (config) => {
+*/ const leaseKvSlug = (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;
 };
 /**
 * KV rows whose key contains one of `fragments`.
-*/ const findRows = async (payload, slug, fragments) => {
+*/ const leasesMatching = async (payload, slug, fragments) => {
 	const { docs } = await payload.db.find({
 		collection: slug,
 		where: { or: fragments.map((fragment) => ({ key: { like: fragment } })) },
@@ -40,15 +38,15 @@ const expOf = (data) => isPlainObject(data) && typeof data["exp"] === "number" ?
 /**
 * 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)));
+*/ const leasesWith = async (payload, slug, prefixes) => (await leasesMatching(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 issueLease = async (payload, slug, args) => {
 	const now = Date.now();
-	const rows = await rowsWith(payload, slug, [args.prefix, args.usedPrefix]);
+	const rows = await leasesWith(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,
@@ -61,7 +59,7 @@ const expOf = (data) => isPlainObject(data) && typeof data["exp"] === "number" ?
 	await payload.db.create({
 		collection: slug,
 		data: {
-			key: `${args.prefix}${rowHandle(payload, id)}`,
+			key: `${args.prefix}${leaseHandle(payload, id)}`,
 			data: {
 				...args.data,
 				exp
@@ -77,7 +75,7 @@ const expOf = (data) => isPlainObject(data) && typeof data["exp"] === "number" ?
 /**
 * Marks the row under `handle` used and removes it. The marker is a
 * unique-key insert, so of two concurrent claims exactly one returns `true`.
-*/ const claimRow = async (payload, slug, prefixes, handle, exp) => {
+*/ const claimLease = async (payload, slug, prefixes, handle, exp) => {
 	try {
 		await payload.db.create({
 			collection: slug,
@@ -99,39 +97,19 @@ const expOf = (data) => isPlainObject(data) && typeof data["exp"] === "number" ?
 	return true;
 };
 /**
-* The KV slug and key id of the request, which a call that stores a grant or
-* a confirmation needs. Throws where the endpoint would not offer one.
-*/ const grantContext = (req) => {
-	const slug = grantKvSlug(req.payload.config);
+* The KV slug and key id of the request, which a call that stores a lease
+* needs. Throws where the endpoint would not offer one.
+*/ const leaseContext = (req) => {
+	const slug = leaseKvSlug(req.payload.config);
 	const apiKeyId = req.context.mcpx?.apiKeyId;
-	if (slug === void 0 || apiKeyId === void 0) throw new Error("A grant or confirmation needs a database KV and a key.");
+	if (slug === void 0 || apiKeyId === void 0) throw new Error("A lease needs a database KV and a key.");
 	return {
 		slug,
 		apiKeyId
 	};
 };
 /**
-* 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 issueRow(payload, slug, {
-	...rowPrefixes("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 (!ROW_ID.test(grantId)) return;
-	const handle = rowHandle(payload, grantId);
-	const row = (await findRows(payload, slug, [handle])).find((candidate) => candidate.key.startsWith("mcpx-grant:") && candidate.key.endsWith(`:${handle}`));
-	const grant = row?.data;
-	if (!row || !isPlainObject(grant) || expOf(grant) <= Date.now()) return;
-	const prefixes = rowPrefixes("grant", grant.apiKeyId);
-	return row.key === `${prefixes.prefix}${handle}` && await claimRow(payload, slug, prefixes, handle, grant.exp) ? grant : void 0;
-};
+* The data of `row` when it has not expired at `now`, otherwise `undefined`.
+*/ const unexpired = (row, now) => row && expOf(row.data) > now ? row.data : void 0;
 //#endregion
-export { NO_REQ, ROW_ID, claimGrant, claimRow, expOf, grantContext, grantKvSlug, issueGrant, issueRow, rowHandle, rowPrefixes, rowsWith };
+export { LEASE_ID, NO_REQ, claimLease, issueLease, leaseContext, leaseHandle, leaseKvSlug, leasePrefixes, leasesMatching, leasesWith, unexpired };

package/dist/tools/run-confirmed.mjs

@@ -1,6 +1,6 @@
 import { defineMcpxTool, isToolEnabled, toolInputSchema } from "../define-tool.mjs";
-import { grantContext } from "../grants/grant.mjs";
-import { claimConfirmation, readConfirmation } from "../grants/confirmation.mjs";
+import { leaseContext } from "../leases/lease.mjs";
+import { claimConfirmation, readConfirmation } from "../leases/confirmation.mjs";
 import { jsonResult, parseResult } from "../result.mjs";
 import { withRequestLocale } from "./document.mjs";
 import { z } from "zod";
@@ -86,7 +86,7 @@ const claimApproved = async (req, slug, apiKeyId, id) => {
 	inputSchema: { ids: z.array(z.string().max(64)).min(1).max(50).describe("\"id\" of each \"confirmation\".") },
 	handler: async ({ args, scope, extra }) => {
 		const { req } = scope;
-		const { slug, apiKeyId } = grantContext(req);
+		const { slug, apiKeyId } = leaseContext(req);
 		const outcomes = [];
 		for (const id of args.ids) {
 			const confirmation = await claimApproved(req, slug, apiKeyId, id);

package/dist/upload/file.mjs

@@ -1,6 +1,7 @@
-import { grantContext, issueGrant } from "../grants/grant.mjs";
+import { leaseContext } from "../leases/lease.mjs";
 import { publicOrigin } from "../request.mjs";
 import { errorResult, jsonResult } from "../result.mjs";
+import { issueGrant } from "../leases/grant.mjs";
 import { SchemaError } from "../schema/errors.mjs";
 import { resolveDataPointer } from "../schema/pointer.mjs";
 import "../schema/index.mjs";
@@ -126,7 +127,7 @@ const handoffUrl = (req, path) => {
 */ const uploadHandoff = async (scope, call) => {
 	const { req } = scope;
 	const { payload } = req;
-	const { slug, apiKeyId } = grantContext(req);
+	const { slug, apiKeyId } = leaseContext(req);
 	const url = handoffUrl(req, "upload");
 	const { id, exp } = await issueGrant(payload, slug, {
 		kind: "upload",
@@ -158,7 +159,7 @@ const handoffUrl = (req, path) => {
 * GET it.
 */ const downloadHandoff = async (scope, target) => {
 	const { req } = scope;
-	const { slug, apiKeyId } = grantContext(req);
+	const { slug, apiKeyId } = leaseContext(req);
 	const url = handoffUrl(req, "file");
 	const { id, exp } = await issueGrant(req.payload, slug, {
 		kind: "download",

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@abinnovision/payloadcms-mcpx",
-  "version": "2.0.0",
+  "version": "2.1.0-beta.1",
   "description": "Payload CMS plugin exposing a fixed, schema-aware MCP tool surface with draft-only writes and per-API-key capabilities.",
   "keywords": [
     "payload",