@nodefony/framework 10.0.0-beta.6 → 10.0.0-beta.7

package/dist/nodefony/service/router.js

@@ -1,7 +1,7 @@
 import Route from "../src/Route.js";
 import Resolver from "../src/Resolver.js";
 import { assertRouteSchemaDeclaration, routeExpectsBodyStream } from "../decorators/routerDecorators.js";
-import __decorate from "../../_virtual/_@oxc-project_runtime@0.157.0/helpers/esm/decorate.js";
+import __decorate from "../../_virtual/_@oxc-project_runtime@0.158.0/helpers/esm/decorate.js";
 import { BootConfigurationError, Injector, Module, Service, injectable, isPromise, stripTrailingSlashes } from "nodefony";
 import { HttpError, isDomainAllowed } from "@nodefony/http";
 // nodefony/service/router.ts
@@ -173,10 +173,11 @@ let Router = class Router extends Service {
 	*   lieu de `context.request.url` — permet de router un path **porté par un message**
 	*   (WS-RPC `invoke`) vers une action, sans muter l'URL de la connexion (état partagé).
 	*   `undefined` (cas hot path normal) → comportement inchangé.
-	* @param methodOverride - méthode HTTP **logique** à exiger en plus du transport
-	*   WEBSOCKET (pont WS-RPC `api.request` d'une MUTATION) : lève l'ambiguïté
-	*   GET-via-WS / POST-via-WS sur un même chemin (`context.method` = "WEBSOCKET").
-	*   `undefined` (GET/HTTP) → match historique sur `context.method`.
+	* @param methodOverride - méthode HTTP **logique** du pont WS-RPC `api.request`,
+	*   GET compris, exigée en plus du transport WEBSOCKET par la règle du cœur
+	*   `bridgeServesVerb` : un GET n'atteint jamais une action POST du même
+	*   chemin. `undefined` (requête HTTP, ouverture de socket) → match sur
+	*   `context.method`.
 	* @returns un `Resolver` (`.resolve === true` si une route a matché) — ou,
 	*   pour un chemin servi en WebSocket SEULEMENT et demandé en HTTP, un
 	*   `Resolver` dont `exception` porte le `426` (en-têtes `Upgrade` posés) :
@@ -220,8 +221,9 @@ let Router = class Router extends Service {
 					return resolver;
 				}
 			} catch (e) {
-				this.log(`Match route exception : ${route.name} ${String(e)}`, "DEBUG");
-				resolver.exception = e;
+				routeMatchLogged ??= this.kernel?.environment !== "production";
+				if (routeMatchLogged) this.log(`Match route exception : ${route.name} ${String(e)}`, "DEBUG");
+				resolver.exception = e instanceof Error ? e : new Error(String(e));
 				continue;
 			}
 		}
@@ -239,12 +241,12 @@ let Router = class Router extends Service {
 					Upgrade: "websocket",
 					Connection: "Upgrade"
 				});
