@nodefony/devkit 10.0.0-alpha.1

package/dist/nodefony/config/config.js

@@ -0,0 +1,200 @@
+import { BUILTIN_MCP_TOOL_KEYS, canonicalResourceUri } from "nodefony";
+import { z } from "zod";
+//#region nodefony/config/config.ts
+/**
+* @nodefony/devkit — CONFIGURATION DU MODULE (schéma Zod = source unique).
+*
+* ⭐ TL;DR : CE SCHÉMA EST LA CONFIG. Chaque `.default(...)` est la valeur d'usine ;
+* changer un défaut du module = ÉDITER ICI (et nulle part ailleurs). L'app, elle,
+* ne surcharge que ses écarts, via `use("@nodefony/devkit", { … })`.
+*
+* RÈGLE D'OR (ADR-0006) : ce fichier porte le schéma commenté (type + validation +
+* défaut + doc) ET matérialise les défauts par `parse({})`. Le builder
+* (`defineDevkitConfig`) importe le schéma d'ici et ne retape aucune valeur —
+* un défaut écrit à deux endroits finit toujours par diverger.
+*
+* SURCHARGE (précédence croissante) :
+*   • défauts du schéma (ce fichier) ;
+*   • app : `use("@nodefony/devkit", { … })` dans `nodefony.config.ts` ;
+*   • déploiement : `NF__DEVKIT__<CHEMIN>=valeur` (override env générique, `__` = niveau).
+*
+* Le schéma reste **PUR** : aucune lecture de `process.env`, aucun accès au kernel
+* (il est évalué à l'import — le kernel n'existe pas encore).
+*
+* Champ sensible (clé, mot de passe) → `.meta({ secret: true })` EN DERNIER de la
+* chaîne : chaque méthode zod clone, une `.default()` posée après `.meta()` perdrait
+* la métadonnée. Ces flags ressortent dans le JSON Schema lu par Studio.
+*/
+/**
+* Rôle **serveur de ressource OAuth 2.1** de la porte MCP — éteint par défaut.
+*
+* ⭐ **Un seul réglage commande : {@link authorizationServers}.** Vide, la porte
+* se comporte exactement comme avant — anonyme, aucune métadonnée publiée,
+* aucun `401`. Non vide, le rôle s'allume ENTIÈREMENT. Un interrupteur séparé
+* aurait permis deux états qui se contredisent (« protégé mais sans serveur
+* d'autorisation », « métadonnées publiées mais jetons ignorés »), et c'est
+* précisément ce genre d'état que personne ne diagnostique.
+*
+* ⚠️ **Allumer ce rôle ne suffit pas à protéger quoi que ce soit** : il faut
+* aussi qu'un service du conteneur sache VÉRIFIER un jeton. S'il n'y en a pas,
+* la porte refuse de servir (et le dit fort) plutôt que d'accepter n'importe
+* quel porteur.
+*/
+const mcpAuthorizationSchema = z.strictObject({
+	/**
+	* Serveurs d'autorisation capables d'émettre un jeton pour cette porte.
+	*
+	* Vide (défaut) = rôle éteint. Non vide, la spécification MCP impose que le
+	* document de métadonnées les publie (« MUST include the
+	* `authorization_servers` field containing at least one authorization
+	* server ») : sans eux, un client apprendrait qu'un jeton est nécessaire
+	* sans jamais pouvoir en obtenir un.
+	*/
+	authorizationServers: z.array(z.string()).default([]).describe("Émetteurs de jetons acceptés (issuer OAuth) ; vide = aucune autorisation"),
+	/**
+	* URI canonique publique de cette porte — l'audience que les jetons doivent
+	* porter (RFC 8707).
+	*
+	* 🔴 **Elle s'écrit, elle ne se devine pas depuis l'en-tête `Host`.** Si
+	* l'URI publiée et l'audience attendue venaient toutes deux de la requête,
+	* un `Host` forgé obtiendrait un jeton d'audience arbitraire *et* passerait
+	* la vérification : la liaison d'audience, dont c'est l'unique raison
+	* d'être, ne protégerait plus rien.
+	*
+	* Ex. `https://mon-app.example/nodefony/mcp`.
+	*/
+	resource: z.string().default("").describe("URI publique de la porte MCP (audience attendue des jetons)"),
+	/**
+	* Autres adresses de CETTE MÊME porte, dont les jetons sont aussi acceptés.
+	*
+	* Le cas courant : l'application sert la porte en clair sur un port et en
+	* TLS sur un autre. Un jeton émis pour l'une était alors refusé sur l'autre
+	* — la liaison d'audience (RFC 8707) faisant son travail. Nommer la seconde
+	* adresse est la bonne réponse ; relâcher la liaison n'en serait pas une.
+	*
+	* 🔴 Ces valeurs s'ÉCRIVENT. Dérivées du `Host`, un en-tête forgé
+	* obtiendrait un jeton d'audience arbitraire ET passerait la vérification.
+	* Seule `resource` est publiée en RFC 9728 : le document n'admet qu'une
+	* valeur, et un client n'a besoin que d'une adresse.
+	*
+	* ⚠️ L'ÉMETTEUR doit servir ces audiences (`security.jwt.audiences`), sinon
+	* il refuse de les émettre — `invalid_target`, et à juste titre.
+	*/
+	additionalResources: z.array(z.string()).default([]).describe("Autres URI de la même porte dont les jetons sont acceptés (jamais dérivées du Host)"),
+	/** Nom lisible, affiché pendant le consentement. */
+	resourceName: z.string().optional().describe("Nom affiché au consentement"),
+	/** Page de documentation destinée à un humain. */
+	resourceDocumentation: z.string().optional().describe("URL de documentation de la ressource"),
+	/**
+	* Servir une requête SANS jeton comme anonyme, au lieu de la refuser.
+	*
+	* `false` (défaut) : sans jeton, `401` + `WWW-Authenticate` — c'est ce qui
+	* apprend au client qu'une autorisation existe et où l'obtenir.
+	* `true` : la porte reste ouverte aux outils publics, et les outils
+	* réservés restent retenus. Utile en développement ; c'est un choix qui
+	* s'écrit, jamais un comportement dont on hérite.
+	*/
+	anonymous: z.boolean().default(false).describe("Tolérer les requêtes sans jeton (outils publics seulement)")
+}).superRefine((value, ctx) => {
+	if (value.authorizationServers.length === 0) return;
+	if (value.resource.length === 0) {
+		ctx.addIssue({
+			code: "custom",
+			path: ["resource"],
+			message: "`mcp.authorization.resource` est requis dès qu'un serveur d'autorisation est déclaré : c'est l'URI publique de la porte, et l'audience que les jetons doivent porter (RFC 8707)."
+		});
+		return;
+	}
+	try {
+		canonicalResourceUri(value.resource);
+	} catch (error) {
+		ctx.addIssue({
+			code: "custom",
+			path: ["resource"],
+			message: error.message
+		});
+	}
+});
+/**
+* Réglages du serveur MCP — extrait en constante pour une raison mécanique.
+*
+* ⚠️ **Piège Zod 4** : un `.default({})` posé à plat sur un sous-objet NE
+* ré-applique PAS les défauts de ses champs. Le pattern du dépôt est donc
+* `sous.default(() => sous.parse({}))` — le callback force la ré-évaluation, et
+* une application qui n'écrit rien obtient bien les valeurs d'usine.
+*/
+const mcpSchema = z.strictObject({
+	/** Répond-on aux requêtes MCP ? Coupé, la route rend `404`. */
+	enabled: z.boolean().default(true).describe("Active l'endpoint MCP (POST /nodefony/mcp)"),
+	/**
+	* Origines acceptées quand l'en-tête `Origin` est PRÉSENT.
+	*
+	* ⭐ La subtilité qui fait toute la sécurité : un client MCP natif est un
+	* process, pas un navigateur — **il n'envoie pas d'`Origin`**. Une page web
+	* malveillante, elle, en envoie toujours un vers `localhost`. La règle est
+	* donc : *absent → on passe* ; *présent et hors de cette liste → `403`*.
+	* C'est ce que la spec exige (`transports/streamable-http` §Security :
+	* « Servers MUST validate the `Origin` header […] MUST respond with HTTP 403
+	* Forbidden »), et c'est ce qui ferme le DNS rebinding.
+	*
+	* Vide (défaut) = aucune origine de navigateur n'est admise.
+	*/
+	allowedOrigins: z.array(z.string()).default([]).describe("Origines navigateur admises ; vide = aucune"),
+	/**
+	* Accepter un appel dont l'adresse distante n'est pas locale.
+	*
+	* La spec recommande de n'écouter que sur la boucle locale ; le serveur de
+	* l'application, lui, écoute pour le développement. La garde est donc portée
+	* par la route : toute adresse non locale reçoit `403`.
+	*/
+	allowRemote: z.boolean().default(false).describe("Autorise les appels depuis une adresse non locale"),
+	/**
+	* Outils exposés — **allowlist**, et lecture seule.
+	*
+	* Tant qu'aucun outil n'écrit, le pire qu'obtienne un appelant illégitime est
+	* la description de l'application. Le jour où un générateur sera exposé, ce
+	* sera un ajout explicite ici — et cette ligne sera l'endroit où quelqu'un
+	* décide de donner à un agent le droit d'écrire des fichiers.
+	*/
+	tools: z.array(z.string()).default([...BUILTIN_MCP_TOOL_KEYS]).describe("Outils MCP activés (allowlist, lecture seule)"),
+	/**
+	* Rôle serveur de ressource OAuth 2.1 — **éteint par défaut**.
+	*
+	* Tant qu'aucun serveur d'autorisation n'est déclaré, la porte se comporte
+	* comme elle l'a toujours fait : anonyme, protégée par son seul périmètre
+	* (`policy: "dev"` + gardes `Origin`/localité).
+	*/
+	authorization: mcpAuthorizationSchema.default(() => mcpAuthorizationSchema.parse({})).describe("Serveur de ressource OAuth 2.1 (RFC 9728/6750/8707)")
+});
+const devkitConfigSchema = z.strictObject({
+	/** Interrupteur du module — l'app peut le charger sans l'activer. */
+	enabled: z.boolean().default(true).describe("Active les fonctionnalités du module devkit"),
+	/**
+	* Serveur MCP — la porte par laquelle un agent externe interroge l'app.
+	*
+	* ## Pourquoi aucune autorisation OAuth
+	*
+	* L'autorisation MCP est **optionnelle** (spec 2026-07-28, `authorization`
+	* §« Protocol Requirements »), et la faire en HTTP signifierait implémenter
+	* OAuth 2.1 en entier — serveur de ressource, métadonnées `RFC 9728`,
+	* découverte du serveur d'autorisation, PKCE, liaison d'audience. Un client
+	* MCP conforme ne sait de toute façon pas présenter un cookie de session
+	* Nodefony : il ne connaît que le jeton Bearer OAuth.
+	*
+	* Ce qui protège ici, c'est le PÉRIMÈTRE, et il est borné par construction :
+	* le module est `policy: "dev"`, donc **cette route n'existe pas en
+	* production** (le Kernel écarte le module au boot). Restent les deux gardes
+	* que la spec impose au transport lui-même, et qui visent le risque réel
+	* d'un serveur local — une page web ouverte dans le navigateur du
+	* développeur : {@link allowedOrigins} et {@link allowRemote}.
+	*
+	* ⚠️ **Écart assumé et énoncé** : la spec dit aussi « Servers SHOULD
+	* implement proper authentication for all connections ». Nous ne le faisons
+	* pas. Une capacité absente s'énonce plutôt qu'elle ne se masque.
+	*/
+	mcp: mcpSchema.default(() => mcpSchema.parse({})).describe("Serveur MCP pour agents externes (développement uniquement)")
+});
+/** Défauts matérialisés (passés au `super()` du Module). */
+const defaults = devkitConfigSchema.parse({});
+//#endregion
+export { defaults as default, devkitConfigSchema };

