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

package/docs/servers.md

@@ -85,7 +85,7 @@ Trois idées à retenir, et tout le reste en découle :
 | Drain                | Vidange : laisser finir les requêtes en cours avant de fermer, plutôt que couper les sockets.                     |
 | Liveness / Readiness | Sondes cloud : « le processus est-il vivant ? » / « peut-il recevoir du trafic ? ».                               |
 | SIGTERM              | Signal d'arrêt poli envoyé par l'orchestrateur (k8s, `docker stop`) avant le `SIGKILL`.                           |
-| SAN                  | _Subject Alternative Name_ : la liste des noms/IP qu'un certificat couvre réellement (RFC 6125).                  |
+| SAN                  | _Subject Alternative Name_ : la liste des noms/IP qu'un certificat couvre réellement (RFC 9525).                  |
 | mkcert               | Outil de développement qui installe une autorité de certification locale **de confiance** sur la machine.         |
 | Reverse-proxy / edge | Le nginx / HAProxy / ingress placé devant l'application, souvent porteur du TLS.                                  |
 | `X-Forwarded-*`      | En-têtes ajoutés par un proxy pour dire l'IP, l'hôte et le protocole d'origine du client.                         |
@@ -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:1619`) —, hérite de la même
+_est_ une requête HTTP (`HttpKernel.onWebsocketRequest()`, `http-kernel.ts:1964`) —, 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:1050`). Elle ne fait rien aujourd'hui.
+> marquée `reserved` (`config.ts:1216`). Elle ne fait rien aujourd'hui.
 
 ## 🚀 Démarrage rapide
 
@@ -249,22 +249,31 @@ export default PingController;
 
 ### 4. Ce qu'on observe au boot
 
-Le kernel démarre les serveurs à la phase `onReady` (`Kernel.ts:1274`), 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`) :
+Le kernel démarre les serveurs à la phase `onReady` (`Kernel.ts:1355`). En développement, le
+bilan de démarrage (`renderStartupHuman`, `startupScreen.ts`) dit d'abord **où aller**,
+puis **ce qui est à regarder**, puis les adresses d'écoute :
 
 ```text
-  ✓  Prêt en 1.4s
+  ✓  Prêt en 6,1 s — Nodefony 10.0.0 · development
 
-     Serveurs
-     ➜  HTTP     http://127.0.0.1:5151
-     ➜  HTTP/2   https://127.0.0.1:5152
-     ➜  WS       ws://127.0.0.1:5151
-     ➜  WSS      wss://127.0.0.1:5152
+  OUVRIR
+    ➜  Application   https://localhost:5152/
+    ➜  Studio        https://localhost:5152/nodefony
+
+  ÉTAT
+    Mode        development · rechargement auto
+    Écoute      HTTP + WS 127.0.0.1:5151 · HTTP/2 + WSS 127.0.0.1:5152
 ```
 
-Hors écran animé (production, CI, `--debug`), ce sont les bannières par serveur qui sortent
-(`ServerHttp.showBanner()`, `server-http.ts:242`, appelées par le kernel — `Kernel.ts:561`) :
+L'adresse à **ouvrir** n'est pas l'adresse de **liaison** : un serveur lié à `127.0.0.1` ou à
+`0.0.0.0` s'ouvre sur `localhost` (`openableHost`, `bootReport.ts:216`) — les passkeys refusent
+une IP comme domaine, et un cookie posé sous un nom ne part pas sous l'autre. Hors d'un
+terminal, le même bilan sort ligne à ligne (`open.app: https://localhost:5152/`,
+`listen.https: 127.0.0.1:5152`) ; pour une machine, `nodefony status --json` le rend en entier.
+
+Hors écran animé (production, CI, `--debug`, sortie non-terminal), les bannières par serveur
+sortent aussi (`ServerHttp.showBanner()`, `server-http.ts:239`, appelées par le kernel —
+`Kernel.ts:1403`) :
 
 ```text
 Server Listen on http://127.0.0.1:5151 Family: IPv4 Protocol : 1.1
@@ -327,8 +336,8 @@ Choisir en cinq secondes :
 | `server-websocket-secure` | `wss://` — 5152     | `server-https` actif      | WebSocket adossé au serveur TLS.                   |
 | `server-static`           | (aucun port propre) | toujours enregistré       | Fichiers statiques, en **repli** après le routing. |
 
