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

package/docs/rate-limit.md

@@ -1,5 +1,5 @@
 ---
-title: "Rate-limit — plafond de trafic par IP (429, close 1013)"
+title: "Rate-limit — plafond de trafic par IP (429, HTTP et handshake WebSocket)"
 navTitle: Rate-limit
 lang: fr
 module: "@nodefony/http"
@@ -15,7 +15,7 @@ tags:
     x-ratelimit,
     fenetre-fixe,
     websocket,
-    1013,
+    handshake,
     ddos,
     trust-proxy,
   ]
@@ -27,11 +27,11 @@ coverageModule: http
 coverageFiles: rateLimit/MemoryRateLimitStore.ts,rateLimit/IRateLimitStore.ts,rateLimit/WsConnectionCounter.ts,http-kernel.ts,HttpAdminApi.ts
 ---
 
-# Rate-limit — plafond de trafic par IP (429, close 1013)
+# Rate-limit — plafond de trafic par IP (429, HTTP et handshake WebSocket)
 
 > Un **tourniquet de métro** posé à l'entrée du processus : chaque IP cliente reçoit un quota de
-> requêtes par fenêtre de temps ; au-delà, on la refoule — un `429 Too Many Requests` en HTTP, une
-> fermeture `1013 Try Again Later` en WebSocket. Le refus se décide **avant** d'allouer le moindre
+> requêtes par fenêtre de temps ; au-delà, on la refoule — un `429 Too Many Requests`, en HTTP comme
+> au handshake d'un WebSocket (avant le `101` : la socket ne s'ouvre jamais). Le refus se décide **avant** d'allouer le moindre
 > contexte, pour qu'un flood coûte une simple recherche dans une table de hachage. C'est une **défense
 > de capacité par IP**, à ne pas confondre avec le backoff anti-bruteforce du **login** (page voisine,
 > côté sécurité). Chaque fait ci-dessous est ancré sur le code.
@@ -49,19 +49,19 @@ flowchart TD
   IP --> HIT["rateLimiter.hit(ip)<br/>fenêtre fixe · O(1) · synchrone"]
   HIT -->|"sous le quota"| PIPE["→ pipeline<br/>+ en-têtes X-RateLimit-*"]
   HIT -->|"quota dépassé · HTTP"| R429["429 Too Many Requests<br/>+ Retry-After"]
-  HIT -->|"quota dépassé · WS"| C1013["close 1013<br/>Try Again Later"]
+  HIT -->|"quota dépassé · handshake WS"| H429["429 au handshake<br/>avant le 101, aucune socket"]
 ```
 
 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:1173`) —
+   résolue exactement comme pour les logs et l'audit (`resolveForwarded()`, `http-kernel.ts#HttpKernel.dispatchHttpRequest`) —
    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
+2. **Le verdict porte tout.** Un seul appel `hit(key)` (`IRateLimitStore.ts#IRateLimitStore.hit`) rend un
+   `RateLimitVerdict` (`IRateLimitStore.ts#RateLimitVerdict`) qui contient déjà limite, restant, reset et
    `Retry-After` — de quoi émettre les en-têtes sans relire l'état.
 3. **HTTP et WebSocket partagent le même compteur.** Un upgrade WS **est** une requête HTTP : il passe
-   par le même `hit()`, seule la façon de refouler change (429 en HTTP, close 1013 en WS).
+   par le même `hit()`, et il est refoulé de la même façon : un `429`, avant que le `101` ne parte.
 
 ## 📖 Lexique
 
@@ -75,7 +75,7 @@ Trois idées à retenir :
 | `429`                   | _Too Many Requests_ (RFC 6585 §4) : le code HTTP du refoulement.                                                         |
 | `Retry-After`           | En-tête indiquant au client **combien de secondes** attendre avant de réessayer.                                         |
 | `X-RateLimit-*`         | Famille d'en-têtes de facto (`Limit`, `Remaining`, `Reset`) qui expose l'état du quota au client.                        |
-| Close `1013`            | _Try Again Later_ (RFC 6455 §7.4.1) : le refoulement d'un WebSocket, faute de pouvoir renvoyer un `429`.                 |
+| Handshake refusé        | Refus d'un upgrade WebSocket par un statut HTTP AVANT le `101` (RFC 6455 §4.2.2) : la socket ne s'ouvre jamais.          |
 | IP forwarded-aware      | IP cliente réelle reconstituée derrière un proxy via `X-Forwarded-For` / `Forwarded` (RFC 7239), sous contrôle de trust. |
 | `trustProxy`            | Réglage qui décide si l'on croit les en-têtes de proxy pour établir l'IP. `false` par défaut (non falsifiable).          |
 | `maxTracked`            | Borne mémoire : nombre max d'IP suivies simultanément. Au cap → purge des expirées puis éviction FIFO.                   |
@@ -89,9 +89,9 @@ processus : famine de l'event-loop, mémoire qui gonfle, latence p99 qui explose
 C'est le cœur d'un **déni de service applicatif** (DoS), volontaire ou accidentel (un script en boucle,
 un crawler mal réglé).
 
-Le rate-limit **refoule** l'IP fautive avant qu'elle ne coûte cher : elle reçoit un `429` (ou une
-fermeture `1013` en WebSocket) tant qu'elle dépasse son quota, pendant que les autres IP passent
-intactes. Le quota est **isolé par IP** (`rateLimit.test.ts:77`) : une IP saturée n'affecte jamais ses
+Le rate-limit **refoule** l'IP fautive avant qu'elle ne coûte cher : elle reçoit un `429` (au handshake,
+pour un WebSocket) tant qu'elle dépasse son quota, pendant que les autres IP passent
+intactes. Le quota est **isolé par IP** (`rateLimit.test.ts`) : une IP saturée n'affecte jamais ses
 voisines.
 
 > [!IMPORTANT]
@@ -106,20 +106,20 @@ 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:1247`) : `null` tant qu'on ne l'active pas → **0
+laisse donc `rateLimit` désarmé par défaut (`config.ts#httpConfigSchema`) : `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.
 
 **Fenêtre fixe, en mémoire, O(1).** L'algorithme est le plus frugal possible :
-`MemoryRateLimitStore` (`MemoryRateLimitStore.ts:33`) tient une entrée `{ count, resetAt }` par IP,
+`MemoryRateLimitStore` (`MemoryRateLimitStore.ts#MemoryRateLimitStore`) tient une entrée `{ count, resetAt }` par IP,
 remise à zéro **en place** à l'expiration (0 allocation pour une IP récurrente). Le prix de cette
 simplicité est connu : un pic à cheval sur deux fenêtres peut laisser passer jusqu'à `2 × max` sur un
