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

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

@@ -1,6 +1,6 @@
 import { type IncomingMessage } from "node:http";
 import type { Duplex } from "node:stream";
-import type { WebSocketServer } from "ws";
+import type { WebSocket, WebSocketServer } from "ws";
 /** Serveur qui émet `upgrade` : HTTP/1.1, HTTPS ou HTTP/2 sécurisé (`allowHTTP1`). */
 interface IUpgradeEmitter {
     on(event: "upgrade", listener: (req: IncomingMessage, socket: Duplex, head: Buffer) => void): unknown;
@@ -11,6 +11,31 @@ interface IUpgradeRelay {
     readonly mounts: readonly unknown[] | null;
     handleUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer): boolean;
 }
+/**
+ * Le verdict d'un upgrade, rendu par le noyau APRÈS sa décision — qui peut
+ * attendre (session, pare-feu, garde de l'action). Un seul verdict compte : le
+ * premier appel l'emporte, les suivants sont ignorés.
+ */
+export interface IUpgradeAdmission {
+    /**
+     * Termine le handshake (`101`) et rend la socket ouverte.
+     *
+     * @returns la socket DIRECTEMENT quand `ws` la rend tout de suite (le cas
+     *   nominal : aucune promesse, aucune micro-tâche), sinon sa promesse ;
+     *   `null` si le client est parti pendant la décision (ou si `ws` a rejeté
+     *   le handshake) — il n'y a alors rien à servir
+     */
+    accept(): WebSocket | null | Promise<WebSocket | null>;
+    /**
+     * Refuse par un statut HTTP, AVANT le `101` (RFC 6455 §4.2.2).
+     *
+     * @param status - statut du refus (`401`, `403`, `429`…)
+     * @param headers - en-têtes du refus (`WWW-Authenticate`, `Retry-After`)
+     */
+    refuse(status: number, headers?: Readonly<Record<string, string | number>> | null): void;
+}
+/** Ce qui décide d'un upgrade : reçoit la requête et rend son verdict, plus tard s'il le faut. */
+export type UpgradeAdmit = (req: IncomingMessage, admission: IUpgradeAdmission) => void;
 /**
  * Pose l'UNIQUE écouteur `upgrade` d'un serveur : le proxy inverse d'abord,
  * puis le serveur WebSocket de Nodefony.
@@ -24,7 +49,10 @@ interface IUpgradeRelay {
  *
  * Entre les deux, `refusal` tranche ce qui doit être refusé AVANT le `101`
  * (RFC 6455 §4.2.2) : un chemin sans route WebSocket reçoit un statut HTTP,
- * jamais une ouverture suivie d'une fermeture.
+ * jamais une ouverture suivie d'une fermeture. Puis la FORME du handshake est
+ * contrôlée (`websocketHandshakeProblem`, la règle du proxy inverse) : un
+ * handshake malformé reçoit `400` sans jamais atteindre le noyau. Enfin
+ * `admit` décide — pare-feu, garde de l'action — et seul son verdict ouvre.
  *
  * Sans montage, le coût par connexion est une lecture de champ.
  *
@@ -33,7 +61,9 @@ interface IUpgradeRelay {
  * @param relay - proxy inverse, lu à chaque upgrade (il peut naître après)
  * @param refusal - statut HTTP qui refuse l'upgrade, `null` pour l'admettre
  *   (cf `HttpKernel.websocketUpgradeRefusal`)
+ * @param admit - décide d'un upgrade admis (cf `HttpKernel.onWebsocketUpgrade`) ;
+ *   par défaut, tout upgrade conforme est accepté et émis en `connection`
  * @returns la fonction qui retire l'écouteur — à appeler à l'arrêt
  */
-export declare function attachUpgradeDispatch(server: IUpgradeEmitter, wss: WebSocketServer, relay: () => IUpgradeRelay | null, refusal: (req: IncomingMessage) => number | null): () => void;
+export declare function attachUpgradeDispatch(server: IUpgradeEmitter, wss: WebSocketServer, relay: () => IUpgradeRelay | null, refusal: (req: IncomingMessage) => number | null, admit?: UpgradeAdmit): () => void;
 export {};

package/docs/cookies.md

@@ -112,20 +112,20 @@ Nodefony ne se contente pas de proposer ces attributs : il **choisit des défaut
 les invariants** que le navigateur exigerait de toute façon — pour que l'erreur ne parte pas sur le fil.
 
 **Le défaut est fermé.** Un cookie créé sans options est `Secure` + `HttpOnly` + `SameSite=Lax`
-(`cookieDefaultSettings`, `cookie.ts:39`). Il faut **choisir** d'ouvrir (ex. `httpOnly: false` pour un
+(`cookieDefaultSettings`, `cookie.ts#cookieDefaultSettings`). Il faut **choisir** d'ouvrir (ex. `httpOnly: false` pour un
 cookie lu en JS), jamais choisir de fermer.
 
 **Les préfixes sont forcés, pas espérés.** Nommer un cookie `__Host-…` ne suffit pas : `serialize()`
-(`cookie.ts:393`) **réécrit** la sortie — `Secure` ajouté, `Path=/` imposé, `Domain` retiré — pour que le
+(`cookie.ts#Cookie.serialize`) **réécrit** la sortie — `Secure` ajouté, `Path=/` imposé, `Domain` retiré — pour que le
 navigateur ne rejette jamais le cookie en silence. Idem `__Secure-` (Secure imposé) et `SameSite=None` (qui
-impose `Secure`, `cookie.ts:393`).
+impose `Secure`, `cookie.ts#Cookie.secure`).
 
 **La signature refuse le secret prévisible.** Un cookie `signed: true` sans secret configuré **jette**