package/dist/nodefony/config/defineModuleConfig.js

@@ -0,0 +1,36 @@
+import { devkitConfigSchema } from "./config.js";
+import { parseModuleConfig } from "nodefony";
+import { z } from "zod";
+//#region nodefony/config/defineModuleConfig.ts
+/**
+* @nodefony/devkit — LE COMMENT : builder PUR de la config.
+*
+* ⭐ TL;DR : ce fichier VALIDE et GÈLE. Il ne porte AUCUNE valeur — les défauts
+* vivent dans le schéma de `./config.ts` (règle d'or ADR-0006). Pour changer un
+* défaut, c'est là-bas ; ici, on ne fait que le faire respecter.
+*
+* Le nom du FICHIER est le même dans tous les modules Nodefony
+* (`defineModuleConfig.ts`) ; la FONCTION, elle, est préfixée par le module —
+* deux modules importés côte à côte ne se marchent pas dessus.
+*
+* L'override env générique (`NF__DEVKIT__<CHEMIN>`) est appliqué par le core,
+* pas ici. Si le module a besoin d'une variable d'env DÉDIÉE, elle s'applique
+* APRÈS le parse, dans cette fonction, pour que le schéma reste pur.
+*
+* @param config - config brute venue de `use("@nodefony/devkit", { … })`.
+* @returns config validée et gelée.
+* @throws BootConfigurationError si un champ est invalide ou une clé inconnue
+*   (anomalies Zod agrégées) — le boot s'interrompt, en dev comme en prod.
+*/
+function defineDevkitConfig(config = {}) {
+	return Object.freeze(parseModuleConfig(devkitConfigSchema, config, "@nodefony/devkit"));
+}
+/**
+* JSON Schema de la config — Studio en dérive son formulaire d'édition
+* (libellés, types, défauts, descriptions), sans une ligne d'UI écrite à la main.
+*/
+function devkitConfigJsonSchema() {
+	return z.toJSONSchema(devkitConfigSchema);
+}
+//#endregion
+export { defineDevkitConfig, devkitConfigJsonSchema };