-court intervalle (`MemoryRateLimitStore.ts:29`). Acceptable pour une défense de **capacité** ; un
+court intervalle (`MemoryRateLimitStore.ts#MemoryRateLimitStore`). Acceptable pour une défense de **capacité** ; un
 _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:1172`) : 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
+(`http-kernel.ts#HttpKernel.dispatchHttpRequest`) : un flood coûte un `Map.get` et rien d'autre. Le contrat `hit()` est
+**synchrone** à dessein (`IRateLimitStore.ts#IRateLimitStore.hit`) — aucune `Promise`, aucune microtask sur le chemin de
 chaque requête.
 
 ## 🚀 Démarrage rapide
@@ -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:497`).
+reconstruit le compteur sans redémarrage (`configureRateLimit()`, `http-kernel.ts#HttpKernel.configureRateLimit`).
 
 ### 2. Observer le 429 et les en-têtes
 
@@ -178,14 +178,14 @@ X-RateLimit-Reset: 1753082460
 Retry-After: 42
 ```
 
-- `X-RateLimit-Remaining` : requêtes restantes dans la fenêtre (`http-kernel.ts:1182`).
-- `X-RateLimit-Reset` : **epoch en secondes** de la fin de fenêtre (`http-kernel.ts:1182`).
+- `X-RateLimit-Remaining` : requêtes restantes dans la fenêtre (`http-kernel.ts#HttpKernel.dispatchHttpRequest`).
+- `X-RateLimit-Reset` : **epoch en secondes** de la fin de fenêtre (`http-kernel.ts#HttpKernel.dispatchHttpRequest`).
 - `Retry-After` (sur le `429` seulement) : secondes à attendre, **jamais 0** — un `Retry-After: 0`
-  relancerait un client bien élevé immédiatement (`MemoryRateLimitStore.ts:80`).
+  relancerait un client bien élevé immédiatement (`MemoryRateLimitStore.ts#MemoryRateLimitStore.hit`).
 
 ## 🏗️ Architecture interne — le parcours d'un `hit`
 
-La logique de fenêtre fixe tient dans `hit()` (`MemoryRateLimitStore.ts:51`). Trois cas, tous O(1) :
+La logique de fenêtre fixe tient dans `hit()` (`MemoryRateLimitStore.ts#MemoryRateLimitStore.hit`). Trois cas, tous O(1) :
 
 ```mermaid
 flowchart TD
@@ -203,34 +203,34 @@ flowchart TD
 
 Autour de ce cœur, le kernel orchestre le cycle de vie :
 
-- **Construction / reconfiguration** : `configureRateLimit()` (`http-kernel.ts:497`) instancie le store
-  depuis la config (`windowMs = windowS × 1000`, `http-kernel.ts:466`) et arme un `GcScheduler`
-  (`http-kernel.ts:502`) 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:1182`) et
-  la requête continue ; au-delà, `Retry-After` (`http-kernel.ts:1189`) puis `writeHead(429)`
-  (`http-kernel.ts:1194`) — corps vide, on ne journalise pas chaque rejet (amplificateur sous flood).
+- **Construction / reconfiguration** : `configureRateLimit()` (`http-kernel.ts#HttpKernel.configureRateLimit`) instancie le store
+  depuis la config (`windowMs = windowS × 1000`, `http-kernel.ts#HttpKernel.onConfigChanged`) et arme un `GcScheduler`
+  (`http-kernel.ts#HttpKernel.configureRateLimit`) 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#HttpKernel.dispatchHttpRequest`) et
+  la requête continue ; au-delà, `Retry-After` (`http-kernel.ts#HttpKernel.dispatchHttpRequest`) puis `writeHead(429)`
+  (`http-kernel.ts#HttpKernel.dispatchHttpRequest`) — 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.
+  (`#evict`, `MemoryRateLimitStore.ts#MemoryRateLimitStore.#evict`) — la mémoire ne dérive jamais.
 
 ## ⚙️ Configuration
 
-Table dérivée de `rateLimitSchema` (`config.ts:889`). Tout est optionnel : ce sont les défauts du
+Table dérivée de `rateLimitSchema` (`config.ts#rateLimitSchema`). 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:891`). | oui   |
-| `windowS`     | int (s)      | `60`      | Largeur de la fenêtre fixe ; le compteur par IP repart à zéro (`config.ts:902`). | oui   |
-| `max`         | int          | `300`     | Requêtes/IP/fenêtre ; au-delà `429` + `Retry-After` (`config.ts:913`).           | oui   |
-| `maxTracked`  | int (≥ 1000) | `100 000` | Borne mémoire : IP suivies ; au cap, purge puis éviction FIFO (`config.ts:925`). | 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   |
+| Option        | Type         | Défaut    | Effet                                                                                        | Chaud |
+| ------------- | ------------ | --------- | -------------------------------------------------------------------------------------------- | ----- |
+| `enabled`     | bool         | `false`   | Arme le rate-limit (HTTP **et** handshakes WS, même compteur) (`config.ts#rateLimitSchema`). | oui   |
+| `windowS`     | int (s)      | `60`      | Largeur de la fenêtre fixe ; le compteur par IP repart à zéro (`config.ts#rateLimitSchema`). | oui   |
+| `max`         | int          | `300`     | Requêtes/IP/fenêtre ; au-delà `429` + `Retry-After` (`config.ts#rateLimitSchema`).           | oui   |
+| `maxTracked`  | int (≥ 1000) | `100 000` | Borne mémoire : IP suivies ; au cap, purge puis éviction FIFO (`config.ts#rateLimitSchema`). | 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   |
 
 Et un réglage **séparé**, propre au WebSocket, à la racine du module :
 
-| Option                  | Type          | Défaut | Effet                                                                                               | Chaud |
-| ----------------------- | ------------- | ------ | --------------------------------------------------------------------------------------------------- | ----- |
-| `wsMaxConnectionsPerIp` | int \| `null` | `null` | Cap de connexions WS **concurrentes** par IP ; au-delà, upgrade fermé en `1013` (`config.ts:1250`). | oui   |
+| Option                  | Type          | Défaut | Effet                                                                                                           | Chaud |
+| ----------------------- | ------------- | ------ | --------------------------------------------------------------------------------------------------------------- | ----- |
+| `wsMaxConnectionsPerIp` | int \| `null` | `null` | Cap de connexions WS **concurrentes** par IP ; au-delà, upgrade refusé en `429` (`config.ts#httpConfigSchema`). | oui   |
 
 > [!TIP]
 > `max: 300` sur `windowS: 60` = **5 req/s soutenu** par IP, avec des rafales tolérées jusqu'à 300 d'un
