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

package/dist/nodefony/src/SecurityApiController.js

@@ -1,23 +1,46 @@
 import Controller from "./Controller.js";
+import { SESSION_AUTH_CHALLENGE } from "nodefony";
 // nodefony/src/SecurityApiController.ts
 const NO_STORE = { "cache-control": "no-store" };
 /**
+* En-têtes d'un 401 : ceux reçus, plus le défi par défaut
+* ({@link SESSION_AUTH_CHALLENGE}) s'ils n'en portent aucun — RFC 9110 §15.5.2
+* exige un `WWW-Authenticate` sur TOUT 401. Un défi posé par l'appelant (un
+* `Bearer` de ressource protégée, par exemple) garde la main.
+*
+* Chemin froid : n'est appelé que pour un 401.
+*
+* @param headers - les en-têtes déjà prévus pour la réponse.
+* @returns les mêmes en-têtes, défi compris.
+*/
+function withAuthChallenge(headers) {
+	if (headers !== void 0) {
+		for (const name in headers) if (name.toLowerCase() === "www-authenticate") return { ...headers };
+	}
+	return {
+		...headers,
+		"www-authenticate": SESSION_AUTH_CHALLENGE
+	};
+}
+/**
 * Base des contrôleurs d'authentification (`/nodefony/security/api/*`) : toute
-* réponse JSON part en `Cache-Control: no-store`.
+* réponse JSON part en `Cache-Control: no-store`, et tout 401 porte un défi.
 *
 * Ces réponses portent une identité, un jeton, un secret affiché une seule
 * fois (clé API, secret TOTP, codes de récupération) ou leur refus. Un cookie
 * ou un en-tête dans la requête n'empêche pas un cache partagé de STOCKER la
-* réponse (RFC 9111 §3) ; RFC 6749 §5.1 exige `no-store` sur un jeton. La règle
-* vit ici, une fois : une action ajoutée à un contrôleur héritier ne peut pas
-* l'oublier. Un en-tête passé par l'action garde la priorité.
+* réponse (RFC 9111 §3) ; RFC 6749 §5.1 exige `no-store` sur un jeton. Un 401
+* reçoit le défi par défaut ({@link withAuthChallenge}, RFC 9110 §15.5.2). Ces
+* règles vivent ici, une fois : une action ajoutée à un contrôleur héritier ne
+* peut pas les oublier. Un en-tête passé par l'action garde la priorité.
 */
 var SecurityApiController = class extends Controller {
 	renderJson(obj, status, headers) {
-		return super.renderJson(obj, status, {
+		const merged = {
 			...NO_STORE,
 			...headers
-		});
+		};
+		return super.renderJson(obj, status, Number(status) === 401 ? withAuthChallenge(merged) : merged);
 	}
 };
-export { SecurityApiController as default };
+export { SecurityApiController as default, withAuthChallenge };

package/dist/nodefony/src/conditionalRequest.js

