@nodefony/ai 10.0.0-beta.3 → 10.0.0-beta.4

package/dist/nodefony/mcp/stdio.js

@@ -0,0 +1,64 @@
+import { JsonRpcError, jsonRpcFailure } from "./protocol.js";
+import { createInterface } from "node:readline";
+// nodefony/mcp/stdio.ts
+/** Un puits stdio : chaque envoi devient une ligne, dans l'ordre d'appel. */
+function lineSink(write) {
+	return {
+		closed: false,
+		send(data) {
+			write(JSON.stringify(data));
+		}
+	};
+}
+/**
+* Sert une porte MCP sur un flux de lignes, jusqu'à la fin de l'entrée.
+*
+* Chaque ligne est servie SANS attendre la précédente : une
+* `notifications/cancelled` doit pouvoir arriver pendant l'appel qu'elle
+* vise. Les réponses partent donc dans l'ordre où elles se terminent — chacune
+* porte son identifiant, c'est ce que JSON-RPC prévoit. Une ligne vide est
+* ignorée ; une ligne illisible rend `-32700` sans arrêter la boucle.
+*
+* L'entrée fermée, le client est parti : les appels encore en cours sont
+* abattus (leur signal), puis la promesse se résout quand tous ont rendu.
+*
+* @param gate - la porte à servir.
+* @param options - entrée, écriture d'une ligne, environnement de la porte.
+* @returns une promesse résolue à la fin de l'entrée, appels en cours clos.
+*/
+function serveMcpStdio(gate, options) {
+	const { input, runtime } = options;
+	const write = (text) => options.write(`${text}\n`);
+	const departure = new AbortController();
+	const pending = /* @__PURE__ */ new Set();
+	const serve = async (line) => {
+		try {
+			const response = await gate.respondStdio({
+				line,
+				signal: departure.signal,
+				openStream: () => lineSink(write)
+			}, runtime);
+			if (response.kind === "json") write(JSON.stringify(response.body));
+		} catch (error) {
+			runtime?.log?.(`MCP stdio — message non servi : ${error instanceof Error ? error.stack ?? error.message : String(error)}`, "ERROR");
+			write(JSON.stringify(jsonRpcFailure(null, JsonRpcError.INTERNAL_ERROR, "erreur interne")));
+		}
+	};
+	return new Promise((resolve) => {
+		const lines = createInterface({
+			input,
+			crlfDelay: Infinity
+		});
+		lines.on("line", (line) => {
+			if (line.trim() === "") return;
+			const task = serve(line);
+			pending.add(task);
+			task.finally(() => pending.delete(task));
+		});
+		lines.once("close", () => {
+			departure.abort();
+			Promise.allSettled(pending).then(() => resolve());
+		});
+	});
+}
+export { serveMcpStdio };

package/dist/nodefony/mcp/stream.js

@@ -0,0 +1,80 @@
+// nodefony/mcp/stream.ts
+/**
+* Le flux de réponse d'une requête MCP, ouvert PARESSEUSEMENT — brique
+* générique de la boîte à outils, indépendante du transport.
+*
+* Toute porte (HTTP de développement, porte d'une application, futur `stdio`)
+* a la même décision à prendre : répondre en un objet, ou en flux quand
+* l'appel a quelque chose à dire en route. La règle vit ICI, une fois : le flux
+* ne s'ouvre qu'au PREMIER envoi, les envois s'enchaînent dans l'ordre, et la
+* réponse finale clôt le flux. Un appel qui ne dit rien en route n'ouvre rien —
+* la porte répond alors comme avant.
+*
+* Exception : un appel encore en cours au bout du délai de grâce
+* ({@link MCP_STREAM_GRACE_MS}) ouvre le flux sans rien y écrire. La norme
+* oblige le client à accepter une réponse SSE (`transports/streamable-http`),
+* avec ou sans `progressToken` ; or une réponse JSON qui tarde tombe sous le
+* délai d'inactivité de la requête (408), quand un flux ouvert le désarme et
+* bat de lui-même. Un outil court n'y voit rien : il a répondu avant.
+*
+* La porte ne fournit que ce qu'elle seule sait faire : OUVRIR son flux
+* (`renderSse()` pour une route HTTP).
+*/
+/**
+* Délai de grâce, en ms : au-delà, un appel sans réponse ouvre le flux. Très en
+* deçà du délai d'inactivité d'une requête (30 s par défaut), assez long pour
+* qu'un outil ordinaire réponde en JSON comme avant.
+*/
+const MCP_STREAM_GRACE_MS = 5e3;
+/**
+* Fabrique le flux de réponse paresseux d'une requête MCP.
+*
+* @param options - signal d'abandon, ouverture du flux, journal des pertes.
+* @returns le transport à donner au protocole, et `finish()`.
+*/
+function createMcpResponseStream(options) {
+	const { signal, open, onError, graceMs } = options;
+	let sink = null;
+	let pending = Promise.resolve();
+	let grace = null;
+	const transport = {};
+	if (signal) transport.signal = signal;
+	if (open && graceMs !== void 0 && graceMs > 0) {
+		grace = setTimeout(() => {
+			grace = null;
+			if (sink !== null || signal?.aborted === true) return;
+			const previous = pending;
+			pending = (async () => {
+				await previous;
+				sink ??= await open();
+			})().catch((error) => onError?.(error, false));
+		}, graceMs);
+		grace.unref();
+	}
+	if (open) transport.notify = (notification) => {
+		const previous = pending;
+		pending = (async () => {
+			await previous;
+			sink ??= await open();
+			if (!sink.closed) await sink.send(notification);
+		})().catch((error) => onError?.(error, false));
+	};
+	return {
+		transport,
+		async finish(body) {
+			if (grace !== null) {
+				clearTimeout(grace);
+				grace = null;
+			}
+			await pending;
+			if (sink === null) return null;
+			if (!sink.closed) try {
+				await sink.send(body);
+			} catch (error) {
+				onError?.(error, true);
+			}
+			return sink;
+		}
+	};
+}
+export { MCP_STREAM_GRACE_MS, createMcpResponseStream };