-(`setValue()`, `cookie.ts:205`) : signer avec le secret public par défaut ne protégerait rien
-(fail-closed). La vérification est **timing-safe** (`unsign()` → `crypto.timingSafeEqual`, `cookie.ts:380`).
+(`setValue()`, `cookie.ts#Cookie.setValue`) : signer avec le secret public par défaut ne protégerait rien
+(fail-closed). La vérification est **timing-safe** (`unsign()` → `crypto.timingSafeEqual`, `cookie.ts#Cookie.unsign`).
 
 **`SameSite` retombe toujours sur `Lax`, jamais sur `None`.** Toute valeur inconnue est normalisée vers
-`Lax` (`setSameSite()`, `cookie.ts:250`) : `None` désactive la protection CSRF, ce n'est jamais un défaut.
+`Lax` (`setSameSite()`, `cookie.ts#Cookie.setSameSite`) : `None` désactive la protection CSRF, ce n'est jamais un défaut.
 
 **HTTP et WebSocket lisent les mêmes cookies.** Le parseur tourne pour les deux transports ; en revanche la
 poignée de main WebSocket **ne peut pas** écrire de cookie (limite de la bibliothèque `ws`) — voir plus bas.
@@ -201,10 +201,13 @@ Pour qu'une valeur ne puisse pas être **falsifiée** côté client (sans la chi
 secret **configuré** (le secret par défaut est refusé) :
 
 ```typescript ignore
-// fragment — un secret prévisible est refusé (fail-closed)
+// fragment — un secret prévisible est refusé (fail-closed).
+// `NF_COOKIE_SECRET` se déclare dans `env.ts` (`envString`), seul lecteur de l'environnement.
+import { env } from "../../env";
+
 const c = new Cookie("pref", "v1", {
   signed: true,
-  secret: process.env.COOKIE_SECRET!,
+  secret: env.NF_COOKIE_SECRET,
 });
 // c.value === "s:v1.<hmac base64url>" ; c.unsign() renvoie "v1" ou false si altéré
 ```
@@ -218,120 +221,124 @@ suit montre l'**usage réel**. La classe s'importe `import { Cookie } from "@nod
 ### Construire un cookie et ses attributs
 
 Le constructeur accepte `(nom, valeur, options?)` ou **un cookie à copier** (surcharge,
-`cookie.ts:149`). Les options fusionnent avec les défauts sûrs.
-
-| Option     | Type                       | Défaut       | Effet                                                                  |
-| ---------- | -------------------------- | ------------ | ---------------------------------------------------------------------- |
-| `maxAge`   | `number` (secondes)        | `0`          | Durée de vie. `0` = cookie de session (ni `Max-Age` ni `Expires`).     |
-| `expires`  | `Date \| string \| number` | —            | Date d'expiration absolue (`setExpires()`, `cookie.ts:272`).           |
-| `path`     | `string`                   | `/`          | Préfixe d'URL de portée.                                               |
-| `domain`   | `string`                   | `undefined`  | Domaine de portée (retiré si nom `__Host-`).                           |
-| `secure`   | `boolean`                  | `true`       | HTTPS only. Forcé si `SameSite=None` ou préfixe `__Host-`/`__Secure-`. |
-| `httpOnly` | `boolean`                  | `true`       | Invisible à `document.cookie` (anti-XSS).                              |
-| `sameSite` | `SameSiteType`             | `Lax`        | `Strict`/`Lax`/`None`. Toute autre valeur retombe sur `Lax`.           |
-| `signed`   | `boolean`                  | `false`      | Signe la valeur (HMAC). Exige `secret` configuré, sinon **jette**.     |
-| `secret`   | `string`                   | (par défaut) | Clé HMAC. Le secret par défaut est **refusé** pour signer.             |
-| `priority` | `High \| Medium \| Low`    | `undefined`  | Attribut `Priority` (`setPriority()`, `cookie.ts:305`).                |
-
-Les défauts sont matérialisés dans `cookieDefaultSettings` (`cookie.ts:39`) ; la fusion se fait dans le
-constructeur de `Cookie` (`cookie.ts:130`).
+`cookie.ts#Cookie.constructor`). Les options fusionnent avec les défauts sûrs.
+
+| Option     | Type                       | Défaut       | Effet                                                                      |
+| ---------- | -------------------------- | ------------ | -------------------------------------------------------------------------- |
+| `maxAge`   | `number` (secondes)        | `0`          | Durée de vie. `0` = cookie de session (ni `Max-Age` ni `Expires`).         |
+| `expires`  | `Date \| string \| number` | —            | Date d'expiration absolue (`setExpires()`, `cookie.ts#Cookie.setExpires`). |
+| `path`     | `string`                   | `/`          | Préfixe d'URL de portée.                                                   |
+| `domain`   | `string`                   | `undefined`  | Domaine de portée (retiré si nom `__Host-`).                               |
+| `secure`   | `boolean`                  | `true`       | HTTPS only. Forcé si `SameSite=None` ou préfixe `__Host-`/`__Secure-`.     |
+| `httpOnly` | `boolean`                  | `true`       | Invisible à `document.cookie` (anti-XSS).                                  |
+| `sameSite` | `SameSiteType`             | `Lax`        | `Strict`/`Lax`/`None`. Toute autre valeur retombe sur `Lax`.               |
+| `signed`   | `boolean`                  | `false`      | Signe la valeur (HMAC). Exige `secret` configuré, sinon **jette**.         |
+| `secret`   | `string`                   | (par défaut) | Clé HMAC. Le secret par défaut est **refusé** pour signer.                 |
+| `priority` | `High \| Medium \| Low`    | `undefined`  | Attribut `Priority` (`setPriority()`, `cookie.ts#Cookie.setPriority`).     |
+
+Les défauts sont matérialisés dans `cookieDefaultSettings` (`cookie.ts#cookieDefaultSettings`) ; la fusion se fait dans le
+constructeur de `Cookie` (`cookie.ts#Cookie.options`).
 
 ### Sérialiser : `serialize()` et `serializeWebSocket()`
 