@@ -0,0 +1,103 @@
+// nodefony/src/conditionalRequest.ts
+/** Une `entity-tag` (RFC 9110 §8.8.3) : `W/` facultatif, puis une chaîne entre guillemets. */
+const ENTITY_TAG = /(?:W\/)?"[^"]*"/g;
+/**
+* Validateurs d'un fichier, tirés de ses métadonnées sans le lire.
+*
+* L'`ETag` est FORTE : taille et date de modification à la microseconde, deux
+* grandeurs qu'une écriture change. C'est la forme que posent les serveurs de
+* fichiers courants, et la seule qui autorise une reprise (§13.1.5).
+*
+* @param stats - taille et date de modification du fichier
+* @param now - instant de la réponse (ms)
+* @returns les validateurs du fichier
+*/
+function fileValidators(stats, now) {
+	const micros = Math.floor(stats.mtimeMs * 1e3);
+	const seconds = Math.floor(Math.min(stats.mtimeMs, now) / 1e3) * 1e3;
+	return {
+		etag: `"${stats.size.toString(16)}-${micros.toString(16)}"`,
+		lastModified: seconds,
+		lastModifiedStrong: stats.mtimeMs + 1e3 <= now
+	};
+}
+/**
+* Date HTTP (RFC 9110 §5.6.7) lue en ms, ou `null` si la valeur n'en est pas
+* une — une condition sur une date invalide DOIT être ignorée (§13.1.3, §13.1.4).
+*
+* @param value - valeur brute de l'en-tête
+*/
+function parseHttpDate(value) {
+	if (value === void 0) return null;
+	const ms = Date.parse(value);
+	return Number.isNaN(ms) ? null : ms;
+}
+/** Les `entity-tag` d'une liste, ou `"*"`. */
+function entityTags(value) {
+	if (value.trim() === "*") return "*";
+	return value.match(ENTITY_TAG) ?? [];
+}
+/** Partie opaque d'une `entity-tag` (sans `W/`). */
+function opaque(tag) {
+	return tag.startsWith("W/") ? tag.slice(2) : tag;
+}
+/** Comparaison FORTE (§8.8.3.2) : aucune des deux n'est faible, et elles sont identiques. */
+function strongMatch(a, b) {
+	return !a.startsWith("W/") && !b.startsWith("W/") && a === b;
+}
+/** Comparaison FAIBLE (§8.8.3.2) : parties opaques identiques. */
+function weakMatch(a, b) {
+	return opaque(a) === opaque(b);
+}
+/**
+* Évalue les préconditions d'une requête sur une représentation qui EXISTE,
+* dans l'ordre de RFC 9110 §13.2.2 — `If-Match`, sinon `If-Unmodified-Since` ;
+* puis `If-None-Match`, sinon `If-Modified-Since`. `Range` et `If-Range`
+* viennent après, s'il faut servir (voir {@link ifRangeHolds}).
+*
+* @param method - méthode de la requête
+* @param headers - en-têtes de la requête
+* @param validators - validateurs de la représentation
+* @returns 200 pour servir, 304 si rien n'a changé (GET et HEAD seulement),
+*   412 si une condition est fausse
+*/
+function evaluatePreconditions(method, headers, validators) {
+	const read = method === "GET" || method === "HEAD";
+	const ifMatch = headers["if-match"];
+	if (ifMatch !== void 0) {
+		const tags = entityTags(ifMatch);
+		const { etag } = validators;
+		if (!(tags === "*" || etag !== null && tags.some((tag) => strongMatch(tag, etag)))) return 412;
+	} else {
+		const since = parseHttpDate(headers["if-unmodified-since"]);
+		if (since !== null && validators.lastModified !== null && validators.lastModified > since) return 412;
+	}
+	const ifNoneMatch = headers["if-none-match"];
+	if (ifNoneMatch !== void 0) {
+		const tags = entityTags(ifNoneMatch);
+		const { etag } = validators;
+		if (tags === "*" || etag !== null && tags.some((tag) => weakMatch(tag, etag))) return read ? 304 : 412;
+	} else if (read) {
+		const since = parseHttpDate(headers["if-modified-since"]);
+		if (since !== null && validators.lastModified !== null && validators.lastModified <= since) return 304;
+	}
+	return 200;
+}
+/**
+* Une condition `If-Range` tient-elle (RFC 9110 §13.1.5) ? Vraie, la plage
+* demandée est servie (206) ; fausse, `Range` est ignoré et la représentation
+* part entière (200) — un client ne recolle jamais deux versions.
+*
+* Une étiquette tient si elle est FORTEMENT égale ; une date, si elle égale
+* exactement `Last-Modified` ET que celle-ci est un validateur fort.
+*
+* @param value - valeur brute de `If-Range`
+* @param validators - validateurs de la représentation
+*/
+function ifRangeHolds(value, validators) {
+	const trimmed = value.trim();
+	if (trimmed.startsWith("\"") || trimmed.startsWith("W/")) return validators.etag !== null && strongMatch(trimmed, validators.etag);
+	const date = parseHttpDate(trimmed);
+	return date !== null && validators.lastModifiedStrong && validators.lastModified === date;
+}
+export { evaluatePreconditions, fileValidators, ifRangeHolds, parseHttpDate };