-L'assemblage est fait par `HttpKernel.initServers()` (`http-kernel.ts:1065`) : chaque serveur est
-consulté sur son drapeau `active`, un serveur désactivé est **sauté**, pas créé (`http-kernel.ts:1062`).
+L'assemblage est fait par `HttpKernel.initServers()` (`http-kernel.ts:1223`) : chaque serveur est
+consulté sur son drapeau `active`, un serveur désactivé est **sauté**, pas créé (`http-kernel.ts:1223`).
 Les serveurs WebSocket ne sont montés que si leur porteur l'a été.
 
 ### `server-http` — HTTP/1.1 en clair
@@ -375,7 +384,7 @@ automatiquement un éventuel décalage de port.
   réglages **forcés** par Nodefony : `server` et `clientTracking: true`, requis par `broadcast()` et par
   le battement de cœur (`server-websocket.ts:80`).
 - **Keep-alive** armé à la création (`startHeartbeat()`, `server-websocket.ts:87`) et par connexion
-  (`trackPong()`, `server-websocket.ts:103`).
+  (`trackPong()`, `server-websocket.ts:113`).
 - **Arrêt** : il s'inscrit en tête des écouteurs de terminaison
   (`prependOnceListener`, `server-websocket.ts:91`) — l'ordre
   compte, voir la section Arrêt gracieux.
@@ -400,7 +409,7 @@ 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:149`) |
-| **Comment** ces serveurs se comportent ?  | `use("@nodefony/http", { … })` | `httpConfigSchema` (`config.ts:989`)                      |
+| **Comment** ces serveurs se comportent ?  | `use("@nodefony/http", { … })` | `httpConfigSchema` (`config.ts:1171`)                     |
 
 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.
@@ -451,16 +460,16 @@ Depuis `http2Schema` (`config.ts:353`), appliqué seulement si défini
 
 ### Niveau 2 — WebSocket (`websocket` et `websocketSecure`)
 
-Depuis `websocketSchema` (`config.ts:517`). Les deux sections partagent la forme et les défauts ; le WSS
-lit `websocketSecure` (`config.ts:1058`).
+Depuis `websocketSchema` (`config.ts:535`). Les deux sections partagent la forme et les défauts ; le WSS
+lit `websocketSecure` (`config.ts:1240`).
 
 | 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:543`).       |
-| `allowedOrigins`         | bool \| str \| list | `false` | Allowlist d'`Origin` au handshake — **anti-CSWSH** (`config.ts:552`).              |
+| `maxPayload`             | octets              | `1 MiB` | Taille max d'un message entrant → au-delà, **close 1009** (`config.ts:561`).       |
+| `allowedOrigins`         | bool \| str \| list | `false` | Allowlist d'`Origin` au handshake — **anti-CSWSH** (`config.ts:570`).              |
 | `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`.   |
@@ -484,7 +493,7 @@ panne, c'est une nuisance.
 
 ### La règle
 
-`resolvePortPolicy()` (cœur, `src/nodefony/src/service/dev/devProcess.ts:1730` — la même règle sert `nodefony doctor`) tranche selon l'environnement, et la valeur explicite gagne
+`resolvePortPolicy()` (cœur, `src/nodefony/src/service/dev/devProcess.ts:1845` — la même règle sert `nodefony doctor`) tranche selon l'environnement, et la valeur explicite gagne
 toujours :
 
 | Environnement | Défaut   | Pourquoi                                                                                                     |
@@ -504,9 +513,11 @@ WARNING  Port 5151 déjà occupé → HTTP écoute sur 5153.
 Le décalage est **toujours annoncé** (`server-http.ts:130`) : jamais de dégradation silencieuse. Trois
 détails d'implémentation valent d'être connus, parce qu'ils expliquent des comportements surprenants.
 