-- `serialize()` (`cookie.ts:393`) produit la **ligne `Set-Cookie`** complète (attributs dans l'ordre,
+- `serialize()` (`cookie.ts#Cookie.serialize`) produit la **ligne `Set-Cookie`** complète (attributs dans l'ordre,
   préfixes forcés, `Max-Age` seulement s'il est positif).
-- `serializeWebSocket()` (`cookie.ts:435`) produit un **objet** `IWsCookie` (mêmes invariants de sécurité)
+- `serializeWebSocket()` (`cookie.ts#Cookie.serializeWebSocket`) produit un **objet** `IWsCookie` (mêmes invariants de sécurité)
   — utilisé quand un cookie doit être décrit hors en-tête HTTP.
-- `toString()` (`cookie.ts:325`) ne rend que `nom=valeurEncodée` (sans attributs).
+- `toString()` (`cookie.ts#Cookie.toString`) ne rend que `nom=valeurEncodée` (sans attributs).
 
 ### Signer / vérifier : `sign()` et `unsign()`
 
-- `sign(val, secret)` (`cookie.ts:331`) → `val.base64url(HMAC-SHA256)` — la valeur d'origine est
+- `sign(val, secret)` (`cookie.ts#Cookie.sign`) → `val.base64url(HMAC-SHA256)` — la valeur d'origine est
   **préservée** (récupérable), la signature garantit l'intégrité.
-- `unsign(val?, secret?)` (`cookie.ts:355`) → la valeur en clair si la signature est valide, sinon `false`.
-  Comparaison **timing-safe** (`cookie.ts:380`) ; tolère le préfixe marqueur `s:`.
+- `unsign(val?, secret?)` (`cookie.ts#Cookie.unsign`) → la valeur en clair si la signature est valide, sinon `false`.
+  Comparaison **timing-safe** (`cookie.ts#Cookie.unsign`) ; tolère le préfixe marqueur `s:`.
 
 ### Lire et écrire depuis le contexte
 
-| Besoin                         | Appel                                                 | Où                                       |
-| ------------------------------ | ----------------------------------------------------- | ---------------------------------------- |
-| Lire un cookie entrant         | `context.getRequestCookies("nom")` → `Cookie \| null` | `getRequestCookies()` (`Context.ts:706`) |
-| 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:717`)         |
-| Supprimer un cookie sortant    | `response.deleteCookieByName("nom")`                  | `http/Response.ts:233`                   |
+| Besoin                         | Appel                                                 | Où                                                             |
+| ------------------------------ | ----------------------------------------------------- | -------------------------------------------------------------- |
+| Lire un cookie entrant         | `context.getRequestCookies("nom")` → `Cookie \| null` | `getRequestCookies()` (`Context.ts#Context.getRequestCookies`) |
+| Lire tous les cookies entrants | `context.cookies` → `Record<string, Cookie>`          | `cookies` (`Context.ts#Context.cookies`)                       |
+| Écrire un cookie sortant       | `context.setCookie(new Cookie(…))`                    | `setCookie()` (`Context.ts#Context.setCookie`)                 |
+| Supprimer un cookie sortant    | `response.deleteCookieByName("nom")`                  | `http/Response.ts#HttpResponse.deleteCookieByName`             |
 
-Côté réponse HTTP, `addCookie()` (`http/Response.ts:215`) enregistre le cookie, et `setCookies()`
-(`http/Response.ts:241`) émet **une ligne `Set-Cookie` par cookie** — un tableau passé à Node, jamais une
+Côté réponse HTTP, `addCookie()` (`http/Response.ts#HttpResponse.addCookie`) enregistre le cookie, et `setCookies()`
+(`http/Response.ts#HttpResponse.setCookies`) é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.
+`clearCookie()` (`cookie.ts#Cookie.clearCookie`) recule `Expires` à l'époque.
 
 ### Parsing des cookies entrants
 
-`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:696`). Il est déclenché automatiquement par le pipeline : `parseCookies()` est appelé à
-l'initialisation du contexte HTTP (`HttpContext.ts:255`) **et** WebSocket (`WebsocketContext.ts:170`).
+`cookiesParser(context)` (`cookie.ts#cookiesParser`) lit l'en-tête `Cookie:` (via la bibliothèque `cookie`,
+`parser()` `cookie.ts#parser`), crée un `Cookie` par entrée et l'ajoute au contexte avec `addRequestCookie()`
+(`Context.ts#Context.addRequestCookie`). Il est déclenché automatiquement par le pipeline : `parseCookies()` est appelé à
+l'initialisation du contexte HTTP (`HttpContext.ts#HttpContext.constructor`) **et** WebSocket (`WebsocketContext.ts#WebsocketContext.constructor`).
 
 ### Côté WebSocket — lecture oui, écriture non
 
 Les cookies **entrants** sont lus au handshake, exactement comme en HTTP (même parseur). Mais la **poignée
 de main WebSocket ne peut pas poser de cookie** : `setCookie()` et `setCookies()` de la réponse WS sont des
