nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/node/kernel/inspect/docOutline.js

@@ -0,0 +1,86 @@
+//#region src/kernel/inspect/docOutline.ts
+/** Un titre atx, hors bloc de code. */
+const HEADING_RE = /^(#{1,6})[^\S\n](.*)$/;
+/** Les `#` de fermeture, forme ATX facultative : `## Titre ##`. */
+const HEADING_CLOSING_RE = /[^\S\n]#+$/;
+/** Ouverture ou fermeture d'un bloc de code clôturé. */
+const FENCE_RE = /^\s*(?:```|~~~)/;
+/**
+* Forme comparable d'un titre : minuscules, sans diacritiques ni ponctuation
+* de décoration — un agent recopie rarement « 🔴 Règle ABSOLUE » à l'identique.
+*/
+function foldTitle(text) {
+	return text.normalize("NFD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+}
+/**
+* Repère les titres d'un markdown, **en ignorant les blocs de code**.
+*
+* Cette exclusion n'est pas un détail de forme : la documentation du framework
+* est pleine d'exemples shell, où un `# commentaire` en début de ligne serait
+* lu comme un titre de niveau 1 — et découperait le document à des endroits qui
+* n'existent pas.
+*
+* @param markdown - corps du document (frontmatter déjà retiré)
+* @returns les titres dans l'ordre du document, avec le poids de leur section
+*/
+function outlineMarkdown(markdown) {
+	const lines = markdown.split("\n");
+	const sections = [];
+	let inFence = false;
+	for (let i = 0; i < lines.length; i += 1) {
+		if (FENCE_RE.test(lines[i])) {
+			inFence = !inFence;
+			continue;
+		}
+		if (inFence) continue;
+		const m = HEADING_RE.exec(lines[i]);
+		if (m) sections.push({
+			level: m[1].length,
+			title: m[2].trim().replace(HEADING_CLOSING_RE, "").trim(),
+			line: i + 1,
+			chars: 0
+		});
+	}
+	for (let s = 0; s < sections.length; s += 1) {
+		const start = sections[s].line - 1;
+		let end = lines.length;
+		for (let n = s + 1; n < sections.length; n += 1) if (sections[n].level <= sections[s].level) {
+			end = sections[n].line - 1;
+			break;
+		}
+		sections[s].chars = lines.slice(start, end).join("\n").length;
+	}
+	return sections;
+}
+/**
+* Extrait UNE section d'un markdown, sous-sections comprises.
+*
+* Le titre demandé est reconnu sans casse, sans accents et sans ponctuation
+* décorative ({@link foldTitle}) : « securite » retrouve « 🔐 Sécurité ». À
+* défaut d'égalité, une inclusion suffit — un agent cite plus souvent un bout
+* de titre que sa forme exacte.
+*
+* @param markdown - corps du document (frontmatter déjà retiré)
+* @param wanted - titre cherché, sous n'importe quelle forme approchante
+* @returns le titre RÉEL et le corps de sa section, ou `null` si rien ne matche
+*/
+function extractMarkdownSection(markdown, wanted) {
+	const sections = outlineMarkdown(markdown);
+	const target = foldTitle(wanted);
+	if (target === "") return null;
+	const found = sections.find((s) => foldTitle(s.title) === target) ?? sections.find((s) => foldTitle(s.title).includes(target));
+	if (!found) return null;
+	const lines = markdown.split("\n");
+	const start = found.line - 1;
+	let end = lines.length;
+	for (const s of sections) if (s.line > found.line && s.level <= found.level) {
+		end = s.line - 1;
+		break;
+	}
+	return {
+		title: found.title,
+		markdown: lines.slice(start, end).join("\n")
+	};
+}
+//#endregion
+export { extractMarkdownSection, outlineMarkdown };

package/dist/node/kernel/lifecycleTags.js

@@ -0,0 +1,76 @@
+//#region src/kernel/lifecycleTags.ts
+/**
+* Pose `owner` + `critical` sur une fonction listener, **en place**, et la renvoie.
+*
+* @typeParam F - type de la fonction (préservé).
+* @param fn - listener (typiquement `hook.bind(module)`).
+* @param owner - nom du module propriétaire.
+* @param critical - criticité du module (cf `Module.critical`).
+* @returns la même fonction `fn`, taguée.
+*/
+function tagListener(fn, owner, critical) {
+	const tagged = fn;
+	tagged.__nodefony_owner = owner;
+	tagged.__nodefony_critical = critical;
+	return fn;
+}
+/**
+* Marque un listener comme n'étant PAS soumis à la borne de temps du boot.
+*
+* 🔴 Vécu, et c'est le pire mode de panne qui soit : l'action d'une commande est
+* câblée comme un écouteur de cycle de vie (`Command.setEvents`), donc bornée
+* comme un hook de module. Passé vingt secondes, la garde abandonnait
+* l'écouteur en fail-soft, le boot enchaînait sur `finishOrPark(0)` et le
+* processus sortait en **0 au milieu du travail**, sans un mot — `doctor
+* --deep` rendait ainsi un succès muet en plein `npm run test`.
+*
+* La distinction est de NATURE, pas de durée : la borne existe pour qu'un module
+* qui se fige ne gèle pas le DÉMARRAGE. Une commande, elle, EST le programme —
+* une migration, une construction, une suite de tests ou une question posée à
+* l'utilisateur dépassent vingt secondes sans rien avoir d'anormal.
+*
+* @typeParam F - type de la fonction (préservé).
+* @param fn - le listener à marquer.
+* @returns la même fonction `fn`, marquée.
+*/
+function tagUnboundedListener(fn) {
+	fn.__nodefony_unbounded = true;
+	return fn;
+}
+/**
+* Dit si un listener a été marqué par {@link tagUnboundedListener}.
+*
+* **Déballe le wrapper `once`** pour la même raison que {@link readListenerTags} :
+* les actions de commande sont câblées via `kernel.once(...)`, et lire le
+* marquage sur le wrapper interne de Node rendrait toujours `false`.
+*
+* @param fn - listener (wrapper `once` ou fonction directe).
+* @returns `true` si ce listener échappe à la borne de temps du boot.
+*/
+function isUnboundedListener(fn) {
+	if (fn == null) return false;
+	const wrapper = fn;
+	return (wrapper.listener ?? wrapper).__nodefony_unbounded === true;
+}
+/**
+* Relit les tags d'un listener. **Déballe le wrapper `once`** : `rawListeners()`
+* renvoie le wrapper interne d'`EventEmitter.once` (qui porte `.listener` =
+* fonction d'origine) — les hooks de module étant câblés via `kernel.once(...)`,
+* lire les tags directement sur le wrapper renverrait toujours `undefined`.
+*
+* @param fn - listener (wrapper `once` ou fonction directe).
+* @returns `{ owner, critical }` (valeurs `undefined` si non tagué).
+*/
+function readListenerTags(fn) {
+	if (fn == null) return {};
+	const wrapper = fn;
+	const target = wrapper.listener ?? wrapper;
+	const rawName = target.name;
+	return {
+		owner: target.__nodefony_owner,
+		critical: target.__nodefony_critical,
+		name: typeof rawName === "string" && rawName !== "" ? rawName : void 0
+	};
+}
+//#endregion
+export { isUnboundedListener, readListenerTags, tagListener, tagUnboundedListener };

package/dist/node/kernel/moduleConfig.js

@@ -0,0 +1,75 @@
+import { BootConfigurationError } from "./BootConfigurationError.js";
+//#region src/kernel/moduleConfig.ts
+/**
+* Rend une anomalie Zod lisible par celui qui a écrit la configuration.
+*
+* Le cas `unrecognized_keys` est traité à part : le message natif de zod
+* (`Unrecognized key: "x"`) ne dit ni où se trouve la clé dans l'arbre, ni ce
+* qu'il faut en faire, et il est en anglais alors que tout ce que Nodefony
+* affiche est en français. Une faute de frappe se corrige d'autant plus vite
+* qu'on lit le chemin COMPLET de la clé refusée.
+*
+* @param issue - anomalie brute remontée par zod.
+* @returns une ligne de message, chemin compris.
+*/
+function formatConfigIssue(issue) {
+	const path = (issue.path ?? []).join(".");
+	if (issue.code === "unrecognized_keys" && issue.keys?.length) {
+		const keys = issue.keys.map((k) => path ? `${path}.${k}` : k).map((k) => `\`${k}\``).join(", ");
+		const plural = issue.keys.length > 1 ? "s" : "";
+		return `clé${plural} inconnue${plural} : ${keys} — retire-la${plural} ou corrige l'orthographe`;
+	}
+	return `${path || "(racine)"} : ${issue.message ?? "invalide"}`;
+}
+/**
+* Extrait les anomalies d'une erreur Zod, quelle que soit la copie de zod qui
+* l'a levée (`issues` est une propriété de données, pas une méthode de classe).
+*
+* @param error - erreur levée par `schema.parse()`.
+* @returns le message agrégé, une ligne par anomalie.
+*/
+function formatConfigIssues(error) {
+	if (error instanceof Error && "issues" in error && Array.isArray(error.issues)) return error.issues.map(formatConfigIssue).join(" · ");
+	return error instanceof Error ? error.message : String(error);
+}
+/**
+* Valide la configuration d'un module contre son schéma Zod, et transforme un
+* refus en {@link BootConfigurationError} nommant le module et la clé fautive.
+*
+* ⭐ TL;DR : c'est LA porte par laquelle toute config de module est validée.
+* Chaque module l'appelle depuis son `define<X>Config()` ; aucun ne réécrit le
+* bloc `try`/`catch`.
+*
+* **Pourquoi une fonction du cœur, et pas un bloc recopié par module.** Les dix
+* modules du framework portaient le même `catch` à l'identique, et il avait
+* divergé sur les deux points qui comptent : le TYPE de l'erreur levée et la
+* LANGUE du message. Une règle écrite à dix endroits diverge au premier ajout.
+*
+* **Pourquoi `BootConfigurationError` et pas une `Error` ordinaire.** Le kernel
+* distingue les deux ({@link BootConfigurationError}) : un hook de cycle de vie
+* qui lève une erreur QUELCONQUE est absorbé en développement — c'est le
+* fail-soft, il protège la DX d'un module optionnel cassé — tandis qu'une
+* erreur de CONFIGURATION interrompt le boot dans TOUS les environnements. Une
+* `Error` nue rendait donc le refus INVISIBLE là où il est le plus utile :
+* sur le poste de celui qui vient d'écrire la faute de frappe.
+*
+* ⚠️ Ne gèle rien — le gel est la décision du module appelant. `@nodefony/http`
+* ne peut PAS geler sa config (ses services la mutent au boot : `uploadDir`,
+* `serialNumber`), quand les autres le font.
+*
+* @param schema - schéma Zod du module (source unique des défauts).
+* @param input - configuration brute venue de `use("<paquet>", { … })`.
+* @param packageName - nom du paquet, préfixe du message (`@nodefony/http`).
+* @returns la configuration validée, défauts appliqués.
+* @throws BootConfigurationError si un champ est invalide ou une clé inconnue —
+*   toutes les anomalies agrégées, chacune avec son chemin.
+*/
+function parseModuleConfig(schema, input, packageName) {
+	try {
+		return schema.parse(input);
+	} catch (e) {
+		throw new BootConfigurationError(`[${packageName}] configuration invalide — ${formatConfigIssues(e)}`, { cause: e });
+	}
+}
+//#endregion
+export { parseModuleConfig as default, parseModuleConfig };

package/dist/node/kernel/moduleGating.js

@@ -0,0 +1,68 @@
+//#region src/kernel/moduleGating.ts
+/** La raison affichée quand la politique du module l'écarte d'un runtime de production. */
+const GATED_BY_POLICY = "policy \"dev\" — runtime production";
+/** La raison affichée quand la garde `when(config)` du module refuse. */
+const GATED_BY_CONDITION = "condition when(config) non remplie";
+/**
+* Applique la règle de gating à un manifeste.
+*
+* `policy`/`when` ne font que FILTRER — jamais réordonner : l'ordre du tableau
+* est la priorité de chargement, et un tri introduirait une dépendance que
+* personne n'a écrite.
+*
+* @param manifest - le manifeste `config.modules`, tel qu'il est déclaré.
+* @param input - ce qu'il faut savoir de l'environnement visé.
+* @returns les entrées retenues, celles écartées, et les dérogations.
+*/
+function gateModuleManifest(manifest, input) {
+	const entries = [];
+	const gated = [];
+	const derogated = [];
+	if (!Array.isArray(manifest)) return {
+		entries,
+		gated,
+		derogated
+	};
+	for (const item of manifest) {
+		const entry = typeof item === "string" ? { name: item } : item;
+		if (!entry?.name) continue;
+		if (entry.policy === "dev" && input.isProduction) {
+			if (input.forceDevModules) derogated.push(entry.name);
+			else {
+				gated.push({
+					module: entry.name,
+					reason: GATED_BY_POLICY
+				});
+				continue;
+			}
+		}
+		let allowed = true;
+		if (typeof entry.when === "function") try {
+			allowed = Boolean(entry.when(input.config));
+		} catch (e) {
+			gated.push({
+				module: entry.name,
+				reason: `condition when(config) en erreur — ${e.message}`
+			});
+			continue;
+		}
+		if (!allowed) {
+			gated.push({
+				module: entry.name,
+				reason: GATED_BY_CONDITION
+			});
+			continue;
+		}
+		entries.push({
+			name: entry.name,
+			config: entry.config
+		});
+	}
+	return {
+		entries,
+		gated,
+		derogated
+	};
+}
+//#endregion
+export { GATED_BY_CONDITION, GATED_BY_POLICY, gateModuleManifest };

package/dist/node/kernel/readinessRegistry.js

@@ -0,0 +1,98 @@
+//#region src/kernel/readinessRegistry.ts
+/**
+* Les contributeurs et le compte de ceux qui retiennent la mise en service.
+*
+* Objet nu (`Object.create(null)`) plutôt que `Map` : quelques entrées, accès
+* ponctuel, aucun héritage de prototype à craindre sur un nom venu d'un module.
+* Le compte des non-prêts est tenu À L'ÉCRITURE — il n'est jamais recalculé par
+* parcours, puisque c'est la lecture qui doit rester gratuite.
+*/
+var ReadinessRegistry = class {
+	entries = Object.create(null);
+	notReady = 0;
+	tracked = 0;
+	/** Nombre de contributeurs qui retiennent la mise en service (0 = disponible). */
+	get blocked() {
+		return this.notReady;
+	}
+	/** Nombre de contributeurs inscrits, prêts ou non. */
+	get size() {
+		return this.tracked;
+	}
+	/**
+	* Inscrit ou met à jour un contributeur nommé. Idempotent par nom : un même
+	* nom réenregistré remplace son verdict, il n'ajoute jamais une seconde voix.
+	*
+	* @param name - nom du contributeur (`"drizzle:schema"`, `"cache"`…)
+	* @param ready - verdict DÉJÀ calculé ; `false` retient la mise en service
+	* @param reason - ce qui retient, en clair — ignoré quand `ready` est vrai
+	* @param blocking - `false` pour PUBLIER l'état sans retenir le trafic ; le
+	*   contributeur apparaît alors au diagnostic (et le noyau sait qu'un état
+	*   externe est en cours), mais `/readyz` continue de répondre 200.
+	* @returns `true` si le verdict AGRÉGÉ a basculé (retenu ⇄ disponible)
+	*/
+	set(name, ready, reason, blocking = true) {
+		const wasBlocked = this.notReady > 0;
+		const entry = this.entries[name];
+		const weighs = (e) => !e.ready && e.blocking;
+		if (entry === void 0) {
+			const neuf = {
+				ready,
+				reason: ready ? void 0 : reason,
+				blocking
+			};
+			this.entries[name] = neuf;
+			this.tracked += 1;
+			if (weighs(neuf)) this.notReady += 1;
+		} else {
+			const weighedBefore = weighs(entry);
+			entry.ready = ready;
+			entry.blocking = blocking;
+			entry.reason = ready ? void 0 : reason;
+			const weighsNow = weighs(entry);
+			if (weighedBefore !== weighsNow) this.notReady += weighsNow ? 1 : -1;
+		}
+		return wasBlocked !== this.notReady > 0;
+	}
+	/**
+	* Retire un contributeur — sa voix ne compte plus, ni pour retenir ni pour
+	* libérer. C'est le geste d'un module qui s'arrête.
+	*
+	* @param name - nom du contributeur
+	* @returns `true` si le verdict AGRÉGÉ a basculé (retenu ⇄ disponible)
+	*/
+	clear(name) {
+		const entry = this.entries[name];
+		if (entry === void 0) return false;
+		const wasBlocked = this.notReady > 0;
+		if (!entry.ready && entry.blocking) this.notReady -= 1;
+		delete this.entries[name];
+		this.tracked -= 1;
+		return wasBlocked !== this.notReady > 0;
+	}
+	/**
+	* Restitue les contributeurs pour un diagnostic (journal, `status`, console
+	* d'administration) — hors du chemin de la sonde, qui ne lit que
+	* {@link ReadinessRegistry.blocked}.
+	*
+	* @returns un contributeur par entrée, triés par nom (ordre stable)
+	*/
+	report() {
+		const out = [];
+		for (const name of Object.keys(this.entries).sort()) {
+			const entry = this.entries[name];
+			const base = {
+				name,
+				ready: entry.ready
+			};
+			out.push({
+				...base,
+				...entry.reason === void 0 ? {} : { reason: entry.reason },
+				...entry.blocking ? {} : { blocking: false }
+			});
+		}
+		return out;
+	}
+};
+//#endregion
+export { ReadinessRegistry };

package/dist/node/kernel/resolveModuleEntry.js

@@ -0,0 +1,61 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+//#region src/kernel/resolveModuleEntry.ts
+/**
+* Rend un chemin importable par `import()`, et laisse tout le reste intact.
+*
+* POURQUOI : le spécificateur d'un `import()` dynamique est une **URL**, pas un chemin.
+* Sous POSIX la confusion est sans conséquence — `/a/b/c.js` n'est l'URL de rien, alors
+* Node le traite en chemin. Sous Windows elle est fatale : dans `D:\app\index.js`, `d:`
+* EST un schéma d'URL syntaxiquement valide, et Node refuse net —
+* `ERR_UNSUPPORTED_ESM_URL_SCHEME: Received protocol 'd:'`. Le chargement des modules
+* échouait donc à chaque démarrage, ce qui ne se voyait pas : le code compile, il ne
+* s'exécute simplement jamais.
+*
+* Ce que la fonction NE touche pas : un nom de paquet (`@nodefony/http`), un chemin
+* relatif, une URL déjà formée (`file:`, `data:`, `node:`) — aucun n'est absolu au sens
+* de `path`, tous sont rendus tels quels. Le test d'absoluité vient donc AVANT toute
+* lecture de schéma : l'inverse reprendrait `d:` pour un protocole, ce qui est
+* précisément le défaut qu'on ferme.
+*
+* @param spec - chemin de fichier, nom de paquet ou URL.
+* @returns une URL `file://` si `spec` est un chemin absolu, `spec` inchangé sinon.
+*/
+function toImportSpecifier(spec) {
+	return path.isAbsolute(spec) ? pathToFileURL(spec).href : spec;
+}
+/**
+* Résout le point d'entrée d'un module Nodefony **depuis l'application**, et non
+* depuis le paquet `nodefony`.
+*
+* POURQUOI cette fonction existe : un `import("@app/blog")` écrit dans le code du
+* core est résolu par Node relativement au FICHIER qui l'écrit. Dès que le paquet
+* `nodefony` n'habite pas l'arbre `node_modules` de l'app — mode `--link` (symlink
+* vers un checkout), monorepo, pnpm, hoisting — les modules LOCAUX de l'app
+* (`modules/*`, workspaces npm) deviennent introuvables (« Cannot find package »),
+* alors qu'ils sont parfaitement résolvables depuis l'app. Le repo self-hosted
+* masquait le défaut par accident de topologie : tout y vit sous le même
+* `node_modules`.
+*
+* La règle est donc : **c'est l'app qui décide où sont ses modules**. On résout à
+* partir de son `package.json`, et on rend une URL `file://` absolue, directement
+* importable.
+*
+* @param appRoot - racine de l'application (`kernel.path`).
+* @param moduleName - nom du paquet, tel qu'écrit dans le manifeste `modules`.
+* @returns URL `file://` absolue du point d'entrée, ou le spécificateur NU si la
+*   résolution depuis l'app échoue (paquet absent, ou n'exposant que la condition
+*   `import` — un cas où `require.resolve` refuse). Le repli rend le comportement
+*   historique : c'est alors `import()` qui produira l'erreur, avec son message.
+*/
+function resolveModuleEntry(appRoot, moduleName) {
+	try {
+		const require = createRequire(path.join(appRoot, "package.json"));
+		return pathToFileURL(require.resolve(moduleName)).href;
+	} catch {
+		return moduleName;
+	}
+}
+//#endregion
+export { resolveModuleEntry, toImportSpecifier };

package/dist/node/mcp/caller.js

@@ -0,0 +1,40 @@
+import { ADMIN_DEFAULT_ROLE } from "../kernel/adminPlane/adminRbac.js";
+import { rolesFromScopes } from "../kernel/adminPlane/adminCaller.js";
+//#region src/mcp/caller.ts
+/**
+* Quels rôles porte l'appelant d'une porte MCP — **la règle, à un seul endroit**.
+*
+* ⭐ Toute porte MCP passe par ici, y compris celles qu'un module créera plus
+* tard (gestion d'agents, passerelles métier). C'est délibéré : la question
+* « que vaut un appelant sur ma porte » a exactement une bonne réponse, et
+* laisser chaque porte la réécrire garantit qu'une copie finira plus permissive
+* que les autres sans que rien ne le signale — c'est déjà ce qui s'est produit
+* quand la lecture d'administration fabriquait un administrateur.
+*
+* Les trois postures :
+*
+* | La porte | L'appelant | Ce qu'il porte |
+* | --- | --- | --- |
+* | non protégée | quiconque l'atteint | `operatorRoles` — sa protection est son PÉRIMÈTRE |
+* | protégée | jeton vérifié | ce que ses SCOPES ouvrent, rien de plus |
+* | protégée | anonyme toléré | **rien** — la déclaration d'autorisation serait vidée de son sens |
+*
+* Le premier cas n'est pas du laxisme : une porte sans serveur d'autorisation
+* est bornée par son module (`policy: "dev"`) et par ses gardes de transport,
+* et qui l'atteint lit déjà les sources de l'application. Lui refuser la
+* lecture n'ajouterait aucune barrière et rendrait l'outillage inutile. Ce qui
+* compte, c'est que ce soit un CHOIX écrit — pas un administrateur fabriqué au
+* fond d'une fonction de lecture.
+*
+* @param posture - ce que la porte sait d'elle-même et de cet appel.
+* @param operatorRoles - ce qu'accorde une porte NON protégée. Une porte qui
+*   veut être plus stricte passe une liste plus courte, voire vide ; elle n'a
+*   pas à réécrire la règle pour autant.
+* @returns les rôles à poser sur `IMcpCaller.roles`.
+*/
+function mcpCallerRoles(posture, operatorRoles = [ADMIN_DEFAULT_ROLE]) {
+	if (!posture.protected) return operatorRoles;
+	return posture.authenticated ? rolesFromScopes(posture.scopes) : [];
+}
+//#endregion
+export { mcpCallerRoles };

package/dist/node/mcp/guard.js

@@ -0,0 +1,51 @@
+//#region src/mcp/guard.ts
+/**
+* Une adresse est-elle celle de la machine locale ?
+*
+* Couvre les trois formes que Node rend selon la pile réseau : IPv4
+* (`127.x.x.x`), IPv6 (`::1`), et l'IPv4 encapsulée en IPv6
+* (`::ffff:127.0.0.1`) — la plus fréquente sur un serveur à double pile, et
+* celle qu'une comparaison naïve à `"127.0.0.1"` rate.
+*
+* @param address - `socket.remoteAddress`, éventuellement absent
+* @returns `true` si l'appel vient de cette machine
+*/
+function isLocalAddress(address) {
+	if (!address) return false;
+	const bare = address.startsWith("::ffff:") ? address.slice(7) : address;
+	if (bare === "::1" || bare === "localhost") return true;
+	return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(bare);
+}
+/**
+* Décide si un appel MCP peut être servi.
+*
+* ⭐ **La règle sur `Origin` est contre-intuitive, et c'est elle qui protège.**
+* Un client MCP légitime est un *process* (Cursor, Claude Code, un agent tiers)
+* : il n'envoie **aucun** `Origin`, cet en-tête étant posé par les navigateurs.
+* Une page web malveillante, elle, en pose **toujours** un lorsqu'elle vise
+* `https://localhost:5152`. Donc : *absent* → on passe ; *présent et hors
+* allowlist* → `403`. C'est ce qui referme le DNS rebinding, le seul vecteur
+* réel contre un serveur MCP local.
+*
+* L'ordre des contrôles est délibéré : la localité d'abord, parce qu'un appel
+* distant ne doit même pas apprendre quelles origines sont admises.
+*
+* @param input - ce que la requête présente
+* @param policy - les réglages du module
+* @returns le verdict, avec le motif quand il refuse
+*/
+function checkMcpAccess(input, policy) {
+	if (!policy.allowRemote && !isLocalAddress(input.remoteAddress)) return {
+		allowed: false,
+		why: `adresse non locale (${input.remoteAddress ?? "inconnue"}) — voir l'option \`allowRemote\` du serveur MCP`
+	};
+	if (input.origin !== void 0 && input.origin !== "") {
+		if (!policy.allowedOrigins.includes(input.origin)) return {
+			allowed: false,
+			why: `origine « ${input.origin} » non admise — voir l'option \`allowedOrigins\` du serveur MCP`
+		};
+	}
+	return { allowed: true };
+}
+//#endregion
+export { checkMcpAccess, isLocalAddress };