@classytic/arc 2.22.0 → 2.25.0

package/dist/{mcpPlugin-ByA2tf6D.mjs → mcpPlugin-Cb7olw0j.mjs}

@@ -1,15 +1,18 @@
 import { p as isArcError, t as ArcError } from "./errors-DkO8Nk6-.mjs";
-import { c as getOrgId, g as getUserId } from "./types-bHblZ9YN.mjs";
-import { t as BaseController } from "./BaseController-C6FlRWxF.mjs";
-import { P as normalizePermissionResult } from "./permissions-BJMuKMl7.mjs";
+import { n as requireSingleHeaderValue } from "./headers-BvlQSDMB.mjs";
+import { b as isElevated, c as getOrgId, g as getUserId, x as isMember } from "./types-CSyCxl2V.mjs";
+import { t as BaseController } from "./BaseController--M8EMzt0.mjs";
+import { i as applyFieldReadPermissions, r as normalizePermissionResult, s as resolveEffectiveRoles } from "./applyPermissionResult-Tw4iXtlf.mjs";
 import { t as executePipeline } from "./pipe-BOLmGIxa.mjs";
-import { i as resolvePipelineSteps, t as resolveActionPermission } from "./actionPermissions-ze70xXJi.mjs";
-import { n as validateAggregations } from "./validate-C2mGgSXg.mjs";
-import { n as executeAggregation } from "./buildHandler-D_2ULWxZ.mjs";
+import { r as resolvePipelineSteps, u as buildRequestScopeProjection } from "./pipeline-BN5G05rd.mjs";
+import { n as validateAggregations } from "./validate-Bk44F2yT.mjs";
+import { n as executeAggregation } from "./buildHandler-Dtwd8fdz.mjs";
 import { t as pluralize } from "./pluralize-BhrgwZb9.mjs";
-import { r as shouldRejectAdditionalProperties, t as normalizeSchemaIR } from "./schemaIR-B-6SPe7g.mjs";
-import { createHash, randomUUID } from "node:crypto";
+import { t as resolveActionPermission } from "./actionPermissions-CAphcmUG.mjs";
+import { t as createIdempotencyResult } from "./interface-n5hpKg1d.mjs";
+import { r as shouldRejectAdditionalProperties, t as normalizeSchemaIR } from "./schemaIR-Ca7ySNPx.mjs";
 import { isHttpError, toErrorContract } from "@classytic/repo-core/errors";
+import { createHash, randomUUID } from "node:crypto";
 import fp from "fastify-plugin";
 import { z } from "zod";
 //#region src/integrations/mcp/createMcpServer.ts