-1. **On retente au `listen()`, jamais après une sonde.** Demander « le port est-il libre ? » puis
-   binder est une course : entre la réponse et le bind, un autre processus peut prendre le port. Le
-   `listen()` est atomique — on retente donc sur l'échec réel (`bindWithFallback()`,
+1. **Le repli se décide au `listen()`, qui est atomique.** Une seule sonde le précède, sur le port
+   désiré : elle détecte un serveur déjà présent sur la boucle locale, que le noyau accorderait quand
+   même à un `0.0.0.0` (`detectPortConflict`). Elle est **sautée dans un worker de cluster**
+   (`cluster.isWorker`) : le port y est partagé par le maître, et le voisin qui répond est un frère,
+   pas un intrus. La course résiduelle retombe sur `EADDRINUSE` (`bindWithFallback()`,
    `portBinder.ts:263`).
 2. **Le port de l'autre serveur est réservé.** Si HTTP est chassé de 5151, incrémenter naïvement le
    ferait voler 5152 à HTTPS, qui se décalerait à son tour. Les ports convoités par les autres serveurs
@@ -524,9 +535,10 @@ laisser un processus se croire démarré.
 
 Si le port peut glisser, alors « le serveur écoute sur 5151 » n'est plus une vérité mais une
 convention — et `nodefony status`, `nodefony stop` ou l'attente de disponibilité sonderaient un port
-que personne n'écoute. `HttpKernel.publishRuntimePorts()` (`http-kernel.ts:1096`) écrit donc la
+que personne n'écoute. `HttpKernel.publishRuntimePorts()` (`http-kernel.ts:1279`) écrit donc la
 topologie réelle (pid, ports obtenus, ports désirés) dans un fichier d'état, **dans tous les
-environnements** : une application qui déclare son port via `PORT` (PaaS) sort aussi de la convention,
+environnements** : une application qui déclare son port (`NF_PORT`, `NF_PORT_HTTPS` ou `servers.http.port`) sort
+aussi de la convention,
 même en `strict`. L'écriture est au mieux-effort — une image en lecture seule ne fait jamais tomber un
 serveur qui, lui, écoute très bien.
 
@@ -537,19 +549,19 @@ 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:407`).
+(`Certificate.resolveStrategy()`, `certificates.ts:577`).
 
 ### Les quatre stratégies
 
-Réglées par `certificates.strategy` (`certificatesSchema`, `config.ts:475`), résolues par
-`Certificate.resolveStrategy()` (`certificates.ts:407`).
+Réglées par `certificates.strategy` (`certificatesSchema`, `config.ts:479`), résolues par
+`Certificate.resolveStrategy()` (`certificates.ts:577`).
 
 | Stratégie       | Quand l'utiliser                            | Ce qui se passe                                                             |
 | --------------- | ------------------------------------------- | --------------------------------------------------------------------------- |
 | `auto` (défaut) | On ne veut pas décider                      | `key`+`cert` fournis → `explicit` ; sinon mkcert en dev ; sinon auto-signé. |
 | `explicit`      | **Production**                              | Charge `key`/`cert`/`ca` depuis la config. Erreur au boot si absents.       |
 | `mkcert`        | Développement avec HTTPS sans avertissement | CA locale de confiance → HMR cross-origin et WSS sans erreur navigateur.    |
-| `selfsigned`    | Secours, CI, machine sans mkcert            | Auto-signé node-forge, non trusté.                                          |
+| `selfsigned`    | Secours, CI, machine sans mkcert            | Auto-signé (`node:crypto`), non trusté.                                     |
 
 ```typescript
 // nodefony.config.ts — production : certificat fourni, jamais généré
@@ -572,13 +584,38 @@ 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:401`).
+> l'annonce et retombe sur l'auto-signé (`certificates.ts:602`).
 
 ### 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:238`) : en production avec un certificat