@@ -239,22 +239,22 @@ Et un réglage **séparé**, propre au WebSocket, à la racine du module :
 
 ## 🔌 Rate-limit côté WebSocket
 
-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:1964`) — **avant** `enterScope`, l'ALS et le pipeline, comme le `429` HTTP.
+Un WebSocket est refoulé comme une requête HTTP : par un **`429` au handshake**, AVANT que le
+`101 Switching Protocols` ne parte (RFC 6455 §4.2.2) — aucune socket ne s'ouvre, le client voit un
+échec d'ouverture. Le refus se décide en tête de `onWebsocketUpgrade()` (`http-kernel.ts#HttpKernel.onWebsocketUpgrade`) —
+**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:471`)                        |
-| Connexions simultanées | Sockets **ouvertes** en même temps par IP      | `wsMaxConnectionsPerIp` | close `1013` — `tryAcquire` refuse (`http-kernel.ts:2240`) |
+| Plafond                | Ce qu'il borne                                 | Source de config        | Refus                                                                                        |
+| ---------------------- | ---------------------------------------------- | ----------------------- | -------------------------------------------------------------------------------------------- |
+| Débit de handshakes    | Ouvertures/seconde (le **même** compteur HTTP) | `rateLimit`             | `429` au handshake (`http-kernel.ts#HttpKernel.onConfigChanged`)                             |
+| Connexions simultanées | Sockets **ouvertes** en même temps par IP      | `wsMaxConnectionsPerIp` | `429` au handshake — `tryAcquire` refuse (`http-kernel.ts#HttpKernel.websocketQuotaRefusal`) |
 
-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:1918`), donc jamais de fuite de compteur, même sur un `terminate` de heartbeat.
+Le cap concurrent est porté par un compteur dédié, `WsConnectionCounter` (`WsConnectionCounter.ts#WsConnectionCounter`) :
+`tryAcquire(ip)` (`WsConnectionCounter.ts#WsConnectionCounter.tryAcquire`) réserve un créneau à l'upgrade, `release(ip)`
+(`WsConnectionCounter.ts#WsConnectionCounter.release`) le rend à la fermeture — branché sur `ws.once("close", …)`
+(`http-kernel.ts#HttpKernel.createWebsocketContext`), 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
@@ -268,26 +268,26 @@ bornes **par message** (taille `maxPayload` → close `1009`, backpressure), dé
 
 ## 🧩 Étendre — un store distribué
 
-Tout passe par le contrat `IRateLimitStore` (`IRateLimitStore.ts:74`). L'implémentation par défaut est
+Tout passe par le contrat `IRateLimitStore` (`IRateLimitStore.ts#IRateLimitStore`). L'implémentation par défaut est
 en mémoire (par process), mais le contrat est pensé pour un futur backend **distribué** (Redis,
 multi-pod) : `hit()` reste synchrone (le hot-path ne tolère pas de `Promise`), tandis que l'introspection
-`listPage()` (`IRateLimitStore.ts:99`) est asynchrone — un store distribué la servira par `SCAN`.
+`listPage()` (`IRateLimitStore.ts#IRateLimitStore.listPage`) est asynchrone — un store distribué la servira par `SCAN`.
 
 Un adapter doit fournir : `hit(key)` (verdict de fenêtre), `gc()` (purge), `listPage(query)`
-(introspection admin), plus les métriques `trackedCount` et `rejectedTotal` (`IRateLimitStore.ts:101`).
+(introspection admin), plus les métriques `trackedCount` et `rejectedTotal` (`IRateLimitStore.ts#IRateLimitStore.rejectedTotal`).
 
 ## 📜 Normes appliquées
 
-| Domaine                            | Norme            | Ancrage                                           |
-| ---------------------------------- | ---------------- | ------------------------------------------------- |
-| `429 Too Many Requests`            | RFC 6585 §4      | `writeHead(429)` (`http-kernel.ts:1194`)          |
-| `Retry-After` (delta-seconds)      | RFC 9110 §10.2.3 | en-tête posé sur le `429` (`http-kernel.ts:1189`) |
-| IP cliente derrière proxy          | RFC 7239         | `resolveForwarded()` (`http-kernel.ts:1173`)      |
-| WebSocket — close `1013` Try Again | RFC 6455 §7.4.1  | refus d'upgrade (`http-kernel.ts:1409`)           |
+| Domaine                        | Norme            | Ancrage                                                                     |
+| ------------------------------ | ---------------- | --------------------------------------------------------------------------- |
+| `429 Too Many Requests`        | RFC 6585 §4      | `writeHead(429)` (`http-kernel.ts#HttpKernel.dispatchHttpRequest`)          |
+| `Retry-After` (delta-seconds)  | RFC 9110 §10.2.3 | en-tête posé sur le `429` (`http-kernel.ts#HttpKernel.dispatchHttpRequest`) |
+| IP cliente derrière proxy      | RFC 7239         | `resolveForwarded()` (`http-kernel.ts#HttpKernel.dispatchHttpRequest`)      |
+| Refus d'un handshake WebSocket | RFC 6455 §4.2.2  | `429` avant le `101` (`http-kernel.ts#HttpKernel.onWebsocketUpgrade`)       |
 
 > [!NOTE]
 > Les en-têtes émis sont la famille **de facto** `X-RateLimit-Limit/Remaining/Reset`
-> (`http-kernel.ts:1129`), largement déployée et lue par les clients. Le brouillon IETF
+> (`http-kernel.ts#HttpKernel.dispatchHttpRequest`), 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.
 
@@ -297,13 +297,13 @@ Le rate-limit vit sur le **chemin chaud absolu** — il s'exécute avant tout le
 Les choix visibles dans le code :
 
 - **Synchrone, O(1)** : `hit()` = 1 `Map.get` + arithmétique, zéro `Promise`, zéro microtask