package/dist/nodefony/controllers/DevkitController.js

@@ -0,0 +1,60 @@
+import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js";
+import __decorate from "../../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js";
+import { Controller, controller, route } from "@nodefony/framework";
+//#region nodefony/controllers/DevkitController.ts
+/**
+* La carte de visite de l'application, servie en HTTP.
+*
+* ## Pourquoi cette route n'est pas `/`
+*
+* Ce qu'elle rend — modules chargés, chemins de documentation, commandes à
+* lancer — aide pendant le développement et n'est, en production, qu'une
+* divulgation de l'architecture. Elle vit donc dans un module `policy: "dev"`,
+* absent du boot en production, et sous le préfixe réservé `/nodefony` plutôt
+* qu'à la racine : `/` appartient à l'application, qui doit pouvoir y répondre
+* ce qu'elle assume devant ses utilisateurs.
+*
+* ## Pourquoi aucune garde `@IsGranted`
+*
+* Le module n'existe qu'en développement : c'est la `policy` qui le protège, pas
+* un rôle. Exiger un rôle imposerait `@nodefony/security` à toute application
+* qui installe le devkit — y compris celles qui n'ont pas de firewall du tout.
+* Une garde qui force une dépendance protège moins qu'elle ne coûte.
+*
+* **Mince par design** : la composition de la carte vit dans le service (et sa
+* construction dans une fonction pure) ; le controller ne fait que traduire en
+* HTTP.
+*/
+let DevkitController = class DevkitController extends Controller {
+	constructor(context) {
+		super("devkit", context);
+	}
+	/** Résout le service depuis le conteneur partagé (clé d'instance). */
+	#service() {
+		const svc = this.get("devkit");
+		if (!svc) throw new Error("DevkitService non enregistré");
+		return svc;
+	}
+	/**
+	* `GET /nodefony/devkit/api/card` — qui répond, et où aller ensuite.
+	*
+	* La réponse est recalculée à chaque appel : elle décrit l'application TELLE
+	* QU'ELLE EST, pas telle qu'elle était au démarrage.
+	*/
+	async card() {
+		return this.renderJson(this.#service().getCard());
+	}
+};
+__decorate([
+	route("devkit-card", {
+		path: "/card",
+		method: "GET"
+	}),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", []),
+	__decorateMetadata("design:returntype", Promise)
+], DevkitController.prototype, "card", null);
+DevkitController = __decorate([controller("/nodefony/devkit/api"), __decorateMetadata("design:paramtypes", [Object])], DevkitController);
+var DevkitController_default = DevkitController;
+//#endregion
+export { DevkitController_default as default };

