@nodefony/http 10.0.0-beta.1 → 10.0.0-beta.2

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

@@ -1,18 +1,18 @@
-import type pkg from "node-forge";
 import { Service, Module } from "nodefony";
-/**
- * Type-valeur du backend node-forge runtime (objet `.pki`/`.md`). L'import type
- * `pkg` sert pour les namespaces de types (`pkg.pki.Certificate`) ; `ForgeModule`
- * pour la valeur chargée dynamiquement (node-forge est un module `export =`).
- */
-type ForgeModule = typeof import("node-forge");
+import { type KeyObject } from "node:crypto";
+import { type ICertificateAttribute } from "./x509.js";
+/** Paire de clés RSA du certificat auto-signé. */
+export interface IRsaKeyPair {
+    privateKey: KeyObject;
+    publicKey: KeyObject;
+}
 /** Algorithmes de hachage de signature autorisés (SHA-1 banni). */
 export type CertHash = "sha256" | "sha384" | "sha512";
 /** Stratégie de fourniture du certificat exposée en configuration. */
 export type CertStrategyConfig = "auto" | "mkcert" | "selfsigned" | "explicit";
 /**
- * Options de génération du certificat AUTO-SIGNÉ (node-forge, JavaScript pur —
- * aucun binaire externe n'est invoqué).
+ * Options de génération du certificat AUTO-SIGNÉ (`node:crypto` — aucun
+ * binaire externe ni aucune dépendance tierce).
  *
  * ⚠️ 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
@@ -29,7 +29,7 @@ export interface SelfSignedOptions {
     /** Recul de `notBefore` (minutes) — tolérance au décalage d'horloge client. */
     backdateMinutes: number;
     /** Attributs du sujet/issuer (commonName, organizationName…). */