-  (`IRateLimitStore.ts:8`).
-- **Lazy** : la `Map` interne n'est allouée qu'au **premier** hit (`MemoryRateLimitStore.ts:33`) →
+  (`IRateLimitStore.ts`).
+- **Lazy** : la `Map` interne n'est allouée qu'au **premier** hit (`MemoryRateLimitStore.ts#MemoryRateLimitStore`) →
   quand le rate-limit est désarmé (défaut), le coût mémoire est **nul**.
 - **0 alloc pour une IP connue** : la fenêtre expirée se réinitialise **en place**, pas de nouvel objet.
 - **Rejet avant allocation** : un flood est refoulé avant le contexte / la portée DI / l'ALS
-  (`http-kernel.ts:872`) → un attaquant paie une recherche de hachage, pas un pipeline complet.
-- **Résolution d'IP seulement si un limiteur est armé** côté WS (`http-kernel.ts:1399`).
+  (`http-kernel.ts#HttpKernel.prepareFrontController`) → un attaquant paie une recherche de hachage, pas un pipeline complet.
+- **Résolution d'IP seulement si un limiteur est armé** côté WS (`http-kernel.ts#HttpKernel.teardownHttp`).
 - **Mémoire bornée** : `maxTracked` + éviction FIFO ; purge périodique `unref` hors hot-path.
 
 Rejouer la pression sous charge : skill `nodefony-load-test`. Gate mémoire avant tout commit touchant le
@@ -311,28 +311,28 @@ pipeline : `npm run test:memory` (skill `nodefony-check-memory-health`).
 
 ## 📡 Observabilité — Studio
 
-Le data plane admin expose **qui martèle** via `createHttpAdminApi()` (`HttpAdminApi.ts:141`) :
+Le data plane admin expose **qui martèle** via `createHttpAdminApi()` (`HttpAdminApi.ts#createHttpAdminApi`) :
 
-- **`GET /nodefony/http/api/rate-limit/list`** (`HttpAdminApi.ts:218`) — les IP suivies, **les plus
+- **`GET /nodefony/http/api/rate-limit/list`** (`HttpAdminApi.ts#createHttpAdminApi`) — les IP suivies, **les plus
   bruyantes d'abord** (tri `count` décroissant), paginé **côté serveur** (`?limited&q&limit&offset`).
   `q` filtre par **préfixe** d'IP (un sous-réseau `10.0.`), pas par sous-chaîne.
-- **Réservé `ROLE_NODEFONY_ADMIN`** (`HttpAdminApi.ts:220`) : une IP est une **donnée personnelle** →
+- **Réservé `ROLE_NODEFONY_ADMIN`** (`HttpAdminApi.ts#createHttpAdminApi`) : une IP est une **donnée personnelle** →
   seul l'état du compteur sort d'ici, jamais l'URL, l'en-tête ou le corps des requêtes.
 - **État honnête quand désarmé** : rate-limit désactivé (le défaut) → `enabled: false` + liste vide, pas
-  un `503` (`HttpAdminApi.ts:241`). La console affiche « désarmé » plutôt qu'une erreur.
+  un `503` (`HttpAdminApi.ts#createHttpAdminApi`). La console affiche « désarmé » plutôt qu'une erreur.
 - Métriques exposées : `trackedCount` (IP suivies) et `rejectedTotal` (429 cumulés depuis le boot).
 
 ## ⚠️ Pièges (symptôme → cause → correction)
 
-| Symptôme                                               | Cause                                                                     | Correction                                                                             |
-| ------------------------------------------------------ | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
-| Le rate-limit « ne fait rien »                         | Désactivé par défaut (opt-in)                                             | `rateLimit.enabled: true` dans `use("@nodefony/http", …)`                              |
-| Toutes les IP derrière le proxy comptent comme **une** | `trustProxy: false` → l'IP vue est celle du proxy, pas du client          | Régler `trustProxy` sur l'IP/CIDR du proxy — voir [Serveurs](servers.md)               |
-| Un burst laisse passer près de `2 × max`               | Limite **assumée** de la fenêtre fixe (pic à cheval sur deux fenêtres)    | Réduire `windowS`, ou attendre l'option _sliding window_                               |
-| Un WebSocket ne reçoit jamais de `429`                 | Le `101` est déjà émis — impossible de renvoyer un code HTTP              | Attendu : le refus WS est une fermeture `1013` (`http-kernel.ts:1409`)                 |
-| `wsMaxConnectionsPerIp` semble inefficace en cluster   | Portée **par process** — chaque pod compte pour lui                       | Déléguer le cap global/IP à l'ingress (nginx `limit_conn`, HAProxy)                    |
-| Confusion avec le lockout de login                     | `security.rateLimit` = backoff NIST **par identifiant**, brique distincte | Ce sont deux étages différents — cf [@nodefony/security](../../security/docs/index.md) |
-| Une IP « fantôme » n'est jamais comptée                | `resolveForwarded()` renvoie `null` (aucun socket fiable)                 | Attendu : on ne compte jamais sous une clé `null` (qui deviendrait un DoS)             |
+| Symptôme                                               | Cause                                                                            | Correction                                                                             |
+| ------------------------------------------------------ | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| Le rate-limit « ne fait rien »                         | Désactivé par défaut (opt-in)                                                    | `rateLimit.enabled: true` dans `use("@nodefony/http", …)`                              |
+| Toutes les IP derrière le proxy comptent comme **une** | `trustProxy: false` → l'IP vue est celle du proxy, pas du client                 | Régler `trustProxy` sur l'IP/CIDR du proxy — voir [Serveurs](servers.md)               |
+| Un burst laisse passer près de `2 × max`               | Limite **assumée** de la fenêtre fixe (pic à cheval sur deux fenêtres)           | Réduire `windowS`, ou attendre l'option _sliding window_                               |
+| Un WebSocket échoue à s'ouvrir sous charge (`1006`)    | Débit ou cap de connexions dépassé : `429` au handshake, que le navigateur cache | Attendu : `NodefonySocket` le lit par sa sonde (`429` = transitoire, il retente)       |
+| `wsMaxConnectionsPerIp` semble inefficace en cluster   | Portée **par process** — chaque pod compte pour lui                              | Déléguer le cap global/IP à l'ingress (nginx `limit_conn`, HAProxy)                    |
+| Confusion avec le lockout de login                     | `security.rateLimit` = backoff NIST **par identifiant**, brique distincte        | Ce sont deux étages différents — cf [@nodefony/security](../../security/docs/index.md) |
+| Une IP « fantôme » n'est jamais comptée                | `resolveForwarded()` renvoie `null` (aucun socket fiable)                        | Attendu : on ne compte jamais sous une clé `null` (qui deviendrait un DoS)             |
 
 ## 🧪 Tests & couverture
 
