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

package/dist/nodefony/src/ResourceController.js

@@ -3,7 +3,7 @@ import { assertPageQuery } from "nodefony";
 import { HttpError } from "@nodefony/http";
 // nodefony/src/ResourceController.ts
 /**
-* Controller de ressource **souverain** (V4.2 — POC API souveraine, Phase 2) :
+* Controller de ressource **duplex** (V4.2 — une action, deux transports) :
 * la logique métier est écrite UNE fois dans le service de ressource, les
 * actions de la sous-classe ne sont que des portes (REST, WS-RPC `invoke`,
 * GraphQL à venir) qui retournent la **valeur brute** — `returnController`
@@ -38,8 +38,12 @@ import { HttpError } from "@nodefony/http";
 *     return this.listResource();
 *   }
 *   \@route("books-get", { path: "/{id}", requirements: { methods: ["GET", "WEBSOCKET"] } })
-*   detail(\@Param("id") id: string) {
-*     return this.getResource(id);
+*   async detail(\@Param("id") id: string) {
+*     // `null` rendu tel quel = « l'action répond elle-même » : la requête
+*     // pendrait jusqu'au délai d'expiration. La porte décide du 404.
+*     const found = await this.getResource(id);
+*     if (!found) throw new HttpError(`Book ${id} not found`, 404);
+*     return found;
 *   }
 * }
 * ```
@@ -117,6 +121,10 @@ var ResourceController = class extends Controller {
 	/**
 	* Lit une entité par id — `null` si absente (la porte décide du 404).
 	*
+	* ⚠️ Ne pas rendre ce `null` tel quel depuis une action : pour le Resolver,
+	* `null` veut dire « l'action répond elle-même », et la requête attend
+	* alors son délai d'expiration. Lever un `HttpError` 404.
+	*
 	* `options.relations` charge les associations dans la foulée. La porte doit
 	* n'y laisser passer que des relations qu'elle a DÉCLARÉES : un `include`
 	* libre laisse le client nommer n'importe quelle association, donc lire des

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/syslogFilters.js

@@ -29,6 +29,8 @@ const SYSLOG_FILTERS = {
 	module: "string",
 	/** Catégorie de message (msgid) — inclusion insensible à la casse. */
 	msgid: "string",
+	/** Module exclu — égalité insensible à la casse (`NODEFONY` = le framework). */
+	excludeModule: "string",
 	/** Protocole d'origine ; absent = les deux. */
 	protocol: ["ws", "http"],
 	/**
@@ -42,6 +44,10 @@ const SYSLOG_FILTERS = {
 	* seconde liste ne peut se périmer.
 	*/
 	flow: { each: Object.keys(FLOW_STEPS) },
+	/** Écarte les lignes d'accès de la console d'administration elle-même. */
+	hideConsole: "boolean",
+	/** Une ligne par requête (sa ligne d'accès), avec le nombre de lignes regroupées. */
+	groupByRequest: "boolean",
 	/** Borne basse d'horodatage (epoch ms, incluse). */
 	from: "int",
 	/** Borne haute d'horodatage (epoch ms, incluse). */

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

@@ -35,11 +35,13 @@ declare class AdminApiController extends Controller {
     constructor(context: ContextType);
     /**
      * Action générique appelée par le Resolver pour toute route admin — DUPLEX
-     * (« API souveraine ») : même exécution sur les deux transports, seul
+     * (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;