-				resolver.exception = new HttpError("Upgrade Required: websocket", 426, context);
+				resolver.exception = HttpError.withoutStack("Upgrade Required: websocket", 426, context);
 				return resolver;
 			}
 			if (allowed.size > 0) {
 				const allowHeader = Array.from(allowed).join(", ");
-				const err = new HttpError(`Method ${context.method} Not Allowed`, 405, context);
+				const err = HttpError.withoutStack(`Method ${context.method} Not Allowed`, 405, context);
 				const methodErr = err;
 				methodErr.allow = allowHeader;
 				methodErr.type = "method";

package/dist/nodefony/src/Controller.js

@@ -4,8 +4,8 @@ import { evaluatePreconditions, fileValidators, ifRangeHolds, parseHttpDate } fr
 import { VIEW_NONCE_LOCAL, signTemplateTags } from "./viewNonce.js";
 import { FileClass, RequestContext, Service } from "nodefony";
 import { HttpContext, HttpError, acceptsEventStream } from "@nodefony/http";
-import { createReadStream } from "node:fs";
 import { Readable } from "node:stream";
+import { createReadStream } from "node:fs";
 // nodefony/src/Controller.ts
 /**
 * Un `<script>` ou un `<style>` qui ne porte pas d'attribut `nonce`.
@@ -131,10 +131,17 @@ function encodeExtValue(value) {
 * hors ASCII imprimable, `"`, `\` et `%` — un nom accentué ne lève donc
 * jamais `ERR_INVALID_CHAR`, et un guillemet ne casse pas la valeur.
 *
+* Exportée pour servir un fichier sous un AUTRE nom que celui du disque —
+* un fichier reçu, rangé sous un identifiant tiré par le serveur, se rend
+* sous le nom que le client lui a donné, passé en en-tête de
+* `renderFileDownload()` ou de `streamFile()`.
+*
 * @param type - `attachment` (téléchargement) ou `inline` (affiché).
 * @param name - le nom du fichier, tel quel.
 * @returns la valeur de l'en-tête.
 */
+/** Aucun fichier reçu : une requête sans corps multipart, ou une socket. */
+const NO_FILES = Object.freeze([]);
 function contentDisposition(type, name) {
 	const fallback = name.replace(/[^\x20-\x7e]|["\\%]/g, "_");
 	if (fallback === name) return `${type}; filename="${name}"`;
@@ -272,7 +279,7 @@ var Controller = class extends Service {
 	* préférer `@UploadedFiles()`.
 	*/
 	get files() {
-		return this.#files ?? (this.context?.request)?.files;
+		return this.#files ?? (this.context?.request)?.files ?? NO_FILES;
 	}
 	set files(value) {
 		this.#assertPerRequest("files");
@@ -532,6 +539,17 @@ var Controller = class extends Service {
 	* });
 	* ```
 	*
+	* HEAD sans lancer le producteur — toute route GET sert HEAD, la source n'y
+	* est jamais lue. `Readable.from([])` seul est en mode OBJET, donc refusé
+	* (500) : le mode octets se demande.
+	* ```ts
+	* if (this.method === "HEAD") {
+	*   return this.renderStream(Readable.from([], { objectMode: false }), {
+	*     headers: { "content-type": "video/mp4" },
+	*   });
+	* }
+	* ```
+	*
 	* @param source - flux Node, ou flux web ; jamais en mode objet.
 	* @param options - statut, en-têtes, `idleTimeout`, `stallTimeout`,
 	*   `maxDuration`, `onClose(reason)`.
@@ -853,4 +871,4 @@ var Controller = class extends Service {
 		return this.#sendFile(File, head, value);
 	}
 };
-export { configureFileServing, Controller as default, parseByteRange };
+export { configureFileServing, contentDisposition, Controller as default, parseByteRange };

package/dist/nodefony/src/Resolver.js

@@ -3,9 +3,13 @@ import { validateRouteInput } from "./routeSchema.js";
 import { buildParamArgs, computeActionMeta, readInvocationBody, readRouteInput, resolveActionMeta, resolveSessionIntent } from "../decorators/routerDecorators.js";
 import { computeFingerprint, evaluateIdempotency, isMutationMethod, resolveIdempotencyKey, resolveIdentity } from "./idempotency.js";
 import { authenticationShortfall, stepUpChallenge } from "./requireAuthentication.js";
-import { RequestContext, finallyMaybe, identityHint, isArray, isPlainObject, isPromise, nodefonyError, thenMaybe, typeOf } from "nodefony";
+import { RequestContext, finallyMaybe, identityHint, isArray, isPlainObject, isPromise, nodefonyError, thenMaybe } from "nodefony";
 import { Http2Response, HttpResponse, WebsocketResponse, isContentlessStatus } from "@nodefony/http";
+import { Buffer } from "node:buffer";
+import { Readable } from "node:stream";
 // nodefony/src/Resolver.ts
+/** Une annulation qui échoue (flux déjà fermé) n'a plus personne à prévenir. */
+const IGNORE_CANCEL_ERROR = () => void 0;
 /**
 * Résout une route vers son couple controller/action et exécute l'action —
 * UN Resolver est alloué par requête HTTP (et par connexion WS, réutilisé
@@ -56,12 +60,12 @@ var Resolver = class {
 	*/
 	queryOverride = null;
 	/**
-	* Méthode HTTP **logique** d'une invocation par le pont WS-RPC `api.request`
-	* quand c'est une MUTATION (POST/PUT/PATCH/DELETE). Posée par
-	* `Router.resolve(ctx, cleanPath, methodOverride)` → consommée par `match()`
-	* pour désambiguïser, sur le transport WEBSOCKET unique, la route logique
-	* visée (cf `Route.matchRequirements`). `null` (GET/HTTP) = match historique
-	* sur `context.method`.
+	* Méthode HTTP **logique** d'une invocation par le pont WS-RPC `api.request`,
+	* GET compris. Posée par `Router.resolve(ctx, cleanPath, methodOverride)` →
+	* consommée par `match()` pour désambiguïser, sur le transport WEBSOCKET
+	* unique, la route logique visée (règle `bridgeServesVerb` du cœur, cf
+	* `Route.matchRequirements`). `null` (requête HTTP, ouverture de socket) =
+	* match sur `context.method`.
 	*/
 	methodOverride = null;
 	/**
@@ -431,6 +435,8 @@ var Resolver = class {
 	async _callWithIdempotency(meta, data, reload = false) {
 		const context = this.context;
 		if (!isMutationMethod(this.methodOverride ?? context.method)) return this.executeAction(data, reload, meta);
+		if (this.preAuthorized) this.preAuthorized = false;
+		else await this._enforceActionSecurity(meta);
 		const als = RequestContext.get();
 		const httpReq = context.request;
 		const params = this._zipRouteParams();
@@ -463,6 +469,7 @@ var Resolver = class {
 				redirectMeta: void 0
 			};
 		}
+		this.preAuthorized = true;
 		if (verdict.kind === "execute") return this.executeAction(data, reload, meta);
 		try {
 			const { result, redirectMeta } = await this.executeAction(data, reload, meta);
@@ -631,7 +638,15 @@ var Resolver = class {
 	/**
 	* Rend la valeur d'une action sur le transport, selon sa nature : promesse
 	* (démêlée puis re-rendue), texte, Buffer, réponse déjà construite, scalaire
-	* ou objet (auto-JSON), rien (l'action envoie elle-même).
+	* ou objet (auto-JSON), rien (l'action envoie elle-même) — et, en HTTP, une
+	* `Response` Web standard (`fetch()`, `new Response(…)`, `Response.json(…)`)
+	* ou un flux d'octets nu (`Readable` Node, `ReadableStream` Web), envoyés EN
+	* FLUX par `HttpContext.openWebResponse` / `HttpContext.openStream`.
+	*
+	* Ces deux-là sont reconnus APRÈS l'objet simple et le tableau : l'auto-JSON,
+	* le cas courant, ne paie aucun test de plus. Une réponse déjà partie
+	* (`sended`) n'est jamais réécrite ; une `Response` renvoyée en plus voit
+	* alors son corps annulé, pour ne pas retenir l'amont.
 	*
 	* Pas `async` : l'envelopper dans une promesse de plus ne changeait rien au
 	* rendu, et coûtait une suspension à chaque requête (#505). La valeur n'est
@@ -643,45 +658,70 @@ var Resolver = class {
 	* @throws de façon SYNCHRONE ce que lève un envoi synchrone.
 	*/
 	returnController(result) {
-		const type = typeOf(result);
-		switch (true) {
-			case result instanceof Promise:
-			case isPromise(result): return result.then((myresult) => this.returnController(myresult));
-			case type === "string":
-			case result instanceof String: return this.context.send(result);
-			case result instanceof Http2Response:
-			case result instanceof HttpResponse:
-			case result instanceof WebsocketResponse: return result;
-			case type === "buffer":
-				if (this.context.sended) return;
-				return this.context.send(result);
-			case type === "number":
-			case type === "boolean":
+		if (isPromise(result)) return result.then((myresult) => this.returnController(myresult));
+		switch (typeof result) {
+			case "object":
+				if (result === null) break;
+				return this.returnObject(result);
+			case "string": return this.context.send(result);
+			case "number":
+			case "boolean":
 				if (this.context.sended) return;
 				this.context.setContextJson();
 				return this.context.render(result);
-			case type === "array":
-			case type === "object":
-				if (this.context.sended) return;
-				if (isPlainObject(result) || isArray(result)) {
-					this.context.setContextJson();
-					return this.context.render(result);
-				}
-				switch (this.context.type) {
-					case "http":
-						this.context.waitAsync = true;
-						this.unrendered = `une instance de ${(typeof result === "object" && result !== null ? result.constructor.name : void 0) ?? "classe"}`;
-				}
-				return;
-			default: switch (this.context.type) {
-				case "http":
-					if (this.context.sended) return;
-					if (this.context.isRedirect) return this.context.send();
-					if (isContentlessStatus(this.getResponseStatus())) return this.context.send();
-					this.context.waitAsync = true;
-					this.unrendered = result === null ? "null" : typeof result;
-			}
 		}
+		return this.returnNothing(result);
+	}
+	/**
+	* Aiguille une valeur OBJET rendue par l'action — dans l'ordre de fréquence :
+	* le tableau et l'objet simple (auto-JSON) d'abord, les instances rares
+	* ensuite. Partie de {@link Resolver.returnController}.
+	*
+	* @param result - un objet non nul.
+	* @returns ce que rend l'envoi, ou `undefined` quand il n'y a rien à envoyer.
+	*/
+	returnObject(result) {
+		const context = this.context;
+		if (isArray(result) || isPlainObject(result)) {
+			if (context.sended) return;
+			context.setContextJson();
+			return context.render(result);
+		}
+		if (Buffer.isBuffer(result)) {
+			if (context.sended) return;
+			return context.send(result);
+		}
+		if (result instanceof String) return context.send(result.valueOf());
+		if (result instanceof HttpResponse || result instanceof Http2Response || result instanceof WebsocketResponse) return result;
+		if (context.sended) {
+			if (result instanceof Response) result.body?.cancel().catch(IGNORE_CANCEL_ERROR);
+			return;
+		}
+		if (result instanceof Date || result instanceof RegExp || result instanceof Error) return this.returnNothing(result);
+		if (context.type === "http") {
+			if (result instanceof Response) return context.openWebResponse(result);
+			if (result instanceof Readable || result instanceof ReadableStream) return context.openStream(result);
+			context.waitAsync = true;
+			this.unrendered = `une instance de ${result.constructor.name || "classe"}`;
+		}
+	}
+	/**
+	* Ce qui arrive quand l'action ne rend RIEN d'envoyable (`undefined`,
+	* `null`, une fonction…) : en HTTP, la redirection posée ou le statut sans
+	* corps part ; sinon la requête est marquée non rendue (`waitAsync`). Partie
+	* de {@link Resolver.returnController}.
+	*
+	* @param result - la valeur rendue par l'action.
+	* @returns l'envoi d'une redirection ou d'un statut sans corps, sinon `undefined`.
+	*/
+	returnNothing(result) {
+		if (this.context.type !== "http") return;
+		const context = this.context;
+		if (context.sended) return;
+		if (context.isRedirect) return context.send();
+		if (isContentlessStatus(this.getResponseStatus())) return context.send();
+		context.waitAsync = true;
+		this.unrendered = result === null ? "null" : typeof result;
 	}
 	/** Statut courant de la réponse (0 si le transport n'en porte pas). */
 	getResponseStatus() {

package/dist/nodefony/src/Route.js

@@ -1,4 +1,4 @@
-import { escapeRegExp, stripTrailingSlashes, typeOf } from "nodefony";
+import { bridgeServesVerb, escapeRegExp, stripTrailingSlashes, typeOf } from "nodefony";
 import { HttpError, compileDomainPatterns, isDomainAllowed } from "@nodefony/http";
 import { createHash } from "node:crypto";
 // nodefony/src/Route.ts
@@ -125,6 +125,24 @@ function withDeclaredMethod(requirements, method) {
 function isSecureScheme(scheme) {
 	return scheme === "https" || scheme === "wss";
 }
+/**
+* Un refus de route (méthode, domaine, schéma, protocole) SANS pile : c'est un
+* verdict que le routeur RATTRAPE pour essayer la route suivante — deux routes
+* sur un même chemin (`GET` et `POST /x`) le lèvent à chaque requête qui
+* croise la voisine. La pile, toujours la même, coûterait ~3,6 µs par refus
+* (`micro-error-path.mjs`) pour ne rien dire de la requête.
+*
+* @param message - le motif lisible.
+* @param code - statut HTTP (ou code de fermeture WebSocket).
+* @param type - la famille du refus (`method`, `domain`, `scheme`, `protocol`).
+* @param allow - les méthodes servies, pour l'en-tête `Allow` d'un 405.
+*/
+function routeRefusal(message, code, type, allow) {
+	const error = HttpError.withoutStack(message, code);
+	error.type = type;
+	if (allow !== void 0) error.allow = allow;
+	return error;
+}
 var Route = class Route {
 	name;
 	path;
@@ -172,6 +190,13 @@ var Route = class Route {
 	/** Route de repli, résolue après toutes les autres. Cf {@link RouteOptions.fallback}. */
 	fallback = false;
 	/**
+	* Délai de réponse PROPRE à la route (ms), `null` = celui du serveur.
+	* Cf {@link RouteOptions.responseTimeout}.
+	*/
+	responseTimeout = null;
+	/** Bornes d'envoi propres à la route. Cf {@link RouteOptions.upload}. */
+	upload = null;
+	/**
 	* P2.9 — Cache mémoïsé : l'action attend-elle le **flux brut** du body
 	* (`@Body({ stream:true })`) ? `undefined` = pas encore calculé (résolu au 1er
 	* `routeExpectsBodyStream(route)` via lecture `Reflect` des `ParamMeta`, O(1)
@@ -179,6 +204,13 @@ var Route = class Route {
 	*/
 	bodyStream;
 	/**
+	* Route servie par un point d'entrée gRPC — posé au démarrage par
+	* `markGrpcRoute` (`@nodefony/http/grpc`), jamais à la main.
+	*
+	* @experimental Surface gRPC, ADR-0026 D11.
+	*/
+	grpc;
+	/**
 	* P5 — Metadata d'action figées (`@HttpCode`/`@Header`/`@Redirect`/params/
 	* session), memo au 1er hit comme {@link bodyStream} : `undefined` = pas
 	* encore résolu (via `resolveActionMeta`, 1 lecture Reflect par route, O(1)
@@ -208,6 +240,8 @@ var Route = class Route {
 			this.bypassFirewall = obj.bypassFirewall ?? false;
 			this.areaRoleExempt = obj.areaRoleExempt ?? false;
 			this.fallback = obj.fallback ?? false;
+			this.responseTimeout = obj.responseTimeout ?? null;
+			this.upload = obj.upload ?? null;
 			this.compile();
 		}
 		this.generateId();
@@ -409,7 +443,9 @@ var Route = class Route {
 			variables: this.variables,
 			bypassFirewall: this.bypassFirewall,
 			areaRoleExempt: this.areaRoleExempt,
-			fallback: this.fallback
+			fallback: this.fallback,
+			responseTimeout: this.responseTimeout,
+			upload: this.upload
 		};
 	}
 	setDefaults(arg) {
@@ -449,10 +485,7 @@ var Route = class Route {
 	matchHostname(context) {
 		if (this.hostRegexp) {
 			if (isDomainAllowed(this.hostRegexp, context.domain)) return true;
-			const error = new HttpError(`Domain ${context.domain} Forbidden for this route`);
-			error.code = 403;
-			error.type = "domain";
-			throw error;
+			throw routeRefusal(`Domain ${context.domain} Forbidden for this route`, 403, "domain");
 		}
 		return true;
 	}
@@ -489,42 +522,19 @@ var Route = class Route {
 		return Object.keys(this.requirements).length;
 	}
 	matchRequirements(context, methodOverride) {
-		if (this.requirements.methods === void 0 && (methodOverride !== void 0 || context.method === "WEBSOCKET")) {
-			const error = new HttpError(`Method ${methodOverride ?? "WEBSOCKET"} Not Allowed`);
-			error.code = 405;
-			error.type = "method";
-			error.allow = "";
-			throw error;
-		}
+		if (this.requirements.methods === void 0 && (methodOverride !== void 0 || context.method === "WEBSOCKET")) throw routeRefusal(`Method ${methodOverride ?? "WEBSOCKET"} Not Allowed`, 405, "method", "");
 		if (this.hasRequirements()) for (const i in this.requirements) switch (i) {
 			case "methods":
 				if (!this.methodsSet) throw new Error(`Bad config route method : ${String(this.requirements.methods)}`);
 				if (methodOverride !== void 0) {
-					if (!this.methodsSet.has("WEBSOCKET") || !this.methodsSet.has(methodOverride)) {
-						const error = new HttpError(`Method ${methodOverride} Not Allowed`);
-						error.code = 405;
-						error.type = "method";
-						error.allow = this.methodsAllow ?? "";
-						throw error;
-					}
+					if (!bridgeServesVerb(this.methodsSet, methodOverride)) throw routeRefusal(`Method ${methodOverride} Not Allowed`, 405, "method", this.methodsAllow ?? "");
 					break;
 				}
-				if (!this.methodsSet.has(context.method)) {
-					const error = new HttpError(`Method ${context.method} Not Allowed`);
-					error.code = 405;
-					error.type = "method";
-					error.allow = this.methodsAllow ?? "";
-					throw error;
-				}
+				if (!this.methodsSet.has(context.method)) throw routeRefusal(`Method ${context.method} Not Allowed`, 405, "method", this.methodsAllow ?? "");
 				break;
 			case "scheme": {
 				const required = this.requirements.scheme;
-				if (required !== void 0 && isSecureScheme(required) !== isSecureScheme(context.scheme)) {
-					const error = new HttpError(`Scheme ${context.scheme} Forbidden for this route : ${required} required`);
-					error.code = 403;
-					error.type = "scheme";
-					throw error;
-				}
+				if (required !== void 0 && isSecureScheme(required) !== isSecureScheme(context.scheme)) throw routeRefusal(`Scheme ${context.scheme} Forbidden for this route : ${required} required`, 403, "scheme");
 				break;
 			}
 			case "domain": break;
@@ -532,18 +542,8 @@ var Route = class Route {
 				const requirement = this.requirements[i];
 				if (!requirement) return true;
 				if (typeof requirement === "string") {
-					if (context.acceptedProtocol !== requirement) {
-						const error = new HttpError(`Protocol ${context.acceptedProtocol} Not Supported`);
-						error.code = 1002;
-						error.type = "protocol";
-						throw error;
-					}
-				} else {
-					const error = new HttpError(`Protocol ${context.acceptedProtocol} Not Supported`);
-					error.code = 1002;
-					error.type = "protocol";
-					throw error;
-				}
+					if (context.acceptedProtocol !== requirement) throw routeRefusal(`Protocol ${context.acceptedProtocol} Not Supported`, 1002, "protocol");
+				} else throw routeRefusal(`Protocol ${context.acceptedProtocol} Not Supported`, 1002, "protocol");
 			}
 		}
 		return true;

package/dist/nodefony/src/loginPage.js

@@ -211,7 +211,7 @@ const LOGIN_PAGE_TEMPLATE = `<!doctype html>
           </p>
           <ul class="badges">
             <li class="agentic">Agentic ready</li>
-            <li>Node.js ≥ 24.14</li>
+            <li>Node.js 24.16+ ou 26+</li>
             <li>TypeScript strict</li>
             <li>ESM only</li>
             <li>Licence Apache 2.0</li>

package/dist/types/index.d.ts

@@ -28,6 +28,7 @@ import Eta from "./nodefony/service/Eta.js";
 import { controllers, route, controller, Get, Post, Put, Delete, Patch, Options, Head, All, Domain, BypassFirewall, IsGranted, RequireScope, RequireAuthentication, Anonymous, Csp, CsrfProtect, CsrfExempt, Idempotent, CurrentUser, Scope, UseSession, HttpCode, Header, Redirect, Param, Body, Query, Headers, Cookie, Session, Req, Res, UploadedFile, UploadedFiles, routeExpectsBodyStream, buildContextParamArgs, getParamArgsMeta, getRouteSchema } from "./nodefony/decorators/routerDecorators.js";
 export type { IHttpMethodDecorator } from "./nodefony/decorators/routerDecorators.js";
 export { validateRouteInput } from "./nodefony/src/routeSchema.js";
+export { contentDisposition } from "./nodefony/src/Controller.js";
 export type { IRouteSchema, RouteInput, RoutePart, RawRouteInput, RawRouteParams, RawRouteQuery, RawRouteHeaders, } from "./nodefony/src/routeSchema.js";
 declare module "nodefony" {
     interface NodefonyModuleConfig {

package/dist/types/nodefony/controller/ProtectedResourceMetadataController.d.ts

@@ -113,10 +113,30 @@ export interface IServiceScan {
  * interface à implémenter formellement — le même couplage que `tokenService` ou
  * `adminBroker`.
  *
+ * Deux sources peuvent déclarer la MÊME ressource — une zone du pare-feu et la
+ * porte MCP qu'elle couvre, typiquement — : elles sont fusionnées
+ * ({@link mergeProtectedResources}), jamais départagées par leur ordre.
+ *
  * @param container - conteneur de services de l'application
- * @returns les ressources déclarées, dans l'ordre des services
+ * @returns les ressources déclarées, une entrée par ressource, dans l'ordre des
+ *          services
  */
 export declare function collectProtectedResources(container: IServiceScan): readonly IProtectedResourceInput[];
+/**
+ * Une ressource, UN document : fusionne les déclarations d'une même ressource
+ * (même URI canonique) — l'union de leurs serveurs d'autorisation et de leurs
+ * scopes ; le premier nom et la première documentation déclarés.
+ *
+ * Pourquoi fusionner plutôt que garder la première : une zone du pare-feu
+ * publie sa ressource avec les émetteurs de confiance, et la porte MCP qu'elle
+ * couvre publie la MÊME ressource avec les scopes de ses outils. Garder la
+ * première jetait les scopes sans un mot — et un agent qui suit le document
+ * demandait alors un jeton sans eux, qui n'ouvrait pas l'outil.
+ *
+ * @param entries - déclarations, dans l'ordre des services
+ * @returns une entrée par ressource, à la place de la première déclaration
+ */
+export declare function mergeProtectedResources(entries: readonly IProtectedResourceInput[]): IProtectedResourceInput[];
 /**
  * Chemins bien connus à monter pour un jeu de ressources déclarées.
  *

package/dist/types/nodefony/decorators/routerDecorators.d.ts

@@ -9,6 +9,7 @@ import { ControllerConstructor } from "../src/Route.js";
 import type { IRouteSchema, RawRouteInput, RouteInput } from "../src/routeSchema.js";
 import type { SessionIntent } from "@nodefony/http";
 type Constructor<T = {}> = new (...args: any[]) => T;
+declare const getReservedActionNames: () => Map<string, string>;
 /**
  * Rattache un ou plusieurs contrôleurs à un module, dont ils suivent le cycle de vie.
  *
@@ -794,7 +795,7 @@ declare function resolveActionMeta(routeDef: {
     classMethod?: string | undefined;
     actionMeta?: RouteActionMeta | undefined;
 }): RouteActionMeta;
-export { route, controller, controllers, Get, Post, Put, Delete, Patch, Options, Head, All, Domain, BypassFirewall, IsGranted, RequireScope, RequireAuthentication, Anonymous, Csp, CsrfProtect, CsrfExempt, Idempotent, CurrentUser, Scope, UseSession, resolveSessionIntent, HttpCode, Header, Redirect, Param, Body, Query, Headers, Cookie, Session, Req, Res, UploadedFile, UploadedFiles, resolveParamArg, buildParamArgs, routeExpectsBodyStream, computeActionMeta, resolveActionMeta, extractActionScopes, };
+export { route, controller, controllers, Get, Post, Put, Delete, Patch, Options, Head, All, Domain, BypassFirewall, IsGranted, RequireScope, RequireAuthentication, Anonymous, Csp, CsrfProtect, CsrfExempt, Idempotent, CurrentUser, Scope, UseSession, resolveSessionIntent, HttpCode, Header, Redirect, Param, Body, Query, Headers, Cookie, Session, Req, Res, UploadedFile, UploadedFiles, resolveParamArg, buildParamArgs, routeExpectsBodyStream, computeActionMeta, resolveActionMeta, extractActionScopes, applyDeclaredRouteOptions, getReservedActionNames, };
 /** Options de {@link RequireAuthentication}. */
 export interface IRequireAuthenticationOptions {
     /** Âge maximal de la connexion, en secondes. Omis = aucune limite d'âge. */

package/dist/types/nodefony/grpc/GrpcController.d.ts

@@ -0,0 +1,75 @@
+import Controller from "../src/Controller.js";
+/**
+ * Classe de base d'un point d'entrée gRPC (ADR-0026 D1), jumelle de
+ * `RealtimeController` : marquée par `@GrpcService(Contrat)`, déclarée par
+ * `@controllers([...])`. Chaque méthode du contrat est une méthode de la
+ * classe, appelée par l'adaptateur Connect avec `(request, HandlerContext)` ;
+ * la logique métier vit dans un service injecté.
+ *
+ * Singleton par défaut : aucune instance par appel, l'adaptateur lie les
+ * méthodes une fois. `@Scope("request")` donne une instance par appel.
+ *
+ * Ce que le framework décide pour chaque méthode, sans code de ta part :
+ * - les gardes (`@IsGranted`, `@RequireAuthentication`…) posées sur la
+ *   méthode ou la classe s'appliquent ; un refus part en 16
+ *   `UNAUTHENTICATED` sans identité, en 7 `PERMISSION_DENIED` sinon ;
+ * - `this.user`, l'ALS et la portée `request` valent pendant tout l'appel,
+ *   flux compris ;
+ * - une `ConnectError` part telle quelle ; une `HttpError` est traduite par
+ *   la table de `google/rpc/code.proto` ; toute autre exception devient 13
+ *   `INTERNAL`. Dans un flux, la traduction ne vaut qu'avant le premier
+ *   message ;
+ * - un flux est interrompu en 14 `UNAVAILABLE` à l'arrêt du serveur et en 16
+ *   à la révocation de son identité : passer `ctx.signal` à ses sources ;
+ * - messages bornés à 4 Mio (section `grpc` de la configuration http).
+ *
+ * Un décorateur sans effet en gRPC (`@Body`, `@UseSession`, `@Csp`,
+ * `@Idempotent`…) sur une méthode du contrat interrompt le démarrage.
+ * Guide complet : `docs/grpc.md` du paquet.
+ *
+ * @example
+ * \@GrpcService(GreetService)
+ * export class GreetController extends GrpcController {
+ *   constructor(context: ContextType) {
+ *     super("GreetController", context);
+ *   }
+ *   greet(request: GreetRequest) {
+ *     return { greeting: `Bonjour, ${request.name} !` };
+ *   }
+ * }
+ *
+ * @experimental Surface gRPC, ADR-0026 D11.
+ */
+export declare abstract class GrpcController extends Controller {
+    /**
+     * Le point d'entrée de transport, posé au démarrage sur le prototype de la
+     * classe déclarée (`assertScope`) : une lecture de prototype par appel.
+     */
+    private readonly grpcEndpoint;
+    /**
+     * Vérifie la déclaration gRPC de la classe et fige ses routes — au
+     * démarrage (`Router.setController`), jamais à la première requête.
+     *
+     * Refuse : une classe sans `@GrpcService` ; une méthode du contrat absente
+     * de la classe ou dont le nom est réservé par le framework ; un décorateur
+     * sans effet en gRPC sur une méthode du contrat (ou sur la classe) — le
+     * refus nomme la méthode et le décorateur.
+     *
+     * Fige ensuite, sur chaque route, la méta d'action lue sur la MÉTHODE DU
+     * CONTRAT (l'action exécutée reste celle de la base) et le corps laissé en
+     * flux : les gardes valent quel que soit l'ordre des décorateurs de classe.
+     *
+     * @throws BootConfigurationError sur une déclaration refusée.
+     */
+    static assertScope(): void;
+    /**
+     * L'action de base de toute route gRPC : remet la requête et la réponse
+     * brutes à l'adaptateur, qui appelle la méthode du contrat et écrit la
+     * réponse. Synchrone, sauf pour un flux dont la session est à sauver : la
+     * promesse de la remise est alors rendue au résolveur, qui en lit l'échec.
+     *
+     * @throws Error quand la classe n'a pas été enregistrée par le routeur, ou
+     *   hors d'une requête HTTP.
+     */
+    serveGrpc(): void | Promise<void>;
+}

package/dist/types/nodefony/grpc/GrpcService.d.ts

@@ -0,0 +1,51 @@
+import type { DescService } from "@bufbuild/protobuf";
+import type { ServiceImpl } from "@connectrpc/connect";
+import type { GrpcController } from "./GrpcController.js";
+/**
+ * Une classe qui peut servir le contrat `S` : elle étend `GrpcController` et
+ * implémente CHAQUE méthode du contrat avec sa signature générée. Une méthode
+ * manquante ou mal typée ne compile pas.
+ *
+ * @experimental Surface gRPC, ADR-0026 D11.
+ */
+export type GrpcServiceClass<S extends DescService> = new (...args: never[]) => GrpcController & ServiceImpl<S>;
+/**
+ * Déclare un contrôleur comme le point d'entrée du service gRPC `service`
+ * (le descripteur généré par `buf`, ex. `EchoService` de `echo_pb.ts`).
+ *
+ * Monte une route littérale du Router par méthode du contrat,
+ * `POST /<paquet.Service>/<Méthode>`, plus `GET` pour une méthode déclarée
+ * `option idempotency_level = NO_SIDE_EFFECTS` (le GET de Connect). Ces
+ * routes passent par tout le pipeline — pare-feu, `@IsGranted`, hôtes
+ * virtuels, profileur, liste des routes —, et leurs gardes se lisent sur la
+ * méthode du contrat. La classe se déclare ensuite par `@controllers([...])`,
+ * comme tout point d'entrée d'un module.
+ *
+ * Les décorateurs de classe `@Domain` et `@BypassFirewall` se placent SOUS
+ * `@GrpcService` (lus au montage des routes, comme sous `@controller`).
+ *
+ * Le descripteur vient du code généré, jamais écrit à la main : contrat dans
+ * `proto/<paquet>/v1/*.proto`, `npx buf generate` vers `nodefony/gen/`, code
+ * commité. Les routes répondent sur 5152 (gRPC, gRPC-Web, Connect), 5151
+ * (gRPC-Web, Connect : HTTP/1.1, jamais le gRPC natif) et 5153 si h2c est
+ * activé. Guide complet : `docs/grpc.md` du paquet.
+ *
+ * @param service - le descripteur du service.
+ * @returns le décorateur de classe.
+ * @throws BootConfigurationError quand une autre classe sert déjà ce contrat.
+ *
+ * @example
+ * \@GrpcService(EchoService)
+ * export class EchoController extends GrpcController {
+ *   constructor(context: ContextType) {
+ *     super("EchoController", context);
+ *   }
+ *   \@IsGranted("ROLE_ECHO")
+ *   say(request: SayRequest) {
+ *     return { sentence: request.sentence };
+ *   }
+ * }
+ *
+ * @experimental Surface gRPC, ADR-0026 D11.
+ */
+export declare function GrpcService<S extends DescService>(service: S): <C extends GrpcServiceClass<S>>(ctor: C) => C;

package/dist/types/nodefony/grpc/declarations.d.ts

@@ -0,0 +1,12 @@
+import type { DescMethod, DescService } from "@bufbuild/protobuf";
+import type Route from "../src/Route.js";
+/** Une route montée par `@GrpcService`, et la méthode du contrat qu'elle sert. */
+export interface IGrpcRoute {
+    readonly route: Route;
+    readonly method: DescMethod;
+}
+/** Ce que `@GrpcService` a déclaré pour une classe, lu au démarrage. */
+export interface IGrpcDeclaration {
+    readonly service: DescService;
+    readonly routes: readonly IGrpcRoute[];
+}