@nodefony/framework 10.0.0-alpha.1

package/dist/nodefony/controller/BenchController.js

@@ -0,0 +1,132 @@
+import Controller from "../src/Controller.js";
+import router_default from "../service/router.js";
+//#region nodefony/controller/BenchController.ts
+/**
+* Corps servi par la cible de banc — **gelé et partagé** : ce qu'on chronomètre
+* est le pipeline, pas la construction d'un objet. Le figer évite qu'une
+* allocation par requête ne s'ajoute au coût mesuré.
+*
+* Sa forme reprend celle du banc comparatif inter-frameworks
+* (`.claude/skills/nodefony-load-test/bench-frameworks/payload.mjs`), pour que
+* Nodefony, bare, Express et Fastify sérialisent **exactement le même corps**.
+* Comparer deux corps différents, c'est comparer deux travaux différents.
+*/
+const BENCH_PAYLOAD = Object.freeze({
+	byContext: {},
+	lastHookRequestId: null,
+	hookUser: null,
+	lateHookRequestId: null,
+	wsHookRequestId: null,
+	wsHookHandshakeId: null,
+	wsHookFireCount: 0,
+	hookCount: 0
+});
+let mounted = false;
+/**
+* Cible de mesure du **pipeline applicatif** — un controller ordinaire qui rend un
+* corps figé, et rien d'autre.
+*
+* **Pourquoi un controller et pas un endpoint du data plane admin** : une route
+* `/nodefony/<ns>/api/*` traverse, en plus du pipeline, la résolution de zone du
+* firewall, un authenticator et le broker d'administration. La mesurer et la
+* comparer à un handler Express nu revient à chronométrer deux choses
+* différentes — et à imputer au framework le coût de son étage d'administration.
+* Ce controller emprunte le chemin d'une route applicative normale : routing,
+* contexte, sérialisation, réponse.
+*
+* **Chemin hors aire admin** : `/nodefony/kernel/bench` (deux segments, sans
+* `/api/`) échappe au pattern `^/nodefony/[^/]+/api(/|$)` de la zone
+* `nodefony-admin`, donc aucune zone ne s'y applique — pas de 401 à mesurer, et
+* pas besoin d'ouvrir une zone dédiée. Il évite aussi le repli SPA mono-segment
+* de Studio (`/nodefony/{page}`).
+*
+* **N'existe que sous `NF_BENCH_ROUTE=1`** : zéro surface en production par
+* défaut. C'est un drapeau d'OUTILLAGE (banc), pas une option applicative — d'où
+* une variable d'environnement plutôt qu'une clé de configuration.
+*/
+var BenchController = class extends Controller {
+	constructor(context) {
+		super("BenchController", context);
+	}
+	/** Rend le corps figé. Aucune lecture de kernel, aucun I/O, aucune allocation. */
+	index() {
+		return this.renderJson(BENCH_PAYLOAD);
+	}
+	/**
+	* Dump de la sonde perf in-situ du http-kernel (`NF_PERF_PROBE=1`) : µs
+	* moyens par requête des postes enterScope / new HttpContext / leaveScope.
+	* Vit ICI (et pas dans `@nodefony/test`, `policy:"dev"`) parce que le décor
+	* de mesure est le mono `production` du banc — où le module test n'existe
+	* pas. `?reset=1` remet les compteurs à zéro (à faire après le warmup, pour
+	* ne pas diluer la mesure avec le code froid).
+	*/
+	probe() {
+		const probe = globalThis.__nfPerfProbe;
+		if (!probe) return this.renderJson({ enabled: false });
+		const url = this.context?.request?.url;
+		const reset = url instanceof URL ? url.searchParams.get("reset") === "1" : false;
+		const n = probe.count || 1;
+		const num = (v) => typeof v === "number" ? v : 0;
+		const out = {
+			enabled: true,
+			count: probe.count,
+			avgUs: {
+				enterScope: probe.enterScopeNs / n / 1e3,
+				ctx: probe.ctxNs / n / 1e3,
+				leaveScope: probe.leaveScopeNs / n / 1e3,
+				total: (probe.enterScopeNs + probe.ctxNs + probe.leaveScopeNs) / n / 1e3
+			},
+			ctxSlicesUs: {
+				svc: probe.svcNs / n / 1e3,
+				ctxTail: (probe.ctxBaseNs - probe.svcNs) / n / 1e3,
+				upload: (probe.uploadNs - probe.ctxBaseNs) / n / 1e3,
+				reqRes: (probe.reqResNs - probe.uploadNs) / n / 1e3,
+				httpTail: (probe.ctxNs - probe.reqResNs) / n / 1e3
+			},
+			svcSlicesUs: {
+				entry: num(probe.svcStartNs) / n / 1e3,
+				opts: (num(probe.svcOptsNs) - num(probe.svcStartNs)) / n / 1e3,
+				lookups: (num(probe.svcLookupsNs) - num(probe.svcOptsNs)) / n / 1e3,
+				event: (num(probe.svcEventNs) - num(probe.svcLookupsNs)) / n / 1e3,
+				tail: (probe.svcNs - num(probe.svcEventNs)) / n / 1e3
+			},
+			reqSlicesUs: {
+				entry: (num(probe.reqStartNs) - probe.uploadNs) / n / 1e3,
+				inits: (num(probe.reqProxyNs) - num(probe.reqStartNs)) / n / 1e3,
+				url: (num(probe.reqUrlNs) - num(probe.reqProxyNs)) / n / 1e3,
+				query: (num(probe.reqQueryNs) - num(probe.reqUrlNs)) / n / 1e3,
+				meta: (num(probe.reqMetaNs) - num(probe.reqQueryNs)) / n / 1e3,
+				accept: (num(probe.reqAcceptNs) - num(probe.reqMetaNs)) / n / 1e3,
+				resp: (probe.reqResNs - num(probe.reqAcceptNs)) / n / 1e3
+			}
+		};
+		if (reset) for (const k of Object.keys(probe)) {
+			if (k === "t0") continue;
+			if (typeof probe[k] === "number") probe[k] = 0;
+		}
+		return this.renderJson(out);
+	}
+};
+/**
+* Monte la route de banc — appelée par le module framework, uniquement si
+* `NF_BENCH_ROUTE=1`.
+*/
+function mountBenchRoutes(frameworkModule) {
+	if (mounted) return;
+	router_default.createRoute("framework.bench", {
+		path: "/nodefony/kernel/bench",
+		constructor: BenchController,
+		classMethod: "index",
+		requirements: { methods: ["GET"] }
+	});
+	router_default.createRoute("framework.bench.probe", {
+		path: "/nodefony/kernel/bench/probe",
+		constructor: BenchController,
+		classMethod: "probe",
+		requirements: { methods: ["GET"] }
+	});
+	if (!Object.prototype.hasOwnProperty.call(BenchController.prototype, "module")) router_default.setController(BenchController, frameworkModule);
+	mounted = true;
+}
+//#endregion
+export { BenchController as default, mountBenchRoutes };