package/dist/nodefony/src/docsReader.js

@@ -1,10 +1,10 @@
 import { basename, dirname, extname, join } from "node:path";
 import { findProjectRoot, isDocVisible, packageManagerCommandLines, packageManagerExecArgs, portableSpawn, readDocScope, readSymbolsGraph, resolvePackageManager } from "nodefony";
 import { existsSync } from "node:fs";
-import { promisify } from "node:util";
 import { readFile, readdir, stat } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { execFile, spawn } from "node:child_process";
+import { promisify } from "node:util";
 // nodefony/src/docsReader.ts
 const execFileAsync = promisify(execFile);
 /**

package/dist/nodefony/src/idempotency.js

@@ -3,7 +3,7 @@ import { createHash } from "node:crypto";
 // nodefony/src/idempotency.ts
 /**
 * Logique **pure et partagée** de la porte d'idempotence des mutations, conforme à
-* `draft-ietf-httpapi-idempotency-key-header-06`. Source unique de la sémantique
+* `draft-ietf-httpapi-idempotency-key-header-08`. Source unique de la sémantique
 * (statuts normatifs, scope de clé, fingerprint, bornage) consommée par les DEUX
 * call-sites qui mutent :
 *  - le **data plane admin** (`AdminApiController` — réponse `{status,headers,body}`) ;

package/dist/nodefony/src/loginPage.js

@@ -1,4 +1,4 @@
-import { LOGIN_PAGE_ASSETS_BASE, LOGIN_PAGE_LAYOUTS, LOGIN_PAGE_SKINS, LOGIN_PAGE_SKIN_SPECS, LOGIN_PAGE_THEME_KEY, OAUTH2_CANCELLED_REASON, isLoginPageSkin, loginPageSkinFile, oauth2AuthorizePath, safeRedirectPath } from "nodefony";
+import { CSP_NONCE_META_PROPERTY, LOGIN_PAGE_ASSETS_BASE, LOGIN_PAGE_LAYOUTS, LOGIN_PAGE_SKINS, LOGIN_PAGE_SKIN_SPECS, LOGIN_PAGE_THEME_KEY, OAUTH2_CANCELLED_REASON, isLoginPageSkin, loginPageSkinFile, oauth2AuthorizePath, safeRedirectPath } from "nodefony";
 // nodefony/src/loginPage.ts
 /**
 * Mémoïse une ressource chargée de façon asynchrone : le SUCCÈS est gardé, un
@@ -158,6 +158,7 @@ const LOGIN_PAGE_TEMPLATE = `<!doctype html>
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <meta name="color-scheme" content="dark light" />
     <meta name="robots" content="noindex" />
+    <% if (it.nonce) { %><meta property="${CSP_NONCE_META_PROPERTY}" nonce="<%= it.nonce %>"><% } %>
     <title><%= it.title %> — <%= it.brand %></title>
     <link rel="icon" href="<%= it.logoHref %>" type="image/svg+xml" />
 <% if (!it.theme) { %>

package/dist/nodefony/src/scopeCatalog.js

@@ -1,5 +1,5 @@
-import { extractActionScopes } from "../decorators/routerDecorators.js";
 import router_default from "../service/router.js";
+import { extractActionScopes } from "../decorators/routerDecorators.js";
 // nodefony/src/scopeCatalog.ts
 /**
 * P6.8 — **Découverte au boot** : scanne TOUTES les routes montées (`Router.routes`)

package/dist/nodefony/src/viewNonce.js

@@ -0,0 +1,58 @@
+// nodefony/src/viewNonce.ts
+/**
+* Signature CSP des vues : chaque `<script>` et `<style>` ÉCRIT dans un
+* gabarit reçoit le nonce de la requête, sans geste de l'auteur.
+*
+* La politique par défaut exige un nonce sur les scripts (`'strict-dynamic'`)
+* et sur les styles (ADR-0024 §C1, §C2). Une page écrite vite, par quelqu'un
+* qui ignore tout de la CSP, ne doit pas être bloquée (§C0) : la signature se
+* pose donc au rendu, par le framework.
+*
+* Elle porte sur le TEXTE DU GABARIT, avant que les données y soient insérées :
+* une balise que les données apporteraient (une valeur insérée brute par
+* `<%~ %>`) n'est jamais signée — c'est ce qui garde au nonce sa valeur contre
+* l'injection. Même principe que l'`index.html` d'un front bâti
+* (`prebuiltUi.ts#splitAroundNonce`).
+*/
+/** Variable de vue qui porte le nonce CSP de la requête (`<%= cspNonce %>`). */
+const VIEW_NONCE_LOCAL = "cspNonce";
+/** Ouverture d'une balise `<script` ou `<style` qui ne porte pas de `nonce`. */
+const UNSIGNED_TAG_OPEN = /<(script|style)\b(?![^>]*\bnonce\s*=)/giu;
+/** Une balise Eta (`<% %>`, `<%= %>`, `<%~ %>`) : du code, jamais du balisage. */
+const ETA_TAG = /<%[\s\S]*?%>/gu;
+/** Attribut inséré : le nonce, lu dans les variables de la vue à chaque rendu. */
+const NONCE_ATTRIBUTE = ` nonce="<%= it.${VIEW_NONCE_LOCAL} %>"`;
+/**
+* Ajoute le nonce de la requête à chaque `<script>` et `<style>` littéral du
+* gabarit qui n'en porte pas.
+*
+* Une balise déjà signée par l'auteur est laissée telle quelle ; un `<script`
+* écrit À L'INTÉRIEUR d'une balise Eta (une chaîne de code) n'est jamais
+* touché. Un `<script>` dont un attribut vient des données
+* (`src="<%= it.url %>"`) n'est pas signé non plus : le signer exécuterait
+* l'URL qu'elles apportent. L'auteur qui la tient pour sûre signe lui-même
+* (`nonce="<%= it.cspNonce %>"`). Le rendu doit fournir la variable
+* {@link VIEW_NONCE_LOCAL}.
+*
+* @param source - texte du gabarit Eta, tel que lu sur le disque.
+* @returns le gabarit signé — la MÊME chaîne quand il n'y a rien à signer.
+*/
+function signTemplateTags(source) {
+	UNSIGNED_TAG_OPEN.lastIndex = 0;
+	if (!UNSIGNED_TAG_OPEN.test(source)) return source;
+	let etaRanges = null;
+	ETA_TAG.lastIndex = 0;
+	for (let m = ETA_TAG.exec(source); m !== null; m = ETA_TAG.exec(source)) (etaRanges ??= []).push(m.index, m.index + m[0].length);
+	return source.replace(UNSIGNED_TAG_OPEN, (tag, name, offset) => {
+		if (etaRanges !== null) for (let i = 0; i < etaRanges.length; i += 2) {
+			const start = etaRanges[i] ?? 0;
+			if (start > offset) {
+				if (name.toLowerCase() === "script" && start < source.indexOf(">", offset)) return tag;
+				break;
+			}
+			if (offset < (etaRanges[i + 1] ?? 0)) return tag;
+		}
+		return tag + NONCE_ATTRIBUTE;
+	});
+}
+export { VIEW_NONCE_LOCAL, signTemplateTags };

