@nodefony/http 10.0.0-alpha.3 → 10.0.0-alpha.5

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

@@ -10,7 +10,16 @@ type ForgeModule = typeof import("node-forge");
 export type CertHash = "sha256" | "sha384" | "sha512";
 /** Stratégie de fourniture du certificat exposée en configuration. */
 export type CertStrategyConfig = "auto" | "mkcert" | "selfsigned" | "explicit";
-export interface OpensslOptions {
+/**
+ * Options de génération du certificat AUTO-SIGNÉ (node-forge, JavaScript pur —
+ * aucun binaire externe n'est invoqué).
+ *
+ * ⚠️ Portée : ces réglages ne valent QUE pour la stratégie `selfsigned`. Sous
+ * `mkcert` (le défaut en développement) ils sont ignorés — mkcert ne reçoit que
+ * les noms d'hôtes — et sous `strategy: "explicit"` le certificat est fourni,
+ * donc rien n'est généré.
+ */
+export interface SelfSignedOptions {
     /** Taille de la clé RSA (bits). */
     size: number;
     /** Algorithme de hachage de la signature (jamais SHA-1). */
@@ -48,7 +57,7 @@ export interface CertificateOptions {
      * (Let's Encrypt, ingress, reverse-proxy) : Nodefony n'est pas une CA.
      */
     strategy?: CertStrategyConfig;
-    openssl: OpensslOptions;
+    selfSigned: SelfSignedOptions;
     dev: CertificateDevOptions;
     san?: CertificateSanOptions;
     /** Permissions POSIX de la clé privée écrite (0600 = owner-only). */
@@ -137,6 +146,28 @@ declare class Certificate extends Service {
     loadForge(): Promise<ForgeModule>;
     /** Accès au backend forge déjà chargé (lève si `loadForge` n'a pas été appelé). */
     private get forgeLib();
+    /**
+     * Fabrique-t-on un certificat au démarrage ?
+     *
+     * 🔴 Seulement si un serveur TLS est ACTIF. Sans cette question, le hook
+     * ci-dessous écrit dans `nodefony/config/certificates` à CHAQUE boot — y
+     * compris celui d'une application qui a coupé son écoute TLS, et y compris un
+     * run de console qui n'ouvre aucun port.
+     *
+     * Ce qu'il en coûtait, mesuré sur une image générée : le code d'une image
+     * appartient à `root` et le processus tourne en `1000` (c'est voulu — une
+     * application qui peut réécrire son propre `dist/` offre à une faille un moyen
+     * de PERSISTER). Le `mkdir` mourait donc en `EACCES`, le hook de boot était
+     * « critique », et l'application ne démarrait PAS — quel que soit son préset.
+     * L'erreur nommait un dossier de certificats sur une application qui n'en veut
+     * aucun : elle envoyait chercher du côté du TLS un défaut de permission.
+     *
+     * C'est aussi ce que le gabarit d'application promet en toutes lettres : en
+     * production, l'écoute TLS est coupée tant qu'aucun port HTTPS n'est demandé,
+     * précisément pour ne PAS fabriquer une clé RSA à chaque démarrage de chaque
+     * exemplaire. La promesse était écrite ; rien ne la tenait.
+     */
+    private get tlsWanted();
     init(): Promise<this>;
     /**
      * Numéro de série X.509 — RFC 5280 §4.1.2.2 : entier positif unique par CA.

package/dist/types/nodefony/service/http-kernel.d.ts

@@ -4,7 +4,7 @@ import type { Controller } from "@nodefony/framework";
 import HttpError from "../src/errors/httpError.js";
 import { type TrustProxyChecker } from "../src/context/trustProxy.js";
 import type { IRateLimitStore } from "../src/rateLimit/IRateLimitStore.js";
-import { type TrustedHostsConfig } from "../src/context/domainMatcher.js";
+import { type ITrustedHostsConfig } from "../src/context/domainMatcher.js";
 import http from "node:http";
 import http2 from "node:http2";
 import type { IncomingMessage } from "node:http";
@@ -79,7 +79,7 @@ declare class HttpKernel extends Service implements IHttpKernelInterface {
     ca: string;
     serverStatic: Statics | null;
     domain: string;
-    trustedHosts?: TrustedHostsConfig;
+    trustedHosts?: ITrustedHostsConfig;
     domainCheck: boolean;
     regAlias: RegExp[];
     module: Module;

package/dist/types/nodefony/src/context/domainMatcher.d.ts

@@ -28,7 +28,7 @@ export type DomainPattern = string | RegExp;
  *   filtre déjà le `Host`, cf doctrine cloud-native).
  * - `string` / `string[]` : patterns additionnels (exact ou `*`-wildcard).
  */
-export type TrustedHostsConfig = boolean | DomainPattern | DomainPattern[];
+export type ITrustedHostsConfig = boolean | DomainPattern | DomainPattern[];
 /**
  * Compile UN pattern de domaine en `RegExp` selon la politique sûre.
  *
@@ -56,7 +56,30 @@ export declare function compileDomainPatterns(patterns: DomainPattern | DomainPa
  * @param isDev - vrai en environnement `development` (ajoute le loopback).
  * @returns liste de `RegExp` pour {@link isDomainAllowed}.
  */
-export declare function compileTrustedHosts(domain: string, trusted: TrustedHostsConfig | undefined, isDev: boolean): RegExp[];
+export declare function compileTrustedHosts(domain: string, trusted: ITrustedHostsConfig | undefined, isDev: boolean): RegExp[];
+/**
+ * Rend les NOMS d'hôtes que la barrière `trustedHosts` accepte — la même
+ * politique que {@link compileTrustedHosts}, mais lisible par un humain ou par
+ * un générateur de configuration (`server_name` nginx, `hdr(host)` haproxy).
+ *
+ * Pourquoi une seconde lecture de la même règle : une `RegExp` ne se réécrit pas
+ * en nom d'hôte. La commande `proxy:generate` lisait donc `trustedHosts` à sa
+ * façon, en le supposant TOUJOURS `string[]` — alors que sa valeur par DÉFAUT
+ * est `false`, celle de toute application générée. Une politique lue à deux
+ * endroits finit par diverger : ici les deux fonctions partent de la même
+ * valeur, et la règle « le domaine canonique est toujours accepté » n'est
+ * écrite qu'une fois.
+ *
+ * Le loopback de développement n'en fait volontairement pas partie : une
+ * configuration de proxy décrit un déploiement, pas la machine de l'auteur.
+ *
+ * @param domain - domaine canonique du serveur (`kernel.domain`).
+ * @param trusted - config `http.trustedHosts` (optionnelle).
+ * @returns les noms acceptés, sans doublon. **Vide** si `trusted === true`
+ *   (bypass : le proxy filtre déjà le `Host`, aucun nom n'est à imposer) ; les
+ *   motifs `RegExp` sont écartés, faute d'être exprimables en nom d'hôte.
+ */
+export declare function resolveTrustedHostNames(domain: string, trusted: ITrustedHostsConfig | undefined): string[];
 /**
  * Teste un `Host` entrant contre une liste de `RegExp` pré-compilée.
  *

package/dist/types/nodefony/src/proxy/generateProxyConfig.d.ts

@@ -16,6 +16,22 @@ export interface ProxyStaticMount {
     /** Dossier absolu servi. */
     dir: string;
 }
+/**
+ * Terminaison TLS au frontal — **nginx uniquement**.
+ *
+ * Les chemins sont ceux vus par le PROXY à l'exécution, jamais ceux de la
+ * machine qui a généré la configuration : une clé privée n'entre pas dans une
+ * image (une couche reste lisible même effacée plus loin), elle se MONTE au
+ * déploiement — volume compose, secret Kubernetes.
+ */
+export interface ProxyTlsTermination {
+    /** Chaîne de certificats servie au client (`fullchain.pem`). */
+    certPath: string;
+    /** Clé privée correspondante (`privkey.pem`). */
+    keyPath: string;
+    /** Port d'écoute TLS du proxy. */
+    listen: number;
+}
 /** Modèle d'introspection consommé par les générateurs. */
 export interface ProxyIntrospection {
     /** `server_name` (hôtes de confiance, IP exclues). Vide → `_` (catch-all). */
@@ -55,6 +71,14 @@ export interface ProxyIntrospection {
      * saines.
      */
     keepaliveIntervalMs: number;
+    /**
+     * Terminaison TLS au frontal, ou `null` pour n'écouter qu'en clair.
+     *
+     * **nginx seulement** : haproxy exige un PEM COMBINÉ (certificat + clé dans
+     * un même fichier), que Nodefony ne fabrique pas — la commande REFUSE donc
+     * l'option sur cette cible plutôt que de l'accepter et de la jeter.
+     */
+    tls: ProxyTlsTermination | null;
 }
 /** Valeurs par défaut d'un modèle d'introspection (complété par la commande). */
 export declare const defaultIntrospection: ProxyIntrospection;

package/docs/cookies.md

@@ -284,8 +284,8 @@ posé pendant la **phase HTTP** qui précède l'upgrade. La forme d'un cookie d
 
 Les cookies **applicatifs** ne se configurent pas par schéma : on les construit dans le code, avec les
 défauts sûrs de `cookieDefaultSettings` (`cookie.ts:43`). Le seul cookie **piloté par la config** est celui
-de la **session** — bloc Zod `sessionCookieSchema` (`config.ts:727`), avec notamment `hostPrefix`
-(`config.ts:730`) qui décide du préfixe `__Host-`. Tout cela est documenté dans [Sessions](session.md) :
+de la **session** — bloc Zod `sessionCookieSchema` (`config.ts:748`), avec notamment `hostPrefix`
+(`config.ts:770`) qui décide du préfixe `__Host-`. Tout cela est documenté dans [Sessions](session.md) :
 cette page ne le duplique pas.
 
 Le nom effectif du cookie de session (avec ou sans `__Host-` selon le transport) est calculé par

package/docs/observabilite.md

@@ -112,7 +112,7 @@ un `requestId`, un `traceparent` et un contrat de logger **uniques** couvrent le
 
 **Le `requestId` est un citoyen du contexte, pas un décor.** Il naît dans le constructeur de base
 `Context.requestId = randomUUID()` (`Context.ts:244`), voyage dans l'ALS via `RequestContext.run(...)`
-(`http-kernel.ts:1300` pour HTTP, `http-kernel.ts:1590` pour WS), et se lit de n'importe où avec
+(`http-kernel.ts:435` pour HTTP, `http-kernel.ts:435` pour WS), et se lit de n'importe où avec
 `RequestContext.getRequestId()` — un controller, un service, un adapter ORM, sans jamais le threader.
 
 **La ligne de bilan est branchable.** Le kernel ne code pas un format en dur : il consulte un
@@ -420,7 +420,7 @@ instancié **qu'en dev** (fuite d'info + coût en prod).
 | Le `X-Request-Id` que j'envoie n'est pas réfléchi   | Valeur non conforme (espace, CR/LF, non-ASCII, > 128) → **rejetée** | Utiliser `[A-Za-z0-9._-]{1,128}` (UUID/nanoid/traceparent OK) — sinon UUID serveur |
 | Les logs de fin de requête n'ont pas de `requestId` | Ils sont émis hors bulle ALS                                        | Déjà géré : l'override `log()` rouvre une micro-bulle (`Context.ts:459`)           |
 | Réponse HTTP/2 sans `x-request-id`                  | Chemin de réponse h2 distinct du 1.1                                | Déjà géré (`http2/Response.ts:71`) — le port 5152 réfléchit aussi                  |
-| Pas de `traceparent` renvoyé sur un WebSocket       | `ws` n'expose pas l'écriture d'en-tête au handshake                 | Attendu — la trace WS reste propagée en ALS (`http-kernel.ts:1296`)                |
+| Pas de `traceparent` renvoyé sur un WebSocket       | `ws` n'expose pas l'écriture d'en-tête au handshake                 | Attendu — la trace WS reste propagée en ALS (`http-kernel.ts:1505`)                |
 | Frame WS binaire loggée en `{"0":..,"1":..}`        | Sérialisation naïve d'un Buffer                                     | Déjà géré : résumé `[binary N B]` (`wsLogContent.ts:63`)                           |
 | Le format de log ne change pas malgré la config     | Un `setRequestLogger(...)` programmatique gagne sur la config       | L'override est volontaire (last setter wins) — retirer l'appel, ou le régler       |
 | Logs d'audit trop volumineux en prod                | `stack` sérialisée, ou 100 % des 2xx audités                        | `includeStack:false` (défaut prod) + `sampleRate` via `setRequestLogger`           |

package/docs/rate-limit.md

@@ -106,7 +106,7 @@ Trois choix structurent l'implémentation, et chacun est un compromis assumé.
 
 **Désactivé par défaut — opt-in explicite.** En cloud-native, le plafond par IP est souvent mieux placé
 à l'**ingress/gateway** (il voit tout le trafic, tous les pods, et rejette avant le coût TLS). Le module
-laisse donc `rateLimit` désarmé par défaut (`config.ts:830`) : `null` tant qu'on ne l'active pas → **0
+laisse donc `rateLimit` désarmé par défaut (`config.ts:1065`) : `null` tant qu'on ne l'active pas → **0
 coût** sur le chemin chaud. On l'active quand on n'a **pas** d'edge devant soi (bare-metal, VPS), ou en
 défense en profondeur.
 
@@ -147,7 +147,7 @@ export default defineConfig(() => ({
 ```
 
 Les trois clés `enabled` / `windowS` / `max` sont **éditables à chaud** (`runtimeMutable`) : le kernel
-reconstruit le compteur sans redémarrage (`configureRateLimit()`, `http-kernel.ts:322`).
+reconstruit le compteur sans redémarrage (`configureRateLimit()`, `http-kernel.ts:416`).
 
 ### 2. Observer le 429 et les en-têtes
 
@@ -214,14 +214,14 @@ Autour de ce cœur, le kernel orchestre le cycle de vie :
 
 ## ⚙️ Configuration
 
-Table dérivée de `rateLimitSchema` (`config.ts:847`). Tout est optionnel : ce sont les défauts du
+Table dérivée de `rateLimitSchema` (`config.ts:868`). Tout est optionnel : ce sont les défauts du
 schéma, écrits ici pour les montrer.
 
 | Option        | Type         | Défaut    | Effet                                                                            | Chaud |
 | ------------- | ------------ | --------- | -------------------------------------------------------------------------------- | ----- |
 | `enabled`     | bool         | `false`   | Arme le rate-limit (HTTP **et** handshakes WS, même compteur) (`config.ts:849`). | oui   |
 | `windowS`     | int (s)      | `60`      | Largeur de la fenêtre fixe ; le compteur par IP repart à zéro (`config.ts:860`). | oui   |
-| `max`         | int          | `300`     | Requêtes/IP/fenêtre ; au-delà `429` + `Retry-After` (`config.ts:871`).           | oui   |
+| `max`         | int          | `300`     | Requêtes/IP/fenêtre ; au-delà `429` + `Retry-After` (`config.ts:892`).           | oui   |
 | `maxTracked`  | int (≥ 1000) | `100 000` | Borne mémoire : IP suivies ; au cap, purge puis éviction FIFO (`config.ts:883`). | non   |
 | `gcIntervalS` | int (s)      | `300`     | Intervalle du balayage de purge des fenêtres expirées, hors hot-path.            | non   |
 | `gcJitter`    | bool         | `true`    | Étale le tick GC d'un jitter aléatoire (anti-thundering-herd multi-pod).         | non   |
@@ -242,7 +242,7 @@ Et un réglage **séparé**, propre au WebSocket, à la racine du module :
 Un WebSocket ne peut **pas** recevoir un `429` : au moment où le rate-limit décide, le `101 Switching
 Protocols` est déjà parti sur le fil (émis par la bibliothèque `ws`). Le refoulement se fait donc par
 une **fermeture RFC 6455 `1013 Try Again Later`**, décidée dans `onWebsocketRequest()`
-(`http-kernel.ts:1505`) — **avant** `enterScope`, l'ALS et le pipeline, comme le `429` HTTP.
+(`http-kernel.ts:1540`) — **avant** `enterScope`, l'ALS et le pipeline, comme le `429` HTTP.
 
 Deux plafonds distincts, tous deux par IP forwarded-aware :
 

package/docs/servers.md

@@ -128,12 +128,12 @@ Nodefony crée un serveur HTTP/2 sécurisé avec `allowHTTP1: true` (`ServerHttp
 
 **Le WebSocket n'est jamais un citoyen de seconde zone.** Il est adossé au serveur HTTP porteur
 (`server-websocket.ts:80`), passe par le **même** rate-limit d'IP que les requêtes HTTP — un upgrade
-_est_ une requête HTTP (`HttpKernel.onWebsocketRequest()`, `http-kernel.ts:1497`) —, hérite de la même
+_est_ une requête HTTP (`HttpKernel.onWebsocketRequest()`, `http-kernel.ts:1540`) —, hérite de la même
 session et du même firewall, et se ferme avec le même soin qu'une réponse HTTP.
 
 > [!NOTE]
 > Le serveur HTTP/3 (QUIC) est **réservé, pas implémenté** : la clé `http3` existe dans le schéma,
-> marquée `reserved` (`config.ts:1029`). Elle ne fait rien aujourd'hui.
+> marquée `reserved` (`config.ts:1035`). Elle ne fait rien aujourd'hui.
 
 ## 🚀 Démarrage rapide
 
@@ -249,7 +249,7 @@ export default PingController;
 
 ### 4. Ce qu'on observe au boot
 
-Le kernel démarre les serveurs à la phase `onReady` (`Kernel.ts:1090`), puis affiche les URL réellement
+Le kernel démarre les serveurs à la phase `onReady` (`Kernel.ts:1214`), puis affiche les URL réellement
 en écoute — le récap de développement liste HTTP, HTTP/2, WS et WSS dans cet ordre
 (`BootReporter.ts:389`) :
 
@@ -264,7 +264,7 @@ en écoute — le récap de développement liste HTTP, HTTP/2, WS et WSS dans ce
 ```
 
 Hors écran animé (production, CI, `--debug`), ce sont les bannières par serveur qui sortent
-(`ServerHttp.showBanner()`, `server-http.ts:226`, appelées par le kernel — `Kernel.ts:457`) :
+(`ServerHttp.showBanner()`, `server-http.ts:226`, appelées par le kernel — `Kernel.ts:545`) :
 
 ```text
 Server Listen on http://127.0.0.1:5151 Family: IPv4 Protocol : 1.1
@@ -399,8 +399,8 @@ C'est la distinction la plus utile de cette page, et celle qu'on rate le plus so
 
 | Question                                  | Où ça se règle                 | Source                                                    |
 | ----------------------------------------- | ------------------------------ | --------------------------------------------------------- |
-| **Quels** serveurs, sur **quels ports** ? | `servers` (config d'app)       | `serversSchema` (`src/nodefony/src/config/schema.ts:132`) |
-| **Comment** ces serveurs se comportent ?  | `use("@nodefony/http", { … })` | `httpConfigSchema` (`config.ts:947`)                      |
+| **Quels** serveurs, sur **quels ports** ? | `servers` (config d'app)       | `serversSchema` (`src/nodefony/src/config/schema.ts:149`) |
+| **Comment** ces serveurs se comportent ?  | `use("@nodefony/http", { … })` | `httpConfigSchema` (`config.ts:953`)                      |
 
 Autrement dit : la **topologie** est une propriété du déploiement (elle change entre le poste du dev,
 la CI et le cluster) ; le **réglage** est une propriété de l'application.
@@ -422,7 +422,7 @@ Défauts matérialisés dans `defaultAppConfig` (`src/nodefony/src/config/defaul
 ### Niveau 2 — le transport HTTP / HTTPS
 
 Table dérivée de `httpServerSchema` (`config.ts:257`) ; la section `https` reprend les mêmes clés et en
-ajoute une (`httpsServerSchema`, `config.ts:315`).
+ajoute une (`httpsServerSchema`, `config.ts:336`).
 
 | Option                       | Type  | Défaut   | Effet                                                                            |
 | ---------------------------- | ----- | -------- | -------------------------------------------------------------------------------- |
@@ -441,7 +441,7 @@ quelle à Node. C'est délibéré — un schéma strict effacerait silencieuseme
 
 ### Niveau 2 — HTTP/2
 
-Depuis `http2Schema` (`config.ts:332`), appliqué seulement si défini
+Depuis `http2Schema` (`config.ts:353`), appliqué seulement si défini
 (`maxSessionMemory`, `server-https.ts:197`).
 
 | Option                 | Type | Défaut | Effet                                                                         |
@@ -451,16 +451,16 @@ Depuis `http2Schema` (`config.ts:332`), appliqué seulement si défini
 
 ### Niveau 2 — WebSocket (`websocket` et `websocketSecure`)
 
-Depuis `websocketSchema` (`config.ts:490`). Les deux sections partagent la forme et les défauts ; le WSS
-lit `websocketSecure` (`config.ts:1037`).
+Depuis `websocketSchema` (`config.ts:517`). Les deux sections partagent la forme et les défauts ; le WSS
+lit `websocketSecure` (`config.ts:1043`).
 
 | Option                   | Type                | Défaut  | Effet                                                                              |
 | ------------------------ | ------------------- | ------- | ---------------------------------------------------------------------------------- |
 | `keepaliveInterval`      | ms                  | `20000` | Intervalle des pings — détecte les connexions zombies.                             |
 | `keepaliveGracePeriod`   | ms                  | `10000` | Délai de grâce après un ping sans réponse avant fermeture.                         |
 | `closeTimeout`           | ms                  | `5000`  | Délai de fermeture propre avant destruction de la socket.                          |
-| `maxPayload`             | octets              | `1 MiB` | Taille max d'un message entrant → au-delà, **close 1009** (`config.ts:516`).       |
-| `allowedOrigins`         | bool \| str \| list | `false` | Allowlist d'`Origin` au handshake — **anti-CSWSH** (`config.ts:525`).              |
+| `maxPayload`             | octets              | `1 MiB` | Taille max d'un message entrant → au-delà, **close 1009** (`config.ts:543`).       |
+| `allowedOrigins`         | bool \| str \| list | `false` | Allowlist d'`Origin` au handshake — **anti-CSWSH** (`config.ts:552`).              |
 | `perMessageDeflate`      | bool \| objet       | `false` | Compression RFC 7692. Désactivée par défaut : coût CPU/RAM + risque de _zip bomb_. |
 | `skipUTF8Validation`     | bool                | `false` | Désactive la validation UTF-8 des frames texte (RFC 6455 §8.1). À laisser `false`. |
 | `autoPong`               | bool                | `true`  | Répond automatiquement aux pings entrants (RFC 6455 §5.5.2-3). À laisser `true`.   |
@@ -537,12 +537,12 @@ serveur qui, lui, écoute très bien.
 **Générer un certificat est un confort de développement, pas une fonction de production.** Nodefony
 n'est pas une autorité de certification : en production, on fournit un vrai certificat (Let's Encrypt,
 ingress k8s, reverse-proxy). Le service crie un avertissement si ce n'est pas le cas
-(`Certificate.resolveStrategy()`, `certificates.ts:409`).
+(`Certificate.resolveStrategy()`, `certificates.ts:418`).
 
 ### Les quatre stratégies
 
-Réglées par `certificates.strategy` (`certificatesSchema`, `config.ts:448`), résolues par
-`Certificate.resolveStrategy()` (`certificates.ts:370`).
+Réglées par `certificates.strategy` (`certificatesSchema`, `config.ts:475`), résolues par
+`Certificate.resolveStrategy()` (`certificates.ts:379`).
 
 | Stratégie       | Quand l'utiliser                            | Ce qui se passe                                                             |
 | --------------- | ------------------------------------------- | --------------------------------------------------------------------------- |
@@ -572,13 +572,13 @@ export default defineConfig(() => ({
 > [!TIP]
 > Pour un HTTPS de développement **sans avertissement navigateur** (indispensable au HMR cross-origin
 > et au WSS) : `brew install mkcert nss && mkcert -install`. Nodefony le détecte tout seul, sinon il
-> l'annonce et retombe sur l'auto-signé (`certificates.ts:392`).
+> l'annonce et retombe sur l'auto-signé (`certificates.ts:401`).
 
 ### Ce que le chemin `explicit` évite
 
 `node-forge` est une grosse dépendance. Elle est chargée **paresseusement**, uniquement sur le chemin
-de génération (`Certificate.loadForge()`, `certificates.ts:218`) : en production avec un certificat
-fourni, elle n'entre jamais dans le processus (`certificates.ts:325`).
+de génération (`Certificate.loadForge()`, `certificates.ts:227`) : en production avec un certificat
+fourni, elle n'entre jamais dans le processus (`certificates.ts:227`).
 
 ### Conformité de l'auto-signé
 
@@ -587,16 +587,16 @@ invalid »). Celui de Nodefony respecte les règles qui comptent :
 
 | Exigence                                | Norme                | Mise en œuvre                                             |
 | --------------------------------------- | -------------------- | --------------------------------------------------------- |
-| Signature SHA-256, **jamais** SHA-1     | RFC 5280, CA/B Forum | `openssl.hash` par défaut `sha256` (`config.ts:379`)      |
-| Numéro de série aléatoire 128 bits      | RFC 5280 §4.1.2.2    | `Certificate.generateSerialHex()` (`certificates.ts:255`) |
-| Le SAN fait foi, pas le CN              | RFC 6125             | SAN dérivé du kernel si non fourni (`config.ts:415`)      |
-| `notBefore` reculé (décalage d'horloge) | pratique             | `openssl.backdateMinutes`, défaut 5 (`config.ts:394`)     |
-| Clé privée non lisible par tous         | hygiène              | `privateKeyMode` `0600` (`config.ts:472`)                 |
+| Signature SHA-256, **jamais** SHA-1     | RFC 5280, CA/B Forum | `selfSigned.hash` par défaut `sha256` (`config.ts:400`)   |
+| Numéro de série aléatoire 128 bits      | RFC 5280 §4.1.2.2    | `Certificate.generateSerialHex()` (`certificates.ts:264`) |
+| Le SAN fait foi, pas le CN              | RFC 6125             | SAN dérivé du kernel si non fourni (`config.ts:444`)      |
+| `notBefore` reculé (décalage d'horloge) | pratique             | `selfSigned.backdateMinutes`, défaut 5 (`config.ts:415`)  |
+| Clé privée non lisible par tous         | hygiène              | `privateKeyMode` `0600` (`config.ts:499`)                 |
 
 ### Régénération automatique
 
 Un certificat présent sur disque n'est pas forcément **adéquat**. `Certificate.isCertAdequate()`
-(`certificates.ts:533`) le régénère s'il est expiré, s'il est signé en SHA-1, ou si son SAN ne couvre
+(`certificates.ts:542`) le régénère s'il est expiré, s'il est signé en SHA-1, ou si son SAN ne couvre
 plus les noms requis — le dernier cas est celui qui sauve : changer le domaine d'écoute sans ce
 contrôle laisserait un certificat obsolète en place indéfiniment.
 
@@ -608,7 +608,7 @@ Dès qu'un proxy est devant l'application, trois questions se posent — et troi
 
 Sans barrière, n'importe quel client peut envoyer `X-Forwarded-For: 1.2.3.4` et usurper son IP :
 contournement de rate-limit, journaux d'audit falsifiés. Le défaut est donc **`false` — ces en-têtes
-sont ignorés** (`config.ts:959`), et l'IP retenue est celle de la socket réelle, non falsifiable.
+sont ignorés** (`config.ts:965`), et l'IP retenue est celle de la socket réelle, non falsifiable.
 
 | Valeur                                       | Sens                                                               |
 | -------------------------------------------- | ------------------------------------------------------------------ |
@@ -628,7 +628,7 @@ Barrière testée **avant le routage**, contre l'injection d'en-tête `Host`. Le
 kernel est toujours accepté, plus le loopback en développement (`HttpKernel.compileAlias()`,
 `http-kernel.ts:936`). `false` (défaut) = ce socle seul ; une liste ajoute des vhosts (exact ou joker
 d'un seul niveau, `*.cdn.example.com`) ; `true` désactive la barrière — à réserver au cas où le proxy
-filtre déjà le `Host` (`config.ts:968`).
+filtre déjà le `Host` (`config.ts:974`).
 
 ### « Cette page a-t-elle le droit d'ouvrir un WebSocket ? » → `allowedOrigins`
 
@@ -664,7 +664,7 @@ rate-limit**. Un kubelet qui reçoit un `429` croit le pod mort → cascade de r
 
 | Option          | Type   | Défaut    | Effet                                                                  |
 | --------------- | ------ | --------- | ---------------------------------------------------------------------- |
-| `enabled`       | bool   | `true`    | Expose les probes (`healthSchema`, `config.ts:919`).                   |
+| `enabled`       | bool   | `true`    | Expose les probes (`healthSchema`, `config.ts:925`).                   |
 | `livenessPath`  | string | `/livez`  | Chemin de la sonde de vie (`livenessProbe.httpGet.path` k8s).          |
 | `readinessPath` | string | `/readyz` | Chemin de la sonde de disponibilité.                                   |
 | `shutdownDelay` | ms     | `0`       | Délai entre la bascule `503` et le début du drain (propagation du LB). |
@@ -784,13 +784,13 @@ processus à l'arrêt.
 
 L'upgrade WebSocket **est** une requête HTTP : il passe donc par le **même** compteur de rate-limit par
 IP que les requêtes ordinaires, vérifié avant toute allocation de contexte
-(`HttpKernel.onWebsocketRequest()`, `http-kernel.ts:1497`). Le `101` étant déjà émis par `ws`, un `429`
+(`HttpKernel.onWebsocketRequest()`, `http-kernel.ts:1540`). Le `101` étant déjà émis par `ws`, un `429`
 est impossible → la connexion est fermée en **1013 « Try Again Later »**
 (`rateLimiter`, `http-kernel.ts:287`), sans
 journalisation (un journal par handshake rejeté serait lui-même un amplificateur sous flood).
 
 Un second plafond, **désactivé par défaut**, borne le nombre de connexions **simultanées** par IP :
-`wsMaxConnectionsPerIp` (`config.ts:1046`). En cloud-native, laisser `null` et déléguer à l'edge —
+`wsMaxConnectionsPerIp` (`config.ts:1052`). En cloud-native, laisser `null` et déléguer à l'edge —
 nginx `limit_conn`, HAProxy `sc_conn_cur` — qui voit tout le trafic, rejette avant le coût du
 descripteur et du TLS, et couvre tous les pods. Ne l'activer que sur une machine sans ingress.
 
@@ -817,7 +817,7 @@ par seconde. Les choix visibles dans le code :
 - **Fichiers statiques en repli** — depuis la bascule « router d'abord », une requête qui matche une
   route ne paie plus l'appel disque de `serve-static` (**+28 % de requêtes par seconde** mesurés en
   production mono-processus).
-- **`node-forge` jamais chargé en production** avec un certificat fourni (`certificates.ts:218`).
+- **`node-forge` jamais chargé en production** avec un certificat fourni (`certificates.ts:227`).
 
 Ordre de grandeur mesuré : un processus Node saturé sur un cœur tient environ 400 requêtes/s en
 boucle locale avec dégradation gracieuse (1600 connexions concurrentes, aucun crash) ; côté WebSocket,
@@ -836,17 +836,17 @@ demande le backplane realtime.
 | ------------------------------------- | ------------------ | -------------------------------------------------------------------------- |
 | HTTP/1.1 (sémantique, message)        | RFC 9110, 9112     | `node:http` + pipeline `HttpKernel.onHttpRequest()` (`http-kernel.ts:819`) |
 | HTTP/2                                | RFC 9113           | `ServerHttps.createServerH2()` (`server-https.ts:174`)                     |
-| HTTP/2 Rapid Reset                    | CVE-2023-44487     | `maxConcurrentStreams` (`config.ts:334`)                                   |
+| HTTP/2 Rapid Reset                    | CVE-2023-44487     | `maxConcurrentStreams` (`config.ts:355`)                                   |
 | En-têtes trop volumineux → 431        | RFC 6585 §5        | `handleClientError()` (`clientError.ts:25`)                                |
-| WebSocket — protocole                 | RFC 6455           | `ws@8` + options (`config.ts:490`)                                         |
+| WebSocket — protocole                 | RFC 6455           | `ws@8` + options (`config.ts:496`)                                         |
 | WebSocket — Close 1001 « Going Away » | RFC 6455 §7.4.1    | `Websocket.terminate()` (`server-websocket.ts:134`)                        |
-| WebSocket — 1009 « Message Too Big »  | RFC 6455 §7.4.1    | `maxPayload` (`config.ts:516`)                                             |
-| WebSocket — validation UTF-8          | RFC 6455 §8.1      | `skipUTF8Validation` (`config.ts:596`)                                     |
-| WebSocket — compression               | RFC 7692           | `perMessageDeflate` (`config.ts:540`)                                      |
+| WebSocket — 1009 « Message Too Big »  | RFC 6455 §7.4.1    | `maxPayload` (`config.ts:543`)                                             |
+| WebSocket — validation UTF-8          | RFC 6455 §8.1      | `skipUTF8Validation` (`config.ts:623`)                                     |
+| WebSocket — compression               | RFC 7692           | `perMessageDeflate` (`config.ts:567`)                                      |
 | CSWSH (Origin au handshake)           | OWASP WSTG-CLNT-10 | `HttpKernel.checkWebsocketOrigin()` (`http-kernel.ts:599`)                 |
 | En-têtes forwarded                    | RFC 7239           | `resolveForwarded()` (`forwarded.ts:253`)                                  |
-| Certificat — série, SAN, extensions   | RFC 5280           | `Certificate.generateSerialHex()` (`certificates.ts:255`)                  |
-| Certificat — identité par le SAN      | RFC 6125           | `sanSchema` (`config.ts:415`)                                              |
+| Certificat — série, SAN, extensions   | RFC 5280           | `Certificate.generateSerialHex()` (`certificates.ts:264`)                  |
+| Certificat — identité par le SAN      | RFC 6125           | `sanSchema` (`config.ts:442`)                                              |
 
 ## ⚠️ Pièges (symptôme → cause → correction)
 
@@ -863,7 +863,7 @@ demande le backplane realtime.
 | Cascade de redémarrages sous charge                             | Sonde de santé soumise au rate-limit                                       | Déjà géré : les probes court-circuitent avant le rate-limit (`http-kernel.ts:848`) |
 | `curl --http2` renvoie du HTTP/1.1                              | `servers.https.protocol: "1.1"`, ou client sans ALPN                       | Passer `protocol: "2.0"` (défaut) et vérifier le client                            |
 | Avertissement navigateur en HTTPS de développement              | Certificat auto-signé (mkcert absent)                                      | `brew install mkcert nss && mkcert -install`, puis redémarrer                      |
-| Le certificat n'est pas régénéré après un changement de domaine | On croit qu'un fichier présent suffit                                      | Déjà géré : le SAN est vérifié (`certificates.ts:546`)                             |
+| Le certificat n'est pas régénéré après un changement de domaine | On croit qu'un fichier présent suffit                                      | Déjà géré : le SAN est vérifié (`certificates.ts:555`)                             |
 | `strategy: "explicit"` fait échouer le boot                     | `key`/`cert` absents de la configuration                                   | Fournir les deux chemins — l'échec est volontaire, jamais un repli silencieux      |
 | Une IP falsifiée passe dans les journaux d'audit                | `trustProxy` accordé trop largement                                        | Restreindre à l'IP/CIDR du proxy, ou revenir à `false`                             |
 | Handshake WebSocket refusé en `1008`                            | `Origin` non autorisée (anti-CSWSH)                                        | Ajouter l'origine dans `websocket.allowedOrigins`                                  |
@@ -886,7 +886,7 @@ l'origine du transport.
 
 `proxy:generate` mérite un mot : la configuration nginx/HAProxy est **dérivée** des domaines de
 confiance, des ports effectifs et des dossiers statiques montés — donc elle ne diverge pas du code. Le
-résumé de certificat vient de `Certificate.describe()` (`certificates.ts:803`), source unique partagée
+résumé de certificat vient de `Certificate.describe()` (`certificates.ts:853`), source unique partagée
 par la commande, le boot et un futur écran d'administration.
 
 **Runtime.** `nodefony status` et `nodefony stop` lisent les ports effectifs publiés au boot ; ils

package/docs/session.md

@@ -144,7 +144,7 @@ seule présence d'un paramètre `@Session` — ou si un cookie arrive déjà : c
 ni `Set-Cookie`**.
 
 **3. Un seul modèle d'état pour le web et le temps réel.** Le même `startSession()` sert
-`HttpKernel.onRequestEnd()` (`http-kernel.ts:1391`) et `HttpKernel.onConnect()` (`http-kernel.ts:1659`) ;
+`HttpKernel.onRequestEnd()` (`http-kernel.ts:1434`) et `HttpKernel.onConnect()` (`http-kernel.ts:1702`) ;
 l'activité HTTP **ou** WS prolonge la même session (`Session.touchIfNeeded()`, `session.ts:421`).
 
 **4. L'administration ne voit jamais un identifiant.** Un opérateur manipule une `ref`, HMAC tronqué
@@ -278,12 +278,12 @@ faute de `Secure` (`Context.getSessionCookieName()`, `Context.ts:714`).
 
 ## ⚙️ Configuration
 
-Source unique des défauts : le schéma Zod `sessionSchema` (`config.ts:761`) et son sous-schéma
-`sessionCookieSchema` (`config.ts:727`).
+Source unique des défauts : le schéma Zod `sessionSchema` (`config.ts:782`) et son sous-schéma
+`sessionCookieSchema` (`config.ts:748`).
 
 | Option              | Type    | Défaut       | Effet                                                                             |
 | ------------------- | ------- | ------------ | --------------------------------------------------------------------------------- |
-| `store`             | string  | `"auto"`     | Backend de persistance — voir la résolution ci-dessous (`config.ts:755`).         |
+| `store`             | string  | `"auto"`     | Backend de persistance — voir la résolution ci-dessous (`config.ts:795`).         |
 | `name`              | string  | `"nodefony"` | Nom du cookie, préfixé `__Host-` selon `cookie.hostPrefix` (`config.ts:750`).     |
 | `strictMode`        | bool    | `true`       | Un identifiant inconnu du store est rejeté → session neuve (anti-fixation).       |
 | `idleTimeoutS`      | int ≥ 0 | `1800`       | Inactivité max (30 min). `0` = pas d'expiration par inactivité (`config.ts:796`). |
@@ -498,7 +498,7 @@ C'est le différenciateur du framework appliqué à l'état de session : un seul
 <!-- prettier-ignore -->
 | Aspect | HTTP | WebSocket |
 | --- | --- | --- |
-| Ouverture | à chaque requête — `startSession()` dans `onRequestEnd()` (`http-kernel.ts:1391`) | **une fois** au handshake — `startSession()` dans `onConnect()` (`http-kernel.ts:1659`) |
+| Ouverture | à chaque requête — `startSession()` dans `onRequestEnd()` (`http-kernel.ts:1434`) | **une fois** au handshake — `startSession()` dans `onConnect()` (`http-kernel.ts:1702`) |
 | Lecture du cookie | constructeur du contexte | constructeur, même nom effectif (`WebsocketContext.ts:172`) |
 | Sauvegarde | fin de requête | après **chaque frame** traitée (`WebsocketContext.ts:302`) |
 | Filet de fermeture | — | `once("onFinish")` sauve si non déjà fait (`http-kernel.ts:1185`) |
@@ -561,13 +561,13 @@ Trois barrières superposées :
    **liste blanche** : `ref`, `user`, `authenticated`, `ip`, `ua`, dates. Jamais un `delete` après coup.
 3. La `ref` elle-même est un HMAC tronqué non réversible (`computeSessionRef()`,
    `sessions-service.ts:100`) ; la clé est dérivée du certificat au boot et n'est jamais sérialisée
-   (`SessionsService.sessionRef()`, `sessions-service.ts:511`).
+   (`SessionsService.sessionRef()`, `sessions-service.ts:528`).
 
 ### Récapitulatif des défenses actives par défaut
 
 | Menace                            | Défense                                           | Ancrage                                            |
 | --------------------------------- | ------------------------------------------------- | -------------------------------------------------- |
-| Vol par script injecté (XSS)      | `HttpOnly`                                        | `sessionCookieSchema` (`config.ts:718`)            |
+| Vol par script injecté (XSS)      | `HttpOnly`                                        | `sessionCookieSchema` (`config.ts:748`)            |
 | Interception réseau               | `Secure` + `__Host-` sur TLS                      | `getSessionCookieName()` (`Context.ts:714`)        |
 | Requête inter-sites               | `SameSite=Lax` par défaut                         | `defaultCookieOptions` (`cookie.ts:48`)            |
 | Fixation (cookie pré-posé)        | `strictMode` + régénération au login              | `Session.resume()` (`session.ts:189`)              |
@@ -582,7 +582,7 @@ Trois barrières superposées :
 
 Les signatures vivent dans `.ai/symbols.json` (jamais recopiées ici). Voici les usages réels.
 
-**Depuis un contrôleur** — `this.session` est un getter sur le contexte (`Controller.ts:229`) ; un
+**Depuis un contrôleur** — `this.session` est un getter sur le contexte (`Controller.ts:279`) ; un
 paramètre `@Session()` suffit à déclarer l'intent.
 
 | Besoin                           | Appel                                | Effet                                                   |

package/docs/upload.md

@@ -126,7 +126,7 @@ champs texte restent en mémoire. C'est ce qui rend un endpoint d'upload public
 **métadonnée** (`filename`), pas dans le chemin.
 
 **Deux budgets, secure-by-default.** Le corps non-multipart est plafonné à **1 MiB** par défaut
-(`maxBodySize`, `http/nodefony/config/config.ts:1005`) — un `POST` JSON géant est rejeté avant d'être bufferisé. Le
+(`maxBodySize`, `http/nodefony/config/config.ts:1026`) — un `POST` JSON géant est rejeté avant d'être bufferisé. Le
 multipart, lui, a ses propres bornes busboy (par fichier, cumul, nombre) qui coupent le flux et
 nettoient les temporaires déjà posés au moindre dépassement (`context/http/Request.ts:481`).
 
@@ -321,8 +321,8 @@ recommandé) et les **getters** de `Controller` (impératif). Les signatures exa
 | `@Body() body`                                     | tous les champs parsés (`queryPost`) | `resolveParamArg` `"body"` (`routerDecorators.ts:1178`)             |
 | `@Body("label") v`                                 | un seul champ du body                | même source, clé (`routerDecorators.ts:1178`)                       |
 | `@Body({ stream: true }) s: NodeJS.ReadableStream` | le **flux brut**, parse **sauté**    | `resolveParamArg` stream (`routerDecorators.ts:1227`)               |
-| `this.queryFile`                                   | équivalent getter des fichiers       | `Controller.queryFile` (`framework/nodefony/src/Controller.ts:205`) |
-| `this.queryPost`                                   | équivalent getter des champs         | `Controller.queryPost` (`framework/nodefony/src/Controller.ts:214`) |
+| `this.queryFile`                                   | équivalent getter des fichiers       | `Controller.queryFile` (`framework/nodefony/src/Controller.ts:239`) |
+| `this.queryPost`                                   | équivalent getter des champs         | `Controller.queryPost` (`framework/nodefony/src/Controller.ts:248`) |
 
 Les décorateurs `@UploadedFile` / `@UploadedFiles` sont des fabriques de paramètre
 (`routerDecorators.ts:1240`), exportées par `@nodefony/framework` ; leurs interfaces `IUploadedFile` /

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodefony/http",
-  "version": "10.0.0-alpha.3",
+  "version": "10.0.0-alpha.5",
   "description": "Serveurs HTTP, HTTPS, HTTP/2 et WebSocket natifs pour Nodefony : sessions, contextes de requête, certificats TLS",
   "author": "Christophe CAMENSULI <ccamensuli@gmail.com>",
   "main": "./dist/index.js",
@@ -66,7 +66,7 @@
     "@types/chai": "5.2.3",
     "@types/mime-types": "3.0.1",
     "@types/ms": "2.1.0",
-    "@types/node": "26.4.1",
+    "@types/node": "26.5.1",
     "@types/node-forge": "1.3.14",
     "@types/qs": "6.15.1",
     "@types/serve-static": "2.2.0",
@@ -75,17 +75,17 @@
     "@types/xml2js": "0.4.14",
     "@vitest/coverage-v8": "5.0.0",
     "chai": "6.2.2",
-    "nodefony": "^10.0.0-alpha.3",
+    "nodefony": "^10.0.0-alpha.5",
     "rimraf": "6.1.3",
     "tsx": "4.23.13",
     "vitest": "5.0.0"
   },
-  "license": "CECILL-B",
+  "license": "Apache-2.0",
   "readmeFilename": "README.md",
   "contributors": [],
   "peerDependencies": {
-    "nodefony": "^10.0.0-alpha.3",
-    "zod": "^4.4.3"
+    "nodefony": "^10.0.0-alpha.5",
+    "zod": "^4.6.1"
   },
   "files": [
     "dist",