-**no-op** (`websocket/Response.ts:315`), une limite de la bibliothèque `ws`. Le cookie de session, lui, est
+**no-op** (`websocket/Response.ts#WebsocketResponse.setCookies`), une limite de la bibliothèque `ws`. Le cookie de session, lui, est
 posé pendant la **phase HTTP** qui précède l'upgrade. La forme d'un cookie décrit pour le WS est
-`IWsCookie` (`ICookie.ts:19`), produite par `serializeWebSocket()`.
+`IWsCookie` (`ICookie.ts#IWsCookie`), produite par `serializeWebSocket()`.
 
 ## ⚙️ Configuration
 
 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:769`), avec notamment `hostPrefix`
-(`config.ts:791`) qui décide du préfixe `__Host-`. Tout cela est documenté dans [Sessions](session.md) :
+défauts sûrs de `cookieDefaultSettings` (`cookie.ts#cookieDefaultSettings`). Le seul cookie **piloté par la config** est celui
+de la **session** — bloc Zod `sessionCookieSchema` (`config.ts#sessionCookieSchema`), avec notamment `hostPrefix`
+(`config.ts#sessionCookieSchema`) 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:757`) — encore un détail qui appartient à la page Sessions.
+`getSessionCookieName()` (`Context.ts#Context.getSessionCookieName`) — encore un détail qui appartient à la page Sessions.
 
 ## 🛡️ Défenses par attribut
 
-| Attribut / mécanisme       | Faille bloquée                          | Comment Nodefony l'applique                                              |
-| -------------------------- | --------------------------------------- | ------------------------------------------------------------------------ |
-| `HttpOnly` (défaut `true`) | Vol de cookie par **XSS**               | Défaut fermé (`cookieDefaultSettings`, `cookie.ts:39`)                   |
-| `SameSite=Lax` (défaut)    | **CSRF** inter-site                     | Fallback toujours `Lax`, jamais `None` (`setSameSite()` `cookie.ts:250`) |
-| `Secure` (défaut `true`)   | Interception en clair                   | Forcé aussi par `None`/préfixes (`serialize()` `cookie.ts:393`)          |
-| Préfixe `__Host-`          | **Session fixation** cross-sous-domaine | `Domain` retiré + `Path=/` imposés (`serialize()` `cookie.ts:393`)       |
-| Cookie signé (HMAC)        | Altération de la valeur côté client     | `sign()`/`unsign()` timing-safe (`cookie.ts:355`, `cookie.ts:355`)       |
-| Refus du secret par défaut | Signature « fantôme » sans protection   | Fail-closed à la signature (`setValue()` `cookie.ts:205`)                |
+| Attribut / mécanisme       | Faille bloquée                          | Comment Nodefony l'applique                                                             |
+| -------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------- |
+| `HttpOnly` (défaut `true`) | Vol de cookie par **XSS**               | Défaut fermé (`cookieDefaultSettings`, `cookie.ts#cookieDefaultSettings`)               |
+| `SameSite=Lax` (défaut)    | **CSRF** inter-site                     | Fallback toujours `Lax`, jamais `None` (`setSameSite()` `cookie.ts#Cookie.setSameSite`) |
+| `Secure` (défaut `true`)   | Interception en clair                   | Forcé aussi par `None`/préfixes (`serialize()` `cookie.ts#Cookie.serialize`)            |
+| Préfixe `__Host-`          | **Session fixation** cross-sous-domaine | `Domain` retiré + `Path=/` imposés (`serialize()` `cookie.ts#Cookie.serialize`)         |
+| Cookie signé (HMAC)        | Altération de la valeur côté client     | `sign()`/`unsign()` timing-safe (`cookie.ts#Cookie.unsign`)                             |
+| Refus du secret par défaut | Signature « fantôme » sans protection   | Fail-closed à la signature (`setValue()` `cookie.ts#Cookie.setValue`)                   |
 
 ## 📜 Normes appliquées
 
-| Domaine                            | Norme                | Ancrage                                                            |
-| ---------------------------------- | -------------------- | ------------------------------------------------------------------ |
-| Cookies — syntaxe `Set-Cookie`     | RFC 6265bis          | `serialize()` (`cookie.ts:393`)                                    |
-| `SameSite` — 3 valeurs canoniques  | RFC 6265bis §5.4.7   | `SameSiteType` (`ICookie.ts:3`), `setSameSite()` (`cookie.ts:250`) |
-| Préfixes `__Host-` / `__Secure-`   | RFC 6265bis §4.1.3   | `serialize()` force les contraintes (`cookie.ts:393`)              |
-| `SameSite=None` impose `Secure`    | RFC 6265bis          | `serialize()` (`cookie.ts:393`)                                    |
-| Intégrité — HMAC-SHA256, base64url | RFC 2104 / RFC 4648  | `sign()` (`cookie.ts:331`)                                         |
-| Vérification à temps constant      | bonne pratique OWASP | `unsign()` → `timingSafeEqual` (`cookie.ts:380`)                   |
+| Domaine                            | Norme                | Ancrage                                                                                      |
+| ---------------------------------- | -------------------- | -------------------------------------------------------------------------------------------- |
+| Cookies — syntaxe `Set-Cookie`     | RFC 6265bis          | `serialize()` (`cookie.ts#Cookie.serialize`)                                                 |
+| `SameSite` — 3 valeurs canoniques  | RFC 6265bis §5.4.7   | `SameSiteType` (`ICookie.ts#SameSiteType`), `setSameSite()` (`cookie.ts#Cookie.setSameSite`) |
+| Préfixes `__Host-` / `__Secure-`   | RFC 6265bis §4.1.3   | `serialize()` force les contraintes (`cookie.ts#Cookie.serialize`)                           |
+| `SameSite=None` impose `Secure`    | RFC 6265bis          | `serialize()` (`cookie.ts#Cookie.serialize`)                                                 |
+| Intégrité — HMAC-SHA256, base64url | RFC 2104 / RFC 4648  | `sign()` (`cookie.ts#Cookie.sign`)                                                           |
+| Vérification à temps constant      | bonne pratique OWASP | `unsign()` → `timingSafeEqual` (`cookie.ts#Cookie.unsign`)                                   |
 
 ## ⚠️ Pièges (symptôme → cause → correction)
 