package/dist/nodefony/mcp/ticketSession.js

@@ -0,0 +1,177 @@
+import { isLocalAddress, isRelayedRequest } from "./guard.js";
+import { SESSION_TICKET_HEADER, SessionTicketStore } from "./sessionTicket.js";
+import { parseModuleConfig } from "nodefony";
+import { z } from "zod";
+// nodefony/mcp/ticketSession.ts
+/** Message unique de tout refus : la cause fine ne sort jamais vers l'appelant. */
+const TICKET_SESSION_REFUSED = "ticket de session refusé";
+const REFUSED = {
+	status: 403,
+	message: TICKET_SESSION_REFUSED
+};
+/**
+* Décide l'ouverture d'une session par ticket.
+*
+* Ordre délibéré : la localité, puis la présence d'un flux de session, et
+* seulement ensuite le rachat du ticket — un appel qui ne peut pas aboutir ne
+* consomme pas le ticket. L'identité vient du TICKET, jamais de la requête.
+*
+* @param request - le ticket présenté et l'adresse de l'appelant.
+* @param deps - magasin de tickets, flux de session, exigence de localité.
+* @returns `200` avec le compte et le pseudonyme de session, `403` uniforme, ou
+*   `503` quand l'application n'a pas de flux de session.
+*/
+async function openTicketSession(request, deps) {
+	if (deps.localOnly !== false && (request.relayed === true || !isLocalAddress(request.remoteAddress))) return REFUSED;
+	if (deps.establish === null) return {
+		status: 503,
+		message: "aucun flux de session : la session par ticket exige @nodefony/security"
+	};
+	const identifier = deps.tickets?.redeem(request.ticket) ?? null;
+	if (identifier === null) return REFUSED;
+	let user;
+	try {
+		user = await deps.establish(identifier);
+	} catch {
+		return REFUSED;
+	}
+	const ref = deps.sessionRef();
+	if (ref === null) return {
+		status: 503,
+		message: "session par ticket non ouverte par le flux de session"
+	};
+	return {
+		status: 200,
+		identifier: user.identifier,
+		roles: user.roles ?? [],
+		ref
+	};
+}
+/**
+* Le service résolu est-il un flux de session utilisable ?
+*
+* @param value - service lu dans le conteneur.
+* @returns `true` s'il ouvre une session pour une identité prouvée.
+*/
+function isSessionFlowView(value) {
+	return typeof value === "object" && value !== null && "establishSessionFor" in value && typeof value.establishSessionFor === "function";
+}
+/**
+* Le service résolu est-il un service de sessions utilisable ?
+*
+* @param value - service lu dans le conteneur.
+* @returns `true` s'il dérive un pseudonyme et détruit une session par lui.
+*/
+function isSessionServiceView(value) {
+	return typeof value === "object" && value !== null && "sessionRef" in value && typeof value.sessionRef === "function" && "destroyByRef" in value && typeof value.destroyByRef === "function";
+}
+/**
+* Lit le compte rendu par le flux de session, sans lui faire confiance.
+*
+* @param value - retour de `establishSessionFor`.
+* @param identifier - identité du ticket, retenue si le retour n'en porte pas.
+* @returns l'identifiant et les rôles chaîne du compte.
+*/
+function toTicketSessionUser(value, identifier) {
+	if (typeof value !== "object" || value === null) return { identifier };
+	return {
+		identifier: "identifier" in value && typeof value.identifier === "string" ? value.identifier : identifier,
+		roles: "roles" in value && Array.isArray(value.roles) ? value.roles.filter((r) => typeof r === "string") : []
+	};
+}
+/**
+* Lit, côté outil, la réponse de la route de connexion par ticket — sans lui
+* faire confiance. Vit à côté de {@link openTicketSession}, qui en produit la
+* forme : deux copies du format divergeraient.
+*
+* @param body - corps de la réponse, `null` si aucun.
+* @returns le compte et le pseudonyme de session, ou le message du refus.
+*/
+function readTicketSessionVerdict(body) {
+	let parsed;
+	try {
+		parsed = JSON.parse(body ?? "");
+	} catch {
+		return { message: "réponse illisible" };
+	}
+	if (typeof parsed !== "object" || parsed === null) return { message: "réponse illisible" };
+	if ("identifier" in parsed && typeof parsed.identifier === "string" && "ref" in parsed && typeof parsed.ref === "string") {
+		const roles = "roles" in parsed && Array.isArray(parsed.roles) ? parsed.roles.filter((r) => typeof r === "string") : [];
+		return {
+			identifier: parsed.identifier,
+			roles,
+			ref: parsed.ref
+		};
+	}
+	return { message: "message" in parsed && typeof parsed.message === "string" ? parsed.message : "réponse sans compte" };
+}
+/** Définition d'une porte de session par ticket — validée et figée au boot. */
+const ticketSessionGateSchema = z.strictObject({
+	/**
+	* Facteur déclaré au flux de session : l'audit écrit `login.success` avec
+	* cette raison, ce qui distingue une session d'outil d'une vraie connexion.
+	*/
+	factor: z.string().regex(/^[a-z][a-z0-9_-]{0,31}$/u),
+	/**
+	* Refuser tout appel non local. Défaut `true` : une porte qui accepte un
+	* appel distant doit l'ÉCRIRE — le ticket seul la protège alors.
+	*/
+	localOnly: z.boolean().default(true)
+});
+/**
+* Définit une porte de session par ticket : ce qui permet à un outil MCP de
+* tirer de vraies requêtes HTTP vers l'application AU NOM d'un compte.
+*
+* Une session ne s'ouvre que par le flux de session de l'application
+* (`authFlow.establishSessionFor`) : il revérifie le compte (actif, non
+* verrouillé), régénère l'identifiant et écrit l'audit. Ce flux exige une
+* requête en cours ; l'outil en envoie donc une, en boucle locale, à la route
+* que le controller déclare, et récupère le cookie que la réponse pose.
+* Fabriquer la session sans requête aurait recopié la règle de connexion.
+*
+* Comme {@link defineMcpGate}, la porte ne monte AUCUNE route : le controller
+* qui en a besoin la déclare, chemin écrit en littéral, et appelle `serve`.
+* Le magasin de tickets n'est alloué qu'au premier ticket émis.
+*
+* @param definition - facteur d'audit et exigence de localité.
+* @returns la porte, figée.
+* @throws BootConfigurationError - définition hors schéma.
+*/
+function defineTicketSessionGate(definition) {
+	const settings = Object.freeze(parseModuleConfig(ticketSessionGateSchema, definition, "porte de session par ticket"));
+	let tickets = null;
+	return {
+		settings,
+		get pending() {
+			return tickets?.pending ?? 0;
+		},
+		issue(identifier) {
+			tickets ??= new SessionTicketStore();
+			return tickets.issue(identifier);
+		},
+		async serve(controller) {
+			const context = controller.context;
+			if (!context?.request) throw new Error("session par ticket : aucun contexte de requête");
+			const flow = controller.get("authFlow");
+			const sessions = controller.get("sessions");
+			const verdict = await openTicketSession({
+				ticket: context.request.headers[SESSION_TICKET_HEADER],
+				remoteAddress: context.remoteAddress ?? void 0,
+				relayed: isRelayedRequest(context.request.headers)
+			}, {
+				tickets,
+				localOnly: settings.localOnly,
+				establish: isSessionFlowView(flow) ? async (identifier) => toTicketSessionUser(await flow.establishSessionFor(context, identifier, settings.factor), identifier) : null,
+				sessionRef: () => {
+					const id = context.session?.id;
+					return typeof id === "string" && isSessionServiceView(sessions) ? sessions.sessionRef(id) : null;
+				}
+			});
+			return controller.renderJson(verdict, verdict.status);
+		},
+		async close(sessions, ref) {
+			return isSessionServiceView(sessions) ? sessions.destroyByRef(ref, settings.factor) : false;
+		}
+	};
+}
+export { TICKET_SESSION_REFUSED, defineTicketSessionGate, isSessionFlowView, isSessionServiceView, openTicketSession, readTicketSessionVerdict, ticketSessionGateSchema, toTicketSessionUser };