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

package/dist/types/nodefony/config/config.d.ts

@@ -1,4 +1,16 @@
 import { z } from "zod";
+/**
+ * Requêtes conditionnelles des fichiers servis par une action (`streamFile`,
+ * `renderFileDownload`, `renderMediaStream`). Le défaut de TOUTE
+ * l'application ; un appel le remplace par ses options (`validators`) ou ses
+ * en-têtes (`Cache-Control`, `ETag`).
+ */
+export declare const fileServingSchema: z.ZodObject<{
+    validators: z.ZodDefault<z.ZodBoolean>;
+    cacheControl: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+/** Réglages des fichiers servis, défauts appliqués. */
+export type IFileServingConfig = z.infer<typeof fileServingSchema>;
 export declare const frameworkConfigSchema: z.ZodObject<{
     router: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
     adminBroker: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
@@ -7,6 +19,10 @@ export declare const frameworkConfigSchema: z.ZodObject<{
         gcIntervalS: z.ZodDefault<z.ZodNumber>;
         gcJitter: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strict>>;
+    fileServing: z.ZodDefault<z.ZodObject<{
+        validators: z.ZodDefault<z.ZodBoolean>;
+        cacheControl: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 /** Type de sortie (config normalisée + défauts appliqués). */
 export type IFrameworkConfig = z.infer<typeof frameworkConfigSchema>;
@@ -24,6 +40,10 @@ declare const _default: {
         gcIntervalS: number;
         gcJitter: boolean;
     };
+    fileServing: {
+        validators: boolean;
+        cacheControl: string | null;
+    };
     "module-security": {
         areas: {
             "nodefony-liveness": {

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

@@ -38,8 +38,10 @@ declare class AdminApiController extends Controller {
      * (une action, deux transports) : même exécution sur les deux transports, seul
      * l'emballage diffère.
      *
-     *  - **HTTP** : rendu historique inchangé (`renderJson` + status + header
-     *    `x-nodefony-instance`).
+     *  - **HTTP** : `renderJson` + status + header `x-nodefony-instance`. Quand
+     *    l'application active un codec binaire, le corps passe par le codec texte
+     *    de la socket (convention `$bytes`, annoncée par `x-nodefony-bytes`) : des
+     *    octets se relisent alors à l'identique sur les deux transports.
      *  - **Pont WS-RPC `api.request`** : valeur **nue** (le pont l'enveloppe
      *    `{id, result}` — snapshot ≡ GET par construction) ; statut ≥ 400 →
      *    {@link RpcError} (`data.status` + `data.body`), symétrie d'un `fetch`

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

@@ -0,0 +1,35 @@
+import { type Module } from "nodefony";
+import { type ContextType } from "@nodefony/http";
+import Controller from "../src/Controller.js";
+/**
+ * Réception PUBLIQUE des rapports de violation CSP (ADR-0024 §C7) —
+ * `POST /nodefony/security/api/csp-report`, adaptateur MINCE au-dessus du
+ * service `cspReports`.
+ *
+ * Le navigateur poste sans identifiant : la route contourne le pare-feu, et la
+ * défense CSRF (`@CsrfExempt`) — elle ne change l'état de personne, et un
+ * rapport n'a aucune session à détourner. Le corps arrive en FLUX
+ * (`@Body({ stream: true })`) pour être borné PENDANT la lecture : au-delà de
+ * {@link CSP_REPORT_MAX_BYTES}, 413 sans rien garder. Tout le reste — quota,
+ * type de contenu, forme, expurgation — appartient au collecteur, et la
+ * réponse est 204 quoi qu'il en pense : l'émetteur n'apprend rien.
+ */
+declare class CspReportController extends Controller {
+    constructor(context: ContextType);
+    /**
+     * Reçoit un rapport, ou un lot de rapports.
+     *
+     * @param stream - le corps brut, jamais lu par le pipeline.
+     * @throws HttpError 413 quand le corps dépasse le plafond.
+     */
+    report(stream: AsyncIterable<Uint8Array>): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+}
+/**
+ * Monte la route de réception — appelé par le module framework à
+ * `onKernelReady`, seulement si le service `cspReports` est présent (rapports
+ * demandés vers la route du framework).
+ *
+ * @param frameworkModule - module qui porte le contrôleur.
+ */
+export declare function mountCspReportRoute(frameworkModule: Module): void;
+export default CspReportController;

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

@@ -6,8 +6,9 @@ import Controller from "../src/Controller.js";
  * feuille `nodefony/login.css`, script `nodefony/login.js`. Aucun front, aucun
  * build côté application.
  *
- * Joignable sans session ; jamais mise en cache (`no-store`) ni affichable
- * dans un cadre (`frame-ancestors 'none'`).
+ * Joignable sans session ; jamais mise en cache (`no-store`). L’encadrement
+ * suit `http.securityHeaders.frameOptions`, qui pose `X-Frame-Options` ET
+ * `frame-ancestors` sur toute la politique (ADR-0024 §C5).
  */
 declare class LoginPageController extends Controller {
     constructor(context: ContextType);

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/controller/SessionAuthController.d.ts

@@ -62,12 +62,11 @@ export interface ISessionAuthFlow {
  * (Auth.js, better-auth). Le `401` y écrivait une erreur réseau dans la console
  * de chaque visiteur anonyme, sans rien protéger : la réponse ne révèle rien.
  *
- * @remarks Dérogation RFC 9110 §15.5.2 DÉLIBÉRÉE : les 401 de `login` ne
- * portent PAS de `WWW-Authenticate` — aucun scheme HTTP ne décrit un cookie de
- * session, et un challenge `Basic` mensonger déclencherait le popup natif du
- * navigateur (l'anti-pattern que le BFF élimine). Les zones du firewall, elles,
- * restent strictement conformes (challenge du premier authenticator qui en
- * déclare un).
+ * @remarks Les 401 de `login` portent le défi `Session realm="nodefony"`
+ * (RFC 9110 §15.5.2, posé par `SecurityApiController`), celui du pare-feu :
+ * aucun schéma HTTP ne décrit un cookie de session, et un `Basic` ouvrirait la
+ * fenêtre de connexion native du navigateur — l'anti-pattern que le BFF
+ * élimine. Un schéma inconnu des navigateurs n'en ouvre aucune.
  */
 declare class SessionAuthController extends SecurityApiController {
     #private;

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

@@ -33,9 +33,9 @@ export interface ITokenIssuer {
  * framework ne peut pas importer les classes d'erreur de security ; un 429
  * reporte le `Retry-After` (RFC 6585) du throttler NIST.
  *
- * @remarks Dérogation RFC 9110 §15.5.2 (comme `SessionAuthController`) : ces 401 ne
- * portent pas de `WWW-Authenticate` — l'endpoint d'émission n'est pas une
- * ressource protégée par Bearer, il DÉLIVRE le Bearer.
+ * @remarks Ces 401 portent le défi `Session realm="nodefony"` (RFC 9110
+ * §15.5.2, posé par `SecurityApiController`) et non un `Bearer` : l'endpoint
+ * d'émission n'est pas une ressource protégée par Bearer, il DÉLIVRE le Bearer.
  */
 declare class TokenAuthController extends SecurityApiController {
     #private;

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[];
+}

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

@@ -0,0 +1,13 @@
+/**
+ * `@nodefony/framework/grpc` — déclarer un service gRPC dans un module
+ * (ADR-0026 D1).
+ *
+ * Sous-chemin à part : le point d'entrée principal de `@nodefony/framework`
+ * ne cite ni Connect ni protobuf (D12). L'importer charge Connect au
+ * démarrage — ce que fait tout contrôleur gRPC, et seulement lui.
+ *
+ * @experimental Surface gRPC, ADR-0026 D11.
+ */
+export { GrpcController } from "./GrpcController.js";
+export { GrpcService } from "./GrpcService.js";
+export type { GrpcServiceClass } from "./GrpcService.js";

package/dist/types/nodefony/interfaces/IController.d.ts

@@ -1,4 +1,4 @@
-import type { contextRequest, HTTPMethod, HttpResponse, Http2Response, WebsocketResponse, Session, ContextType } from "@nodefony/http";
+import type { contextRequest, HTTPMethod, HttpResponse, Http2Response, WebsocketResponse, Session, ContextType, IUploadedFile } from "@nodefony/http";
 import type { Module, FileClass, MaybePromise } from "nodefony";
 import type { OutgoingHttpHeaders } from "node:http";
 import type { ReadStream } from "node:fs";
@@ -11,7 +11,7 @@ export interface IController {
     session?: Session | null;
     method?: HTTPMethod | undefined;
     query: Record<string, unknown>;
-    files: readonly unknown[];
+    files: readonly IUploadedFile[];
     body: Record<string, unknown>;
     module?: Module | undefined;
     setContext(context: ContextType): void;
@@ -34,6 +34,6 @@ export interface IController {
     getFile(file: FileClass | string): FileClass;
     /** Variante async de `getFile` (stat non bloquant via `FileClass.from`). */
     getFileAsync(file: FileClass | string): Promise<FileClass>;
-    renderFileDownload(file: unknown, options?: unknown, headers?: OutgoingHttpHeaders): Promise<ReadStream>;
-    streamFile(file: FileClass | string, headers?: OutgoingHttpHeaders, options?: Record<string, unknown>): Promise<ReadStream>;
+    renderFileDownload(file: unknown, options?: unknown, headers?: OutgoingHttpHeaders): Promise<ReadStream | null>;
+    streamFile(file: FileClass | string, headers?: OutgoingHttpHeaders, options?: Record<string, unknown>): Promise<ReadStream | null>;
 }

package/dist/types/nodefony/service/router.d.ts

@@ -60,10 +60,11 @@ declare class Router extends Service implements IRequestRouter {
      *   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) :
@@ -111,8 +112,9 @@ declare class Router extends Service implements IRequestRouter {
  * installées du framework feraient échouer `instanceof` en silence. Une
  * lecture de propriété.
  *
- * @param router - le routeur lu sur le contexte (`context.router`).
+ * @param router - le routeur lu sur le contexte (`context.router`) ou le
+ *   service `router` du conteneur.
  * @returns `true` si c'est le Router du framework.
  */
-export declare function isFrameworkRouter(router: IRequestRouter | null | undefined): router is Router;
+export declare function isFrameworkRouter(router: unknown): router is Router;
 export default Router;

package/dist/types/nodefony/src/Controller.d.ts

@@ -1,12 +1,13 @@
 import { Service, Module, type Pci, type Severity, type Msgid, type Message, FileClass } from "nodefony";
-import type { IRequestUser, MaybePromise } from "nodefony";
+import type { DefaultEventsMap, EventsMap, IRequestUser, MaybePromise } from "nodefony";
 import type { IController } from "../interfaces/index.js";
 import Route from "./Route.js";
 import { contextRequest, HTTPMethod, HttpResponse, Session, ContextType, Http2Response, WebsocketResponse } from "@nodefony/http";
-import type { ISseStreamOptions, SseStream } from "@nodefony/http";
+import type { ByteStreamSource, IByteStreamOptions, IByteStreamResult, ISseStreamOptions, IUploadedFile, SseStream } from "@nodefony/http";
 import { OutgoingHttpHeaders } from "node:http";
 import { ReadStream } from "node:fs";
 import Eta from "../service/Eta.js";
+import type { IFileServingConfig } from "../config/config.js";
 type ReadStreamOptions = {
     flags?: string;
     encoding?: BufferEncoding;
@@ -17,6 +18,17 @@ type ReadStreamOptions = {
     start?: number;
     end?: number;
     highWaterMark?: number;
+    /**
+     * `false` coupe les requêtes conditionnelles : ni `ETag`, ni
+     * `Last-Modified`, ni 304/412, ni `Cache-Control` par défaut, et
+     * `If-Range` n'autorise aucune reprise. Pour des fichiers dont la date
+     * n'est pas fiable (archive décompressée, build reproductible : même taille
+     * et même date pour deux contenus) — passer plutôt sa propre `ETag`
+     * (hachage du contenu) garde le 304. Défaut : `fileServing.validators` de
+     * la config du module (`true` d'usine) ; `true` ici le rétablit pour un
+     * appel quand la config l'a coupé.
+     */
+    validators?: boolean;
 };
 /**
  * Parse un header `Range` mono-plage en octets (RFC 9110 §14.1.2).
@@ -50,6 +62,14 @@ export declare function parseByteRange(range: string, length: number): {
  *   dans `initialize()`, ou garde un état sur `this`.
  */
 export type ControllerScope = "request" | "singleton";
+/**
+ * Fixe le défaut des fichiers servis (validateurs, `Cache-Control`) pour
+ * toute l'application. Appelé par le module au boot avec sa config validée.
+ *
+ * @param config - section `fileServing` validée
+ */
+export declare function configureFileServing(config: IFileServingConfig): void;
+export declare function contentDisposition(type: "attachment" | "inline", name: string): string;
 declare class Controller extends Service implements IController {
     #private;
     static prefix: string;
@@ -125,8 +145,8 @@ declare class Controller extends Service implements IController {
      * texte du même corps sont dans {@link body}. Pour une action typée,
      * préférer `@UploadedFiles()`.
      */
-    get files(): readonly unknown[];
-    set files(value: readonly unknown[]);
+    get files(): readonly IUploadedFile[];
+    set files(value: readonly IUploadedFile[]);
     /**
      * Le CORPS de la requête, parsé — nom universel de l'écosystème (Express,
      * Fastify, NestJS). Jamais un paramètre d'URL : ceux-là sont dans
@@ -176,6 +196,13 @@ declare class Controller extends Service implements IController {
      */
     renderResponse(data: unknown, encoding?: BufferEncoding, status?: string | number, headers?: OutgoingHttpHeaders): MaybePromise<Http2Response | HttpResponse | WebsocketResponse>;
     renderView(path: string | FileClass, param?: Record<string, unknown>, status?: string | number, headers?: Record<string, string | number>): Promise<Http2Response | HttpResponse | WebsocketResponse>;
+    /**
+     * Expose le nonce CSP de la requête à la vue (`cspNonce`), lu seulement si
+     * le gabarit s'en sert : un accesseur, pas une valeur — une vue sans
+     * `<script>` ni `<style>` ne tire aucun nonce. Une valeur `cspNonce`
+     * fournie par l'action est gardée.
+     */
+    private withNonceLocal;
     /**
      * Injecte les helpers frontend (`frontendTags`/`frontendDocument`) dans les
      * locals du template (passés en data, pas de registre global de fonctions).
@@ -217,11 +244,72 @@ declare class Controller extends Service implements IController {
      * }
      * ```
      *
+     * Typé par le contrat temps réel de l'application, le flux lit la MÊME carte
+     * que la socket : `this.renderSse<ContractServerEmit<ChatContract>>()`, puis
+     * `sse.send(m, { event: "chat:room" })`. Sans paramètre de type, il reste
+     * libre — un flux hors contrat est valide.
+     *
+     * @typeParam Events - carte des événements du flux (défaut : libre).
      * @param options - battement de cœur, délai `retry:` initial.
      * @returns le flux, ou sa promesse quand une session est à sauver d'abord.
      * @throws HttpError 500 hors HTTP (WebSocket) ou quand la réponse est partie.
      */
-    renderSse(options?: ISseStreamOptions): SseStream | Promise<SseStream>;
+    renderSse<Events extends EventsMap = DefaultEventsMap>(options?: ISseStreamOptions): SseStream<Events> | Promise<SseStream<Events>>;
+    /**
+     * Répond par un FLUX D'OCTETS : un `<video src>`, un `fetch()`, un
+     * téléchargement ou un outil tiers (curl) le consomment comme n'importe quelle
+     * réponse HTTP, une réponse par consommateur. Pour des ÉVÉNEMENTS texte lus
+     * par `EventSource`, voir {@link Controller.renderSse}. Pour UNE source
+     * d'octets diffusée à N lecteurs par la socket, publier un `Uint8Array` sur
+     * un canal temps réel (`@nodefony/realtime`), pas une réponse HTTP.
+     *
+     * La réponse est prise à l'appel ; les en-têtes partent au premier morceau.
+     * Une erreur de la source AVANT lui rend la page d'erreur ordinaire (500, ou
+     * le code d'une `HttpError`) ; APRÈS, le client voit une coupure. La source
+     * appartient au flux dès l'appel : détruite à la fin, quelle qu'en soit la
+     * raison, et détruite aussi quand l'appel lève (un flux web est annulé). La
+     * promesse ne rejette jamais : elle rend la raison de la fin et les octets
+     * envoyés.
+     *
+     * @example
+     * ```ts
+     * const ff = spawn("ffmpeg", args, { stdio: ["ignore", "pipe", "ignore"], windowsHide: true });
+     * try {
+     *   await this.renderStream(ff.stdout, { headers: { "content-type": "video/mp4" } });
+     * } finally {
+     *   ff.kill("SIGKILL"); // le flux est fini, quelle qu'en soit la raison
+     * }
+     * ```
+     *
+     * Relais d'un autre service — le signal coupe l'amont au départ du client ;
+     * ne recopier que `content-type` (`fetch` a déjà décompressé le corps) :
+     * ```ts
+     * const r = await fetch(url, { signal: this.context.signal });
+     * if (!r.ok || r.body === null) throw new HttpError(502);
+     * return this.renderStream(r.body, {
+     *   headers: { "content-type": r.headers.get("content-type") ?? "application/octet-stream" },
+     * });
+     * ```
+     *
+     * 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)`.
+     * @returns la raison de la fin et le nombre d'octets envoyés.
+     * @throws HttpError 500 hors HTTP (WebSocket) ou quand la réponse est partie ;
+     *   429 au-delà du plafond de connexions par IP. La source est alors détruite.
+     */
+    renderStream(source: ByteStreamSource, options?: IByteStreamOptions): Promise<IByteStreamResult>;
     /**
      * Pose la route de la requête courante sur l'instance (per-request).
      *
@@ -281,9 +369,10 @@ declare class Controller extends Service implements IController {
      * @param file - chemin ou `FileClass` du fichier à servir.
      * @param options - options de `createReadStream`.
      * @param headers - en-têtes ajoutés (écrasent ceux posés par défaut).
-     * @returns le flux de lecture, une fois la réponse écoulée.
+     * @returns le flux de lecture, une fois la réponse écoulée — `null` quand
+     *   les préconditions ont répondu 304 ou 412 (cf {@link Controller.streamFile}).
      */
-    renderFileDownload(file: FileClass | string, options?: ReadStreamOptions, headers?: OutgoingHttpHeaders): Promise<ReadStream>;
+    renderFileDownload(file: FileClass | string, options?: ReadStreamOptions, headers?: OutgoingHttpHeaders): Promise<ReadStream | null>;
     /**
      * Envoie un fichier en FLUX, du disque vers la réponse, sans jamais le charger
      * en mémoire.
@@ -295,17 +384,38 @@ declare class Controller extends Service implements IController {
      * `Content-Range`). Annoncer `Accept-Ranges: bytes` depuis ici est un piège :
      * le client croit pouvoir se déplacer et reçoit tout le fichier.
      *
-     * Ce que cette méthode garantit et qui justifie son existence : le NETTOYAGE.
-     * Le flux est ouvert en `autoClose: false` ; un client qui raccroche en plein
-     * téléchargement laisserait sinon un descripteur ouvert et une promesse pendue.
+     * Le cycle de vie est celui de toute réponse en flux
+     * ({@link Controller.renderStream}) : la réponse est prise à l'appel, les
+     * en-têtes partent au premier morceau, le flux est DÉTRUIT (descripteur
+     * fermé) quand le client raccroche. Un fichier illisible à l'ouverture
+     * (`EACCES`) rend la page d'erreur ordinaire, 500 ; une lecture qui échoue
+     * en cours de route coupe la connexion. Sans délai d'inactivité (un disque
+     * n'est pas une source muette).
+     *
+     * **Requêtes conditionnelles** (RFC 9110 §13) : le fichier ENTIER porte une
+     * `ETag` forte et un `Last-Modified`, tirés de sa taille et de sa date de
+     * modification ; `If-Match`, `If-Unmodified-Since`, `If-None-Match` et
+     * `If-Modified-Since` y sont évalués dans l'ordre de §13.2.2 → 304 ou 412,
+     * sans ouvrir le fichier. Une `ETag` ou un `Last-Modified` passés dans
+     * `headers` (ou déjà posés sur la réponse) l'emportent, et servent à la
+     * comparaison. `Cache-Control: private, no-cache` est posé si l'action n'en
+     * fixe aucun — en passer un dans `headers` le remplace. Un EXTRAIT
+     * (`start`/`end`) n'est pas la représentation entière : il ne reçoit ni
+     * validateur ni évaluation.
+     * `{ validators: false }` dans `options` coupe le tout — validateurs,
+     * évaluation et `Cache-Control` par défaut — pour des fichiers dont la date
+     * n'est pas fiable ; une `ETag` tirée du contenu garde, elle, le 304.
      *
      * @param file - chemin ou `FileClass` du fichier à servir.
      * @param headers - en-têtes ajoutés à la réponse (le type MIME est déduit si absent).
      * @param options - options de `createReadStream` (`start`/`end` pour un extrait).
-     * @returns le flux de lecture, une fois la réponse écoulée.
-     * @throws Si la réponse n'est pas disponible, ou si le fichier est illisible.
+     * @returns le flux de lecture, une fois la réponse écoulée — détruit, quelle
+     *   que soit la fin ; `null` quand les préconditions ont répondu 304 ou 412 :
+     *   aucun fichier n'a alors été ouvert.
+     * @throws HttpError 404 si le fichier n'existe pas ; 500 hors HTTP
+     *   (WebSocket) ou quand la réponse est déjà partie.
      */
-    streamFile(file: FileClass | string, headers?: OutgoingHttpHeaders, options?: ReadStreamOptions | undefined): Promise<ReadStream>;
-    renderMediaStream(file: FileClass | string, headers?: OutgoingHttpHeaders, options?: ReadStreamOptions | undefined): Promise<HttpResponse | ReadStream | WebsocketResponse>;
+    streamFile(file: FileClass | string, headers?: OutgoingHttpHeaders, options?: ReadStreamOptions): Promise<ReadStream | null>;
+    renderMediaStream(file: FileClass | string, headers?: OutgoingHttpHeaders, options?: ReadStreamOptions | undefined): Promise<HttpResponse | ReadStream | WebsocketResponse | null>;
 }
 export default Controller;