@@ -351,7 +351,7 @@ Ce qui **manque** aujourd'hui :
 - Aucun test d'**intégration** ne prouve, sur un serveur vivant, le `429` HTTP **et** les en-têtes
   `X-RateLimit-*` de bout en bout (le comportement du store est prouvé unitairement, son câblage kernel
   ne l'est pas).
-- Aucun test d'intégration ne couvre la **fermeture `1013`** (débit de handshakes et cap concurrent) :
+- Aucun test d'intégration ne couvre le **refus `429` au handshake** (débit de handshakes et cap concurrent) :
   le compteur est prouvé unitairement, le refus WS de bout en bout est exercé par les bancs E2E
   (`nodefony-load-test` → `run.sh ws-handshake-rl` / `ws-conn-cap`), pas par une suite du module.
 - Pas de banc de **charge dédié** au coût du rate-limit sur le hot-path.

package/docs/reverse-proxy.md

@@ -56,11 +56,11 @@ flowchart LR
 Trois idées suffisent pour raisonner :
 
 1. **Un montage = un préfixe → une origine.** `"/billing/"` → `http://127.0.0.1:8080`. Le préfixe le
-   plus long gagne (`ReverseProxy.match()`, `reverse-proxy.ts:229`).
+   plus long gagne (`ReverseProxy.match()`, `reverse-proxy.ts#ReverseProxy.match`).
 2. **L'aiguillage passe AVANT le routage.** Une route attrape-tout de l'application ne peut pas
-   avaler un préfixe monté (`HttpKernel.routeHttpRequest()`, `http-kernel.ts:1699`).
+   avaler un préfixe monté (`HttpKernel.routeHttpRequest()`, `http-kernel.ts#HttpKernel.routeHttpRequest`).
 3. **Sans montage, il ne coûte rien.** Le pipeline lit un champ (`mounts === null`) et passe son
-   chemin (`ReverseProxy.mounts`, `reverse-proxy.ts:174`).
+   chemin (`ReverseProxy.mounts`, `reverse-proxy.ts#ReverseProxy.mounts`).
 
 ## 📖 Lexique
 
@@ -100,17 +100,17 @@ autres. Mal écrit, un proxy ouvre ses propres failles, et c'est contre elles qu
 
 - **Contournement de préfixe** — `/billing/..%2fadmin` : le proxy voit `/billing/`, l'amont décode
   `/admin`. Un chemin ambigu est refusé en 400, jamais normalisé en silence (`isAmbiguousPath()`,
-  `rules.ts:229`).
+  `rules.ts#isAmbiguousPath`).
 - **Désynchronisation de requête** (_request smuggling_) — proxy et amont ne s'accordent pas sur la
-  fin du corps. Le cadrage est recalculé à chaque relais (`bodyFramingOf()`, `forward.ts:166`).
+  fin du corps. Le cadrage est recalculé à chaque relais (`bodyFramingOf()`, `forward.ts#bodyFramingOf`).
 - **Usurpation d'origine** — un client pose lui-même `X-Forwarded-For: 10.0.0.1`. Ces en-têtes ne
-  sont crus que d'un pair `trustProxy` (`requestHeadersFor()`, `forward.ts:201`).
+  sont crus que d'un pair `trustProxy` (`requestHeadersFor()`, `forward.ts#requestHeadersFor`).
 
 ## La vision Nodefony
 
 Le proxy est un **service générique** de `@nodefony/http`, `reverse-proxy` (`ReverseProxy`,
-`reverse-proxy.ts:82`). Il accepte deux sources de montages, soumises aux **mêmes règles**
-(`proxyMountProblems()`, `rules.ts:98`) :
+`reverse-proxy.ts#ReverseProxy`). Il accepte deux sources de montages, soumises aux **mêmes règles**
+(`proxyMountProblems()`, `rules.ts#proxyMountProblems`) :
 
 - **la configuration** de l'application — `proxy.mounts`, validée au démarrage ;
 - **un module**, par `mount()` — c'est ainsi que `@nodefony/frontend` sert Vite sous `/_vite/`.
@@ -130,7 +130,7 @@ Le compromis assumé :
 > **Un préfixe monté est servi AVANT le pare-feu, la protection CSRF et les en-têtes de sécurité
 > APPLICATIFS de l'application (CSP, `Referrer-Policy`, COOP).** C'est une surface publique pour qui
 > atteint Nodefony : l'amont porte sa propre politique d'accès (`ReverseProxy.forward()`,
-> `reverse-proxy.ts:319`). Ne montez jamais un service qui suppose être protégé par le pare-feu
+> `reverse-proxy.ts#ReverseProxy.forward`). Ne montez jamais un service qui suppose être protégé par le pare-feu
 > Nodefony.
 
 Ce qui s'applique malgré tout, parce que posé à l'entrée, avant l'aiguillage :
@@ -212,12 +212,12 @@ via: 1.1 nodefony-3f9a1c2e
 - Le préfixe a été retiré du chemin, et l'amont l'apprend par `X-Forwarded-Prefix`.
 - `Host` est celui de l'amont ; le nom demandé par le client part dans `X-Forwarded-Host`.
 - `Via` porte le pseudonyme de CE processus, tiré au hasard au démarrage — il ne dit rien de la
-  machine (`ReverseProxy.pseudonym`, `reverse-proxy.ts:290`).
+  machine (`ReverseProxy.pseudonym`, `reverse-proxy.ts#ReverseProxy.pseudonym`).
 
 ## ⚙️ Configuration
 
 Section `proxy` de `use("@nodefony/http", { … })`, schéma Zod strict : une clé inconnue interrompt le
-démarrage en la nommant (`proxySchema`, `config.ts:1085`).
+démarrage en la nommant (`proxySchema`, `config.ts#proxySchema`).
 
 | Option             | Type     | Défaut  | Effet                                                                                                                                                         |
 | ------------------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -226,7 +226,7 @@ démarrage en la nommant (`proxySchema`, `config.ts:1085`).
 | `maxSockets`       | entier   | `256`   | Connexions simultanées vers UN amont (pool dédié par montage) ; au-delà, les requêtes attendent. Borne aussi les tunnels WebSocket, hors pool : au-delà, 503. |
 | `mounts`           | `record` | `{}`    | Préfixe → montage. Préfixe le plus long d'abord.                                                                                                              |
 