-| Symptôme                                                  | Cause                                                                     | Correction                                                               |
-| --------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
-| Le cookie posé en HTTP clair n'est pas stocké             | Défaut `Secure: true` → le navigateur exige HTTPS (sauf `localhost`)      | Servir en HTTPS, ou `secure: false` en dev hors localhost                |
-| Un cookie `__Host-` ignore mon `Domain`/`Path`            | `serialize()` **force** les contraintes du préfixe                        | Attendu (RFC 6265bis) — renommer sans préfixe si tu veux un `Domain`     |
-| `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:241`) |
-| `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                          |
+| Symptôme                                                  | Cause                                                                     | Correction                                                                                   |
+| --------------------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| Le cookie posé en HTTP clair n'est pas stocké             | Défaut `Secure: true` → le navigateur exige HTTPS (sauf `localhost`)      | Servir en HTTPS, ou `secure: false` en dev hors localhost                                    |
+| Un cookie `__Host-` ignore mon `Domain`/`Path`            | `serialize()` **force** les contraintes du préfixe                        | Attendu (RFC 6265bis) — renommer sans préfixe si tu veux un `Domain`                         |
+| `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#HttpResponse.setCookies`) |
+| `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                                              |
 
 ## 📡 Observabilité
 
 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:261`) — 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`.
+réponse HTTP — nom et attributs, **valeur masquée** (`ADD COOKIE ==> nodefony=<masqué>; Path=/; …`,
+`http/Response.ts#HttpResponse.setCookie`) — visible via le skill `nodefony-tail-error-logs` ou le Suivi
+de requête. La valeur n'y figure jamais : ce journal se lit par le plan d'administration, et un
+identifiant de session y passerait à quiconque le consulte, agent de code compris. La ligne n'est
+construite que si `DEBUG` passe le seuil du journal (debug ciblé compris) : en production, rien n'est
+alloué. La valeur se lit sur le fil : un `curl -i` montre les lignes `Set-Cookie`.
 
 ## 🧪 Tests & couverture
 

package/docs/diagnostics-channel.md