package/dist/types/index.d.ts

@@ -16,6 +16,7 @@ import IssuerMetadataController, { mountIssuerMetadataRoutes } from "./nodefony/
 import ProtectedResourceMetadataController, { mountProtectedResourceRoutes, protectedResourceRoutePaths, collectProtectedResources } from "./nodefony/controller/ProtectedResourceMetadataController.js";
 import WebAuthnController, { mountWebAuthnRoutes } from "./nodefony/controller/WebAuthnController.js";
 import OAuth2Controller, { mountOAuth2Routes } from "./nodefony/controller/OAuth2Controller.js";
+import CspReportController, { mountCspReportRoute } from "./nodefony/controller/CspReportController.js";
 import BenchController, { mountBenchRoutes } from "./nodefony/controller/BenchController.js";
 import ApiKeyController, { mountApiKeyRoutes } from "./nodefony/controller/ApiKeyController.js";
 import TotpController, { mountTotpRoutes } from "./nodefony/controller/TotpController.js";
@@ -24,7 +25,7 @@ import { createFrameworkAdminApi } from "./nodefony/src/FrameworkAdminApi.js";
 import { buildPlaygroundSnapshot } from "./nodefony/src/PlaygroundAdminApi.js";
 import { createSyslogAdminApi } from "./nodefony/src/SyslogAdminApi.js";
 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 } from "./nodefony/decorators/routerDecorators.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 type { IRouteSchema, RouteInput, RoutePart, RawRouteInput, RawRouteParams, RawRouteQuery, RawRouteHeaders, } from "./nodefony/src/routeSchema.js";