-Chaque montage (`proxyMountSchema`, `config.ts:1013`) :
+Chaque montage (`proxyMountSchema`, `config.ts#proxyMountSchema`) :
 
 | Option         | Type       | Défaut            | Effet                                                                                                                        |
 | -------------- | ---------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------- |
@@ -239,13 +239,13 @@ Chaque montage (`proxyMountSchema`, `config.ts:1013`) :
 | `timeoutMs`    | entier     | `proxy.timeoutMs` | Délai d'inactivité propre au montage, handshake WebSocket compris (jusqu'au `101`). Ne s'applique pas à un WebSocket établi. |
 | `secure`       | `boolean`  | `true`            | Vérifie le certificat d'une cible `https`. `false` n'est accepté que vers la boucle locale.                                  |
 
-**Refusés au démarrage**, avec le motif (`proxyMountProblems()`, `rules.ts:98`) :
+**Refusés au démarrage**, avec le motif (`proxyMountProblems()`, `rules.ts#proxyMountProblems`) :
 
 - le préfixe `/` — il relaierait toute l'application, routes et pare-feu compris ;
 - un préfixe sous `/nodefony/` (console d'administration) ou, depuis la configuration, sous
-  `/_vite/` (monté par `@nodefony/frontend`) — `RESERVED_PROXY_PREFIXES` (`rules.ts:18`) ;
+  `/_vite/` (monté par `@nodefony/frontend`) — `RESERVED_PROXY_PREFIXES` (`rules.ts#RESERVED_PROXY_PREFIXES`) ;
 - un préfixe qui contient `?`, `#`, `%`, `\`, un espace ou un segment `.`/`..` ;
-- une cible qui n'est pas une origine `http(s)` nue (`parseProxyOrigin()`, `rules.ts:56`) ;
+- une cible qui n'est pas une origine `http(s)` nue (`parseProxyOrigin()`, `rules.ts#parseProxyOrigin`) ;
 - deux clés qui désignent le même préfixe (`/svc` et `/svc/`).
 
 ### Choisir les réglages — en situation
@@ -259,7 +259,7 @@ retirer.
 
 **L'amont croit être à la racine** (un service existant qu'on ne modifie pas) : retirer le préfixe.
 Ses redirections `Location: /login` sont ramenées en `/billing/login`
-(`rewriteLocation()`, `forward.ts:288`).
+(`rewriteLocation()`, `forward.ts#rewriteLocation`).
 
 ```ts ignore
 "/billing/": { target: "http://127.0.0.1:8080", stripPrefix: true }
@@ -305,7 +305,7 @@ réglage.
 Ce qui se règle reste côté frontend, dans `use("@nodefony/frontend", { … })` : `devHost` (défaut
 `127.0.0.1`, à garder — le navigateur ne joint jamais Vite directement) et `devPort` (défaut `5173`,
 chaque famille prend le port suivant). Le préfixe `/_vite/` est refusé dans `proxy.mounts` : il
-appartient au module (`MODULE_PROXY_PREFIXES`, `rules.ts:25`). En production, Vite ne tourne pas et
+appartient au module (`MODULE_PROXY_PREFIXES`, `rules.ts#MODULE_PROXY_PREFIXES`). En production, Vite ne tourne pas et
 aucun montage n'est posé.
 
 ## 🔌 WebSocket relayé
@@ -313,10 +313,10 @@ aucun montage n'est posé.
 Avec `websocket: true`, l'upgrade du préfixe est relayé au lieu d'aller au serveur WebSocket de
 Nodefony. Un seul écouteur `upgrade` par serveur fait l'aiguillage : le proxy d'abord, puis `ws`,
 créé en `noServer` pour garder ses propres contrôles (`path`, `verifyClient`, `maxPayload`)
-(`attachUpgradeDispatch()`, `upgradeDispatch.ts:41`).
+(`attachUpgradeDispatch()`, `upgradeDispatch.ts#attachUpgradeDispatch`).
 
 Avant de relayer, chaque contrôle rend la réponse qu'aurait rendue le serveur WebSocket de Nodefony
-(`ReverseProxy.handleUpgrade()`, `reverse-proxy.ts:384`) :
+(`ReverseProxy.handleUpgrade()`, `reverse-proxy.ts#ReverseProxy.handleUpgrade`) :
 
 | Le handshake…                                                             | Réponse |
 | ------------------------------------------------------------------------- | ------- |
@@ -328,7 +328,7 @@ Avant de relayer, chaque contrôle rend la réponse qu'aurait rendue le serveur
 | passe tous les contrôles                                                  | relayé  |
 
 Les quotas sont ceux d'un upgrade servi par Nodefony, appliqués par la **même** règle du noyau
-(`HttpKernel.websocketQuotaRefusal()`, `http-kernel.ts:2230`) ; un tunnel ouvert garde sa place
+(`HttpKernel.websocketQuotaRefusal()`, `http-kernel.ts#HttpKernel.websocketQuotaRefusal`) ; un tunnel ouvert garde sa place
 jusqu'à sa fermeture. Seule la forme du refus diffère : le proxy répond avant le `101`, il peut donc
 rendre un statut HTTP, là où le serveur WebSocket ne peut plus que fermer avec le code 1013.
 
@@ -337,9 +337,9 @@ Une fois l'upgrade transmis, un amont qui accepte la connexion puis se tait est
 qu'il veut.
 
 Seul `Upgrade: websocket` est relayé : un tunnel `h2c` ou tout autre protocole raccordé octet pour
-octet échapperait à toute inspection (`websocketHandshakeProblem()`, `rules.ts:252`). Une fois la
+octet échapperait à toute inspection (`websocketHandshakeProblem()`, `rules.ts#websocketHandshakeProblem`). Une fois la
 connexion établie, les deux sockets sont raccordées et détruites ensemble ; le TCP keep-alive détecte
-un pair mort (`forwardUpgrade()`, `forward.ts:590`).
+un pair mort (`forwardUpgrade()`, `forward.ts#forwardUpgrade`).
 
 ## 🧩 Étendre — monter depuis un module
 
@@ -359,13 +359,13 @@ proxy?.unmount("/outil/");
 ```
 
 - `mount()` est **idempotent** pour un préfixe : il remplace le montage précédent. S'il remplace un
-  montage de la configuration, il le dit en `WARNING` (`ReverseProxy.mount()`, `reverse-proxy.ts:129`).
+  montage de la configuration, il le dit en `WARNING` (`ReverseProxy.mount()`, `reverse-proxy.ts#ReverseProxy.mount`).
 - `unmount()` ferme le pool de l'amont ; le dernier retiré remet `mounts` à `null`, et le pipeline