@@ -0,0 +1,303 @@
+---
+title: "Canal de diagnostic — le cycle de chaque requête publié sur diagnostics_channel"
+navTitle: Canal de diagnostic
+lang: fr
+module: "@nodefony/http"
+topic: diagnostics-channel
+section: "Cœur runtime"
+audience: [developer, devops]
+tags:
+  [
+    observabilite,
+    diagnostics_channel,
+    tracingchannel,
+    opentelemetry,
+    apm,
+    trace,
+    requestId,
+    websocket,
+  ]
+version: "doc"
+status: stable
+updated: 2026-10-24
+source: "src/packages/@nodefony/http/docs/diagnostics-channel.md"
+coverageModule: http
+coverageFiles: requestTrace.ts
+---
+
+# Canal de diagnostic — le cycle de chaque requête publié sur `diagnostics_channel`
+
+> Nodefony **annonce** le début et la fin de chaque requête HTTP et de chaque handshake WebSocket
+> sur un canal natif de Node, `nodefony.http.request`. Un outil d'observation installé dans le même
+> process — OpenTelemetry, Datadog, Sentry, ou votre propre code — s'y abonne et reçoit, sans
+> monkey-patch, ce que Nodefony est seul à connaître : la **route** qui a répondu, son **gabarit**,
+> le **module** signataire, le `requestId`, le statut réel et la durée. Personne n'écoute ? Le canal
+> coûte une lecture de booléen par requête, et rien n'est alloué.
+
+📍 [Documentation](../../../../../docs/index.md) › [@nodefony/http](index.md) › **Canal de diagnostic**
+
+## Schéma général
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant N as Nodefony (pipeline)
+    participant A as Abonné (agent APM)
+    C->>N: GET /users/42
+    N->>A: start — requestId, méthode, URL
+    N->>A: end — la partie synchrone a rendu la main
+    N->>C: 200 (dernier octet remis)
+    N->>A: asyncStart puis asyncEnd — route, gabarit, module, statut, durée
+```
+
+Le **même objet** voyage de `start` à `asyncEnd` : l'abonné y lit à la fin ce qui n'était pas
+encore connu au début.
+
+## Lexique
+
+| Terme                     | Sens                                                                                                                                                      |
+| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `diagnostics_channel`     | Module natif de Node (`node:diagnostics_channel`) : un bus de publication NOMMÉ, interne au process, fait pour que des outils observent une bibliothèque. |
+| Canal                     | Un nom (`tracing:nodefony.http.request:start`) ; publieur et abonné le retrouvent par ce nom, sans s'importer l'un l'autre.                               |
+| `TracingChannel`          | La forme « trace » du bus : cinq sous-canaux (`start`, `end`, `asyncStart`, `asyncEnd`, `error`) qui encadrent UNE opération, avec un objet partagé.      |
+| `runStores` / `bindStore` | Un abonné lie un `AsyncLocalStorage` au canal (`bindStore`) ; le publieur entre dans ce store pour la durée de l'opération (`runStores`).                 |
+| APM                       | _Application Performance Monitoring_ : agent (Datadog, New Relic, Elastic…) qui mesure et trace une application en production.                            |
+| OTel                      | _OpenTelemetry_ : standard ouvert de traces, métriques et journaux, et ses conventions de nommage d'attributs (« semconv »).                              |
+| Span                      | Une opération chronométrée d'une trace distribuée — ici, une requête serveur.                                                                             |
+| Gabarit de route          | Le chemin déclaré (`/users/{id}`), pas l'URL reçue (`/users/42`) : faible cardinalité, donc agrégeable. C'est l'attribut `http.route` d'OTel.             |
+| `requestId`               | Identifiant de corrélation de la requête (`X-Request-Id`), voir [Observabilité HTTP](observabilite.md).                                                   |
+
+## Qu'est-ce que c'est ?
+
+Un **haut-parleur interne au process**. Nodefony annonce « une requête commence », puis « elle est
+finie, voici son bilan ». Quiconque s'est mis à l'écoute de ce canal, dans le même process, reçoit
+l'annonce — immédiatement, sur le même fil, avec le même objet : pas de copie, pas de réseau, pas
+de fichier. Rien ne sort du process par lui-même : c'est l'abonné qui décide d'exporter, avec son
+propre transport (OTLP vers un collecteur, agent Datadog, Sentry).
+
+Le problème qu'il résout : sans lui, un outil de traçage ne voit d'une application Nodefony que ce
+que `node:http` publie — une requête brute, sans route, sans module, sans `requestId`. Pour en savoir
+plus, il devrait patcher les classes du framework à l'exécution, ce qui casse à chaque version.
+Node publie bien ses propres canaux serveur (`http.server.request.start`,
+`http.server.response.finish`), mais ils ne portent que la requête et la réponse brutes : ce que
+Nodefony a décidé — quelle route, quel module, quel statut réel derrière un proxy — n'y figure pas.
+
+## La vision Nodefony
+
+- **Un contrat, pas un crochet** : le canal et la forme de son message (`IRequestTrace`) sont une
+  API publique de `@nodefony/http`. Un plugin d'APM s'écrit contre eux, et non contre l'intérieur du
+  pipeline. C'est un contrat neuf : les agents existants ne le lisent pas d'office, un plugin doit
+  le consommer (comme Fastify publie `tracing:fastify.request.handler` pour les siens).
+- **Zéro coût sans abonné** : la garde (`requestTrace.ts#hasRequestTraceSubscribers`) est lue UNE
+  fois, au début de la requête. Faux → aucun message n'est construit, la fin ne lit qu'un champ
+  `null` (`Context.ts#Context.requestTrace`). Pas d'option de configuration : « éteint » veut dire
+  « personne n'écoute ».
+- **Une seule horloge** : la durée publiée est celle de la ligne d'accès (`Context.ts#Context.stopClock`),
+  jamais une mesure propre au canal.
+- **La séquence de Node, à la main** : `start` sous `runStores` à l'entrée, `end` quand la partie
+  synchrone rend la main (`requestTrace.ts#runTraced`), puis `error`, `asyncStart` et `asyncEnd` au
+  démontage, quand le dernier octet est remis (`requestTrace.ts#closeRequestTrace`). C'est l'ordre
+  de `TracingChannel.tracePromise`, que les abonnés génériques attendent ; la publication est
+  manuelle parce que la fin d'une requête arrive sur l'événement `close` de la réponse, hors de
+  toute fonction qu'on pourrait envelopper.
+- **Les stores des abonnés sont honorés** : un agent qui lie son `AsyncLocalStorage` au canal
+  (`bindStore`) voit son contexte actif pendant tout le traitement — les requêtes SQL et les appels
+  sortants d'une route deviennent des enfants de son span.
+
+## Démarrage rapide
+
+Un abonné de dix lignes, dans un fichier chargé AVANT l'application — c'est ainsi que se chargent
+les agents d'APM :
+
+```ts
+// tracing.ts — chargé par `--import`, avant l'application
+import diagnosticsChannel from "node:diagnostics_channel";
+import { REQUEST_TRACE_CHANNEL } from "@nodefony/http";
+import type { IRequestTrace } from "@nodefony/http";
+
+const channel = diagnosticsChannel.tracingChannel<IRequestTrace>(
+  REQUEST_TRACE_CHANNEL,
+);
+
+channel.subscribe({
+  start: () => {},
+  end: () => {},
+  asyncStart: () => {},
+  asyncEnd: (trace) => {
+    console.log(
+      `${trace.requestId} ${trace.method} ${trace.routePath ?? "-"} → ${trace.statusCode} en ${trace.durationMs?.toFixed(3)} ms (${trace.module})`,
+    );
+  },
+  error: (trace) => {
+    console.error(trace.requestId, trace.error);
+  },
+});
+```
+
+On le charge par `NODE_OPTIONS`, que les process lancés par la commande de développement héritent :
+
+```bash
+NODE_OPTIONS="--import ./tracing.ts" npx nodefony development
+curl -k https://127.0.0.1:5152/
+```
+
+Ce qu'on observe, une ligne par requête servie — ici la page d'accueil d'une application générée :
+
+```text
+6f1c…-9e2a GET / → 200 en 3.528 ms (app)
+```
+
+Importer `REQUEST_TRACE_CHANNEL` plutôt que recopier la chaîne : le nom vit en un seul endroit.
+
+## Le message — `IRequestTrace`
+
+Déclaré dans `IRequestTrace.ts#IRequestTrace`, exporté par `@nodefony/http`. Tout est en lecture
+seule pour l'abonné.
+
+| Champ        | Posé à  | Contenu                                                                                                                  |
+| ------------ | ------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `requestId`  | `start` | identifiant de corrélation (celui de `X-Request-Id` entrant, sinon généré)                                               |
+| `protocol`   | `start` | `"http"` pour une requête, `"websocket"` pour un handshake                                                               |
+| `method`     | `start` | méthode de la requête (`"WEBSOCKET"` pour un handshake)                                                                  |
+| `scheme`     | `start` | `http`, `https`, `ws`, `wss` — tel que vu par le client, proxy de confiance compris                                      |
+| `url`        | `start` | URL complète, **chaîne de requête comprise**                                                                             |
+| `route`      | fin     | nom de la route qui a répondu, `null` sans route (fichier statique, 404)                                                 |
+| `routePath`  | fin     | gabarit de la route, préfixe compris (`/users/{id}`) ; la racine vaut `/` ; `null` sans route                            |
+| `module`     | fin     | module qui a signé la réponse — le même que celui de la ligne d'accès                                                    |
+| `statusCode` | fin     | statut rendu : celui de l'amont pour une requête relayée, `101` pour un handshake accepté, `null` si le client est parti |
+| `durationMs` | fin     | construction du contexte → dernier octet remis (fin du handshake en WebSocket) ; `null` si `timing.enabled: false`       |
+| `error`      | `error` | l'exception attrapée par le pipeline, `null` sinon                                                                       |
+
+Les champs « fin » valent `null` à `start` et `end` : c'est normal, la route et le statut ne sont
+pas encore connus. On les lit sur `asyncEnd`.
+
+### Correspondance avec OpenTelemetry
+
+Pour qui écrit un plugin OTel, la table des attributs du span serveur (conventions sémantiques HTTP) :
+
+| Attribut OTel                  | Champ                                                          |
+| ------------------------------ | -------------------------------------------------------------- |
+| `http.request.method`          | `method`                                                       |
+| `url.scheme`                   | `scheme`                                                       |
+| `url.path` / `url.query`       | découpés de `url` par l'abonné (`new URL(trace.url)`)          |
+| `http.route`                   | `routePath` — jamais `route`, qui est un nom et pas un gabarit |
+| `http.response.status_code`    | `statusCode`                                                   |
+| `error.type`                   | dérivé de `error` (nom de la classe d'erreur)                  |
+| `http.server.request.duration` | `durationMs / 1000` (la métrique OTel est en secondes)         |
+
+Un **4xx sans exception** ne publie pas `error` : pour un span serveur, OTel demande de laisser le
+statut d'un 4xx non renseigné. C'est à l'abonné de classer un statut ; `statusCode` est là pour ça.
+
+## La séquence, sortie par sortie
+
+| Situation                               | Événements publiés                                    | `statusCode`         |
+| --------------------------------------- | ----------------------------------------------------- | -------------------- |
+| HTTP servi                              | `start` · `end` · `asyncStart` · `asyncEnd`           | statut de la réponse |
+| HTTP dont le pipeline lève              | `start` · `end` · `error` · `asyncStart` · `asyncEnd` | statut de l'erreur   |
+| Handshake WebSocket accepté             | `start` · `end` · `asyncStart` · `asyncEnd`           | `101`                |
+| Handshake refusé (origine, pare-feu, …) | `start` · `end` · `error` · `asyncStart` · `asyncEnd` | statut du refus      |
+| Client parti pendant la décision        | `start` · `end` · `asyncStart` · `asyncEnd`           | `null`               |
+
+La trace d'un WebSocket couvre le **handshake**, pas la vie de la connexion : elle se ferme au
+`101`. Les messages qui suivent ne sont pas publiés sur ce canal.
+
+## Architecture interne
+
+```mermaid
+flowchart TD
+    E["contexte construit"] --> G{"quelqu'un écoute ?"}
+    G -->|non| P["pipeline, rien d'alloué"]
+    G -->|oui| O["message créé, pipeline sous runStores"]
+    O --> F["démontage : error, asyncStart, asyncEnd"]
+```
+
+- **Entrée HTTP** — `http-kernel.ts#HttpKernel.handleHttp` : juste après la construction du
+  contexte, la garde ; avec abonné, le message est créé (`requestTrace.ts#openRequestTrace`, seule
+  allocation du canal) et le pipeline tourne sous `start.runStores`
+  (`http-kernel.ts#HttpKernel.dispatchHttpContext`).
+- **Fin HTTP** — `http-kernel.ts#HttpKernel.teardownHttp`, sur l'événement `close` de la réponse,
+  APRÈS la ligne d'accès : celle-ci a déjà recopié le statut de l'amont d'une requête relayée
+  (`HttpContext.ts#HttpContext.logRequest`).
+- **Handshake WebSocket** — `http-kernel.ts#HttpKernel.handleWebsocket` ouvre la trace ; elle se
+  ferme à l'acceptation (`WebsocketContext.ts#WebsocketContext.connect`, au même point que la ligne
+  d'accès), au refus (`WebsocketContext.ts#WebsocketContext.refuseHandshake`, seul endroit où le
+  statut du refus est connu), ou en échec (`http-kernel.ts#HttpKernel.closeFailedWebsocketTrace`).
+- **Idempotence** — `closeRequestTrace` remet `Context.requestTrace` à `null` avant de publier : un
+  handshake a plusieurs sorties, la première ferme la trace, les suivantes ne font rien.
+
+## Configuration
+
+Aucune, à dessein. Lire un réglage à chaque requête coûterait autant que lire la garde elle-même,
+pour un résultat identique : sans abonné, rien n'est publié. Pour couper le canal, on ne s'y abonne
+pas — ou on se désabonne (`channel.unsubscribe(subscribers)`).
+
+## Normes appliquées
+
+- **Documentation de `node:diagnostics_channel`** — nommage des canaux de trace en
+  `tracing:module.function:start` (d'où `nodefony.http.request`) ; et la règle « les événements ne
+  sont publiés que si l'abonné était présent **avant le début** de la trace » : un abonné qui arrive
+  en cours de requête ne reçoit rien de cette requête, pas même sa fin.
+- **Conventions sémantiques HTTP d'OpenTelemetry** — `http.route` exige un gabarit de faible
+  cardinalité, d'où `routePath` ; la durée de `http.server.request.duration` doit égaler celle du
+  span serveur, d'où une seule horloge.
+
+## Sécurité
+
+- **L'URL complète part chez l'abonné, chaîne de requête comprise** — un jeton passé en `?token=`
+  y figure. L'abonné est du code que l'exploitant a choisi d'installer, et les canaux natifs de
+  `node:http` exposent déjà la requête entière ; mais un agent qui EXPORTE l'URL doit en retirer les
+  paramètres sensibles. Préférer `routePath` pour nommer une opération.
+- **Une exception levée par un abonné fait tomber le process** : Node la relance par
+  `process.nextTick` en exception non capturée, hors de la pile de Nodefony. Un abonné se protège
+  lui-même (`try`/`catch`).
+- **Un abonné lent ralentit chaque requête** : il est appelé de façon synchrone, sur le fil du
+  serveur.
+
+## Performance & mémoire
+
+Mesuré au micro-banc (Node 26, médiane de 7 passages) :
+
+| Chemin                        | Coût par requête                                                                      |
+| ----------------------------- | ------------------------------------------------------------------------------------- |
+| Personne n'écoute (le défaut) | une lecture de `hasSubscribers` (~1,6 ns), un champ `null` sur le contexte (8 octets) |
+| Un abonné                     | un objet de message, l'appel des abonnés, l'entrée dans les stores liés               |
+
+`diagnostics_channel.hasSubscribers("nom")` coûterait ~41 ns : la garde lit donc le
+`TracingChannel` gardé en mémoire de module, jamais une recherche par nom. Le gate mémoire
+(`npm run test:memory`) est vert **sans** abonné et **avec** un abonné armé : le message ne retient
+ni contexte ni scope.
+
+## Pièges
+
+| Symptôme                                                    | Cause                                                            | Correction                                                              |
+| ----------------------------------------------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| L'abonné ne reçoit rien des premières requêtes              | il s'est abonné après leur début — règle des `TracingChannel`    | s'abonner AVANT l'application (`--import`)                              |
+| `route`, `statusCode` à `null` dans le gestionnaire `start` | ils ne sont connus qu'à la fin                                   | les lire dans `asyncEnd`                                                |
+| Le tableau de bord explose en cardinalité                   | l'opération est nommée d'après `url` (`/users/42`, `/users/43`…) | nommer par `routePath` (`/users/{id}`)                                  |
+| Le serveur tombe sur une exception venue de l'agent         | un abonné a levé : Node la relance en exception non capturée     | `try`/`catch` dans chaque gestionnaire de l'abonné                      |
+| Un 404 apparaît en erreur dans l'APM                        | l'abonné classe sur l'événement `error` sans regarder le statut  | classer par `statusCode` ; `error` signale une exception, pas un statut |
+| `durationMs` toujours `null`                                | `timing.enabled: false` dans la configuration de l'application   | rétablir le défaut — la durée est mesurée partout, production comprise  |
+
+## Tests & couverture
+
+| Type                      | Où                                                                                                                                                                                      |
+| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Intégration — abonné réel | `integration/request-trace-channel.test.ts` — séquences HTTP servi / en erreur, handshake accepté / refusé, abonné tardif sans fin orpheline, désabonnement, même objet de bout en bout |
+| Mémoire                   | `http/memory.test.ts` — le gate, rejoué sans abonné (le défaut) et avec la sonde armée                                                                                                  |
+
+L'abonné vit dans le process du serveur : la sonde `TraceChannelController` du module `test`
+(`/nodefony/test/trace-channel/{arm,disarm,events}`) s'abonne à la demande. Ce qui **manque** : pas
+de banc unitaire isolé de `requestTrace.ts` (exercé de bout en bout par le banc d'intégration), et
+pas de cas « client parti pendant la décision » au banc (sortie couverte par lecture du code).
+
+Suites : `npm run test:integration` (serveur requis), `npm run test:memory`. Skills associés :
+`nodefony-check-memory-health`, `nodefony-load-test`.
+
+## Pour aller plus loin
+
+- ⬆️ **Retour au hub** : [@nodefony/http — vue du module](index.md) · [Toute la documentation](../../../../../docs/index.md)
+- 🧭 **Pages sœurs** : [Observabilité HTTP](observabilite.md) · [Serveurs](servers.md)
+- La durée d'une requête et sa définition → [Observabilité HTTP](observabilite.md)
+- Le trajet complet d'une requête → [pipeline-requete](../../../../../docs/architecture/pipeline-requete.md)
+- Le proxy inverse (statut de l'amont) → [Proxy inverse](reverse-proxy.md)
+- Les lignes du journal, sur le canal `nodefony.syslog.log` → [Journalisation](../../../../nodefony/docs/syslog.md#observer-le-journal-depuis-un-outil-tiers)