-fourni, elle n'entre jamais dans le processus (`certificates.ts:238`).
+Aucune génération : le certificat fourni est lu tel quel (`certificates.ts:330`). La génération de
+l'auto-signé, elle, n'emploie que `node:crypto` (`x509.ts`) — aucune dépendance cryptographique
+tierce n'est installée avec `@nodefony/http`.
+
+### Autorités sortantes — `extraCaFiles`
+
+Les certificats ci-dessus sont ceux que l'application **présente**. L'inverse compte autant :
+quand l'application **appelle** un autre service en `https` (Keycloak, une API partenaire, l'amont
+du proxy inverse), elle n'accepte que les certificats signés par une autorité qu'elle connaît. Une
+autorité publique ne demande rien, et celle de développement de Nodefony est reconnue d'office ;
+une autorité **d'entreprise** se déclare :
+
+```typescript ignore
+use("@nodefony/http", {
+  certificates: {
+    // Fichiers PEM, absolus ou relatifs à la racine de l'application.
+    // Un fichier peut porter une chaîne entière (racine + intermédiaires).
+    extraCaFiles: ["certs/autorite-entreprise.pem"],
+  },
+});
+```
+
+Le gabarit d'application la lit dans `NF_TLS_CA_FILE`. Les autorités sont ajoutées à celles du
+processus à l'enregistrement du module, avant tout service — donc aussi pour une commande en ligne
+(`Http.onKernelRegister()`, `index.ts:104` ; `trustCaFile()`, `certificates.ts:131`). Un fichier
+introuvable ou sans certificat **interrompt le démarrage** en nommant le chemin (code 78), plutôt
+qu'un `fetch failed` loin de sa cause. C'est l'équivalent de `NODE_EXTRA_CA_CERTS`, porté par la
+configuration : rien à poser au lancement, et la même écriture sous Windows.
 
 ### Conformité de l'auto-signé
 
@@ -588,15 +625,15 @@ 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 | `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:302`) |
-| Le SAN fait foi, pas le CN              | RFC 6125             | SAN dérivé du kernel si non fourni (`config.ts:444`)      |
+| Numéro de série aléatoire 128 bits      | RFC 5280 §4.1.2.2    | `Certificate.generateSerialHex()` (`certificates.ts:443`) |
+| Le SAN fait foi, pas le CN              | RFC 9525             | 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:579`) le régénère s'il est expiré, s'il est signé en SHA-1, ou si son SAN ne couvre
+(`certificates.ts:743`) 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.
 
@@ -618,7 +655,7 @@ sont ignorés** (`config.ts:965`), et l'IP retenue est celle de la socket réell
 | `"loopback"`, `"linklocal"`, `"uniquelocal"` | Préréglages de plages privées.                                     |
 
 La politique est compilée **une seule fois** au premier usage (`HttpKernel.getTrustProxyChecker()`,
-`http-kernel.ts:562`, via `buildTrustProxy()`, `trustProxy.ts:100`) : aucune structure allouée par
+`http-kernel.ts:627`, via `buildTrustProxy()`, `trustProxy.ts:103`) : aucune structure allouée par
 requête. La résolution de l'IP cliente remonte la chaîne **de droite à gauche** depuis la socket réelle
 (`resolveForwarded()`, `forwarded.ts:253`) — conforme RFC 7239 et à la recommandation OWASP.
 
@@ -626,7 +663,7 @@ requête. La résolution de l'IP cliente remonte la chaîne **de droite à gauch
 
 Barrière testée **avant le routage**, contre l'injection d'en-tête `Host`. Le domaine canonique du
 kernel est toujours accepté, plus le loopback en développement (`HttpKernel.compileAlias()`,
-`http-kernel.ts:964`). `false` (défaut) = ce socle seul ; une liste ajoute des vhosts (exact ou joker
+`http-kernel.ts:1082`). `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:974`).
 
@@ -635,13 +672,13 @@ filtre déjà le `Host` (`config.ts:974`).
 Les navigateurs **n'appliquent pas CORS aux WebSockets**. Sans contrôle, une page tierce peut ouvrir un
 WS authentifié par le cookie de session de la victime (CSWSH, OWASP WSTG-CLNT-10). Nodefony exige donc
 par défaut que l'`Origin` du handshake corresponde au `Host` servi
-(`HttpKernel.checkWebsocketOrigin()`, `http-kernel.ts:621`), avec tolérance loopback en développement
+(`HttpKernel.checkWebsocketOrigin()`, `http-kernel.ts:724`), avec tolérance loopback en développement
 et allowlist explicite pour les SPA cross-origine. Un refus se solde par une fermeture **1008 (Policy
 Violation)**, jamais par un code HTTP.
 
 > [!NOTE]
 > Une requête **sans** `Origin` (client non navigateur : script, agent, test) est acceptée
-> (`http-kernel.ts:630`). Ce n'est pas un trou : un attaquant non navigateur n'a aucun besoin de CSWSH,
+> (`http-kernel.ts:642`). Ce n'est pas un trou : un attaquant non navigateur n'a aucun besoin de CSWSH,
 > il se connecte directement. Le contrôle protège les **utilisateurs**, pas le port.
 
 ## Probes de santé — `/livez` et `/readyz`
@@ -658,13 +695,13 @@ redémarrer le pod **en plein drain** par le kubelet, et casserait précisément
 protéger.
 
 Implémentation : court-circuit **total** du pipeline dans `HttpKernel.onHttpRequest()`
-(`http-kernel.ts:972`) — pas de contexte, pas de portée DI, pas de session, pas de journal par sonde,
-réponses pré-allouées (`HttpKernel.#respondHealth()`, `http-kernel.ts:497`). Et surtout : **avant le
+(`http-kernel.ts:1093`) — pas de contexte, pas de portée DI, pas de session, pas de journal par sonde,
+réponses pré-allouées (`HttpKernel.#respondHealth()`, `http-kernel.ts:561`). Et surtout : **avant le
 rate-limit**. Un kubelet qui reçoit un `429` croit le pod mort → cascade de redémarrages.
 
 | Option          | Type   | Défaut    | Effet                                                                  |
 | --------------- | ------ | --------- | ---------------------------------------------------------------------- |