-  cesse de le consulter (`ReverseProxy.unmount()`, `reverse-proxy.ts:199`).
+  cesse de le consulter (`ReverseProxy.unmount()`, `reverse-proxy.ts#ReverseProxy.unmount`).
 
 **Exemple réel** : `@nodefony/frontend` monte ainsi chaque famille Vite (voir « Le cas Vite »), avec
 une cible fonction qui ne vise un port que si le Vite de CETTE application y répond
-(`FrontendService.mountDevProxy()`, `FrontendService.ts:486`).
+(`FrontendService.mountDevProxy()`, `FrontendService.ts#FrontendService.mountDevProxy`).
 
 ## 🏗️ Architecture interne — le parcours d'une requête relayée
 
@@ -386,25 +386,25 @@ sequenceDiagram
 
 Ce que le relais fait aux en-têtes, dans les deux sens :
 
-| Vers l'amont (`requestHeadersFor()`, `forward.ts:201`)                | Vers le client (`responseHeadersFor()`, `forward.ts:311`)        |
-| --------------------------------------------------------------------- | ---------------------------------------------------------------- |
-| retire les en-têtes de connexion, et ceux que nomme `Connection`      | retire les en-têtes de connexion, et ceux que nomme `Connection` |
-| retire `Expect` (Nodefony a déjà répondu `100`) et les `stripHeaders` | garde les `Set-Cookie` multiples                                 |
-| réécrit `Host` sur la cible (sauf `preserveHost`)                     | ramène `Location` sous le préfixe (`stripPrefix`)                |
-| `X-Forwarded-*` : prolongés d'un pair `trustProxy`, recommencés sinon | prolonge `Via`                                                   |
-| `X-Forwarded-Prefix` : à la suite de celui d'un pair `trustProxy`     |                                                                  |
-| `Forwarded` d'un pair `trustProxy` : prolongé de ce saut, jamais créé |                                                                  |
-| prolonge `Via` ; recalcule le cadrage du corps                        |                                                                  |
+| Vers l'amont (`requestHeadersFor()`, `forward.ts#requestHeadersFor`)  | Vers le client (`responseHeadersFor()`, `forward.ts#responseHeadersFor`) |
+| --------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| retire les en-têtes de connexion, et ceux que nomme `Connection`      | retire les en-têtes de connexion, et ceux que nomme `Connection`         |
+| retire `Expect` (Nodefony a déjà répondu `100`) et les `stripHeaders` | garde les `Set-Cookie` multiples                                         |
+| réécrit `Host` sur la cible (sauf `preserveHost`)                     | ramène `Location` sous le préfixe (`stripPrefix`)                        |
+| `X-Forwarded-*` : prolongés d'un pair `trustProxy`, recommencés sinon | prolonge `Via`                                                           |
+| `X-Forwarded-Prefix` : à la suite de celui d'un pair `trustProxy`     |                                                                          |
+| `Forwarded` d'un pair `trustProxy` : prolongé de ce saut, jamais créé |                                                                          |
+| prolonge `Via` ; recalcule le cadrage du corps                        |                                                                          |
 
-Les échecs, dans l'ordre où ils peuvent survenir (`forwardRequest()`, `forward.ts:408`) :
+Les échecs, dans l'ordre où ils peuvent survenir (`forwardRequest()`, `forward.ts#forwardRequest`) :
 
 - **508** — la requête porte déjà le pseudonyme de ce processus dans `Via`, ou au moins
   `MAX_VIA_HOPS` (10) sauts : une boucle, l'amont n'est pas contacté (`viaLoops()`,
-  `forward.ts:129`). Le plafond compte parce que le pseudonyme ne repère une boucle qu'au retour
+  `forward.ts#viaLoops`). Le plafond compte parce que le pseudonyme ne repère une boucle qu'au retour
   dans ce processus — derrière un répartiteur qui tourne sur N instances, après N+1 sauts ;
 - **501** — un `Transfer-Encoding` autre que `chunked` seul (`gzip, chunked`) : le transmettre
   réétiqueté livrerait à l'amont un corps compressé qu'il croirait en clair (`bodyFramingOf()`,
-  `forward.ts:166`) ;
+  `forward.ts#bodyFramingOf`) ;
 - **504** — connexion non établie sous `connectTimeoutMs`, ou amont muet au-delà de `timeoutMs` ;
 - **502** — amont injoignable, ou réponse que la sortie refuse (en-tête interdit en HTTP/2) ;
 - **coupure** — si l'amont tombe APRÈS avoir commencé à répondre, la réponse au client est
