@nodefony/ai 0.0.0-stage → 10.0.0-beta.4

package/dist/nodefony/mcp/gate.js

@@ -0,0 +1,628 @@
+import { mcpConfigSchema } from "../config/config.js";
+import { mcpCallerRoles } from "./caller.js";
+import { checkMcpAccess, isRelayedRequest } from "./guard.js";
+import { JsonRpcError, MCP_SUPPORTED_VERSIONS, jsonRpcFailure } from "./protocol.js";
+import { collectMcpTools, declareMcpTools, insufficientScopeMessage, mcpCallScopes, mcpDeclaredScopes, mcpText } from "./tools.js";
+import { handleMcpMessage } from "./server.js";
+import { MCP_STREAM_GRACE_MS, createMcpResponseStream } from "./stream.js";
+import { ACCESS_ACCOUNT_RESOLVER, ACCESS_TOKEN_VERIFIER, BearerError, BootConfigurationError, Nodefony, RequestContext, authorizeProtectedResource, buildBearerChallenge, isPlainObject, missingScopes, parseModuleConfig, protectedResourceMetadataUrl, readBearerHeader } from "nodefony";
+import { z } from "zod";
+// nodefony/mcp/gate.ts
+/**
+* Une porte MCP sur HTTP — la mécanique, sans la route.
+*
+* `@nodefony/ai` ne monte AUCUNE route : une porte se DÉCLARE, par qui en a
+* besoin — devkit pour l'outillage de développement, une application pour ses
+* propres outils, en développement ou en production selon son choix. On la
+* définit une fois ({@link defineMcpGate}), on la sert d'une ligne
+* (`gate.serve(this, body)`). Gardes d'origine et de localité, validation du
+* jeton, défi `401` avec `resource_metadata`, traduction HTTP ↔ JSON-RPC, flux
+* SSE, refus `405` des verbes retirés : une porte qui recoderait l'une de ces
+* règles finirait plus permissive que les autres sans que rien ne le dise.
+*/
+/**
+* Plafond d'un événement sur le flux de réponse MCP, octets UTF-8 — celui de la
+* réponse finale, qui porte le résultat entier de l'outil (16 Mio).
+*/
+const MCP_STREAM_MAX_EVENT_BYTES = 16777216;
+/** Un objet a-t-il la forme d'un outil MCP (nom, description, schéma, handler) ? */
+function isMcpToolLike(value) {
+	return typeof value === "object" && value !== null && "name" in value && typeof value.name === "string" && "description" in value && typeof value.description === "string" && "inputSchema" in value && typeof value.inputSchema === "object" && value.inputSchema !== null && "handler" in value && typeof value.handler === "function";
+}
+/**
+* Le schéma d'une porte — les réglages de transport et d'autorisation de
+* {@link mcpConfigSchema} (les MÊMES clés que `devkit.mcp.*`), plus ce que la
+* porte publie et comment. Strict : une clé inconnue arrête le démarrage en la
+* nommant, au lieu d'être ignorée.
+*/
+const mcpGateSchema = mcpConfigSchema.extend({
+	name: z.string().min(1).optional().describe("Nom annoncé à l'agent ; défaut : le nom du projet"),
+	version: z.string().min(1).optional().describe("Version annoncée à l'agent ; défaut : celle de Nodefony"),
+	instructions: z.string().min(1).optional().describe("Ce que l'agent lit pour savoir QUAND se servir de la porte"),
+	tools: z.union([z.literal("modules"), z.array(z.custom(isMcpToolLike, { message: "un outil MCP porte `name`, `description`, `inputSchema` et `handler`" }))]).describe("Les outils servis : une liste, ou `\"modules\"` pour ceux que déclarent les modules chargés (`getMcpTools()`)"),
+	unprotectedRoles: z.array(z.string().min(1)).default([]).describe("Rôles accordés à qui entre SANS jeton (porte sans `authorization`) ; défaut : aucun"),
+	protocol: z.strictObject({ versions: z.array(z.enum(MCP_SUPPORTED_VERSIONS)).min(1).optional().describe("Révisions du protocole acceptées ; défaut : toutes celles du paquet installé") }).default({}),
+	cache: z.strictObject({
+		ttlMs: z.number().int().min(0).default(0).describe("Durée de fraîcheur des listes, en millisecondes"),
+		scope: z.enum(["public", "private"]).default("private").describe("`private` dès que la liste dépend de l'appelant")
+	}).default({
+		ttlMs: 0,
+		scope: "private"
+	})
+}).superRefine((value, ctx) => {
+	if (value.unprotectedRoles.length > 0 && value.authorization.authorizationServers.length > 0) ctx.addIssue({
+		code: "custom",
+		path: ["unprotectedRoles"],
+		message: "`unprotectedRoles` ne s'applique qu'à une porte SANS serveur d'autorisation : une porte protégée tire les rôles des scopes du jeton."
+	});
+});
+/**
+* Un `tools/call` exige-t-il, par ses ARGUMENTS, des scopes que l'appelant n'a
+* pas ? Seul un outil SERVI est jugé : un nom retenu reste « inconnu », son
+* existence n'est pas révélée par un défi.
+*
+* @param body - message JSON-RPC reçu (objet)
+* @param tools - outils servis à cet appelant
+* @param caller - appelant établi
+* @returns les scopes de l'opération et le message, ou `null` si rien ne manque
+*   (ou si l'appel n'est pas jugeable ici — le moteur le refusera lui-même)
+*/
+function requiredElevation(body, tools, caller) {
+	if (!("method" in body) || body.method !== "tools/call") return null;
+	if (!("params" in body) || typeof body.params !== "object") return null;
+	const params = body.params;
+	if (params === null || !("name" in params)) return null;
+	const tool = tools.find((candidate) => candidate.name === params.name);
+	if (tool?.scopesFor === void 0) return null;
+	const args = "arguments" in params && isPlainObject(params.arguments) ? params.arguments : {};
+	const scopes = mcpCallScopes(tool, args);
+	if (scopes === null) return null;
+	const missing = missingScopes(caller.scopes, scopes);
+	return missing.length === 0 ? null : {
+		scopes,
+		missing,
+		message: insufficientScopeMessage(tool.name, missing)
+	};
+}
+const EMPTY_PROTECTED_RESOURCES = Object.freeze([]);
+/** La porte coupée par configuration n'existe pas : elle ne se défend pas. */
+const DISABLED = Object.freeze({
+	kind: "json",
+	status: 404,
+	body: Object.freeze({ error: "MCP désactivé" })
+});
+/** `GET` / `DELETE` : `405`, `Allow: POST`. */
+const METHOD_NOT_ALLOWED = Object.freeze({
+	kind: "empty",
+	status: 405,
+	headers: Object.freeze({ allow: "POST" })
+});
+function failure(status, code, message, headers) {
+	const response = {
+		kind: "json",
+		status,
+		body: jsonRpcFailure(null, code, message)
+	};
+	if (headers) response.headers = headers;
+	return response;
+}
+/** JSON-RPC 2.0 §5.1 : `-32700`, un texte qui ne se PARSE pas. */
+function parseFailure() {
+	return failure(400, JsonRpcError.PARSE_ERROR, "corps illisible : JSON invalide");
+}
+/** JSON-RPC 2.0 §5.1 : `-32600`, un JSON lisible qui n'est pas un message. */
+function notAMessage() {
+	return failure(400, JsonRpcError.INVALID_REQUEST, "corps attendu : un message JSON-RPC (objet)");
+}
+/** Clé d'annulation de l'unique appelant d'un transport de process. */
+const STDIO_CALLER_KEY = "stdio";
+/** Ce qu'une porte stdio répond à un appel annulé : rien. */
+const CANCELLED_SILENCE = Object.freeze({
+	kind: "empty",
+	status: 202
+});
+/**
+* Branche un témoin sur la table d'annulation : il est prévenu quand le client
+* annule l'appel inscrit. Sans témoin, la table est rendue telle quelle.
+*/
+function trackCancellation(cancellation, onCancelled) {
+	if (onCancelled === void 0) return cancellation;
+	return {
+		open(id) {
+			const handle = cancellation.open(id);
+			handle.signal.addEventListener("abort", onCancelled, { once: true });
+			return handle;
+		},
+		cancel: (id, reason) => cancellation.cancel(id, reason)
+	};
+}
+/**
+* L'en-tête porte-t-il un gabarit d'interpolation jamais substitué ?
+*
+* Un `.mcp.json` déclare son jeton par `${NF_MCP_TOKEN}` : le client développe
+* la variable, ou transmet la chaîne telle quelle si elle manque. Le second cas
+* ne se distingue d'un jeton invalide par AUCUN symptôme observable de
+* l'extérieur, et c'est pourtant le plus fréquent des deux.
+*/
+function isUnsubstitutedTemplate(header) {
+	const read = readBearerHeader(header);
+	return read.kind === "token" && read.token.startsWith("${") && read.token.endsWith("}");
+}
+/**
+* Le corps reçu est-il un texte qui ne se PARSE pas en JSON ?
+*
+* Le parseur HTTP ignore un JSON malformé et rend `{}` : seul le brut permet
+* de distinguer un `{}` envoyé d'un texte illisible. Relu uniquement sur ce
+* chemin froid (corps vide d'apparence).
+*/
+function unparsableBody(body, rawBody) {
+	if (rawBody === void 0 || body === null || typeof body !== "object" || Array.isArray(body) || Object.keys(body).length > 0) return false;
+	const text = rawBody()?.trim();
+	if (!text) return false;
+	try {
+		JSON.parse(text);
+		return false;
+	} catch {
+		return true;
+	}
+}
+/** Première valeur d'un en-tête HTTP, ou rien. */
+function firstHeader(value) {
+	return Array.isArray(value) ? value[0] : value;
+}
+/**
+* Définit une porte MCP — UNE fois, à côté de son controller.
+*
+* La définition est validée et figée ici : une clé inconnue, une révision du
+* protocole que le paquet installé ne sait pas servir, un outil mal formé, un
+* nom en double ou réservé (`nodefony_`) lèvent une `BootConfigurationError`
+* qui nomme la faute — au démarrage, jamais à la première requête. Chaque
+* requête ne paie ensuite aucune validation.
+*
+* ```ts
+* const shopGate = defineMcpGate({
+*   name: "shop",
+*   instructions: "Stock et commandes du magasin.",
+*   tools: [stockTool, orderTool],
+* });
+*
+* @route("shop-mcp", { path: "/mcp", requirements: { methods: ["POST", "GET", "DELETE"] } })
+* mcp(@Body() body: unknown) {
+*   return shopGate.serve(this, body);
+* }
+* ```
+*
+* Défauts : appels locaux seulement (`allowRemote: false`), aucune origine
+* navigateur, aucun jeton exigé, AUCUN rôle accordé — les outils réservés
+* (`scopes`, `requiresAuth`) restent retenus tant qu'une `authorization` ne
+* les ouvre pas.
+*
+* @param definition - ce que la porte publie, à qui, et comment.
+* @returns la porte, prête à servir.
+* @throws BootConfigurationError si la définition est invalide.
+*/
+function defineMcpGate(definition) {
+	const label = typeof definition.name === "string" && definition.name.length > 0 ? `porte MCP « ${definition.name} »` : "porte MCP";
+	const settings = Object.freeze(parseModuleConfig(mcpGateSchema, definition, label));
+	let fixedModules = null;
+	if (settings.tools !== "modules") {
+		const tools = settings.tools;
+		fixedModules = Object.freeze({ gate: Object.freeze({
+			getModuleName: () => void 0,
+			getMcpTools: () => tools
+		}) });
+		const faults = [];
+		declareMcpTools({
+			modules: fixedModules,
+			onSkip: (why) => faults.push(why)
+		});
+		if (faults.length > 0) throw new BootConfigurationError(`[${label}] outils refusés — ${faults.join(" ; ")}`);
+	}
+	const pinned = settings.protocol.versions;
+	const versions = pinned ? Object.freeze(MCP_SUPPORTED_VERSIONS.filter((v) => pinned.includes(v))) : MCP_SUPPORTED_VERSIONS;
+	const cache = Object.freeze({
+		ttlMs: settings.cache.ttlMs,
+		cacheScope: settings.cache.scope
+	});
+	const gateProtected = settings.authorization.authorizationServers.length > 0;
+	/** Les modules dont la porte sert les outils, pour CETTE requête. */
+	function servedModules(runtime) {
+		return fixedModules ?? runtime?.modules;
+	}
+	let inflight = null;
+	/**
+	* La table des appels en cours, vue d'UN appelant : il n'atteint que les
+	* appels qu'il a lui-même émis.
+	*/
+	function cancellationFor(callerKey, log) {
+		const keyOf = (id) => `${callerKey}\u0000${typeof id === "number" ? "n" : "s"}${id}`;
+		return {
+			open(id) {
+				const key = keyOf(id);
+				const controller = new AbortController();
+				inflight ??= /* @__PURE__ */ new Map();
+				const owned = !inflight.has(key);
+				if (owned) inflight.set(key, controller);
+				return {
+					signal: controller.signal,
+					close() {
+						if (owned && inflight?.get(key) === controller) inflight.delete(key);
+					}
+				};
+			},
+			cancel(id, reason) {
+				const controller = inflight?.get(keyOf(id));
+				if (controller === void 0) return;
+				log?.(`MCP — appel ${JSON.stringify(id)} annulé par le client${reason ? ` : ${reason}` : ""}`, "DEBUG");
+				controller.abort();
+			}
+		};
+	}
+	let defaultServerInfo = null;
+	/** Identité annoncée — résolue au premier usage, le kernel existant alors. */
+	function serverInfo() {
+		defaultServerInfo ??= Object.freeze({
+			name: settings.name ?? Nodefony.getKernel()?.projectName ?? "nodefony",
+			version: settings.version ?? Nodefony.version
+		});
+		return defaultServerInfo;
+	}
+	async function respond(request, runtime) {
+		const log = runtime?.log;
+		if (!settings.enabled) return DISABLED;
+		const verdict = checkMcpAccess({
+			origin: request.origin,
+			remoteAddress: request.remoteAddress,
+			relayed: request.relayed
+		}, {
+			allowedOrigins: settings.allowedOrigins,
+			allowRemote: settings.allowRemote
+		});
+		if (!verdict.allowed) {
+			log?.(`MCP refusé — ${verdict.why}`, "WARNING");
+			return failure(403, JsonRpcError.INVALID_REQUEST, "origine refusée");
+		}
+		const { body } = request;
+		if (unparsableBody(body, request.rawBody)) return parseFailure();
+		if (body === null || typeof body !== "object") return notAMessage();
+		const modules = servedModules(runtime);
+		const authz = settings.authorization;
+		let caller = {
+			authenticated: false,
+			scopes: [],
+			roles: mcpCallerRoles({
+				protected: gateProtected,
+				authenticated: false,
+				scopes: []
+			}, settings.unprotectedRoles)
+		};
+		let callerKey = `addr\u0000${request.remoteAddress ?? ""}`;
+		let principal = null;
+		if (gateProtected) {
+			const authVerdict = await authorizeProtectedResource(request.authorization, {
+				resource: authz.resource,
+				acceptedResources: authz.additionalResources,
+				metadataUrl: protectedResourceMetadataUrl(authz.resource),
+				scopes: mcpDeclaredScopes({ modules }),
+				allowAnonymous: authz.anonymous
+			}, runtime?.verifier);
+			switch (authVerdict.outcome) {
+				case "unverifiable":
+					log?.(authVerdict.why ? `MCP — la vérification du jeton a ÉCHOUÉ, le jeton n'est donc ni accepté ni refusé : la porte refuse de servir (503). Cause — ${authVerdict.why}` : "MCP — la porte déclare un serveur d'autorisation, mais aucun vérificateur de jeton n'est posé (`accessTokenVerifier`). La porte refuse de servir : accepter les porteurs sans les valider serait pire que rester anonyme.", "CRITIC");
+					return failure(503, JsonRpcError.INTERNAL_ERROR, "autorisation indisponible");
+				case "challenge":
+					if (isUnsubstitutedTemplate(request.authorization)) log?.("MCP — l'en-tête `Authorization` porte un GABARIT non substitué : la variable d'environnement du jeton n'est pas posée dans le process du client. Émettre le jeton (`nodefony security:mcp:token`) et le poser, ou rendre la porte anonyme pour ce client (`nodefony ai:mcp --no-auth`) — sans en-tête, les outils publics sont servis.", "WARNING");
+					return failure(authVerdict.status, JsonRpcError.INVALID_REQUEST, "autorisation requise", { "WWW-Authenticate": authVerdict.wwwAuthenticate });
+				case "authenticated":
+					caller = {
+						authenticated: true,
+						scopes: authVerdict.principal.scopes,
+						subject: authVerdict.principal.subject,
+						roles: mcpCallerRoles({
+							protected: true,
+							authenticated: true,
+							scopes: authVerdict.principal.scopes
+						})
+					};
+					callerKey = `sub\u0000${authVerdict.principal.issuer}\u0000${authVerdict.principal.subject}`;
+					principal = authVerdict.principal;
+					break;
+				case "anonymous":
+					if (authVerdict.rejected) log?.("MCP — jeton REJETÉ (expiré, mauvaise audience ou signature invalide) : la requête est servie en ANONYME, les outils réservés restent retenus. Renouveler le jeton (`nodefony security:mcp:token`) pour les retrouver.", "WARNING");
+					caller = {
+						authenticated: false,
+						scopes: [],
+						roles: mcpCallerRoles({
+							protected: true,
+							authenticated: false,
+							scopes: []
+						})
+					};
+			}
+		}
+		return dispatch(body, {
+			caller,
+			callerKey,
+			principal,
+			challenge: gateProtected
+		}, request, modules, runtime);
+	}
+	/**
+	* Répond à UNE ligne reçue sur l'entrée standard.
+	*
+	* La frontière d'un transport de process est celle du process : qui a lancé
+	* la commande a déjà un terminal dans l'application. Aucune origine, aucune
+	* adresse, aucun jeton n'y voyage — les gardes de transport HTTP n'y ont rien
+	* à juger. L'appelant reste donc anonyme et ne reçoit que les rôles d'une
+	* porte NON protégée (aucun par défaut). Une porte protégée ne s'ouvre pas
+	* davantage : sans jeton, ses outils réservés restent retenus.
+	*/
+	async function respondStdio(request, runtime) {
+		if (!settings.enabled) return failure(404, JsonRpcError.INVALID_REQUEST, "MCP désactivé");
+		let body;
+		try {
+			body = JSON.parse(request.line);
+		} catch {
+			return parseFailure();
+		}
+		if (body === null || typeof body !== "object") return notAMessage();
+		const call = { cancelled: false };
+		const open = request.openStream;
+		const exchange = {
+			signal: request.signal,
+			openStream: open && (async () => {
+				const sink = await open();
+				return {
+					get closed() {
+						return call.cancelled || sink.closed;
+					},
+					send: (data) => sink.send(data)
+				};
+			})
+		};
+		const reply = await dispatch(body, {
+			caller: {
+				authenticated: false,
+				scopes: [],
+				roles: mcpCallerRoles({
+					protected: gateProtected,
+					authenticated: false,
+					scopes: []
+				}, settings.unprotectedRoles)
+			},
+			callerKey: STDIO_CALLER_KEY,
+			principal: null,
+			challenge: false,
+			onCancelled: () => {
+				call.cancelled = true;
+			}
+		}, exchange, servedModules(runtime), runtime);
+		return call.cancelled ? CANCELLED_SILENCE : reply;
+	}
+	/**
+	* Le tronc commun à tous les transports, une fois l'appelant établi :
+	* collecte, élévation, flux, moteur.
+	*/
+	async function dispatch(body, admitted, exchange, modules, runtime) {
+		const log = runtime?.log;
+		const { caller, principal } = admitted;
+		let withheldCount = 0;
+		const tools = collectMcpTools({
+			modules,
+			caller,
+			onSkip: (why) => log?.(`MCP — ${why}`, "WARNING"),
+			onWithheld: (name, why) => {
+				withheldCount += 1;
+				log?.(`MCP — outil « ${name} » retenu : ${why}`, "DEBUG");
+			}
+		});
+		if (admitted.challenge) {
+			const elevation = requiredElevation(body, tools, caller);
+			if (elevation !== null) {
+				const metadataUrl = protectedResourceMetadataUrl(settings.authorization.resource);
+				return failure(caller.authenticated ? 403 : 401, JsonRpcError.INVALID_REQUEST, elevation.message, { "WWW-Authenticate": buildBearerChallenge({
+					resourceMetadataUrl: metadataUrl,
+					scopes: elevation.scopes,
+					...caller.authenticated ? {
+						error: BearerError.INSUFFICIENT_SCOPE,
+						description: `missing scope: ${elevation.missing.join(" ")}`
+					} : {}
+				}) });
+			}
+		}
+		const stream = createMcpResponseStream({
+			signal: exchange.signal,
+			open: exchange.openStream,
+			graceMs: MCP_STREAM_GRACE_MS,
+			onError: (error, final) => log?.(`MCP — ${final ? "réponse finale" : "notification"} perdue sur le flux : ${error instanceof Error ? error.message : String(error)}`, final ? "WARNING" : "DEBUG")
+		});
+		const served = principal !== null && !("method" in body && body.method === "tools/list") ? actingTools(tools, {
+			principal,
+			resolver: runtime?.accountResolver,
+			onAccount: exchange.onAccount,
+			log
+		}) : tools;
+		const reply = await handleMcpMessage(body, {
+			tools: served,
+			caller,
+			withheldCount,
+			authorizable: admitted.challenge,
+			transport: stream.transport,
+			cancellation: trackCancellation(cancellationFor(admitted.callerKey, log), admitted.onCancelled),
+			serverInfo: runtime?.serverInfo ?? serverInfo(),
+			versions,
+			cache,
+			...settings.instructions !== void 0 ? { instructions: settings.instructions } : {}
+		}, { protocolVersion: exchange.protocolVersion });
+		if (reply.failure) {
+			const { tool, error } = reply.failure;
+			log?.(`MCP — l'outil « ${tool} » a levé : ${error instanceof Error ? error.stack ?? error.message : String(error)}`, "ERROR");
+		}
+		const sse = await stream.finish(reply.body);
+		if (sse !== null) return {
+			kind: "stream",
+			stream: sse
+		};
+		if (reply.body === null) return {
+			kind: "empty",
+			status: reply.status
+		};
+		return {
+			kind: "json",
+			status: reply.status,
+			body: reply.body
+		};
+	}
+	return Object.freeze({
+		settings,
+		respond,
+		respondStdio,
+		async serve(controller, body) {
+			const context = controller.context;
+			const method = context?.method;
+			if (method === "GET" || method === "DELETE") return write(controller, settings.enabled ? METHOD_NOT_ALLOWED : DISABLED);
+			const request = controller.request;
+			const headers = request?.headers ?? {};
+			return write(controller, await respond({
+				body,
+				rawBody: () => request && "data" in request ? request.data.toString(request.charset) : void 0,
+				origin: firstHeader(headers.origin),
+				protocolVersion: firstHeader(headers["mcp-protocol-version"]),
+				authorization: firstHeader(headers.authorization),
+				remoteAddress: context?.remoteAddress ?? void 0,
+				relayed: isRelayedRequest(headers),
+				signal: context?.signal,
+				onAccount: gateProtected && context ? (identifier) => {
+					context.userIdentifier = identifier;
+				} : void 0,
+				openStream: controller.acceptsSse() ? () => controller.renderSse({ maxEventBytes: MCP_STREAM_MAX_EVENT_BYTES }) : void 0
+			}, {
+				modules: fixedModules === null ? context?.kernel?.modules ?? Nodefony.getKernel()?.modules : void 0,
+				verifier: gateProtected ? controller.get(ACCESS_TOKEN_VERIFIER) ?? void 0 : void 0,
+				accountResolver: gateProtected ? controller.get(ACCESS_ACCOUNT_RESOLVER) ?? void 0 : void 0,
+				log: (message, severity) => controller.log(message, severity)
+			}));
+		},
+		protectedResources(modules) {
+			const authz = settings.authorization;
+			if (!settings.enabled || !gateProtected) return EMPTY_PROTECTED_RESOURCES;
+			return [{
+				resource: authz.resource,
+				authorizationServers: authz.authorizationServers,
+				scopesSupported: mcpDeclaredScopes({ modules: fixedModules ?? modules }),
+				resourceName: authz.resourceName,
+				resourceDocumentation: authz.resourceDocumentation
+			}];
+		}
+	});
+}
+/** Écrit une réponse décrite sur un controller. */
+function write(controller, response) {
+	switch (response.kind) {
+		case "stream": return response.stream.close();
+		case "empty": return controller.renderResponse("", void 0, response.status, response.headers);
+		case "json": return controller.renderJson(response.body, response.status, response.headers);
+	}
+}
+/**
+* Message UNIFORME d'un compte inutilisable — la cause (introuvable,
+* verrouillé, sujet externe sans rattachement) part au journal, jamais à
+* l'agent : un refus détaillé dirait quels comptes existent.
+*/
+const ACCOUNT_UNAVAILABLE = "le compte désigné par le jeton n'est pas utilisable : l'outil ne s'exécute pas";
+/** Plus long délai qu'un minuteur accepte (2³¹ − 1 ms, ~24,8 jours). */
+const MAX_TIMER_MS = 2147483647;
+/**
+* Les outils servis, ceux qui agissent au nom du compte enveloppés : leur
+* handler s'exécute dans une bulle de requête où le compte est posé.
+*
+* Aucune allocation tant qu'aucun outil ne le déclare : la liste servie est
+* rendue telle quelle.
+*/
+function actingTools(tools, acting) {
+	let wrapped = null;
+	for (const [index, tool] of tools.entries()) {
+		if (tool.actsForUser !== true) continue;
+		wrapped ??= tools.slice();
+		wrapped[index] = {
+			...tool,
+			handler: (args, caller, run) => runAsAccount(tool, args, caller, run, acting)
+		};
+	}
+	return wrapped ?? tools;
+}
+/**
+* Exécute un outil au nom du compte que désigne le jeton.
+*
+* Le compte est retrouvé AVANT le handler : les lecteurs de l'identité
+* (`RequestContext.getAuthenticatedUser()`, le voteur de rôles) sont
+* synchrones, une résolution paresseuse ne les atteindrait jamais. La bulle est
+* un NOUVEL objet — elle hérite de la corrélation et du scope de la requête,
+* deux appels concurrents ne se voient pas — vidée en `finally`. Le handler
+* meurt avec le jeton : son signal s'abat à l'expiration.
+*
+* Fail-closed : sans résolveur (CRITIC) ou sans compte utilisable, l'appel rend
+* `isError` — jamais une exécution en anonyme. Une PANNE du résolveur lève, et
+* la porte la traite comme l'exception d'un outil (journal, `-32603` opaque).
+*/
+async function runAsAccount(tool, args, caller, run, acting) {
+	const { principal, resolver, log } = acting;
+	if (resolver === void 0) {
+		log?.(`MCP — l'outil « ${tool.name} » agit au nom d'un compte, mais aucun résolveur de compte n'est posé (\`${ACCESS_ACCOUNT_RESOLVER}\`, module \`@nodefony/security\`) : l'appel est refusé plutôt que servi en anonyme.`, "CRITIC");
+		return mcpText(ACCOUNT_UNAVAILABLE, true);
+	}
+	const account = await resolver(principal);
+	if (account === null) {
+		log?.(`MCP — l'outil « ${tool.name} » : aucun compte utilisable pour le sujet du jeton (émetteur ${principal.issuer}) — introuvable, inactif, verrouillé ou sans rattachement. Appel refusé.`, "WARNING");
+		return mcpText(ACCOUNT_UNAVAILABLE, true);
+	}
+	const remainingMs = principal.expiresAt === void 0 ? null : principal.expiresAt * 1e3 - Date.now();
+	if (remainingMs !== null && remainingMs <= 0) return mcpText("le jeton a expiré : l'outil ne s'exécute pas", true);
+	acting.onAccount?.(account.user.identifier);
+	const store = {
+		...RequestContext.get() ?? { requestId: "" },
+		token: account.token,
+		user: account.user
+	};
+	const bounded = boundedRun(run, remainingMs);
+	try {
+		return await RequestContext.run(store, () => tool.handler(args, caller, bounded.run));
+	} finally {
+		bounded.dispose();
+		RequestContext.release(store);
+	}
+}
+/** Rien à faire : ni minuteur à couper, ni écouteur à retirer, ni progression à porter. */
+const NOOP = () => {};
+/**
+* L'exécution prêtée au handler, bornée par l'expiration du jeton : son signal
+* s'abat quand l'agent abandonne OU quand le jeton expire.
+*
+* Minuteur `unref` et écouteur retirés par `dispose` — rien ne survit à
+* l'appel. Sans expiration connue (ou au-delà de ce qu'un minuteur accepte),
+* l'exécution d'origine est rendue telle quelle.
+*/
+function boundedRun(run, remainingMs) {
+	if (remainingMs === null || remainingMs > MAX_TIMER_MS) return {
+		run,
+		dispose: NOOP
+	};
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(/* @__PURE__ */ new Error("jeton expiré")), remainingMs);
+	timer.unref();
+	const parent = run?.signal;
+	const onAbort = () => controller.abort(parent?.reason);
+	if (parent?.aborted) controller.abort(parent.reason);
+	else parent?.addEventListener("abort", onAbort, { once: true });
+	return {
+		run: {
+			signal: controller.signal,
+			progress: run ? run.progress.bind(run) : NOOP
+		},
+		dispose: () => {
+			clearTimeout(timer);
+			parent?.removeEventListener("abort", onAbort);
+		}
+	};
+}
+export { MCP_STREAM_MAX_EVENT_BYTES, defineMcpGate, mcpGateSchema };