-| `enabled`       | bool   | `true`    | Expose les probes (`healthSchema`, `config.ts:940`).                   |
+| `enabled`       | bool   | `true`    | Expose les probes (`healthSchema`, `config.ts:961`).                   |
 | `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). |
@@ -728,11 +765,11 @@ sequenceDiagram
 ```
 
 **Étape 1 — la disponibilité bascule en premier.** L'écouteur est posé à `onPostReady` pour être
-inséré **en tête** et donc s'exécuter **en premier** (`http-kernel.ts:515`). `readyz` répond `503`, le
+inséré **en tête** et donc s'exécuter **en premier** (`http-kernel.ts:587`). `readyz` répond `503`, le
 load balancer cesse d'envoyer du trafic, et `shutdownDelay` laisse à cette information le temps de se
 propager.
 
-**Étape 2 — les clients WebSocket sont prévenus.** `Websocket.terminate()` (`server-websocket.ts:113`)
+**Étape 2 — les clients WebSocket sont prévenus.** `Websocket.terminate()` (`server-websocket.ts:121`)
 envoie un message applicatif puis une **frame Close 1001 « Going Away »** (`server-websocket.ts:113`).
 Sans elle, la coupure TCP ferait voir un **1006** au client — code réservé, jamais émis sur le fil,
 indiscernable d'une panne réseau. Avec 1001, le client sait qu'il doit simplement se reconnecter.
@@ -770,27 +807,27 @@ ferme explicitement (`handleClientError()`, `clientError.ts:15`) : `431` si les
 
 Une socket dont le pair a disparu sans frame Close reste « ouverte » côté TCP : slot mémoire et
 descripteur retenus pour personne. Le battement de cœur les réclame
-(`startHeartbeat()`, `wsHeartbeat.ts:69`) : un ping toutes les `keepaliveInterval` ms ; sans pong dans
-les `keepaliveGracePeriod` ms, la socket est détruite (`terminate`, `wsHeartbeat.ts:98`).
+(`startHeartbeat()`, `wsHeartbeat.ts:124`) : un ping toutes les `keepaliveInterval` ms ; sans pong dans
+les `keepaliveGracePeriod` ms, la socket est détruite (`terminate`, `wsHeartbeat.ts:37`).
 
 L'implémentation est délibérément frugale — c'est du chemin chaud : **un seul `setInterval` par
 serveur**, jamais un timer par connexion ; deux horodatages posés directement sur la socket