@@ -79,7 +80,7 @@ declare class Framework extends Module<IFrameworkConfig> {
     onKernelReady(): Promise<this>;
 }
 export default Framework;
-export { Controller, ResourceController, Route, Router, FRAMEWORK_ROUTER, isFrameworkRouter, Resolver, AdminBroker, MemoryIdempotencyStore, AdminApiController, SessionAuthController, mountSessionAuthRoutes, LoginPageController, mountLoginPage, TokenAuthController, mountTokenAuthRoutes, IssuerMetadataController, mountIssuerMetadataRoutes, ProtectedResourceMetadataController, mountProtectedResourceRoutes, protectedResourceRoutePaths, collectProtectedResources, WebAuthnController, mountWebAuthnRoutes, OAuth2Controller, mountOAuth2Routes, BenchController, mountBenchRoutes, ApiKeyController, mountApiKeyRoutes, TotpController, mountTotpRoutes, createKernelAdminApi, createFrameworkAdminApi, createSyslogAdminApi, buildPlaygroundSnapshot, Eta, route, controller, controllers, 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, registerIdempotencyStore, getIdempotencyStoreFactory, listIdempotencyStores, };
+export { Controller, ResourceController, Route, Router, FRAMEWORK_ROUTER, isFrameworkRouter, Resolver, AdminBroker, MemoryIdempotencyStore, AdminApiController, SessionAuthController, mountSessionAuthRoutes, LoginPageController, mountLoginPage, TokenAuthController, mountTokenAuthRoutes, IssuerMetadataController, mountIssuerMetadataRoutes, ProtectedResourceMetadataController, mountProtectedResourceRoutes, protectedResourceRoutePaths, collectProtectedResources, WebAuthnController, mountWebAuthnRoutes, OAuth2Controller, mountOAuth2Routes, CspReportController, mountCspReportRoute, BenchController, mountBenchRoutes, ApiKeyController, mountApiKeyRoutes, TotpController, mountTotpRoutes, createKernelAdminApi, createFrameworkAdminApi, createSyslogAdminApi, buildPlaygroundSnapshot, Eta, route, controller, controllers, 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, registerIdempotencyStore, getIdempotencyStoreFactory, listIdempotencyStores, };
 export { frameworkConfigSchema } from "./nodefony/config/config.js";
 export type { IdempotencyStoreFactory, IIdempotencyStoreFactoryContext, } from "./nodefony/src/idempotencyStoreRegistry.js";
 export type { SecurityClause, SecurityRequirement, IAuthenticationRequirement, IRequireAuthenticationOptions, CspDirectives, IParamArgSource, ParamMeta, } from "./nodefony/decorators/routerDecorators.js";

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/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/interfaces/IController.d.ts

@@ -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

@@ -111,8 +111,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, 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,13 @@ 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;
 declare class Controller extends Service implements IController {
     #private;
     static prefix: string;
@@ -176,6 +195,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 +243,61 @@ 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" },
+     * });
+     * ```
+     *
+     * @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 +357,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 +372,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;