-    attrs: pkg.pki.CertificateField[];
+    attrs: ICertificateAttribute[];
 }
 /** Options de génération du certificat TLS en mode développement. */
 export interface CertificateDevOptions {
@@ -37,7 +37,7 @@ export interface CertificateDevOptions {
      * Préférer `mkcert` (CA locale ajoutée au trust store système) pour générer
      * le certificat de dev. Donne un HTTPS sans erreur navigateur — indispensable
      * pour les sous-ressources cross-origin (Vite) et le WSS du HMR.
-     * Si `mkcert` est absent, on retombe sur un auto-signé node-forge (non trusté).
+     * Si `mkcert` est absent, on retombe sur un auto-signé (non trusté).
      * Ignoré hors `development`.
      */
     useMkcert: boolean;
@@ -96,7 +96,7 @@ export interface CertificateInfo {
  *
  * Trois stratégies : `explicit` (certificat fourni en config — le cas de
  * PRODUCTION), `mkcert` (CA locale trustée, confort de dev) et `selfsigned`
- * (auto-signé node-forge, secours). La génération est réservée au
+ * (auto-signé, secours). La génération est réservée au
  * DÉVELOPPEMENT : en production sans certificat fourni, le service crie un
  * avertissement (Nodefony n'est pas une autorité de certification).
  *
@@ -108,8 +108,7 @@ export interface CertificateInfo {
 declare class Certificate extends Service {
     module: Module;
     files: filesCertType[];
-    keysPair: pkg.pki.rsa.KeyPair | null;
-    certForge: pkg.pki.Certificate | null;
+    keysPair: IRsaKeyPair | null;
     ca: Buffer | string | null;
     key: Buffer | string | null;
     cert: Buffer | string | null;
@@ -119,13 +118,6 @@ declare class Certificate extends Service {
     intermediateCertPem: Buffer | string | null;
     /** CAROOT résolu de mkcert (null tant que non détecté / indisponible). */
     private mkcertCaRoot;
-    /**
-     * Backend crypto node-forge, chargé PARESSEUSEMENT. La génération de
-     * certificat est un confort de DÉVELOPPEMENT : en production avec un
-     * certificat fourni (`strategy: "explicit"`), cette grosse dépendance n'est
-     * jamais importée (règle perf-mémoire — pas de dep chargée « au cas où »).
-     */
-    private forge;
     path: string;
     serverPath: string;
     caPath: string;
@@ -138,14 +130,6 @@ declare class Certificate extends Service {
     private get certOptions();
     /** Vrai en environnement de développement (mkcert réservé à ce mode). */
     private isDev;
-    /**
-     * Charge node-forge à la demande (idempotent) — uniquement sur le chemin de
-     * GÉNÉRATION (selfsigned / mkcert / inspection). Le chemin `explicit` (prod)
-     * ne l'appelle jamais.
-     */
-    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 ?
      *
@@ -182,7 +166,7 @@ declare class Certificate extends Service {
     /**
      * Génère (ou recharge) le certificat serveur selon la stratégie résolue :
      * `explicit` (fourni en config / prod), `mkcert` (dev, CA trustée) ou
-     * `selfsigned` (auto-signé node-forge, secours). Régénère automatiquement si
+     * `selfsigned` (auto-signé, secours). Régénère automatiquement si
      * le certificat présent sur disque n'est pas adéquat pour la stratégie active
      * (expiré, SHA-1, SAN incomplet).
      *
@@ -195,7 +179,7 @@ declare class Certificate extends Service {
      *   erreur si absents.
      * - `mkcert` : dev + binaire mkcert + CA locale présents. Forcé hors dev →
      *   retombe sur `selfsigned` avec avertissement.
-     * - `selfsigned` : auto-signé node-forge (fallback). En PRODUCTION, crie un
+     * - `selfsigned` : auto-signé (fallback). En PRODUCTION, crie un
      *   avertissement : la génération n'est pas le rôle d'un serveur de prod.
      */
     private resolveStrategy;
@@ -248,30 +232,31 @@ declare class Certificate extends Service {
      * par mkcert passe aussi par ici). Échec silencieux hors POSIX.
      */
     private restrictPrivateKey;
-    generateKeys(): pkg.pki.rsa.KeyPair;
+    /** Génère la paire RSA (taille configurée) hors de la boucle d'événements. */
+    generateKeys(): Promise<IRsaKeyPair>;
+    /** Clé privée en PEM PKCS#1 (`BEGIN RSA PRIVATE KEY`). */
     generatePrivateKeyPem(): Buffer;
+    /** Clé publique en PEM SPKI (`BEGIN PUBLIC KEY`). */
     generatePublickeyPem(): Buffer;
-    generateCertPem(): Buffer;
-    createCertificate(): pkg.pki.Certificate;
-    /** subjectAltName de l'auto-signé : DNS + IP (config explicite sinon dérivé). */
-    private altNames;
-    setExtension(): void;
     /**
-     * Signe le certificat avec le hachage configuré (SHA-256 par défaut).
-     * SHA-1 est INTERDIT (collision SHAttered 2017, CA/Browser Forum depuis 2016) :
-     * `node-forge` signe en SHA-1 par défaut si on ne passe pas de digest → on en
-     * passe toujours un.
+     * Fabrique et signe le certificat auto-signé avec la paire courante.
+     *
+     * Série aléatoire unique (RFC 5280 §4.1.2.2), `notBefore` reculé (décalage
+     * d'horloge du client), SAN DNS + IP (config explicite sinon dérivé), signé
+     * avec le hachage configuré — jamais SHA-1 (collision SHAttered 2017,
+     * CA/Browser Forum depuis 2016).
+     *
+     * @returns le certificat en PEM
+     * @throws Si la paire de clés n'a pas été générée
      */
-    sign(): void;
+    createCertificate(): Promise<Buffer>;
     /**
      * Résumé introspectable du certificat serveur courant — réutilisé par la
      * commande CLI `certificates` et un futur endpoint d'admin Studio (parité
-     * CLI ↔ Web). Parse le certificat chargé (charge node-forge à la demande).
+     * CLI ↔ Web).
      */
     describe(): Promise<CertificateInfo>;
-    /** Nom lisible de l'OID d'algorithme de signature. */
-    private oidName;
-    /** Digest node-forge correspondant au hachage configuré (jamais SHA-1). */
-    private digestFor;
+    /** Hachage configuré, ramené à SHA-256 s'il sort du contrat (jamais SHA-1). */
+    private allowedHash;
 }
 export default Certificate;

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

@@ -0,0 +1,86 @@
+/**
+ * Fabrique et lecture de certificats X.509 par `node:crypto` seul — aucune
+ * dépendance tierce.
+ *
+ * `node:crypto` sait LIRE un certificat (`X509Certificate`) et SIGNER, pas
+ * en FABRIQUER un : ce module encode le `TBSCertificate` en DER (RFC 5280
+ * §4.1), le signe avec `crypto.sign`, puis l'assemble. Seul le sous-ensemble
+ * nécessaire à un certificat serveur auto-signé est couvert. Les fonctions
+ * sont PURES (aucun disque, aucun kernel) : elles s'éprouvent sans décor.
+ *
+ * Pourquoi pas node-forge : sa vérification de signature RSA PKCS#1 v1.5
+ * accepte des signatures forgées (GHSA-86w9-cpqp-85rv), sans aucune version
+ * corrigée. Nous ne vérifions aucune signature, mais `npm audit` signale le
+ * paquet pour tous ceux qui installent `@nodefony/http`.
+ */
+import { type KeyObject } from "node:crypto";
+/** Hachages de signature que le builder sait déclarer. */
+export type X509Hash = "sha1" | "sha256" | "sha384" | "sha512";
+/**
+ * Attribut d'un nom distinctif (sujet / émetteur). Forme reprise de la config
+ * historique : `name` long (`commonName`), `shortName` (`CN`) ou `type` (OID
+ * pointé) — le premier présent fait foi.
+ */
+export interface ICertificateAttribute {
+    name?: string | undefined;
+    shortName?: string | undefined;
+    type?: string | undefined;
+    value?: string | undefined;
+}
+/** Ce qu'il faut pour fabriquer un certificat serveur auto-signé. */
+export interface ISelfSignedSpec {
+    privateKey: KeyObject;
+    publicKey: KeyObject;
+    /** Numéro de série en hexadécimal (entier positif, RFC 5280 §4.1.2.2). */
+    serialHex: string;
+    notBefore: Date;
+    notAfter: Date;
+    /** Sujet ET émetteur (auto-signé). Vide = nom vide, SAN alors critique. */
+    attributes: ICertificateAttribute[];
+    dns: string[];
+    ip: string[];
+    /** `sha1` n'est accepté que pour fabriquer des témoins de test. */
+    hash: X509Hash;
+}
+/** OID de la signature RSA-SHA1, que le service régénère. */
+export declare const SHA1_WITH_RSA_OID: string;
+/** Octets d'une adresse IP pour un SAN `iPAddress` (4 ou 16 octets). */
+export declare function ipAddressBytes(ip: string): Buffer;
+/**
+ * OID de l'algorithme de signature d'un certificat DER (champ
+ * `signatureAlgorithm`, RFC 5280 §4.1.1.2). Lu dans le DER plutôt que par
+ * `X509Certificate.signatureAlgorithmOid`, absent des Node du plancher.
+ *
+ * @param der - certificat encodé DER (`X509Certificate.raw`)
+ * @throws Si le DER n'a pas la forme d'un certificat
+ */
+export declare function signatureAlgorithmOid(der: Buffer): string;
+/** Nom lisible d'un OID de signature (l'OID lui-même s'il est inconnu). */
+export declare function signatureAlgorithmName(oid: string): string;
+/**
+ * Entrées DNS et IP d'un `subjectAltName` tel que le rend
+ * `X509Certificate.subjectAltName` (`DNS:a, IP Address:1.2.3.4`).
+ */
+export declare function parseSubjectAltName(value: string | undefined): {
+    dns: string[];
+    ip: string[];
+};
+/**
+ * Valeur d'un champ d'un nom distinctif tel que le rend
+ * `X509Certificate.subject` / `.issuer` (une ligne `CLÉ=valeur` par champ).
+ */
+export declare function distinguishedNameField(dn: string, key: string): string | null;
+/**
+ * Fabrique un certificat serveur auto-signé et le rend en PEM.
+ *
+ * Contenu : version 3, sujet = émetteur, `basicConstraints` cA=false,
+ * `keyUsage` (digitalSignature, keyEncipherment — critique),
+ * `extKeyUsage` (serverAuth, clientAuth), `subjectAltName` (critique si le
+ * sujet est vide, RFC 5280 §4.2.1.6) et `subjectKeyIdentifier` (SHA-1 de la
+ * clé publique, méthode 1 de RFC 5280 §4.2.1.2).
+ *
+ * @param spec - clés, série, validité, noms et hachage
+ * @returns le certificat encodé PEM
+ * @throws Si un attribut ou une adresse IP est invalide
+ */
+export declare function createSelfSignedCertificate(spec: ISelfSignedSpec): Promise<string>;

package/dist/types/nodefony/src/servers/portBinder.d.ts

@@ -1,48 +1,3 @@
-/**
- * **portBinder** — écoute sur le port désiré, ou sur le prochain port libre.
- *
- * Pourquoi ce fichier existe : lancer deux apps Nodefony côte à côte (le repo et
- * une app générée, deux projets, un banc et une démo…) faisait mourir la seconde
- * en `EADDRINUSE`. Le port désiré est une PRÉFÉRENCE en développement ; il reste
- * un CONTRAT en production.
- *
- * ## Pourquoi retenter au `listen()` plutôt que sonder d'abord
- *
- * La tentation est d'appeler « le port 5151 est-il libre ? » puis de binder. C'est
- * une **course** (TOCTOU) : entre la réponse et le bind, un autre process peut
- * prendre le port — et on échoue quand même, après avoir cru le contraire. Le
- * `listen()` est, lui, **atomique** : soit il réussit, soit le noyau dit
- * `EADDRINUSE`. On retente donc sur l'échec réel, jamais sur une prédiction.
- *
- * ## Pourquoi une SONDE malgré cela
- *
- * Le `listen()` est atomique, mais il ne dit pas tout : un port peut être **déjà
- * servi** et le noyau l'accorder quand même. Lier `0.0.0.0:P` alors qu'un autre
- * processus tient `127.0.0.1:P` **réussit** sur macOS et les BSD — ce sont deux
- * liaisons distinctes, et les connexions locales partent à la PLUS SPÉCIFIQUE.
- * Entre familles d'adresses (`::1` tenu, `0.0.0.0` demandé), même linux
- * l'accorde. L'application annonce alors `READY`, publie ses ports… et ne reçoit
- * rien : une panne muette, et un banc qui interroge le serveur du VOISIN.
- *
- * On constate donc, AVANT de binder, qu'aucun serveur ne répond déjà là où notre
- * liaison va recevoir (`isPortListening` — une connexion en boucle locale, aucun
- * outil système, même verdict sur les trois plateformes). Ce n'est pas la sonde
- * « ce port est-il libre ? » écartée plus haut : elle ne remplace pas le repli
- * atomique, qui reste le seul à trancher la course — elle ajoute le seul conflit
- * que le noyau n'exprime JAMAIS. La course résiduelle (un tiers prend le port
- * entre la sonde et le bind) retombe donc sur `EADDRINUSE`, inchangé.
- *
- * ## Pourquoi sauter les ports réservés
- *
- * HTTP veut 5151, HTTPS veut 5152. Si 5151 est pris, incrémenter naïvement ferait
- * voler 5152 à HTTPS — qui se décalerait à son tour, en cascade. Les ports que les
- * AUTRES serveurs convoitent sont donc sautés d'emblée.
- *
- * ## Fail-loud
- *
- * Un décalage est TOUJOURS annoncé (`onShift`) : une app qui écoute ailleurs que
- * là où on l'attend sans le dire est une dégradation silencieuse.
- */
 import type { AddressInfo } from "node:net";
 import { resolvePortPolicy } from "nodefony";
 import type { PortPolicy } from "nodefony";
@@ -138,9 +93,18 @@ export declare function detectPortConflict(port: number, host: string | undefine
  * handler d'erreur durable s'installe APRÈS, sur le serveur qui écoute — sinon il
  * verrait passer les `EADDRINUSE` de repli et croirait à une panne).
  *
+ * @param server - serveur à mettre en écoute.
+ * @param host - hôte passé à `listen`.
+ * @param plan - port désiré et nombre de replis permis.
+ * @param probe - sonde de présence (injectée par le banc).
+ * @param sharedListener - vrai dans un worker `node:cluster` : le port y est
+ *   PARTAGÉ par le maître, et un voisin qui y répond est un frère, pas un
+ *   conflit. Sans cette exception, `nodefony cluster -w N` ne gardait qu'un
+ *   worker en vie — les autres mouraient sur « port déjà servi » et
+ *   bouclaient en relance.
  * @returns l'adresse obtenue + le port désiré si un décalage a eu lieu.
  * @throws l'erreur de `listen` : soit un code qui ne dit pas « ce port est pris »
  *   (`ENOTFOUND`, `EACCES` sous 1024 — cf `isPortUnavailable`), soit un port
  *   indisponible après épuisement des essais (le fallback n'est PAS infini).
  */
-export declare function bindWithFallback(server: Listenable, host: string, plan: BindPlan, probe?: PortListeningProbe): Promise<BindResult>;
+export declare function bindWithFallback(server: Listenable, host: string, plan: BindPlan, probe?: PortListeningProbe, sharedListener?: boolean): Promise<BindResult>;

package/docs/cookies.md

@@ -255,13 +255,13 @@ constructeur de `Cookie` (`cookie.ts:130`).
 
 | Besoin                         | Appel                                                 | Où                                       |
 | ------------------------------ | ----------------------------------------------------- | ---------------------------------------- |
-| Lire un cookie entrant         | `context.getRequestCookies("nom")` → `Cookie \| null` | `getRequestCookies()` (`Context.ts:660`) |
+| Lire un cookie entrant         | `context.getRequestCookies("nom")` → `Cookie \| null` | `getRequestCookies()` (`Context.ts:674`) |
 | Lire tous les cookies entrants | `context.cookies` → `Record<string, Cookie>`          | `cookies` (`Context.ts:193`)             |
-| Écrire un cookie sortant       | `context.setCookie(new Cookie(…))`                    | `setCookie()` (`Context.ts:667`)         |
-| Supprimer un cookie sortant    | `response.deleteCookieByName("nom")`                  | `http/Response.ts:156`                   |
+| Écrire un cookie sortant       | `context.setCookie(new Cookie(…))`                    | `setCookie()` (`Context.ts:685`)         |
+| Supprimer un cookie sortant    | `response.deleteCookieByName("nom")`                  | `http/Response.ts:213`                   |
 
-Côté réponse HTTP, `addCookie()` (`http/Response.ts:138`) enregistre le cookie, et `setCookies()`
-(`http/Response.ts:164`) émet **une ligne `Set-Cookie` par cookie** — un tableau passé à Node, jamais une
+Côté réponse HTTP, `addCookie()` (`http/Response.ts:195`) enregistre le cookie, et `setCookies()`
+(`http/Response.ts:221`) émet **une ligne `Set-Cookie` par cookie** — un tableau passé à Node, jamais une
 boucle de `setHeader` (qui écraserait tout sauf le dernier). Pour expirer un cookie chez le client :
 `clearCookie()` (`cookie.ts:200`) recule `Expires` à l'époque.
 
@@ -269,7 +269,7 @@ boucle de `setHeader` (qui écraserait tout sauf le dernier). Pour expirer un co
 
 `cookiesParser(context)` (`cookie.ts:87`) lit l'en-tête `Cookie:` (via la bibliothèque `cookie`,
 `parser()` `cookie.ts:50`), crée un `Cookie` par entrée et l'ajoute au contexte avec `addRequestCookie()`
-(`Context.ts:650`). Il est déclenché automatiquement par le pipeline : `parseCookies()` est appelé à
+(`Context.ts:664`). Il est déclenché automatiquement par le pipeline : `parseCookies()` est appelé à
 l'initialisation du contexte HTTP (`HttpContext.ts:190`) **et** WebSocket (`WebsocketContext.ts:170`).
 
 ### Côté WebSocket — lecture oui, écriture non
@@ -284,12 +284,12 @@ 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:39`). Le seul cookie **piloté par la config** est celui
-de la **session** — bloc Zod `sessionCookieSchema` (`config.ts:748`), avec notamment `hostPrefix`
+de la **session** — bloc Zod `sessionCookieSchema` (`config.ts:752`), 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
-`getSessionCookieName()` (`Context.ts:714`) — encore un détail qui appartient à la page Sessions.
+`getSessionCookieName()` (`Context.ts:733`) — encore un détail qui appartient à la page Sessions.
 
 ## 🛡️ Défenses par attribut
 
@@ -322,7 +322,7 @@ Le nom effectif du cookie de session (avec ou sans `__Host-` selon le transport)
 | `new Cookie(..., { signed: true })` **jette**             | Aucun `secret` configuré → refus du secret prévisible (fail-closed)       | Passer un `secret` réel (`{ signed: true, secret: … }`)                  |
 | Modifier un cookie entrant ne change rien côté client     | Lecture (`context.cookies`) et écriture (réponse) ne sont pas symétriques | (Re)poser le cookie sur la réponse : `context.setCookie(new Cookie(…))`  |
 | Le cookie WS posé au handshake n'arrive jamais            | `setCookie`/`setCookies` de la réponse WS sont des no-op (`ws`)           | Poser le cookie pendant la phase HTTP avant l'upgrade (cf session)       |
-| Deux `Set-Cookie` s'écrasent, un seul survit              | Un `setHeader('Set-Cookie', str)` remplace le précédent                   | Déjà géré : `setCookies()` passe un **tableau** (`http/Response.ts:164`) |
+| Deux `Set-Cookie` s'écrasent, un seul survit              | Un `setHeader('Set-Cookie', str)` remplace le précédent                   | Déjà géré : `setCookies()` passe un **tableau** (`http/Response.ts:221`) |
 | `SameSite` mal orthographié devient `Lax` silencieusement | Fallback fail-safe sur `Lax`                                              | Attendu — vérifier la casse ; `Strict`/`Lax`/`None` seulement            |
 | `maxAge` interprété en millisecondes                      | `maxAge` est en **secondes** (comme `Set-Cookie` Max-Age)                 | Passer des secondes (`30*24*60*60`), pas des ms                          |
 
@@ -330,7 +330,7 @@ Le nom effectif du cookie de session (avec ou sans `__Host-` selon le transport)
 
 Il n'y a pas d'écran Studio dédié aux cookies applicatifs (le cookie **de session** est surfacé dans
 l'écran **Sessions**). En développement, chaque écriture de cookie est journalisée en `DEBUG` par la
-réponse HTTP (`ADD COOKIE ==> …`, `setCookie()` `http/Response.ts:184`) — visible via le skill
+réponse HTTP (`ADD COOKIE ==> …`, `setCookie()` `http/Response.ts:241`) — visible via le skill
 `nodefony-tail-error-logs` ou le Suivi de requête. Sur le fil, un `curl -i` montre les lignes `Set-Cookie`.
 
 ## 🧪 Tests & couverture

package/docs/index.md

@@ -125,8 +125,10 @@ se périmeraient en silence.
 ## ⚙️ Configuration
 
 Tout se déclare dans `nodefony.config.ts` via `use("@nodefony/http", { … })`. Les blocs Zod
-(`nodefony/config/config.ts`) couvrent : `servers` (ports, transport, TLS, HTTP/2), `session` et
-`cookie`, `trustProxy`, `certificates`, `upload`, le rate-limit et les fichiers statiques. Chaque page
+(`nodefony/config/config.ts`) couvrent : `http`, `https`, `http2` (transport, TLS), `websocket` / `websocketSecure`, `session`
+(dont `session.cookie`), `trustProxy` et `trustedHosts`, `certificates`, `upload` et `maxBodySize`,
+`rateLimit`, `health` et `statics`. La topologie (`servers` : ports, protocole, politique de port) est
+un bloc de la configuration d'application, pas de ce module. Chaque page
 de brique détaille son bloc et ses défauts réels.
 
 ## 📜 Normes appliquées

package/docs/observabilite.md

@@ -112,12 +112,12 @@ 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:455` pour HTTP, `http-kernel.ts:455` pour WS), et se lit de n'importe où avec
+(`http-kernel.ts:1510` pour HTTP, `http-kernel.ts:1929` 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
 `IRequestLogger` (`IRequestLogger.ts:25`) résolu au boot depuis la config (`applyRequestLoggerFromConfig`,
-`http-kernel.ts:682`), remplaçable à chaud par `httpKernel.setRequestLogger(...)` (`http-kernel.ts:888`).
+`http-kernel.ts:682`), remplaçable à chaud par `httpKernel.setRequestLogger(...)` (`http-kernel.ts:910`).
 Trois formateurs sont livrés ; un quatrième maison s'écrit en implémentant l'interface.
 
 **Zero Trust sur l'entrée cliente.** Un `X-Request-Id` fourni par le client finit réfléchi en réponse,
@@ -226,16 +226,16 @@ GET  200 /trace/whoami 3.1ms 127.0.0.1                   [demo-abc]
 | ------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Génération          | `Context.requestId = randomUUID()` (`Context.ts:244`)               | UUID v4 posé dans le constructeur de base — HTTP **et** WS.                                                                                                                             |
 | Adoption HTTP       | `sanitizeRequestId(headers["x-request-id"])` (`HttpContext.ts:158`) | Remplace l'UUID **si** la valeur cliente est sûre, sinon on garde l'UUID.                                                                                                               |
-| Adoption WS         | `sanitizeRequestId(...)` au handshake (`WebsocketContext.ts:139`)   | Même validation, stable sur toute la durée de la socket (handshake → close).                                                                                                            |
-| Réflexion HTTP/1.1  | `Response.setHeader("x-request-id", …)` (`Response.ts:191`)         | Écrit dans `writeHead()`, sur **chaque** réponse.                                                                                                                                       |
+| Adoption WS         | `sanitizeRequestId(...)` au handshake (`WebsocketContext.ts:162`)   | Même validation, stable sur toute la durée de la socket (handshake → close).                                                                                                            |
+| Réflexion HTTP/1.1  | `Response.setHeader("x-request-id", …)` (`Response.ts:248`)         | Écrit dans `writeHead()`, sur **chaque** réponse.                                                                                                                                       |
 | Réflexion HTTP/2    | `this.headers["x-request-id"] = requestId` (`http2/Response.ts:71`) | Sinon les réponses du port 5152 sortiraient sans corrélation.                                                                                                                           |
-| ALS (HTTP)          | `RequestContext.run({ requestId, … })` (`http-kernel.ts:455`)       | Ouvre la bulle → tout `Pdu` créé dedans est tagué.                                                                                                                                      |
-| ALS (WS)            | `RequestContext.run({ requestId, … })` (`http-kernel.ts:455`)       | Handshake **et** messages : la bulle ouverte à la connexion est reliée à chaque message par `AsyncResource.bind`, sinon l'identité résolue au handshake se perdrait au premier message. |
+| ALS (HTTP)          | `RequestContext.run({ requestId, … })` (`http-kernel.ts:1510`)      | Ouvre la bulle → tout `Pdu` créé dedans est tagué.                                                                                                                                      |
+| ALS (WS)            | `RequestContext.run({ requestId, … })` (`http-kernel.ts:1929`)      | Handshake **et** messages : la bulle ouverte à la connexion est reliée à chaque message par `AsyncResource.bind`, sinon l'identité résolue au handshake se perdrait au premier message. |
 | Capture dans le log | `Pdu.requestId = Pdu.requestIdProvider?.()` (`Pdu.ts:262`)          | Provider injectable branché sur l'ALS côté Node — 0 lecture côté navigateur.                                                                                                            |
 
 > [!IMPORTANT]
 > Les logs de **fin** de requête (bilan `req`, `onClose`) sont émis **hors** de la bulle ALS (déjà
-> refermée). L'override `Context.log()` (`Context.ts:520`) rouvre alors une micro-bulle depuis
+> refermée). L'override `Context.log()` (`Context.ts:535`) rouvre alors une micro-bulle depuis
 > `this.requestId` pour que le `Pdu` capture quand même la corrélation — sinon la ligne d'entrée d'une
 > trace serait la seule à ne PAS porter son `requestId`.
 
@@ -249,15 +249,15 @@ Nodefony implémente **W3C Trace Context** (le code s'y réfère explicitement,
 - La validation refuse `version=ff` et un `traceId`/`spanId` tout-à-zéro — `parseTraceparent()`
   (`trace.ts:38`), conforme à la spec (le récepteur NE DOIT PAS propager ces valeurs).
 
-Le `traceparent` résolu est propagé en ALS **et** réfléchi sur la réponse HTTP (`context/http/Response.ts:494`). Côté
+Le `traceparent` résolu est propagé en ALS **et** réfléchi sur la réponse HTTP (`context/http/Response.ts:551`). Côté
 **WebSocket**, il est propagé en ALS mais **pas** réfléchi dans la réponse de handshake — la bibliothèque
 `ws` n'expose pas proprement ce chemin (`http-kernel.ts:1419`) ; la corrélation reste visible côté serveur.
 
 ### Le contrat de logger — `IRequestLogger`
 
 Le kernel tient un `IRequestLogger` singleton (`http-kernel.ts:289`) et lui délègue le rendu de la ligne
-de bilan, au teardown, via `Context.logRequest()` (`Context.ts:595`) côté HTTP et
-`WebsocketContext.logRequest()` (`WebsocketContext.ts:209`) côté WS. Le contrat a trois méthodes
+de bilan, au teardown, via `Context.logRequest()` (`Context.ts:608`) côté HTTP et
+`WebsocketContext.logRequest()` (`WebsocketContext.ts:233`) côté WS. Le contrat a trois méthodes
 (`IRequestLogger.ts:25`) :
 
 - `renderHttp(context, error?)` → `{ text, severity, msgid }` remis à `context.log()`.
@@ -337,7 +337,7 @@ Singleton sans état, 0 allocation par requête (`request-logger.ts:21`). Conser
 ### Écrire son propre formateur
 
 Implémenter `IRequestLogger` (`IRequestLogger.ts:25`) et l'injecter — NCSA Common Log Format, syslog RFC
-5424 texte, OpenTelemetry logs… `httpKernel.setRequestLogger(monLogger)` (`http-kernel.ts:888`). Les trois
+5424 texte, OpenTelemetry logs… `httpKernel.setRequestLogger(monLogger)` (`http-kernel.ts:910`). Les trois
 formateurs et le type sont exportés depuis `@nodefony/http` (`index.ts:221`).
 
 ## 🔐 Sécurité
@@ -418,9 +418,9 @@ instancié **qu'en dev** (fuite d'info + coût en prod).
 | Symptôme                                            | Cause                                                               | Correction                                                                         |
 | --------------------------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
 | 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:520`)           |
+| 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:535`)           |
 | Réponse HTTP/2 sans `x-request-id`                  | Chemin de réponse h2 distinct du 1.1                                | Déjà géré (`http2/Response.ts:106`) — 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:1698`)                |
+| 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:1915`)                |
 | 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

@@ -55,7 +55,7 @@ flowchart TD
 Trois idées à retenir :
 
 1. **La clé est l'IP, pas l'utilisateur.** On borne du **trafic**, pas des identités. L'IP est
-   résolue exactement comme pour les logs et l'audit (`resolveForwarded()`, `http-kernel.ts:1020`) —
+   résolue exactement comme pour les logs et l'audit (`resolveForwarded()`, `http-kernel.ts:1089`) —
    non falsifiable tant que `trustProxy` n'accorde pas sa confiance à un proxy.
 2. **Le verdict porte tout.** Un seul appel `hit(key)` (`IRateLimitStore.ts:79`) rend un
    `RateLimitVerdict` (`IRateLimitStore.ts:20`) qui contient déjà limite, restant, reset et
@@ -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:1065`) : `null` tant qu'on ne l'active pas → **0
+laisse donc `rateLimit` désarmé par défaut (`config.ts:1069`) : `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.
 
@@ -118,7 +118,7 @@ court intervalle (`MemoryRateLimitStore.ts:29`). Acceptable pour une défense de
 _sliding window_ viendrait en option si le besoin s'en fait sentir.
 
 **Refoulé avant toute allocation.** Le verdict est rendu **avant** le contexte, la portée DI et l'ALS
-(`http-kernel.ts:1019`) : un flood coûte un `Map.get` et rien d'autre. Le contrat `hit()` est
+(`http-kernel.ts:1097`) : un flood coûte un `Map.get` et rien d'autre. Le contrat `hit()` est
 **synchrone** à dessein (`IRateLimitStore.ts:8`) — aucune `Promise`, aucune microtask sur le chemin de
 chaque requête.
 
@@ -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:433`).
+reconstruit le compteur sans redémarrage (`configureRateLimit()`, `http-kernel.ts:444`).
 
 ### 2. Observer le 429 et les en-têtes
 
@@ -178,7 +178,7 @@ X-RateLimit-Reset: 1753082460
 Retry-After: 42
 ```
 
-- `X-RateLimit-Remaining` : requêtes restantes dans la fenêtre (`http-kernel.ts:1030`).
+- `X-RateLimit-Remaining` : requêtes restantes dans la fenêtre (`http-kernel.ts:1099`).
 - `X-RateLimit-Reset` : **epoch en secondes** de la fin de fenêtre (`http-kernel.ts:1031`).
 - `Retry-After` (sur le `429` seulement) : secondes à attendre, **jamais 0** — un `Retry-After: 0`
   relancerait un client bien élevé immédiatement (`MemoryRateLimitStore.ts:80`).
@@ -203,12 +203,12 @@ flowchart TD
 
 Autour de ce cœur, le kernel orchestre le cycle de vie :
 
-- **Construction / reconfiguration** : `configureRateLimit()` (`http-kernel.ts:433`) instancie le store
-  depuis la config (`windowMs = windowS × 1000`, `http-kernel.ts:433`) et arme un `GcScheduler`
-  (`http-kernel.ts:443`) qui **purge les fenêtres expirées** hors du chemin chaud.
-- **Émission HTTP** : sous le quota, les en-têtes `X-RateLimit-*` sont posés (`http-kernel.ts:1029`) et
-  la requête continue ; au-delà, `Retry-After` (`http-kernel.ts:1036`) puis `writeHead(429)`
-  (`http-kernel.ts:1041`) — corps vide, on ne journalise pas chaque rejet (amplificateur sous flood).
+- **Construction / reconfiguration** : `configureRateLimit()` (`http-kernel.ts:444`) instancie le store
+  depuis la config (`windowMs = windowS × 1000`, `http-kernel.ts:454`) et arme un `GcScheduler`
+  (`http-kernel.ts:460`) qui **purge les fenêtres expirées** hors du chemin chaud.
+- **Émission HTTP** : sous le quota, les en-têtes `X-RateLimit-*` sont posés (`http-kernel.ts:1098`) et
+  la requête continue ; au-delà, `Retry-After` (`http-kernel.ts:1105`) puis `writeHead(429)`
+  (`http-kernel.ts:1110`) — corps vide, on ne journalise pas chaque rejet (amplificateur sous flood).
 - **Borne mémoire** : au cap `maxTracked`, le store purge les expirées puis évince en **FIFO**
   (`#evict`, `MemoryRateLimitStore.ts:169`) — la mémoire ne dérive jamais.
 
@@ -242,19 +242,19 @@ 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:1619`) — **avant** `enterScope`, l'ALS et le pipeline, comme le `429` HTTP.
+(`http-kernel.ts:1848`) — **avant** `enterScope`, l'ALS et le pipeline, comme le `429` HTTP.
 
 Deux plafonds distincts, tous deux par IP forwarded-aware :
 
 | Plafond                | Ce qu'il borne                                 | Source de config        | Refus                                                      |
 | ---------------------- | ---------------------------------------------- | ----------------------- | ---------------------------------------------------------- |
-| Débit de handshakes    | Ouvertures/seconde (le **même** compteur HTTP) | `rateLimit`             | close `1013` (`http-kernel.ts:1638`)                       |
-| Connexions simultanées | Sockets **ouvertes** en même temps par IP      | `wsMaxConnectionsPerIp` | close `1013` — `tryAcquire` refuse (`http-kernel.ts:1649`) |
+| Débit de handshakes    | Ouvertures/seconde (le **même** compteur HTTP) | `rateLimit`             | close `1013` (`http-kernel.ts:448`)                        |
+| Connexions simultanées | Sockets **ouvertes** en même temps par IP      | `wsMaxConnectionsPerIp` | close `1013` — `tryAcquire` refuse (`http-kernel.ts:1882`) |
 
 Le cap concurrent est porté par un compteur dédié, `WsConnectionCounter` (`WsConnectionCounter.ts:18`) :
 `tryAcquire(ip)` (`WsConnectionCounter.ts:33`) réserve un créneau à l'upgrade, `release(ip)`
 (`WsConnectionCounter.ts:45`) le rend à la fermeture — branché sur `ws.once("close", …)`
-(`http-kernel.ts:1652`), donc jamais de fuite de compteur, même sur un `terminate` de heartbeat.
+(`http-kernel.ts:1887`), donc jamais de fuite de compteur, même sur un `terminate` de heartbeat.
 
 > [!WARNING]
 > `wsMaxConnectionsPerIp` a une **portée par process** (1 pod) : il ne voit que le trafic de son propre
@@ -280,14 +280,14 @@ Un adapter doit fournir : `hit(key)` (verdict de fenêtre), `gc()` (purge), `lis
 
 | Domaine                            | Norme            | Ancrage                                           |
 | ---------------------------------- | ---------------- | ------------------------------------------------- |
-| `429 Too Many Requests`            | RFC 6585 §4      | `writeHead(429)` (`http-kernel.ts:1041`)          |
-| `Retry-After` (delta-seconds)      | RFC 9110 §10.2.3 | en-tête posé sur le `429` (`http-kernel.ts:1036`) |
-| IP cliente derrière proxy          | RFC 7239         | `resolveForwarded()` (`http-kernel.ts:1020`)      |
+| `429 Too Many Requests`            | RFC 6585 §4      | `writeHead(429)` (`http-kernel.ts:1110`)          |
+| `Retry-After` (delta-seconds)      | RFC 9110 §10.2.3 | en-tête posé sur le `429` (`http-kernel.ts:1105`) |
+| IP cliente derrière proxy          | RFC 7239         | `resolveForwarded()` (`http-kernel.ts:1089`)      |
 | WebSocket — close `1013` Try Again | RFC 6455 §7.4.1  | refus d'upgrade (`http-kernel.ts:1378`)           |
 
 > [!NOTE]
 > Les en-têtes émis sont la famille **de facto** `X-RateLimit-Limit/Remaining/Reset`
-> (`http-kernel.ts:1000`), largement déployée et lue par les clients. Le brouillon IETF
+> (`http-kernel.ts:1098`), largement déployée et lue par les clients. Le brouillon IETF
 > `draft-ietf-httpapi-ratelimit-headers` (en-têtes `RateLimit` / `RateLimit-Policy`) n'est **pas** encore
 > émis — une évolution possible, pas une régression : rien ne le promet aujourd'hui.