-(`trackPong()`, `wsHeartbeat.ts:41`), donc zéro allocation par tick et aucun nettoyage à prévoir (les
+(`trackPong()`, `wsHeartbeat.ts:54`), donc zéro allocation par tick et aucun nettoyage à prévoir (les
 horodatages meurent avec la socket) ; une granularité de réveil plancher à 250 ms pour borner une
-configuration pathologique (`tick`, `wsHeartbeat.ts:81`) ; et un timer `unref` qui ne retient jamais le
+configuration pathologique (`tick`, `wsHeartbeat.ts:136`) ; et un timer `unref` qui ne retient jamais le
 processus à l'arrêt.
 
 ### Floods de connexions
 
 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:1619`). Le `101` étant déjà émis par `ws`, un `429`
+(`HttpKernel.onWebsocketRequest()`, `http-kernel.ts:1964`). 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:1644`), sans
+(`websocketQuotaRefusal()`, `http-kernel.ts:2230`), 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:1067`). En cloud-native, laisser `null` et déléguer à l'edge —
+`wsMaxConnectionsPerIp` (`config.ts:1250`). 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.
 
@@ -807,17 +844,17 @@ Le transport est du **chemin chaud absolu** : ce qui coûte ici est multiplié p
 par seconde. Les choix visibles dans le code :
 
 - **Aucun timer par connexion** — un `setInterval` par serveur WebSocket, `unref`, et deux `number` par
-  socket (`wsHeartbeat.ts:69`).
+  socket (`wsHeartbeat.ts:137`).
 - **Rien de compilé par requête** — la politique de trust-proxy, celle des `Origin` WS et les motifs de
-  `trustedHosts` sont compilés une fois et mémoïsés (`http-kernel.ts:407`, `http-kernel.ts:407`).
+  `trustedHosts` sont compilés une fois et mémoïsés (`getTrustProxyChecker()`, `http-kernel.ts:627` ; `getWsOriginPolicy()`, `http-kernel.ts:634` ; `compileAlias()`, `http-kernel.ts:1082`).
 - **Rejets avant allocation** — rate-limit HTTP et bornes WS sont vérifiés avant le contexte, la portée
   DI et l'ALS : un flood coûte une recherche dans une table de hachage.
 - **Probes hors pipeline** — réponses pré-allouées, aucun objet créé, aucun journal
-  (`http-kernel.ts:383`). Un kubelet qui sonde toutes les 2 secondes ne pèse rien.
+  (`http-kernel.ts:388`). Un kubelet qui sonde toutes les 2 secondes ne pèse rien.
 - **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:227`).
+- **Aucune génération en production** avec un certificat fourni (`certificates.ts:330`).
 
 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,
@@ -832,21 +869,21 @@ demande le backplane realtime.
 
 ## 📜 Normes appliquées
 