@@ -160,6 +163,13 @@ function registerPrompt(server, prompt) {
 //#endregion
 //#region src/integrations/mcp/buildRequestContext.ts
 /**
+* @classytic/arc — MCP → IRequestContext Bridge
+*
+* Builds an IRequestContext from MCP tool input + session identity.
+* Ensures MCP tool handlers go through the same BaseController pipeline
+* as REST requests (AccessControl, BodySanitizer, QueryResolver, HookSystem).
+*/
+/**
 * Build an IRequestContext from MCP tool input and session auth.
 *
 * | Operation | params     | query                | body                |
@@ -177,7 +187,7 @@ function registerPrompt(server, prompt) {
 * the session-derived scope is `public` (i.e. MCP called with `auth: false`).
 * An authenticated session scope is never overwritten.
 */
-function buildRequestContext(input, auth, operation, policyFilters, scopeOverride) {
+function buildRequestContext(input, auth, operation, policyFilters, scopeOverride, extras) {
 	const sessionScope = buildScope(auth);
 	const scope = scopeOverride && sessionScope.kind === "public" ? scopeOverride : sessionScope;
 	const base = {
@@ -188,10 +198,13 @@ function buildRequestContext(input, auth, operation, policyFilters, scopeOverrid
 		} : null,
 		headers: {},
 		context: {},
+		scope: buildRequestScopeProjection(scope),
 		metadata: {
 			_scope: scope,
-			_policyFilters: policyFilters ?? {}
-		}
+			_policyFilters: policyFilters ?? {},
+			...extras?.arc ? { arc: extras.arc } : {}
+		},
+		...extras?.server ? { server: extras.server } : {}
 	};
 	switch (operation) {
 		case "list": return {
@@ -375,6 +388,42 @@ async function evaluatePermission(check, session, resource, action, input) {
 	}));
 }
 /**
+* Apply field-level READ permissions to an MCP tool payload — the same
+* masking `sendControllerResponse` applies on the HTTP wire and the
+* realtime plugin applies per frame. Without this, a resource declaring
+* `fields: { salary: fields.visibleTo(['admin']) }` masked salary over
+* REST and SSE but leaked it verbatim through every MCP tool.
+*
+* Mirrors the HTTP adapter's semantics exactly:
+*  - Elevated scope (platform admin) bypasses masking — consistent with
+*    `requireOrgRole()` and `BodySanitizer` bypass logic.
+*  - Effective roles = session roles ∪ org roles (member scope only),
+*    via the shared `resolveEffectiveRoles`.
+*  - `scopeOverride` (a `PermissionResult.scope`) follows the same
+*    non-downgrade rule as `buildRequestContext`: honored only when the
+*    session-derived scope is `public`.
+*
+* Handles the three payload shapes MCP tools emit: a single record, an
+* array of records, and a paginated result object carrying an inner
+* `data: T[]`. Scalars and `null` pass through untouched.
+*/
+function applyMcpReadMasking(data, options) {
+	const { fields, session, scopeOverride } = options;
+	if (!fields || data === null || typeof data !== "object") return data;
+	const sessionScope = buildScope(session);
+	const scope = scopeOverride && sessionScope.kind === "public" ? scopeOverride : sessionScope;
+	if (isElevated(scope)) return data;
+	const roles = resolveEffectiveRoles(session?.roles ?? [], isMember(scope) ? scope.orgRoles : []);
+	const maskItem = (item) => item !== null && typeof item === "object" && !Array.isArray(item) ? applyFieldReadPermissions(item, fields, roles) : item;
+	if (Array.isArray(data)) return data.map(maskItem);
+	const inner = data.data;
+	if (Array.isArray(inner)) return {
+		...data,
+		data: inner.map(maskItem)
+	};
+	return maskItem(data);
+}
+/**
 * Convert a controller response envelope into an MCP `CallToolResult`.
 * Carries `meta` into the serialized payload so consumers see pagination
 * totals, stripped-field arrays, etc.
@@ -476,6 +525,78 @@ function createMcpController(resource) {
 //#endregion
 //#region src/integrations/mcp/invokeController.ts
 /**
+* @classytic/arc — Non-HTTP controller invocation for MCP / jobs / workflows.
+*
+* Internal callers (MCP tools, scheduled jobs, workflow steps) need to invoke
+* controller methods without going through Fastify's preHandler chain.
+* Before this module landed, every call site reinvented the same shim:
+* fabricate `params` / `body` / `headers`, project the session into a
+* `RequestScope`, run the permission check by hand, translate thrown errors
+* to the MCP `CallToolResult` shape. The drift across those copies is what
+* the mentora review flagged as the "buildCtx synthetic-context hack."
+*
+* Two public surfaces, layered so callers reach for the smallest piece that
+* does the job:
+*
+*   - {@link invokeController}    full pipeline: permission → context →
+*                                 dispatch → canonical envelope/error
+*                                 conversion. Returns `CallToolResult`.
+*   - {@link mcpHandlerAdapter}   thin try/catch wrapper that turns any
+*                                 async function into a `ToolDefinition`
+*                                 handler with canonical error shape. Use
+*                                 when you want to compose multiple
+*                                 controller calls or weave in custom logic
+*                                 between them.
+*
+* Both honor the same {@link buildRequestContext} primitive — re-exported
+* from this module so authors who want the synthetic context as data (e.g.
+* to pass into `executePipeline`) can grab it without depending on an
+* internal subpath.
+*/
+/**
+* Assemble the {@link McpContextExtras} for a controller invocation from
+* resource-scoped metadata + app-level wiring. Mirrors what
+* `buildArcDecorator` (metadata.arc) and `createRequestContext` (server
+* accessor) assemble on the HTTP path.
+*/
+function buildContextExtras(options) {
+	const { wiring, resourceName, permissions, fields, schemaOptions, idField } = options;
+	if (!wiring) return void 0;
+	return {
+		arc: {
+			resourceName,
+			schemaOptions,
+			permissions,
+			hooks: wiring.hooks,
+			events: wiring.events,
+			fields,
+			idField
+		},
+		server: {
+			events: wiring.events,
+			audit: wiring.audit,
+			log: wiring.log
+		}
+	};
+}
+/**
+* Stable fingerprint of a tool invocation — sorted-key JSON, hashed.
+* Scopes an idempotency key to (resource, action, input, caller) so a
+* reused key with DIFFERENT input is a fresh execution, matching the HTTP
+* plugin's method+url+bodyHash+user fingerprint semantics.
+*/
+function invocationFingerprint(resourceName, actionName, input, session) {
+	const sortKeys = (value) => {
+		if (Array.isArray(value)) return value.map(sortKeys);
+		if (value !== null && typeof value === "object") return Object.fromEntries(Object.keys(value).sort().map((k) => [k, sortKeys(value[k])]));
+		return value;
+	};
+	return `mcp:${resourceName}:${actionName}:${createHash("sha256").update(JSON.stringify(sortKeys(input))).digest("hex").substring(0, 16)}:u=${session?.userId ?? session?.clientId ?? "anon"}`;
+}
+/** TTLs matching the HTTP idempotency plugin's defaults. */
+const MCP_IDEMPOTENCY_TTL_MS = 1440 * 60 * 1e3;
+const MCP_IDEMPOTENCY_LOCK_MS = 1e4;
+/**
 * Invoke a controller method through the MCP synthetic-context path.
 *
 * Runs the same chain CRUD MCP tools run:
@@ -508,7 +629,7 @@ function createMcpController(resource) {
 * checks compose.
 */
 async function invokeController(controller, op, input, options) {
-	const { session, resourceName, actionName = op, permissions, methodName = op } = options;
+	const { session, resourceName, actionName = op, permissions, methodName = op, fields, wiring, idempotencyKey } = options;
 	const ctrl = controller;
 	try {
 		const method = ctrl[methodName];
@@ -524,7 +645,39 @@ async function invokeController(controller, op, input, options) {
 			reason: permResult.reason,
 			session
 		});
-		return toCallToolResult(await method(buildRequestContext(input, session, op, permResult?.filters, permResult?.scope)));
+		const dispatch = async () => {
+			const reqCtx = buildRequestContext(input, session, op, permResult?.filters, permResult?.scope, buildContextExtras(options));
+			const response = await method(reqCtx);
+			const data = applyMcpReadMasking(response.data, {
+				fields,
+				session,
+				scopeOverride: permResult?.scope
+			});
+			return toCallToolResult(data === response.data ? response : {
+				...response,
+				data
+			});
+		};
+		const store = wiring?.idempotencyStore;
+		if (idempotencyKey && store) {
+			const fullKey = `${idempotencyKey}:${invocationFingerprint(resourceName, actionName, input, session)}`;
+			const cached = await store.get(fullKey);
+			if (cached) return cached.body;
+			const lockId = randomUUID();
+			if (!await store.tryLock(fullKey, lockId, MCP_IDEMPOTENCY_LOCK_MS)) return toCallToolError({
+				code: "arc.idempotency_conflict",
+				message: "A call with this idempotency key is already in progress",
+				status: 409
+			});
+			try {
+				const result = await dispatch();
+				if (!result.isError) await store.set(fullKey, createIdempotencyResult(200, result, {}, MCP_IDEMPOTENCY_TTL_MS));
+				return result;
+			} finally {
+				await store.unlock(fullKey, lockId);
+			}
+		}
+		return await dispatch();
 	} catch (err) {
 		return toCallToolError(err instanceof Error ? err : new Error(String(err)));
 	}
@@ -605,13 +758,33 @@ const CRUD_ANNOTATIONS = {
 * build + envelope/error conversion all live in one place — this factory
 * only resolves the op-specific permission and threads it through.
 */
-function createCrudHandler(op, controller, resourceName, permissions) {
+/** Ops where an idempotency key is meaningful (mutations). */
+const MUTATING_CRUD_OPS = /* @__PURE__ */ new Set([
+	"create",
+	"update",
+	"delete"
+]);
+function createCrudHandler(op, controller, resourceName, permissions, fields, extras) {
 	const permission = permissions?.[op];
-	return (input, ctx) => invokeController(controller, op, input, {
-		session: ctx.session,
-		resourceName,
-		permissions: permission
-	});
+	return (input, ctx) => {
+		let idempotencyKey;
+		let payload = input;
+		if ("_idempotencyKey" in input) {
+			const { _idempotencyKey, ...rest } = input;
+			payload = rest;
+			if (MUTATING_CRUD_OPS.has(op) && typeof _idempotencyKey === "string" && _idempotencyKey) idempotencyKey = _idempotencyKey;
+		}
+		return invokeController(controller, op, payload, {
+			session: ctx.session,
+			resourceName,
+			permissions: permission,
+			fields,
+			wiring: extras?.wiring,
+			schemaOptions: extras?.schemaOptions,
+			idField: extras?.idField,
+			idempotencyKey
+		});
+	};
 }
 /**
 * Default description for a CRUD tool. Enriches list descriptions with the
@@ -1008,7 +1181,24 @@ function convertActionSchemaToZod(raw) {
 * in the 2.10.8 review: REST and MCP action tools share identical
 * context-building machinery.
 */
-function createActionToolHandler(actionName, handler, permissions, resourceName, _resourcePermissions, rawSchema, idLess = false) {
+function createActionToolHandler(actionName, handler, permissions, resourceName, _resourcePermissions, rawSchema, idLess = false, fields, extras) {
+	const wiring = extras?.wiring;
+	const contextExtras = wiring ? {
+		arc: {
+			resourceName,
+			schemaOptions: extras?.schemaOptions,
+			permissions,
+			hooks: wiring.hooks,
+			events: wiring.events,
+			fields,
+			idField: extras?.idField
+		},
+		server: {
+			events: wiring.events,
+			audit: wiring.audit,
+			log: wiring.log
+		}
+	} : void 0;
 	const ir = rawSchema ? normalizeSchemaIR(rawSchema) : void 0;
 	const allowedKeys = (ir ? shouldRejectAdditionalProperties(ir) : false) && ir ? /* @__PURE__ */ new Set([...idLess ? [] : ["id"], ...Object.keys(ir.properties)]) : void 0;
 	return async (input, ctx) => {
@@ -1036,11 +1226,15 @@ function createActionToolHandler(actionName, handler, permissions, resourceName,
 		const reqCtx = buildRequestContext({
 			...input,
 			action: actionName
-		}, session, "action", permResult?.filters, permResult?.scope);
+		}, session, "action", permResult?.filters, permResult?.scope, contextExtras);
 		const id = idLess ? "" : typeof input.id === "string" ? input.id : "";
 		const { id: _discardId, ...data } = input;
 		try {
-			return toCallToolSuccess(await handler(id, data, reqCtx));
+			return toCallToolSuccess(applyMcpReadMasking(await handler(id, data, reqCtx), {
+				fields,
+				session,
+				scopeOverride: permResult?.scope
+			}));
 		} catch (err) {
 			return toCallToolError(err instanceof Error ? err : new Error(String(err)));
 		}
@@ -1055,7 +1249,7 @@ function createActionToolHandler(actionName, handler, permissions, resourceName,
 * every aggregation opts out via `mcp: false`.
 */
 function buildAggregationTools(args) {
-	const { resourceName, displayName, aggregations, schemaOptions, repo, buildOptionsFromSession, prefix } = args;
+	const { resourceName, displayName, aggregations, schemaOptions, repo, buildOptionsFromSession, prefix, fields } = args;
 	if (!aggregations || Object.keys(aggregations).length === 0) return [];
 	const normalized = validateAggregations(resourceName, aggregations, schemaOptions);
 	const tools = [];
@@ -1079,7 +1273,8 @@ function buildAggregationTools(args) {
 				permissions: config.permissions,
 				resourceName,
 				repo,
-				buildOptionsFromSession
+				buildOptionsFromSession,
+				fields
 			})
 		});
 	}
@@ -1121,7 +1316,7 @@ function buildAggregationInputSchema(norm) {
 	return shape;
 }
 function createAggregationToolHandler(args) {
-	const { normalized, permissions, resourceName, repo, buildOptionsFromSession } = args;
+	const { normalized, permissions, resourceName, repo, buildOptionsFromSession, fields } = args;
 	return async (input, ctx) => {
 		const permResult = await evaluatePermission(permissions, ctx.session, resourceName, `aggregation:${normalized.name}`, input);
 		if (permResult && !permResult.granted) return permissionDeniedResult({
@@ -1140,7 +1335,21 @@ function createAggregationToolHandler(args) {
 			query: filterInput,
 			tenantOptions
 		});
-		if (result.status === 200) return toCallToolSuccess(result.body);
+		if (result.status === 200) {
+			const body = result.body;
+			if (fields && Array.isArray(body?.rows)) {
+				const rows = applyMcpReadMasking(body.rows, {
+					fields,
+					session: ctx.session,
+					scopeOverride: permResult?.scope
+				});
+				return toCallToolSuccess({
+					...body,
+					rows
+				});
+			}
+			return toCallToolSuccess(result.body);
+		}
 		return toCallToolError(result.body);
 	};
 }
@@ -1480,8 +1689,24 @@ function operationKindForRoute(method, hasId) {
 function createCustomRouteHandler(route, controller, hasId, options) {
 	const ctrl = controller;
 	const handlerName = typeof route.handler === "string" ? route.handler : route.operation ?? slugifyRoute(route.method, route.path);
-	const { resourceName, operationName, permissions, pipeline } = options;
+	const { resourceName, operationName, permissions, pipeline, fields, wiring } = options;
 	const pipelineSteps = resolvePipelineSteps(pipeline, operationName);
+	const contextExtras = wiring ? {
+		arc: {
+			resourceName,
+			schemaOptions: options.schemaOptions,
+			permissions,
+			hooks: wiring.hooks,
+			events: wiring.events,
+			fields,
+			idField: options.idField
+		},
+		server: {
+			events: wiring.events,
+			audit: wiring.audit,
+			log: wiring.log
+		}
+	} : void 0;
 	return async (input, _ctx) => {
 		const session = _ctx.session;
 		const permResult = await evaluatePermission(permissions, session, resourceName, operationName, input);
@@ -1492,7 +1717,18 @@ function createCustomRouteHandler(route, controller, hasId, options) {
 			session
 		});
 		try {
-			const reqCtx = buildRequestContext(input, session, operationKindForRoute(route.method, hasId), permResult?.filters, permResult?.scope);
+			const reqCtx = buildRequestContext(input, session, operationKindForRoute(route.method, hasId), permResult?.filters, permResult?.scope, contextExtras);
+			const emit = (envelope) => {
+				const data = applyMcpReadMasking(envelope.data, {
+					fields,
+					session,
+					scopeOverride: permResult?.scope
+				});
+				return toCallToolResult(data === envelope.data ? envelope : {
+					...envelope,
+					data
+				});
+			};
 			if (typeof route.handler === "function") {
 				const fn = route.handler;
 				if (pipelineSteps.length > 0) {
@@ -1501,13 +1737,13 @@ function createCustomRouteHandler(route, controller, hasId, options) {
 						resource: resourceName,
 						operation: operationName
 					};
-					return toCallToolResult(await executePipeline(pipelineSteps, pipeCtx, async (ctx) => {
+					return emit(await executePipeline(pipelineSteps, pipeCtx, async (ctx) => {
 						const raw = await fn(ctx);
 						return raw !== null && typeof raw === "object" && "data" in raw ? raw : { data: raw };
 					}, operationName));
 				}
 				const out = await fn(reqCtx);
-				return toCallToolResult(out !== null && typeof out === "object" && "data" in out ? out : { data: out });
+				return emit(out !== null && typeof out === "object" && "data" in out ? out : { data: out });
 			}
 			if (!ctrl) return {
 				content: [{
@@ -1524,7 +1760,7 @@ function createCustomRouteHandler(route, controller, hasId, options) {
 				}],
 				isError: true
 			};
-			return toCallToolResult(await method(reqCtx));
+			return emit(await method(reqCtx));
 		} catch (err) {
 			return toCallToolError(err instanceof Error ? err : new Error(String(err)));
 		}
@@ -1598,6 +1834,7 @@ function resourceToTools(resource, config = {}) {
 	const hasSoftDelete = resource._appliedPresets?.includes("softDelete") ?? false;
 	const tools = [];
 	const prefix = config.toolNamePrefix;
+	const wiring = config.wiring;
 	if (controller) {
 		let ops = ALL_CRUD_OPS.filter((op) => !resource.disabledRoutes?.includes(op));
 		if (config.operations) ops = ops.filter((op) => config.operations?.includes(op));
@@ -1608,6 +1845,15 @@ function resourceToTools(resource, config = {}) {
 				allowedOperators,
 				sortableFields
 			});
+			const inputSchema = buildInputSchema(op, fieldRules, {
+				hiddenFields,
+				readonlyFields,
+				extraHideFields: config.hideFields,
+				filterableFields,
+				allowedOperators,
+				adapterBodies
+			});
+			if (wiring?.idempotencyStore && op !== "list" && op !== "get") inputSchema._idempotencyKey = z.string().optional().describe("Optional idempotency key — retrying with the same key and input replays the first successful result instead of re-executing.");
 			tools.push({
 				name,
 				description: resolveCrudDescription(config.descriptions?.[op], {
@@ -1620,15 +1866,12 @@ function resourceToTools(resource, config = {}) {
 					sortableFields
 				}),
 				annotations: CRUD_ANNOTATIONS[op],
-				inputSchema: buildInputSchema(op, fieldRules, {
-					hiddenFields,
-					readonlyFields,
-					extraHideFields: config.hideFields,
-					filterableFields,
-					allowedOperators,
-					adapterBodies
+				inputSchema,
+				handler: createCrudHandler(op, controller, resource.name, resource.permissions, resource.fields, {
+					wiring,
+					schemaOptions: resource.schemaOptions,
+					idField: resource.idField
 				}),
-				handler: createCrudHandler(op, controller, resource.name, resource.permissions),
 				source: `crud:${resource.name}:${op}`
 			});
 		}
@@ -1680,7 +1923,11 @@ function resourceToTools(resource, config = {}) {
 				resourceName: resource.name,
 				operationName: opName,
 				permissions: route.permissions,
-				pipeline: resource.pipe
+				pipeline: resource.pipe,
+				fields: resource.fields,
+				wiring,
+				schemaOptions: resource.schemaOptions,
+				idField: resource.idField
 			})
 		});
 	}
@@ -1711,7 +1958,11 @@ function resourceToTools(resource, config = {}) {
 			annotations,
 			inputSchema: inputShape,
 			source: `action:${resource.name}:${actionName}`,
-			handler: createActionToolHandler(actionName, handler, actionPerms, resource.name, resource.permissions, rawSchema, idLess)
+			handler: createActionToolHandler(actionName, handler, actionPerms, resource.name, resource.permissions, rawSchema, idLess, resource.fields, {
+				wiring,
+				schemaOptions: resource.schemaOptions,
+				idField: resource.idField
+			})
 		});
 	}
 	if (resource.aggregations && Object.keys(resource.aggregations).length > 0) {
@@ -1738,7 +1989,8 @@ function resourceToTools(resource, config = {}) {
 			schemaOptions: resource.schemaOptions,
 			repo: repoForAgg,
 			buildOptionsFromSession,
-			prefix
+			prefix,
+			fields: resource.fields
 		}));
 	}
 	return tools;
@@ -1948,10 +2200,29 @@ const mcpPluginImpl = async (fastify, options) => {
 		include: options.include,
 		exclude: options.exclude
 	});
+	const fastifyAny = fastify;
+	const wiring = {
+		get hooks() {
+			return fastifyAny.arc?.hooks;
+		},
+		get events() {
+			return fastifyAny.events;
+		},
+		get audit() {
+			return fastifyAny.audit;
+		},
+		get log() {
+			return fastify.log;
+		},
+		get idempotencyStore() {
+			return fastifyAny.idempotency?.store;
+		}
+	};
 	const overrides = options.overrides ?? {};
 	const allTools = enabledResources.flatMap((r) => {
 		const resOverrides = overrides[r.name] ?? {};
 		return resourceToTools(r, {
+			wiring,
 			...resOverrides,
 			toolNamePrefix: resOverrides.toolNamePrefix ?? options.toolNamePrefix
 		});
@@ -2113,7 +2384,7 @@ function registerStatefulRoutes(fastify, prefix, options, cache, createServer, T
 				}
 			});
 		}
-		const sessionId = request.headers["mcp-session-id"];
+		const sessionId = requireSingleHeaderValue(request.headers, "mcp-session-id");
 		if (sessionId) {
 			const entry = cache.get(sessionId);
 			if (entry) {
@@ -2148,7 +2419,7 @@ function registerStatefulRoutes(fastify, prefix, options, cache, createServer, T
 		await transport.handleRequest(request.raw, reply.raw, request.body);
 	});
 	fastify.get(prefix, async (request, reply) => {
-		const sessionId = request.headers["mcp-session-id"];
+		const sessionId = requireSingleHeaderValue(request.headers, "mcp-session-id");
 		if (!sessionId) return reply.code(400).send({ error: "Missing Mcp-Session-Id header" });
 		const entry = cache.get(sessionId);
 		if (!entry) return reply.code(403).send({ error: "Unauthorized" });
@@ -2163,7 +2434,7 @@ function registerStatefulRoutes(fastify, prefix, options, cache, createServer, T
 		await entry.transport.handleRequest(request.raw, reply.raw);
 	});
 	fastify.delete(prefix, async (request, reply) => {
-		const sessionId = request.headers["mcp-session-id"];
+		const sessionId = requireSingleHeaderValue(request.headers, "mcp-session-id");
 		if (!sessionId) return reply.code(400).send({ error: "Missing Mcp-Session-Id header" });
 		const entry = cache.get(sessionId);
 		if (!entry) return reply.code(204).send();

package/dist/{memory-CLXA2VeJ.mjs → memory-CmnzXE5Z.mjs}

@@ -76,6 +76,35 @@ var MemoryCacheStore = class {
 		const entry = this.cache.get(key);
 		if (entry) this.removeEntry(key, entry);
 	}
+	/**
+	* Atomic increment (canonical `CacheAdapter` signature: key, by, ttl) —
+	* synchronous on purpose: no `await` between read and write means
+	* concurrent bumps on the event loop can't interleave, which is the whole
+	* point of the `CacheStore.increment` contract.
+	*
+	* TTL semantics follow the repo-core contract: `ttlSeconds` applies only
+	* when the key is CREATED — an existing counter keeps its original expiry
+	* (Redis `EXPIRE ... NX` semantics), so every conforming adapter ages a
+	* counter identically.
+	*/
+	increment(key, by = 1, ttlSeconds) {
+		const now = Date.now();
+		const entry = this.cache.get(key);
+		const live = entry && entry.expiresAt > now;
+		const next = (live && typeof entry.value === "number" ? entry.value : 0) + by;
+		const effectiveTtlSeconds = ttlSeconds ?? this.defaultTtlSeconds;
+		if (entry) this.currentBytes -= entry.size;
+		this.cache.delete(key);
+		const size = 8;
+		this.cache.set(key, {
+			value: next,
+			size,
+			expiresAt: live ? entry.expiresAt : now + Math.max(1, effectiveTtlSeconds) * 1e3
+		});
+		this.currentBytes += size;
+		this.evictToLimit();
+		return next;
+	}
 	async clear(pattern) {
 		if (pattern === void 0) {
 			this.cache.clear();

package/dist/middleware/index.d.mts

@@ -1,4 +1,4 @@
-import { I as MiddlewareHandler, L as RequestWithExtras, Q as MiddlewareConfig } from "../index-DbtgCOCj.mjs";
+import { I as MiddlewareHandler, L as RequestWithExtras, Q as MiddlewareConfig } from "../index-DPRH0Cme.mjs";
 import { RouteHandlerMethod } from "fastify";
 //#region src/middleware/middleware.d.ts
 interface NamedMiddleware {
@@ -90,6 +90,14 @@ interface MultipartBodyOptions {
    * @example ['avatar', 'cover']       // multi-field upload (profile editor)
    */
   requiredFields?: string[];
+  /**
+   * Cap on the TOTAL buffered file bytes per request (default: 25 MiB).
+   * Per-file and per-count limits bound individual files but not their
+   * SUM — without this, `maxFiles: 5` × `maxFileSize: 10 MiB` lets one
+   * request retain ~50 MiB of process memory, and concurrency multiplies
+   * it (20 such uploads ≈ 1 GiB). Exceeding the cap returns 413.
+   */
+  maxTotalBytes?: number;
 }
 /**
  * Create a multipart body parsing middleware.
@@ -102,6 +110,14 @@ interface MultipartBodyOptions {
  * For non-multipart requests (regular JSON), this is a no-op — the request
  * passes through unchanged. This makes it safe to add to create/update
  * middlewares without breaking JSON clients.
+ *
+ * **BUFFERED — for small uploads only.** Every accepted file is held fully
+ * in process memory for the request's lifetime; memory cost is
+ * `concurrency × maxTotalBytes`. Suitable for avatars, documents, and
+ * form attachments. For large files use PRESIGNED direct-to-object-storage
+ * uploads (see the files-upload preset / production guide) and pair upload
+ * routes with strict rate limits — buffering video through the app tier is
+ * the wrong architecture regardless of limits.
  */
 declare function multipartBody(options?: MultipartBodyOptions): RouteHandlerMethod;
 //#endregion

package/dist/middleware/index.mjs

@@ -1,5 +1,5 @@
 import { t as CRUD_OPERATIONS } from "../constants-DNre0wRg.mjs";
-import { t as multipartBody } from "../multipartBody-CHEQSZ6G.mjs";
+import { t as multipartBody } from "../multipartBody-D0eBvkeq.mjs";
 //#region src/middleware/middleware.ts
 /**
 * Named Middleware — Priority-based, conditional middleware execution.