package/dist/nodefony/controller/IssuerMetadataController.js

@@ -0,0 +1,148 @@
+import Controller from "../src/Controller.js";
+import router_default from "../service/router.js";
+import { askedAuthority, onDeclaredAuthority } from "./oauthAuthority.js";
+import { JWKS_PATH, authorizationServerMetadataPath, buildAuthorizationServerMetadata } from "nodefony";
+//#region nodefony/controller/IssuerMetadataController.ts
+let mounted = false;
+/**
+* Les deux documents qui rendent une application Nodefony **découvrable** comme
+* émetteur de jetons — RFC 8414 :
+*
+*  - `GET /.well-known/oauth-authorization-server` — métadonnées d'émetteur
+*    (`issuer`, `jwks_uri`) ; c'est le seul document qu'un tiers sait trouver,
+*    puisqu'il ne le lit pas mais le CONSTRUIT depuis l'identifiant d'émetteur
+*    par insertion de chemin (§3.1).
+*  - `GET /.well-known/jwks.json` — le jeu de clés publiques lui-même.
+*
+* ## Pourquoi ces routes existent
+*
+* Sans elles, `getPublicJWKS()` n'a qu'un usage interne : Nodefony vérifie ses
+* propres jetons en mémoire. Un tiers — une autre application Nodefony, un
+* agent, un service — ne peut donc PAS valider une signature émise ici, même en
+* connaissant l'URL des clés : il n'y en a pas. C'est le symétrique exact du
+* rôle serveur de ressource : là, on refusait en disant où aller ; ici, on
+* permet à quelqu'un d'autre de vérifier ce qu'on a signé.
+*
+* ## Ce qui les monte, et ce qui les retient
+*
+* Montées par le module framework UNIQUEMENT si `tokenService.publishedIssuer()`
+* rend une valeur — c'est-à-dire si le JWT est actif, `security.jwt.jwks` vrai,
+* et l'émetteur écrit sous forme d'URL https. Sinon les routes **n'existent
+* pas** (`404`, zéro surface) : un document creux apprendrait à un client qu'il
+* y a quelque chose à découvrir sans lui donner de quoi le faire.
+*
+* Le montage ne suffit pas : servir encore exige que la requête entre par
+* **l'autorité de l'émetteur** ({@link IssuerMetadataController.metadata}). Un
+* serveur écoute plusieurs adresses ; l'émetteur n'en désigne qu'une.
+*
+* `bypassFirewall: true` : ces documents sont publics par construction. Un JWKS
+* derrière une authentification serait un non-sens — il sert précisément à
+* vérifier les jetons de ceux qui ne sont pas encore authentifiés. Ils ne
+* révèlent rien de secret : des clés PUBLIQUES et un identifiant, jamais `d`.
+*
+* @remarks Le chemin des métadonnées est **dérivé** de l'émetteur
+* (`authorizationServerMetadataPath`) et non écrit en dur : un émetteur porteur
+* d'un chemin se publie SOUS ce chemin (RFC 8414 §3.1), et c'est la même
+* fonction qui sert au lecteur, dans `@nodefony/security`.
+*/
+var IssuerMetadataController = class extends Controller {
+	constructor(context) {
+		super("IssuerMetadataController", context);
+	}
+	/** Résout le service d'émission — absent = capacité éteinte. */
+	#publisher() {
+		return this.get("tokenService") ?? null;
+	}
+	/**
+	* 🔴 Ces documents ne sont servis QUE sur l'autorité de l'émetteur.
+	*
+	* Un serveur écoute presque toujours plusieurs autorités — deux ports en
+	* développement, plusieurs hôtes virtuels en production. Servir le document
+	* sur toutes revient à répondre « le serveur d'autorisation, c'est ici » à un
+	* client qui interroge une adresse dont l'émetteur ne se réclame pas : il
+	* DOIT alors rejeter le document (RFC 8414 §3.3 exige l'égalité stricte de
+	* `issuer`), et un client réel s'arrête là — il ne cherche pas ailleurs.
+	* Vécu : un client MCP sondant `http://localhost:5151` recevait le document
+	* de `https://localhost:5152` et déclarait la connexion en échec, alors que
+	* `404` l'aurait simplement fait continuer sans authentification.
+	*
+	* La comparaison porte sur l'**autorité demandée** (hôte + port, tels que le
+	* client les a écrits), jamais sur le schéma : derrière un relais qui termine
+	* TLS, le processus voit `http` pour une requête que le client a faite en
+	* `https`, et refuser là-dessus fermerait le document en production. Le port
+	* par défaut est normalisé par `URL` — `app.example:443` et `app.example`
+	* désignent le même serveur et doivent se valoir.
+	*
+	* @param issuer - émetteur canonique publié
+	* @returns `true` si la requête entre par l'autorité de l'émetteur
+	*/
+	#onIssuerAuthority(issuer) {
+		return onDeclaredAuthority(askedAuthority(this.request?.headers), issuer);
+	}
+	/**
+	* `GET /.well-known/oauth-authorization-server` — métadonnées d'émetteur.
+	*
+	* @returns le document RFC 8414, ou `404` si la publication a été coupée
+	*          après le montage des routes
+	*/
+	async metadata() {
+		const issuer = this.#publisher()?.publishedIssuer() ?? null;
+		if (!issuer || !this.#onIssuerAuthority(issuer)) return this.renderJson({ error: "not_found" }, 404);
+		let document;
+		try {
+			document = buildAuthorizationServerMetadata({ issuer });
+		} catch (error) {
+			this.log(`métadonnées d'émetteur impubliables : ${error.message}`, "CRITIC");
+			return this.renderJson({ error: "server_error" }, 500);
+		}
+		return this.renderJson(document, 200, { "Cache-Control": "public, max-age=3600" });
+	}
+	/**
+	* `GET /.well-known/jwks.json` — clés publiques de signature.
+	*
+	* @returns le JWK Set (paramètres publics seuls)
+	*/
+	async jwks() {
+		const publisher = this.#publisher();
+		const issuer = publisher?.publishedIssuer() ?? null;
+		if (!publisher || !issuer || !this.#onIssuerAuthority(issuer)) return this.renderJson({ error: "not_found" }, 404);
+		let keys;
+		try {
+			keys = await publisher.getPublicJWKS();
+		} catch (error) {
+			this.log(`JWKS illisible : ${error.message}`, "CRITIC");
+			return this.renderJson({ error: "server_error" }, 500);
+		}
+		return this.renderJson(keys, 200, { "Cache-Control": "public, max-age=300" });
+	}
+};
+/**
+* Monte les deux documents d'émetteur — appelé par le module framework à
+* `onKernelReady`, seulement si `tokenService.publishedIssuer()` répond.
+*
+* @param frameworkModule - module porteur des routes
+* @param issuer - émetteur canonique, qui DÉTERMINE le chemin des métadonnées
+*/
+function mountIssuerMetadataRoutes(frameworkModule, issuer) {
+	if (mounted) return;
+	const routes = [[
+		"security.issuer.metadata",
+		authorizationServerMetadataPath(issuer),
+		"metadata"
+	], [
+		"security.issuer.jwks",
+		JWKS_PATH,
+		"jwks"
+	]];
+	for (const [name, path, classMethod] of routes) router_default.createRoute(name, {
+		path,
+		constructor: IssuerMetadataController,
+		classMethod,
+		requirements: { methods: ["GET"] },
+		bypassFirewall: true
+	});
+	if (!Object.prototype.hasOwnProperty.call(IssuerMetadataController.prototype, "module")) router_default.setController(IssuerMetadataController, frameworkModule);
+	mounted = true;
+}
+//#endregion
+export { IssuerMetadataController as default, mountIssuerMetadataRoutes };

package/dist/nodefony/controller/OAuth2Controller.js

@@ -0,0 +1,133 @@
+import Controller from "../src/Controller.js";
+import router_default from "../service/router.js";
+//#region nodefony/controller/OAuth2Controller.ts
+const STATE_KEY = "oauth2:state";
+const VERIFIER_KEY = "oauth2:verifier";
+const PROVIDER_KEY = "oauth2:provider";
+let mounted = false;
+/**
+* Endpoints HTTP du **social login OAuth 2.0** (P6 J9) — adaptateurs MINCES
+* au-dessus du service `oauth2` (`@nodefony/security`) :
+*
+*  - `GET /nodefony/security/api/oauth2/{provider}/authorize` — démarre le flux :
+*    pose `state`+`code_verifier` en session (anonyme), redirige (302) vers le
+*    fournisseur.
+*  - `GET /nodefony/security/api/oauth2/{provider}/callback` — valide le `state`
+*    (anti-CSRF), échange le `code`, provisionne le Shadow User et OUVRE la
+*    session BFF (302 vers `successRedirect`).
+*
+* Montés UNIQUEMENT si le service `oauth2` existe (social login activé) — 404
+* sinon, zéro surface.
+*
+* @remarks `bypassFirewall` : ces routes SONT (ou précèdent) le mécanisme d'auth
+* (l'utilisateur est anonyme pendant tout l'aller-retour). Le firewall, sur l'aire
+* data plane, déclencherait un deadlock identique au login BFF / WebAuthn login.
+* La session anonyme ne porte que `state`/`verifier` ; `establishSessionFor`
+* régénère l'ID (anti-fixation) à la promotion.
+*/
+var OAuth2Controller = class extends Controller {
+	constructor(context) {
+		super("OAuth2Controller", context);
+	}
+	/**
+	* Liste PUBLIQUE des fournisseurs activés (configurés ET connus du registre).
+	* Consommé par l'UI de login pour n'afficher QUE les boutons opérationnels —
+	* jamais de bouton mort. Aucun secret n'est exposé (uniquement les noms).
+	*/
+	providers() {
+		const svc = this.#service();
+		return this.renderJson({ providers: svc ? svc.listProviders() : [] });
+	}
+	/** Démarre le flux : URL d'autorisation + état anti-replay en session, 302. */
+	async authorize(provider) {
+		const svc = this.#service();
+		const flow = this.#flow();
+		if (!svc || !flow) return this.renderJson({ error: "OAuth unavailable" }, 503);
+		if (!svc.listProviders().includes(provider)) return this.renderJson({ error: "Unknown provider" }, 404);
+		const auth = await svc.createAuthorization(provider);
+		const session = await flow.ensureSession(this.context);
+		if (!session) return this.renderJson({ error: "Session unavailable" }, 503);
+		session.set(STATE_KEY, auth.state);
+		session.set(VERIFIER_KEY, auth.codeVerifier);
+		session.set(PROVIDER_KEY, provider);
+		await session.save();
+		return this.redirect(auth.url, 302);
+	}
+	/** Valide `state`, échange le `code`, ouvre la session BFF (302). */
+	async callback(provider) {
+		const svc = this.#service();
+		const flow = this.#flow();
+		if (!svc || !flow) return this.renderJson({ error: "OAuth unavailable" }, 503);
+		const { success, failure } = svc.getRedirects(provider);
+		const session = this.context.session;
+		const expectedState = session?.get(STATE_KEY);
+		const storedVerifier = session?.get(VERIFIER_KEY);
+		const expectedProvider = session?.get(PROVIDER_KEY);
+		session?.set(STATE_KEY, null);
+		session?.set(VERIFIER_KEY, null);
+		session?.set(PROVIDER_KEY, null);
+		await session?.save();
+		const code = this.#queryString("code");
+		const returnedState = this.#queryString("state");
+		const returnedIss = this.#queryString("iss");
+		if (code === null || returnedState === null || typeof expectedState !== "string" || returnedState !== expectedState || expectedProvider !== provider) return this.redirect(failure, 302);
+		try {
+			const { identifier } = await svc.exchangeAndProvision(provider, code, typeof storedVerifier === "string" ? storedVerifier : null, returnedIss);
+			await flow.establishSessionFor(this.context, identifier, "oauth");
+			return this.redirect(success, 302);
+		} catch {
+			return this.redirect(failure, 302);
+		}
+	}
+	#service() {
+		const svc = this.get("oauth2");
+		return svc && svc.isEnabled() ? svc : null;
+	}
+	#flow() {
+		return this.get("authFlow") ?? null;
+	}
+	/** Lit un paramètre de query string (GET), ou `null`. */
+	#queryString(key) {
+		const v = (this.queryGet ?? {})[key];
+		return typeof v === "string" && v.length > 0 ? v : null;
+	}
+};
+/**
+* Monte les routes du social login OAuth — appelé par le module framework à
+* `onKernelReady`, seulement si le service `oauth2` est présent.
+*/
+function mountOAuth2Routes(frameworkModule) {
+	if (mounted) return;
+	const base = "/nodefony/security/api/oauth2";
+	const routes = [
+		[
+			"security.oauth2.providers",
+			`${base}/providers`,
+			"GET",
+			"providers"
+		],
+		[
+			"security.oauth2.authorize",
+			`${base}/{provider}/authorize`,
+			"GET",
+			"authorize"
+		],
+		[
+			"security.oauth2.callback",
+			`${base}/{provider}/callback`,
+			"GET",
+			"callback"
+		]
+	];
+	for (const [name, path, method, classMethod] of routes) router_default.createRoute(name, {
+		path,
+		constructor: OAuth2Controller,
+		classMethod,
+		requirements: { methods: [method] },
+		bypassFirewall: true
+	});
+	if (!Object.prototype.hasOwnProperty.call(OAuth2Controller.prototype, "module")) router_default.setController(OAuth2Controller, frameworkModule);
+	mounted = true;
+}
+//#endregion
+export { OAuth2Controller as default, mountOAuth2Routes };