-| Domaine                               | Norme              | Ancrage                                                                    |
-| ------------------------------------- | ------------------ | -------------------------------------------------------------------------- |
-| HTTP/1.1 (sémantique, message)        | RFC 9110, 9112     | `node:http` + pipeline `HttpKernel.onHttpRequest()` (`http-kernel.ts:972`) |
-| HTTP/2                                | RFC 9113           | `ServerHttps.createServerH2()` (`server-https.ts:187`)                     |
-| HTTP/2 Rapid Reset                    | CVE-2023-44487     | `maxConcurrentStreams` (`config.ts:355`)                                   |
-| En-têtes trop volumineux → 431        | RFC 6585 §5        | `handleClientError()` (`clientError.ts:15`)                                |
-| 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:113`)                        |
-| 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:621`)                 |
-| En-têtes forwarded                    | RFC 7239           | `resolveForwarded()` (`forwarded.ts:253`)                                  |
-| Certificat — série, SAN, extensions   | RFC 5280           | `Certificate.generateSerialHex()` (`certificates.ts:302`)                  |
-| Certificat — identité par le SAN      | RFC 6125           | `sanSchema` (`config.ts:442`)                                              |
+| Domaine                               | Norme              | Ancrage                                                                     |
+| ------------------------------------- | ------------------ | --------------------------------------------------------------------------- |
+| HTTP/1.1 (sémantique, message)        | RFC 9110, 9112     | `node:http` + pipeline `HttpKernel.onHttpRequest()` (`http-kernel.ts:1093`) |
+| HTTP/2                                | RFC 9113           | `ServerHttps.createServerH2()` (`server-https.ts:187`)                      |
+| HTTP/2 Rapid Reset                    | CVE-2023-44487     | `maxConcurrentStreams` (`config.ts:355`)                                    |
+| En-têtes trop volumineux → 431        | RFC 6585 §5        | `handleClientError()` (`clientError.ts:15`)                                 |
+| 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:121`)                         |
+| WebSocket — 1009 « Message Too Big »  | RFC 6455 §7.4.1    | `maxPayload` (`config.ts:561`)                                              |
+| WebSocket — validation UTF-8          | RFC 6455 §8.1      | `skipUTF8Validation` (`config.ts:641`)                                      |
+| WebSocket — compression               | RFC 7692           | `perMessageDeflate` (`config.ts:585`)                                       |
+| CSWSH (Origin au handshake)           | OWASP WSTG-CLNT-10 | `HttpKernel.checkWebsocketOrigin()` (`http-kernel.ts:724`)                  |
+| En-têtes forwarded                    | RFC 7239           | `resolveForwarded()` (`forwarded.ts:253`)                                   |
+| Certificat — série, SAN, extensions   | RFC 5280           | `Certificate.generateSerialHex()` (`certificates.ts:443`)                   |
+| Certificat — identité par le SAN      | RFC 9525           | `sanSchema` (`config.ts:446`)                                               |
 
 ## ⚠️ Pièges (symptôme → cause → correction)
 
@@ -854,16 +891,16 @@ demande le backplane realtime.
 | --------------------------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
 | L'app écoute sur 5153 au lieu de 5151                           | `portPolicy: "auto"` (défaut dev) : le port était pris — c'est **annoncé** | Libérer le port, ou `servers.portPolicy: "strict"` pour échouer franchement        |
 | En production, le pod est « sain » mais injoignable             | Un port glissé en silence                                                  | Rien à faire : `strict` est le défaut hors dev — vérifier qu'on ne l'a pas forcé   |
-| `nodefony status` ne voit pas le serveur                        | Ports sondés par convention alors qu'ils ont glissé                        | Déjà géré : les ports effectifs sont publiés (`http-kernel.ts:215`)                |
+| `nodefony status` ne voit pas le serveur                        | Ports sondés par convention alors qu'ils ont glissé                        | Déjà géré : les ports effectifs sont publiés (`http-kernel.ts:220`)                |
 | Le WSS ignore `websocket.maxPayload`                            | Le serveur secure lit `websocketSecure`, section distincte                 | Régler **les deux** sections (`server-websocket-secure.ts:50`)                     |
 | Plus de WebSocket après avoir mis `servers.https: false`        | Le WSS est adossé au serveur HTTPS et tombe avec lui                       | Attendu — utiliser `ws://` sur le port clair, ou réactiver HTTPS                   |
 | Le client WebSocket voit `1006` à chaque redéploiement          | Frame Close jamais reçue (socket coupée avant)                             | Déjà géré : close `1001` avant le drain (`server-websocket.ts:134`)                |
 | Requêtes coupées à chaque mise à jour progressive               | Destruction des connexions au lieu d'un drain                              | Déjà géré (`createDrainTerminator()`) — vérifier `shutdownTimeout` < grâce k8s     |
 | Le pod redémarre en boucle pendant l'arrêt                      | `livez` répondrait `503` pendant le drain                                  | Déjà géré : `livez` reste `200`, seul `readyz` bascule                             |
-| 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`) |
+| 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:860`) |
 | `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:555`)                             |
+| 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:543`)                             |
 | `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 +923,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:862`), source unique partagée
+résumé de certificat vient de `Certificate.describe()` (`certificates.ts:973`), 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