package/dist/nodefony/controllers/McpController.js

@@ -0,0 +1,223 @@
+import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js";
+import __decorate from "../../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js";
+import __decorateParam from "../../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateParam.js";
+import { ACCESS_TOKEN_VERIFIER, JsonRpcError, Nodefony, authorizeProtectedResource, checkMcpAccess, collectMcpTools, handleMcpMessage, jsonRpcFailure, mcpCallerRoles, protectedResourceMetadataUrl, readBearerHeader } from "nodefony";
+import { Body, Controller, Headers, controller, route } from "@nodefony/framework";
+//#region nodefony/controllers/McpController.ts
+/**
+* Serveur **Model Context Protocol** de l'application — la porte par laquelle
+* un agent externe l'interroge.
+*
+* ## Pourquoi une route, et pas un process
+*
+* La révision `2026-07-28` du transport « Streamable HTTP » a supprimé les
+* sessions de niveau protocole et le flux `GET` : il ne reste qu'**un endpoint
+* qui accepte `POST`**, chaque message étant autonome. Un serveur MCP n'a donc
+* plus besoin d'être un process séparé lancé par le client — c'est une route de
+* l'application, qui tourne déjà. Conséquence directe en développement : quand
+* le superviseur relance le serveur sur une sauvegarde, rien n'est perdu, et la
+* réponse suivante vient du code qui vient d'être rechargé. Aucun cache à
+* invalider — la fraîcheur est une propriété du protocole.
+*
+* ## Ce qui protège cette route
+*
+* **Par défaut, le périmètre — et lui seul.** Ce module est `policy: "dev"`,
+* donc cette route n'existe pas en production ; restent les deux gardes que la
+* spec impose au transport, portées par {@link checkMcpAccess} : l'en-tête
+* `Origin` et la localité de l'appelant. Elles visent le seul vecteur réel
+* contre un serveur local — une page web ouverte dans le navigateur du
+* développeur.
+*
+* **Dès qu'un serveur d'autorisation est déclaré** (`mcp.authorization`), la
+* porte prend son rôle de *resource server* OAuth 2.1 : elle publie ses
+* métadonnées (RFC 9728, publiées par `@nodefony/framework` depuis
+* `DevkitService.publishedProtectedResources()`), valide le porteur
+* présenté, et refuse en citant `resource_metadata` — l'en-tête qui apprend au
+* client où obtenir un jeton (RFC 6750). L'audience attendue est l'URI
+* canonique de la porte (RFC 8707) : c'est ce qui empêche un jeton émis pour un
+* autre service d'être rejoué ici.
+*
+* ⚠️ **Le serveur d'AUTORISATION n'est pas de notre ressort**, et ne l'a jamais
+* été : la spec le place « beyond the scope […] or a separate entity ». Avoir
+* écrit l'inverse a servi d'excuse à ne rien faire pendant tout un cycle.
+*
+* 🔴 **La vérification du jeton est déléguée, et son absence est fatale.** Ce
+* module ne peut pas dépendre de `@nodefony/security` (il disparaît en
+* production, pas elle) : il cherche un `accessTokenVerifier` dans le conteneur
+* — nom GÉNÉRIQUE, car le contrat prend l'audience en paramètre : un seul
+* vérificateur sert toutes les ressources protégées d'une application, celle-ci
+* étant seulement la première.
+* Rôle déclaré + aucun vérificateur = `503` et journal `CRITIC`, jamais une
+* porte qui laisse passer les porteurs sans les lire.
+*
+* **Mince par design** : tout le protocole vit AU CŒUR (`nodefony`, en fonctions
+* pures) ; ce controller ne fait que traduire HTTP ↔ JSON-RPC et fournir au
+* collecteur ce que lui seul connaît — le service du module, le broker
+* d'administration, la racine du projet. C'est ce qui permet à un autre module
+* d'ouvrir la même porte ailleurs (en production, sous authentification) sans
+* réécrire une ligne de protocole.
+*/
+let McpController = class McpController extends Controller {
+	constructor(context) {
+		super("devkit-mcp", context);
+	}
+	/** Résout le service du module depuis le conteneur partagé. */
+	#service() {
+		const svc = this.get("devkit");
+		if (!svc) throw new Error("DevkitService non enregistré");
+		return svc;
+	}
+	/**
+	* Ce qui, dans cette application, sait valider un jeton — ou rien.
+	*
+	* Résolu par NOM dans le conteneur, et non importé : ce module est
+	* `policy: "dev"` et ne peut pas dépendre de `@nodefony/security`, qui porte
+	* la cryptographie. Une application peut donc fournir sa propre
+	* implémentation du contrat sous ce nom, sans que cette porte en sache quoi
+	* que ce soit.
+	*
+	* L'absence est un cas NORMAL (rôle éteint) ou une faute de configuration
+	* (rôle allumé) — c'est l'appelant qui tranche, pas cette méthode.
+	*/
+	#tokenVerifier() {
+		return this.get(ACCESS_TOKEN_VERIFIER) ?? void 0;
+	}
+	/**
+	* 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 —
+	* une session lancée depuis un terminal où la variable n'était pas posée.
+	*
+	* @param header - la valeur brute de l'en-tête `Authorization`
+	* @returns vrai si ce qui est présenté est resté un gabarit
+	*/
+	#isUnsubstitutedTemplate(header) {
+		const read = readBearerHeader(header);
+		return read.kind === "token" && read.token.startsWith("${") && read.token.endsWith("}");
+	}
+	/**
+	* `POST /nodefony/mcp` — un message JSON-RPC entre, une réponse sort.
+	*
+	* Les trois statuts que rend cette route sont ceux que la spec impose, et pas
+	* un de plus : `202` sans corps pour une notification acceptée, `403` pour un
+	* appel dont l'origine ou l'adresse est refusée, `404` pour une méthode
+	* inconnue (afin de la distinguer d'un serveur qui n'hébergerait pas
+	* d'endpoint MCP du tout).
+	*/
+	async mcp(body, origin, protocolVersion, authorization) {
+		const settings = this.#service().mcpSettings();
+		if (!settings.enabled) return this.renderJson({ error: "MCP désactivé" }, 404);
+		const verdict = checkMcpAccess({
+			origin,
+			remoteAddress: this.context?.remoteAddress ?? void 0
+		}, {
+			allowedOrigins: settings.allowedOrigins,
+			allowRemote: settings.allowRemote
+		});
+		if (!verdict.allowed) {
+			this.log(`MCP refusé — ${verdict.why}`, "WARNING");
+			return this.renderJson(jsonRpcFailure(null, JsonRpcError.INVALID_REQUEST, "origine refusée"), 403);
+		}
+		if (body === null || typeof body !== "object") return this.renderJson(jsonRpcFailure(null, JsonRpcError.PARSE_ERROR, "corps attendu : un message JSON-RPC"), 400);
+		const authz = settings.authorization;
+		const gateProtected = settings.authorization.authorizationServers.length > 0;
+		let caller = {
+			authenticated: false,
+			scopes: [],
+			roles: mcpCallerRoles({
+				protected: gateProtected,
+				authenticated: false,
+				scopes: []
+			})
+		};
+		if (gateProtected) {
+			const authVerdict = await authorizeProtectedResource(authorization, {
+				resource: authz.resource,
+				acceptedResources: authz.additionalResources,
+				metadataUrl: protectedResourceMetadataUrl(authz.resource),
+				scopes: this.#service().declaredMcpScopes(),
+				allowAnonymous: authz.anonymous
+			}, this.#tokenVerifier());
+			switch (authVerdict.outcome) {
+				case "unverifiable":
+					this.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 — `mcp.authorization` déclare un serveur d'autorisation, mais aucun service du conteneur ne sait vérifier un jeton (`accessTokenVerifier`). La porte refuse de servir : accepter les porteurs sans les valider serait pire que rester anonyme.", "CRITIC");
+					return this.renderJson(jsonRpcFailure(null, JsonRpcError.INTERNAL_ERROR, "autorisation indisponible"), 503);
+				case "challenge":
+					if (this.#isUnsubstitutedTemplate(authorization)) this.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: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 this.renderJson(jsonRpcFailure(null, JsonRpcError.INVALID_REQUEST, "autorisation requise"), authVerdict.status, { "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
+						})
+					};
+					break;
+				case "anonymous":
+					if (authVerdict.rejected) this.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:token`) pour les retrouver.", "WARNING");
+					caller = {
+						authenticated: false,
+						scopes: [],
+						roles: mcpCallerRoles({
+							protected: true,
+							authenticated: false,
+							scopes: []
+						})
+					};
+			}
+		}
+		const kernel = Nodefony.getKernel();
+		let withheldCount = 0;
+		const tools = collectMcpTools({
+			builtins: settings.tools,
+			modules: kernel?.modules,
+			caller,
+			onSkip: (why) => this.log(`MCP — ${why}`, "WARNING"),
+			onWithheld: (name, why) => {
+				withheldCount += 1;
+				this.log(`MCP — outil « ${name} » retenu : ${why}`, "DEBUG");
+			},
+			deps: this.#service().mcpToolDeps()
+		});
+		const reply = await handleMcpMessage(body, {
+			tools,
+			caller,
+			withheldCount,
+			serverInfo: {
+				name: kernel?.projectName ?? "nodefony",
+				version: Nodefony.version
+			}
+		}, { protocolVersion });
+		if (reply.body === null) return this.renderResponse("", void 0, reply.status);
+		return this.renderJson(reply.body, reply.status);
+	}
+};
+__decorate([
+	route("devkit-mcp", {
+		path: "/mcp",
+		method: "POST"
+	}),
+	__decorateParam(0, Body()),
+	__decorateParam(1, Headers("origin")),
+	__decorateParam(2, Headers("mcp-protocol-version")),
+	__decorateParam(3, Headers("authorization")),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", [
+		Object,
+		String,
+		String,
+		String
+	]),
+	__decorateMetadata("design:returntype", Promise)
+], McpController.prototype, "mcp", null);
+McpController = __decorate([controller("/nodefony"), __decorateMetadata("design:paramtypes", [Object])], McpController);
+var McpController_default = McpController;
+//#endregion
+export { McpController_default as default };

package/dist/nodefony/controllers/OAuthMetadataController.js

@@ -0,0 +1,89 @@
+import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.143.0/helpers/esm/decorateMetadata.js";
+import __decorate from "../../_virtual/_@oxc-project_runtime@0.143.0/helpers/esm/decorate.js";
+import { MCP_ENDPOINT_PATH, buildProtectedResourceMetadata, protectedResourceMetadataPath } from "nodefony";
+import { Controller, controller, route } from "@nodefony/framework";
+//#region nodefony/controllers/OAuthMetadataController.ts
+/**
+* Chemin bien connu où se publient les métadonnées de la porte MCP.
+*
+* **Dérivé, jamais recopié** : il se compose du chemin de l'endpoint par la
+* règle d'insertion de la RFC 9728 §3.1. Le littéral qu'on serait tenté
+* d'écrire ici deviendrait faux le jour où la porte déménage — et l'erreur
+* serait parfaitement silencieuse : un client sonde ce chemin, reçoit `404`,
+* et conclut que l'application n'a pas d'autorisation.
+*/
+const METADATA_PATH = protectedResourceMetadataPath(MCP_ENDPOINT_PATH);
+/**
+* Métadonnées OAuth 2.1 de la porte MCP — **le seul moyen normalisé** pour
+* qu'un agent apprenne où obtenir un jeton.
+*
+* ## Pourquoi un controller séparé
+*
+* Trois raisons, et aucune n'est esthétique. Le chemin vit **hors** du préfixe
+* `/nodefony` (la RFC impose `/.well-known/…` juste après l'hôte). Le document
+* est **public par conception** — un client doit pouvoir le lire avant d'avoir
+* le moindre jeton, donc il ne porte ni garde d'origine ni exigence de
+* localité, contrairement à la porte elle-même. Et il répond en `GET`, quand la
+* porte n'accepte que `POST`.
+*
+* ## Ce que publier coûte, et ce que ne rien publier coûte
+*
+* Le document ne révèle rien de sensible : l'émetteur des jetons, les scopes
+* compris, un nom. En revanche, ne PAS le publier a un coût mesuré — un client
+* qui ne le trouve pas suppose que le serveur d'autorisation est le serveur
+* lui-même, et part sonder des chemins qui n'existent pas. C'est exactement ce
+* qui a produit le bruit OAuth observé sur cette porte.
+*
+* 🔴 **Rôle éteint = `404`, jamais un document vide.** Un document sans serveur
+* d'autorisation apprendrait au client qu'un jeton est nécessaire sans jamais
+* lui dire où le demander : la spécification MCP l'interdit d'ailleurs
+* explicitement (« MUST include […] at least one authorization server »).
+*/
+let OAuthMetadataController = class OAuthMetadataController extends Controller {
+	constructor(context) {
+		super("devkit-oauth-metadata", context);
+	}
+	/** Résout le service du module depuis le conteneur partagé. */
+	#service() {
+		const svc = this.get("devkit");
+		if (!svc) throw new Error("DevkitService non enregistré");
+		return svc;
+	}
+	/**
+	* `GET /.well-known/oauth-protected-resource/nodefony/mcp` — RFC 9728 §3.
+	*
+	* @returns le document JSON, ou `404` si cette porte n'est pas protégée
+	*/
+	async metadata() {
+		const settings = this.#service().mcpSettings();
+		const authz = settings.authorization;
+		if (!settings.enabled || authz.authorizationServers.length === 0) return this.renderJson({ error: "not_found" }, 404);
+		let document;
+		try {
+			document = buildProtectedResourceMetadata({
+				resource: authz.resource,
+				authorizationServers: authz.authorizationServers,
+				scopesSupported: authz.scopesSupported,
+				resourceName: authz.resourceName,
+				resourceDocumentation: authz.resourceDocumentation
+			});
+		} catch (error) {
+			this.log(`MCP — métadonnées impubliables : ${error.message}`, "CRITIC");
+			return this.renderJson({ error: "server_error" }, 500);
+		}
+		return this.renderJson(document, 200, { "Cache-Control": "public, max-age=3600" });
+	}
+};
+__decorate([
+	route("devkit-mcp-protected-resource", {
+		path: METADATA_PATH,
+		method: "GET"
+	}),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", []),
+	__decorateMetadata("design:returntype", Promise)
+], OAuthMetadataController.prototype, "metadata", null);
+OAuthMetadataController = __decorate([controller(""), __decorateMetadata("design:paramtypes", [Object])], OAuthMetadataController);
+var OAuthMetadataController_default = OAuthMetadataController;
+//#endregion
+export { OAuthMetadataController_default as default };

package/dist/nodefony/interfaces/IDevkitService.js

@@ -0,0 +1 @@
+export {};

package/dist/nodefony/interfaces/index.js

@@ -0,0 +1 @@
+export {};