@@ -412,8 +412,8 @@ Les échecs, dans l'ordre où ils peuvent survenir (`forwardRequest()`, `forward
 
 Chaque montage a son **pool keep-alive dédié**, jamais l'agent global de Node : sous
 `NODE_USE_ENV_PROXY` (poste d'entreprise), l'agent global enverrait un amont local au proxy de
-l'entreprise (`ReverseProxy.agentFor()`, `reverse-proxy.ts:270`). Les pools sont fermés à l'arrêt du
-noyau (`ReverseProxy.closeAll()`, `reverse-proxy.ts:215`) ; un relais encore en vol part ensuite sur
+l'entreprise (`ReverseProxy.agentFor()`, `reverse-proxy.ts#ReverseProxy.agentFor`). Les pools sont fermés à l'arrêt du
+noyau (`ReverseProxy.closeAll()`, `reverse-proxy.ts#ReverseProxy.closeAll`) ; un relais encore en vol part ensuite sur
 une connexion à usage unique, sans recréer de pool que personne ne fermerait.
 
 ## 🔐 Sécurité
@@ -424,9 +424,9 @@ une connexion à usage unique, sans recréer de pool que personne ne fermerait.
 - **Quotas maintenus** : rate-limit par IP sur les requêtes relayées ; mêmes bornes par IP pour un
   upgrade relayé que pour un upgrade servi, plus `maxSockets` tunnels par amont.
 - **Barrière d'hôte maintenue** : un `Host` hors `trustedHosts` n'est jamais relayé ; il suit le
-  pipeline jusqu'au 421, comme toute requête (`HttpKernel.routeHttpRequest()`, `http-kernel.ts:1699`).
+  pipeline jusqu'au 421, comme toute requête (`HttpKernel.routeHttpRequest()`, `http-kernel.ts#HttpKernel.routeHttpRequest`).
 - **Chemins ambigus refusés**, pas normalisés : `.`, `..`, `\`, octet nul et leurs formes encodées
-  `%2e`, `%2f`, `%5c`, `%00`, `%25` (`isAmbiguousPath()`, `rules.ts:229`).
+  `%2e`, `%2f`, `%5c`, `%00`, `%25` (`isAmbiguousPath()`, `rules.ts#isAmbiguousPath`).
 - **Chaîne de confiance** : `Forwarded`, `X-Forwarded-*` et `X-Real-IP` d'un client direct sont
   écartés ; seul un pair `trustProxy` les prolonge.
 - **Certificat vérifié** vers une cible `https` ; `secure: false` n'est accepté que vers
@@ -437,18 +437,18 @@ une connexion à usage unique, sans recréer de pool que personne ne fermerait.
 
 ## 📜 Normes appliquées
 
-| Norme                   | Exigence                                                 | Comment le code s'y conforme                                                                      |
-| ----------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
-| RFC 9110 §7.6.1         | Un intermédiaire retire les en-têtes de connexion        | Liste fixe + jetons de `Connection`, dans les deux sens (`requestHeadersFor()`, `forward.ts:201`) |
-| RFC 9110 §7.6.3         | Un intermédiaire ajoute son entrée à `Via`               | Pseudonyme par processus, prolongé à l'aller et au retour (`forward.ts:244`)                      |
-| RFC 9112 §6.3           | Un seul cadrage de corps ; `Transfer-Encoding` l'emporte | `Content-Length` retiré quand le corps est découpé (`bodyFramingOf()`, `forward.ts:166`)          |
-| RFC 9112 §6.1           | Codage de transfert non compris → 501                    | Tout autre que `chunked` seul est refusé, jamais réétiqueté (`forward.ts:147`)                    |
-| RFC 9113 §8.2.2         | Pas d'en-tête de connexion en HTTP/2                     | Réponse refusée par la sortie h2 → 502, jamais une exception non rattrapée                        |
-| RFC 7239 §8.1           | Ne croire `Forwarded` que d'un relais de confiance       | `trustProxy` décide (`ReverseProxy.forward()`, `reverse-proxy.ts:319`)                            |
-| RFC 7239 §4 · §6        | Chaque relais ajoute son élément ; IPv6 entre crochets   | Élément `for=…;proto=…;host=…` ajouté, valeurs non-jeton entre guillemets                         |
-| RFC 6585 §4             | `429 Too Many Requests`                                  | Quota par IP dépassé sur un upgrade relayé, avant le `101`                                        |
-| RFC 6455 §4.2.1 · §10.2 | Handshake conforme ; contrôle d'Origin contre le CSWSH   | `websocketHandshakeProblem()` (`rules.ts:252`) + règle d'Origin du serveur WS                     |
-| RFC 5842 §7.2           | `508 Loop Detected`                                      | Emprunté à WebDAV pour une boucle de relais (`viaLoops()`, `forward.ts:129`)                      |
+| Norme                   | Exigence                                                 | Comment le code s'y conforme                                                                                    |
+| ----------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| RFC 9110 §7.6.1         | Un intermédiaire retire les en-têtes de connexion        | Liste fixe + jetons de `Connection`, dans les deux sens (`requestHeadersFor()`, `forward.ts#requestHeadersFor`) |
+| RFC 9110 §7.6.3         | Un intermédiaire ajoute son entrée à `Via`               | Pseudonyme par processus, prolongé à l'aller et au retour (`forward.ts#requestHeadersFor`)                      |
+| RFC 9112 §6.3           | Un seul cadrage de corps ; `Transfer-Encoding` l'emporte | `Content-Length` retiré quand le corps est découpé (`bodyFramingOf()`, `forward.ts#bodyFramingOf`)              |
+| RFC 9112 §6.1           | Codage de transfert non compris → 501                    | Tout autre que `chunked` seul est refusé, jamais réétiqueté (`forward.ts#viaEntry`)                             |
+| RFC 9113 §8.2.2         | Pas d'en-tête de connexion en HTTP/2                     | Réponse refusée par la sortie h2 → 502, jamais une exception non rattrapée                                      |
+| RFC 7239 §8.1           | Ne croire `Forwarded` que d'un relais de confiance       | `trustProxy` décide (`ReverseProxy.forward()`, `reverse-proxy.ts#ReverseProxy.forward`)                         |
+| RFC 7239 §4 · §6        | Chaque relais ajoute son élément ; IPv6 entre crochets   | Élément `for=…;proto=…;host=…` ajouté, valeurs non-jeton entre guillemets                                       |
+| RFC 6585 §4             | `429 Too Many Requests`                                  | Quota par IP dépassé sur un upgrade relayé, avant le `101`                                                      |
+| RFC 6455 §4.2.1 · §10.2 | Handshake conforme ; contrôle d'Origin contre le CSWSH   | `websocketHandshakeProblem()` (`rules.ts#websocketHandshakeProblem`) + règle d'Origin du serveur WS             |
+| RFC 5842 §7.2           | `508 Loop Detected`                                      | Emprunté à WebDAV pour une boucle de relais (`viaLoops()`, `forward.ts#viaLoops`)                               |
 
 ## ⚡ Performance & mémoire
 
@@ -472,7 +472,7 @@ en-tête `Via`.
 
 | Symptôme                                                         | Cause                                                         | Correction                                                                                              |
 | ---------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
-| Le boot s'arrête sur `proxy.mounts`                              | Préfixe `/`, réservé, ou cible avec un chemin                 | Lire le motif : il nomme la clé et le geste (`rules.ts:98`)                                             |
+| Le boot s'arrête sur `proxy.mounts`                              | Préfixe `/`, réservé, ou cible avec un chemin                 | Lire le motif : il nomme la clé et le geste (`rules.ts#proxyMountProblems`)                             |
 | Une route de l'application sous le préfixe n'est jamais atteinte | Le proxy passe AVANT le routage                               | Attendu : choisir un préfixe qui n'appartient qu'à l'amont                                              |
 | L'amont redirige hors du montage                                 | `stripPrefix` + liens absolus dans le HTML de l'amont         | Servir l'amont sous son préfixe, ou lui faire lire `X-Forwarded-Prefix`                                 |
 | L'amont voit `127.0.0.1` comme client                            | Lecture de l'IP de la socket au lieu de `X-Forwarded-For`     | Faire confiance à Nodefony côté amont (son équivalent de `trustProxy`)                                  |