package/dist/nodefony/controller/ProtectedResourceMetadataController.js

@@ -0,0 +1,221 @@
+import Controller from "../src/Controller.js";
+import router_default from "../service/router.js";
+import { askedAuthority, onDeclaredAuthority } from "./oauthAuthority.js";
+import { buildProtectedResourceMetadata, canonicalResourceUri, protectedResourceMetadataPath } from "nodefony";
+//#region nodefony/controller/ProtectedResourceMetadataController.ts
+let mounted = false;
+/**
+* Ce qui a été PUBLIÉ au montage — la même liste qui a décidé des chemins.
+*
+* Le controller la relit plutôt que de réinterroger les services à chaque
+* requête, pour deux raisons. La première est la justesse : les routes sont
+* montées une fois, à partir de cette liste ; servir un document composé
+* d'autre chose ferait répondre une ressource à un chemin dérivé d'une autre.
+* La seconde est le coût : balayer le conteneur sur le chemin de la requête
+* pour un document qui ne change qu'au redéploiement est exactement la dépense
+* que la règle de perf proscrit.
+*/
+let published = Object.freeze([]);
+/**
+* Le document qui rend un refus APPRENABLE — RFC 9728.
+*
+* ## Le trou que ce controller ferme
+*
+* Un `401` d'une zone qui déclare sa ressource porte désormais un défi complet :
+*
+* ```
+* WWW-Authenticate: Bearer resource_metadata="https://app/.well-known/oauth-protected-resource/api"
+* ```
+*
+* Sans ce controller, cette URL rendait **404** : un pointeur syntaxiquement
+* conforme qui ne mène nulle part. Le client le lit, le suit, trouve une erreur,
+* et conclut qu'il n'y a pas d'autorisation ici — c'est-à-dire exactement
+* l'inverse de ce que le refus voulait lui apprendre. Seul `@nodefony/devkit`
+* publiait un document, et uniquement pour SA porte MCP.
+*
+* ## Une route par CHEMIN, un document par AUTORITÉ
+*
+* La RFC 9728 §3.1 **insère** le chemin de la ressource dans l'URL bien connue
+* (« Using path components enables supporting multiple resources per host ») :
+* deux ressources de chemins distincts ont donc deux URL distinctes, et l'on
+* monte une route par chemin. Deux ressources qui partagent le chemin mais pas
+* l'autorité (`https://a.example/api` et `https://b.example/api`) partagent en
+* revanche la même route : c'est alors l'autorité demandée qui départage, à la
+* requête.
+*
+* ## Ce qui retient la publication
+*
+* Rien n'est monté si le service `firewall` est absent, ou s'il ne déclare
+* aucune ressource : **`404`, zéro surface**. Un document creux apprendrait à un
+* client qu'il y a quelque chose à découvrir sans lui donner de quoi le faire —
+* et la spécification MCP l'interdit explicitement (« MUST include […] at least
+* one authorization server »).
+*
+* `bypassFirewall: true` : ce document est public par construction. Le placer
+* derrière l'authentification serait circulaire — il sert précisément à
+* expliquer comment s'authentifier à qui ne l'est pas encore. Il ne révèle rien
+* de secret : une URI publique, des émetteurs, des scopes.
+*
+* @see references/rfc/ietf/rfc9728.txt — métadonnées de la ressource protégée
+* @see references/rfc/ietf/rfc8707.txt — l'audience, qui LIE un jeton à CE service
+*/
+var ProtectedResourceMetadataController = class extends Controller {
+	constructor(context) {
+		super("ProtectedResourceMetadataController", context);
+	}
+	/** Chemin bien connu demandé, tel que le Router l'a matché. */
+	#askedPath() {
+		const req = this.request;
+		const p = req?.pathname;
+		if (typeof p === "string") return p;
+		const url = req?.url;
+		if (url instanceof URL) return url.pathname;
+		if (typeof url === "string") try {
+			return new URL(url, "http://localhost").pathname;
+		} catch {
+			return null;
+		}
+		return null;
+	}
+	/**
+	* `GET /.well-known/oauth-protected-resource/<chemin>` — RFC 9728 §3.
+	*
+	* 🔴 Le document n'est servi que sur l'autorité de SA ressource. Un client
+	* conforme rejette un document dont la `resource` ne correspond pas à l'URI
+	* qu'il interrogeait (§3.3) — et un client réel s'arrête là au lieu de
+	* continuer sans authentification. C'est la faille déjà vécue sur le document
+	* d'émetteur, transposée : la règle est partagée (`onDeclaredAuthority`).
+	*
+	* @returns le document JSON, ou `404` si aucune ressource déclarée ne
+	*          correspond au chemin ET à l'autorité demandés
+	*/
+	async metadata() {
+		const declared = published;
+		const path = this.#askedPath();
+		const asked = askedAuthority(this.request?.headers);
+		if (!path || declared.length === 0) return this.renderJson({ error: "not_found" }, 404);
+		let match = null;
+		for (const entry of declared) {
+			let canonical;
+			try {
+				canonical = canonicalResourceUri(entry.resource);
+			} catch {
+				continue;
+			}
+			if (protectedResourceMetadataPath(canonical) !== path) continue;
+			if (!onDeclaredAuthority(asked, canonical)) continue;
+			match = entry;
+			break;
+		}
+		if (!match) return this.renderJson({ error: "not_found" }, 404);
+		let document;
+		try {
+			document = buildProtectedResourceMetadata(match);
+		} catch (error) {
+			this.log(`métadonnées de ressource protégée impubliables : ${error.message}`, "CRITIC");
+			return this.renderJson({ error: "server_error" }, 500);
+		}
+		return this.renderJson(document, 200, { "Cache-Control": "public, max-age=3600" });
+	}
+};
+/**
+* Rassemble ce que TOUS les services du conteneur déclarent protéger.
+*
+* ⭐ **Pourquoi balayer plutôt que demander à un service nommé.** Les ressources
+* protégées d'une application n'ont pas une source unique : le pare-feu en
+* déclare (une zone qui exige un jeton tiers), et un module peut en déclarer une
+* de son propre chef — la porte MCP de `@nodefony/devkit` en est le premier cas.
+* Interroger le seul `firewall` aurait laissé chaque autre module monter SON
+* document, c'est-à-dire recopier cette règle autant de fois qu'il y a de
+* sources, avec la collision de chemin en prime : `Router.createRoute` empile
+* sans vérifier, et la seconde route ne serait jamais atteinte.
+*
+* Un **registre** aurait fait le même travail, au prix d'une dépendance d'ordre :
+* un module qui s'enregistre après le `onKernelReady` du framework ne serait
+* jamais publié, et rien ne le dirait. Le balayage n'a pas ce défaut — les
+* services sont tous en place bien avant, et la question se pose au moment où
+* l'on monte.
+*
+* Le contrat est **structurel** : porter la méthode suffit, aucun import, aucune
+* interface à implémenter formellement — le même couplage que `tokenService` ou
+* `adminBroker`.
+*
+* @param container - conteneur de services de l'application
+* @returns les ressources déclarées, dans l'ordre des services
+*/
+function collectProtectedResources(container) {
+	const collected = [];
+	for (const name of container.keys()) {
+		const service = container.get(name);
+		if (typeof service?.publishedProtectedResources !== "function") continue;
+		let declared;
+		try {
+			declared = service.publishedProtectedResources();
+		} catch {
+			continue;
+		}
+		for (const entry of declared) collected.push(entry);
+	}
+	return collected;
+}
+/**
+* Chemins bien connus à monter pour un jeu de ressources déclarées.
+*
+* Fonction **pure**, exportée pour être éprouvée sans serveur : c'est elle qui
+* porte les deux décisions qui font la différence entre un document servi et un
+* `404` — la dérivation du chemin (insertion RFC 9728 §3.1, jamais une
+* concaténation) et la déduplication.
+*
+* Deux zones peuvent parfaitement déclarer la même ressource (typiquement une
+* zone HTTP et son pendant WebSocket) ; deux hôtes virtuels peuvent en déclarer
+* deux différentes sous le même chemin. Dans les deux cas il ne faut monter
+* qu'**une** route : `Router.createRoute` empile sans vérifier, et la seconde
+* ne serait jamais atteinte — une collision parfaitement silencieuse.
+*
+* @param resources - ressources déclarées par le publieur
+* @returns les chemins distincts à servir, dans l'ordre de déclaration
+*/
+function protectedResourceRoutePaths(resources) {
+	const paths = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const entry of resources) {
+		let canonical;
+		try {
+			canonical = canonicalResourceUri(entry.resource);
+		} catch {
+			continue;
+		}
+		const path = protectedResourceMetadataPath(canonical);
+		if (seen.has(path)) continue;
+		seen.add(path);
+		paths.push(path);
+	}
+	return paths;
+}
+/**
+* Monte les documents de ressource protégée — appelé par le module framework à
+* `onKernelReady`, seulement si un publieur déclare au moins une ressource.
+*
+* @param frameworkModule - module porteur des routes
+* @param resources - ressources déclarées, qui DÉTERMINENT les chemins montés
+* @returns le nombre de routes montées
+*/
+function mountProtectedResourceRoutes(frameworkModule, resources) {
+	if (mounted) return 0;
+	const paths = protectedResourceRoutePaths(resources);
+	if (paths.length === 0) return 0;
+	published = resources;
+	let index = 0;
+	for (const path of paths) router_default.createRoute(`security.resource.metadata.${index++}`, {
+		path,
+		constructor: ProtectedResourceMetadataController,
+		classMethod: "metadata",
+		requirements: { methods: ["GET"] },
+		bypassFirewall: true
+	});
+	if (!Object.prototype.hasOwnProperty.call(ProtectedResourceMetadataController.prototype, "module")) router_default.setController(ProtectedResourceMetadataController, frameworkModule);
+	mounted = true;
+	return paths.length;
+}
+//#endregion
+export { collectProtectedResources, ProtectedResourceMetadataController as default, mountProtectedResourceRoutes, protectedResourceRoutePaths };