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

package/docs/session.md

@@ -69,8 +69,8 @@ flowchart TD
 ```
 
 Le point d'activation est **unique et commun aux deux transports** : `HttpKernel.startSession()`
-(`http-kernel.ts:1246`). Il commence par la garde paresseuse `if (!intent && !context.hasSession())`
-(`http-kernel.ts:1283`) — sans intent de route ni cookie entrant, **aucune session n'est ouverte**.
+(`http-kernel.ts:1330`). Il commence par la garde paresseuse `if (!intent && !context.hasSession())`
+(`http-kernel.ts:1314`) — sans intent de route ni cookie entrant, **aucune session n'est ouverte**.
 
 ## 📖 Lexique
 
@@ -114,15 +114,15 @@ défaut** dans Nodefony :
 
 - **Vol du cookie (hijacking).** Un script injecté (XSS) ou un réseau en clair capte le cookie et
   rejoue la session. → `HttpOnly` et `Secure` sont à `true` par défaut (`sessionCookieSchema`,
-  `config.ts:752-755`), et le nom du cookie prend le préfixe `__Host-` dès que le transport est TLS
-  (`Context.getSessionCookieName()`, `Context.ts:733`).
+  `config.ts:769`), et le nom du cookie prend le préfixe `__Host-` dès que le transport est TLS
+  (`Context.getSessionCookieName()`, `Context.ts:757`).
 - **Fixation.** L'attaquant pose lui-même un identifiant dans le navigateur de la victime, attend
   qu'elle se connecte, puis réutilise **le même** identifiant. → double défense : `strictMode` rejette
-  tout identifiant inconnu du store (`Session.resume()`, `session.ts:177`), et le login **régénère**
+  tout identifiant inconnu du store (`Session.resume()`, `session.ts:197`), et le login **régénère**
   l'identifiant (`AuthFlow` — voir plus bas).
 - **Exploitation prolongée d'un identifiant volé.** Une session maintenue artificiellement vivante
   resterait exploitable indéfiniment. → l'**absolute timeout** borne l'âge depuis la création et n'est
-  **jamais** prolongé (`Session.isValidSession()`, `session.ts:371`), en plus de l'idle timeout.
+  **jamais** prolongé (`Session.isValidSession()`, `session.ts:389`), en plus de l'idle timeout.
 
 > [!IMPORTANT]
 > Le cookie **ne chiffre rien** et n'a pas à le faire : il ne porte qu'un numéro. La sécurité repose
@@ -134,18 +134,18 @@ défaut** dans Nodefony :
 Quatre partis pris, chacun vérifiable dans le code.
 
 **1. Le cookie ne transporte que l'identifiant.** `Session.getSession()` lit la **valeur brute** du
-cookie, sans déchiffrement (`session.ts:160`) ; l'identifiant vient de `Session.generateId()`
+cookie, sans déchiffrement (`session.ts:180`) ; l'identifiant vient de `Session.generateId()`
 (`session.ts:231`). Modèle BFF : le web reste sur un cookie opaque, le JWT est réservé aux API et aux
 agents (voir [Firewall](../../security/docs/firewall.md)).
 
 **2. La session est paresseuse.** Elle n'existe que si une route la demande — `@UseSession`, ou la
 seule présence d'un paramètre `@Session` — ou si un cookie arrive déjà : c'est la garde de
-`HttpKernel.startSession()` (`http-kernel.ts:1246`). Une route publique ne paie **ni lecture de store,
+`HttpKernel.startSession()` (`http-kernel.ts:1330`). Une route publique ne paie **ni lecture de store,
 ni `Set-Cookie`**.
 
 **3. Un seul modèle d'état pour le web et le temps réel.** Le même `startSession()` sert
-`HttpKernel.onRequestEnd()` (`http-kernel.ts:1697`) et `HttpKernel.onConnect()` (`http-kernel.ts:2008`) ;
-l'activité HTTP **ou** WS prolonge la même session (`Session.touchIfNeeded()`, `session.ts:421`).
+`HttpKernel.onRequestEnd()` (`http-kernel.ts:1800`) et `HttpKernel.onConnect()` (`http-kernel.ts:2098`) ;
+l'activité HTTP **ou** WS prolonge la même session (`Session.touchIfNeeded()`, `session.ts:454`).
 
 **4. L'administration ne voit jamais un identifiant.** Un opérateur manipule une `ref`, HMAC tronqué
 non réversible produit par `computeSessionRef()` (`sessions-service.ts:100`) — comme la liste
@@ -274,19 +274,19 @@ curl -sk -b /tmp/jar https://localhost:5152/panier
 Le cookie obtenu porte `__Host-`, `HttpOnly`, `Secure`, `SameSite=Lax`, `Path=/` et **aucun** `Domain` :
 c'est exactement ce qu'assert le banc d'intégration `session-runtime` (« Set-Cookie de session sur TLS »).
 Sur un transport en clair (port 5151), le préfixe `__Host-` est omis — le navigateur le rejetterait
-faute de `Secure` (`Context.getSessionCookieName()`, `Context.ts:733`).
+faute de `Secure` (`Context.getSessionCookieName()`, `Context.ts:757`).
 
 ## ⚙️ Configuration
 
-Source unique des défauts : le schéma Zod `sessionSchema` (`config.ts:786`) et son sous-schéma
-`sessionCookieSchema` (`config.ts:752`).
+Source unique des défauts : le schéma Zod `sessionSchema` (`config.ts:803`) et son sous-schéma
+`sessionCookieSchema` (`config.ts:769`).
 
 | Option              | Type    | Défaut       | Effet                                                                                    |
 | ------------------- | ------- | ------------ | ---------------------------------------------------------------------------------------- |
 | `store`             | string  | `"auto"`     | Backend de persistance — voir la résolution ci-dessous (`config.ts:795`).                |
 | `name`              | string  | `"nodefony"` | Nom du cookie, préfixé `__Host-` selon `cookie.hostPrefix` (`config.ts:770`).            |
 | `strictMode`        | bool    | `true`       | Un identifiant inconnu du store est rejeté → session neuve (anti-fixation).              |
-| `idleTimeoutS`      | int ≥ 0 | `1800`       | Inactivité max (30 min). `0` = pas d'expiration par inactivité (`config.ts:823`).        |
+| `idleTimeoutS`      | int ≥ 0 | `1800`       | Inactivité max (30 min). `0` = pas d'expiration par inactivité (`config.ts:844`).        |
 | `absoluteTimeoutS`  | int ≥ 0 | `43200`      | Âge max depuis la création (12 h), **jamais** prolongé. `0` = désactivé.                 |
 | `gcIntervalS`       | int ≥ 0 | `600`        | Période de purge des sessions expirées, hors requête. `0` = timer désarmé.               |
 | `gcJitter`          | bool    | `true`       | Décale le départ du GC par process (anti _thundering herd_ sur un store partagé).        |
@@ -351,7 +351,7 @@ Ce qui change, c'est la topologie et la façon d'expirer.
 
 ### `memory` — l'implémentation de référence
 
-Store built-in de `@nodefony/http`, enregistré d'office (`sessions-service.ts:913`). Les sessions vivent
+Store built-in de `@nodefony/http`, enregistré d'office (`sessions-service.ts:950`). Les sessions vivent
 dans une `Map` du process : elles **disparaissent au redémarrage** et ne sont **pas partagées** entre
 pods — c'est un choix (mesurer le framework sans le goulot disque/SQL), pas une limite.
 
@@ -380,24 +380,24 @@ traduit (`$null`) au lieu de chercher `""` (`@nodefony/drizzle/nodefony/src/Sess
 ### `redis` — TTL natif, zéro balayage
 
 Ici l'expiration **idle** est portée par Redis lui-même : `SET … EX` pose le TTL à chaque écriture
-(`@nodefony/redis/nodefony/src/SessionStorage.ts:137`) et `touch` le repositionne par un `EXPIRE` O(1)
+(`@nodefony/redis/nodefony/src/SessionStorage.ts:247`) et `touch` le repositionne par un `EXPIRE` O(1)
 (`@nodefony/redis/nodefony/src/SessionStorage.ts:166`). Conséquence : `gc()` est un **no-op assumé**
 (`@nodefony/redis/nodefony/src/SessionStorage.ts:168`) — aucun balayage périodique.
 
 L'absolute timeout, lui, n'est pas exprimable par un TTL glissant : il reste honoré **à la lecture**
-par `Session.isValidSession()` (`session.ts:371`). Une entrée trop vieille peut donc survivre côté
+par `Session.isValidSession()` (`session.ts:389`). Une entrée trop vieille peut donc survivre côté
 Redis jusqu'à son TTL idle, mais elle est **refusée à la reprise**.
 
 Capacités réduites, annoncées et non simulées : la pagination est **par curseur** (pas de `total`, pas
 d'ordre global) et `countSessions()` renvoie **`-1`** = « je ne sais pas »
-(`@nodefony/redis/nodefony/src/SessionStorage.ts:303`). L'appelant affiche l'inconnu, il ne l'invente pas.
+(`@nodefony/redis/nodefony/src/SessionStorage.ts:474`). L'appelant affiche l'inconnu, il ne l'invente pas.
 
 ### `mongoose` — MongoDB, parité de comportement
 
 Même sémantique que le store SQL : `findOneAndUpdate({ upsert: true })` en une passe
-(`@nodefony/mongoose/nodefony/src/SessionStorage.ts:195`), `touch` en `updateOne`
-(`@nodefony/mongoose/nodefony/src/SessionStorage.ts:174`), GC en deux suppressions `$lt`
-(`@nodefony/mongoose/nodefony/src/SessionStorage.ts:144-166`). Les horodatages sont des **nombres**
+(`@nodefony/mongoose/nodefony/src/SessionStorage.ts:149`), `touch` en `updateOne`
+(`@nodefony/mongoose/nodefony/src/SessionStorage.ts:219`), GC en deux suppressions `$lt`
+(`@nodefony/mongoose/nodefony/src/SessionStorage.ts:189-211`). Les horodatages sont des **nombres**
 (epoch ms) et non des `Date` Mongo, précisément pour que le store reste interchangeable avec Drizzle.
 
 > [!TIP]
@@ -435,12 +435,12 @@ sequenceDiagram
   end
 ```
 
-**Reprise ou création.** `Session.start()` (`session.ts:144`) délègue à `getSession()` : cookie présent
-→ `resume()` (`session.ts:177`), sinon `create()` (`session.ts:204`) qui tire un identifiant CSPRNG,
+**Reprise ou création.** `Session.start()` (`session.ts:164`) délègue à `getSession()` : cookie présent
+→ `resume()` (`session.ts:197`), sinon `create()` (`session.ts:227`) qui tire un identifiant CSPRNG,
 pose le cookie et marque la session à persister.
 
-**Validation à la reprise.** `Session.isValidSession()` (`session.ts:371`) applique l'**absolute**
-(âge depuis `created`) puis l'**idle** (depuis `updated`). Échec → `invalidate()` (`session.ts:290`)
+**Validation à la reprise.** `Session.isValidSession()` (`session.ts:389`) applique l'**absolute**
+(âge depuis `created`) puis l'**idle** (depuis `updated`). Échec → `invalidate()` (`session.ts:308`)
 détruit l'entrée et recrée une session vierge.
 
 > [!WARNING]
@@ -450,7 +450,7 @@ détruit l'entrée et recrée une session vierge.
 > activer `refererCheck` quand l'expiration des sessions compte — c'est-à-dire presque toujours.
 
 **Écriture minimale.** `SessionsService.saveSession()` (`sessions-service.ts:463`) n'écrit **que** si la
-session est `dirty` et non `readOnly` ; sinon il appelle `Session.touchIfNeeded()` (`session.ts:421`),
+session est `dirty` et non `readOnly` ; sinon il appelle `Session.touchIfNeeded()` (`session.ts:454`),
 qui prolonge l'idle **sans réécrire le blob**, et seulement au-delà d'une demi-vie d'idle
 (`session.ts:445`). Une requête de lecture coûte donc au pire un `UPDATE` d'horodatage toutes les
 15 minutes (défaut).
@@ -503,17 +503,17 @@ C'est le différenciateur du framework appliqué à l'état de session : un seul
 <!-- prettier-ignore -->
 | Aspect | HTTP | WebSocket |
 | --- | --- | --- |
-| Ouverture | à chaque requête — `startSession()` dans `onRequestEnd()` (`http-kernel.ts:1697`) | **une fois** au handshake — `startSession()` dans `onConnect()` (`http-kernel.ts:2008`) |
+| Ouverture | à chaque requête — `startSession()` dans `onRequestEnd()` (`http-kernel.ts:1800`) | **une fois** au handshake — `startSession()` dans `onConnect()` (`http-kernel.ts:2098`) |
 | Lecture du cookie | constructeur du contexte | constructeur, même nom effectif (`WebsocketContext.ts:172`) |
 | Sauvegarde | fin de requête | après **chaque frame** traitée (`WebsocketContext.ts:302`) |
-| Filet de fermeture | — | `once("onFinish")` sauve si non déjà fait (`http-kernel.ts:1801`) |
-| Portée ALS | une requête | **handshake + toutes les frames** (`http-kernel.ts:1495`) |
+| Filet de fermeture | — | `once("onFinish")` sauve si non déjà fait (`http-kernel.ts:1904`) |
+| Portée ALS | une requête | **handshake + toutes les frames** (`http-kernel.ts:1526`) |
 
 La conséquence pratique la plus utile : côté WebSocket, la bulle `AsyncLocalStorage` ouverte au
-handshake par `RequestContext.run()` **enveloppe aussi les messages** (`http-kernel.ts:1929`). L'identité résolue une fois est donc
+handshake par `RequestContext.run()` **enveloppe aussi les messages** (`http-kernel.ts:519`). L'identité résolue une fois est donc
 disponible à chaque frame sans relire la base — c'est ce dont profite
 `FirewallRealtimeAuthenticator.supports()` (`FirewallRealtimeAuthenticator.ts:80`), câblé automatiquement
-par le firewall sur les zones temps réel protégées (`firewall.ts:297`).
+par le firewall sur les zones temps réel protégées (`firewall.ts:298`).
 
 > [!WARNING]
 > Rien à écrire dans `initialize()` : il n'existe **pas** de `Controller.startSession()`. La session WS
@@ -526,13 +526,13 @@ par le firewall sur les zones temps réel protégées (`firewall.ts:297`).
 ### Régénération d'identifiant à la connexion (anti-fixation)
 
 C'est la défense la plus importante et elle est **active**. `AuthFlow.#openSession()`
-(`authFlow.ts:378`) : reprise ou ouverture de la session, mémorisation de l'ancien identifiant, puis
+(`authFlow.ts:524`) : reprise ou ouverture de la session, mémorisation de l'ancien identifiant, puis
 appel **inconditionnel** de `Session.regenerateId()` (`authFlow.ts:388`), et enfin destruction de
 l'ancienne entrée du store (`authFlow.ts:390`). Un cookie pré-posé par un attaquant **ne survit donc pas
 au login**. Le nouvel identifiant est un CSPRNG frais, l'état applicatif est conservé
-(`Session.regenerateId()`, `session.ts:236`).
+(`Session.regenerateId()`, `session.ts:260`).
 
-Au passage, la provenance est capturée dans le `metaBag` : `ip` (`authFlow.ts:405`) et `ua`
+Au passage, la provenance est capturée dans le `metaBag` : `ip` (`authFlow.ts:556`) et `ua`
 (`authFlow.ts:407`), en mode « au mieux » — ce sont ces deux champs que la console d'administration
 affiche.
 
@@ -540,20 +540,20 @@ affiche.
 
 | Surface                  | Méthode                                         | Portée                                      |
 | ------------------------ | ----------------------------------------------- | ------------------------------------------- |
-| Déconnexion locale       | `Session.destroy()` (`session.ts:306`)          | la session courante + pierre tombale        |
+| Déconnexion locale       | `Session.destroy()` (`session.ts:324`)          | la session courante + pierre tombale        |
 | Révocation par un admin  | `destroyByRef()` (`sessions-service.ts:745`)    | une session désignée par sa `ref` publique  |
-| « Déconnecter partout »  | `destroyByUser()` (`sessions-service.ts:775`)   | toutes les sessions d'un utilisateur        |
-| « Mes appareils » (self) | `destroyOwnByRef()` (`sessions-service.ts:872`) | une session, **restreinte au propriétaire** |
+| « Déconnecter partout »  | `destroyByUser()` (`sessions-service.ts:831`)   | toutes les sessions d'un utilisateur        |
+| « Mes appareils » (self) | `destroyOwnByRef()` (`sessions-service.ts:898`) | une session, **restreinte au propriétaire** |
 
 Deux finesses valent d'être connues.
 
 `destroyByUser()` ne fait pas un seul passage : il **repasse jusqu'à ce qu'un passage complet ne
-détruise plus rien** (`sessions-service.ts:775`), car supprimer en parcourant décale les rangs sous un
+détruise plus rien** (`sessions-service.ts:831`), car supprimer en parcourant décale les rangs sous un
 curseur offset. Une révocation « partout » qui en laisserait une n'est pas une imprécision, c'est une
 faille — on rend donc la main avec la preuve, pas l'espoir.
 
 `destroyOwnByRef()` ferme l'IDOR **par construction** : parcours restreint aux sessions du demandeur,
-et appartenance **re-vérifiée** avant même de comparer la `ref` (`sessions-service.ts:863`). Une
+et appartenance **re-vérifiée** avant même de comparer la `ref` (`sessions-service.ts:900`). Une
 `ref` d'autrui est structurellement introuvable.
 
 ### Redaction — l'identifiant ne sort jamais du process
@@ -572,22 +572,22 @@ Trois barrières superposées :
 
 | Menace                            | Défense                                           | Ancrage                                            |
 | --------------------------------- | ------------------------------------------------- | -------------------------------------------------- |
-| Vol par script injecté (XSS)      | `HttpOnly`                                        | `sessionCookieSchema` (`config.ts:752`)            |
-| Interception réseau               | `Secure` + `__Host-` sur TLS                      | `getSessionCookieName()` (`Context.ts:733`)        |
+| Vol par script injecté (XSS)      | `HttpOnly`                                        | `sessionCookieSchema` (`config.ts:769`)            |
+| Interception réseau               | `Secure` + `__Host-` sur TLS                      | `getSessionCookieName()` (`Context.ts:757`)        |
 | Requête inter-sites               | `SameSite=Lax` par défaut                         | `cookieDefaultSettings` (`cookie.ts:39`)           |
-| Fixation (cookie pré-posé)        | `strictMode` + régénération au login              | `Session.resume()` (`session.ts:177`)              |
+| Fixation (cookie pré-posé)        | `strictMode` + régénération au login              | `Session.resume()` (`session.ts:197`)              |
 | Identifiant deviné                | 32 octets CSPRNG (43 caractères base64url)        | `Session.generateId()` (`session.ts:231`)          |
-| Session volée exploitée longtemps | absolute timeout, jamais prolongé                 | `absoluteTimeoutS` à la reprise (`session.ts:388`) |
-| Session oubliée ouverte           | idle timeout glissant                             | `idleTimeoutS` à la reprise (`session.ts:401`)     |
+| Session volée exploitée longtemps | absolute timeout, jamais prolongé                 | `absoluteTimeoutS` à la reprise (`session.ts:411`) |
+| Session oubliée ouverte           | idle timeout glissant                             | `idleTimeoutS` à la reprise (`session.ts:426`)     |
 | Résurrection après révocation     | pierre tombale 5 min sur `write` **et** `touch`   | `RevocationGuardStorage.ts:127-171`                |
 | Fuite d'identifiant en admin      | `ref` HMAC + projection en liste blanche          | `toSessionSummary()` (`sessions-service.ts:112`)   |
-| IDOR sur « mes sessions »         | périmètre depuis l'identité ALS, jamais du client | `destroyOwnByRef()` (`sessions-service.ts:872`)    |
+| IDOR sur « mes sessions »         | périmètre depuis l'identité ALS, jamais du client | `destroyOwnByRef()` (`sessions-service.ts:898`)    |
 
 ## 🧰 API publique
 
 Les signatures vivent dans `.ai/symbols.json` (jamais recopiées ici). Voici les usages réels.
 
-**Depuis un contrôleur** — `this.session` est un getter sur le contexte (`Controller.ts:384`) ; un
+**Depuis un contrôleur** — `this.session` est un getter sur le contexte (`Controller.ts:397`) ; un
 paramètre `@Session()` suffit à déclarer l'intent.
 
 | Besoin                           | Appel                                | Effet                                                   |
@@ -595,20 +595,20 @@ paramètre `@Session()` suffit à déclarer l'intent.
 | Lire une valeur                  | `session.get("panier")`              | `null` si absente — jamais `undefined`.                 |
 | Écrire une valeur                | `session.set("panier", items)`       | Marque la session `dirty` → écriture en fin de requête. |
 | Message « une seule lecture »    | `session.setFlashBag("notice", "…")` | Consommé (et effacé) au premier `getFlashBag`.          |
-| Lire ce message                  | `session.getFlashBag("notice")`      | Rend la valeur puis la supprime (`session.ts:530`).     |
+| Lire ce message                  | `session.getFlashBag("notice")`      | Rend la valeur puis la supprime (`session.ts:551`).     |
 | Métadonnée technique             | `session.getMetaBag("ip")`           | ip / ua / host / remoteAddress posés à la création.     |
 | Se déconnecter                   | `await session.destroy(true)`        | Détruit l'entrée store **et** efface le cookie.         |
-| Renouveler l'identifiant         | `session.regenerateId()`             | Nouvel identifiant, état conservé (`session.ts:236`).   |
-| Savoir si une écriture aura lieu | `session.dirty`                      | Le drapeau de dirty-tracking (`session.ts:128`).        |
+| Renouveler l'identifiant         | `session.regenerateId()`             | Nouvel identifiant, état conservé (`session.ts:260`).   |
+| Savoir si une écriture aura lieu | `session.dirty`                      | Le drapeau de dirty-tracking (`session.ts:148`).        |
 
-**Intent de route** — `UseSession(options)` (`routerDecorators.ts:800`) s'applique à une classe **ou** à
+**Intent de route** — `UseSession(options)` (`routerDecorators.ts:830`) s'applique à une classe **ou** à
 une méthode ; la méthode l'emporte, par fusion et non par remplacement
 (`resolveSessionIntent()`, `routerDecorators.ts:858`). **Une seule** option (`SessionIntent`,
 `ISession.ts:17`) :
 
 - `readOnly: true` — la session est reprise et lue mais **jamais** persistée ; une mutation tentée est
-  journalisée en WARNING sans écriture (`Session.save()`, `session.ts:255-264`). C'est le seul champ
-  propagé par le kernel (`http-kernel.ts:1210`).
+  journalisée en WARNING sans écriture (`Session.save()`, `session.ts:273-282`). C'est le seul champ
+  propagé par le kernel (`http-kernel.ts:1241`).
 
 En décorateur de **classe**, `@UseSession` se place **sous** `@controller` (`routerDecorators.ts:189`).
 
@@ -643,12 +643,12 @@ Trois règles de conception se dégagent du contrat, et méritent d'être respec
 | Domaine                       | Norme                     | Comment le code s'y conforme                                                  |
 | ----------------------------- | ------------------------- | ----------------------------------------------------------------------------- |
 | Attributs et préfixes cookie  | RFC 6265bis §4.1.3        | `__Host-` impose `Secure` + `Path=/`, interdit `Domain` (`cookie.ts:386-403`) |
-| Nom du cookie selon transport | RFC 6265bis / OWASP       | `getSessionCookieName()` (`Context.ts:733`)                                   |
-| Idle timeout                  | NIST SP 800-63B-4 / OWASP | défaut 1800 s, glissant par `touch` (`config.ts:831`)                         |
+| Nom du cookie selon transport | RFC 6265bis / OWASP       | `getSessionCookieName()` (`Context.ts:757`)                                   |
+| Idle timeout                  | NIST SP 800-63B-4 / OWASP | défaut 1800 s, glissant par `touch` (`config.ts:844`)                         |
 | Absolute timeout              | NIST SP 800-63B-4 / OWASP | défaut 43200 s, jamais prolongé (`config.ts:808`)                             |
 | Identifiant de session        | OWASP Session Management  | 32 octets CSPRNG, opaque (`session.ts:226`)                                   |
 | Identifiant hors URL          | OWASP Session Management  | cookie uniquement — jamais de réécriture d'URL (`session.ts:20-26`)           |
-| Renouvellement après auth     | OWASP (anti-fixation)     | `regenerateId()` inconditionnel au login (`authFlow.ts:388`)                  |
+| Renouvellement après auth     | OWASP (anti-fixation)     | `regenerateId()` inconditionnel au login (`authFlow.ts:528`)                  |
 | Révocation côté serveur       | OWASP                     | pierre tombale générique (`RevocationGuardStorage.ts:121`)                    |
 
 ## ⚡ Performance & mémoire
@@ -656,9 +656,9 @@ Trois règles de conception se dégagent du contrat, et méritent d'être respec
 Le coût d'une session est **payé seulement quand elle sert** :
 
 - **Zéro par défaut** — sans intent ni cookie, `startSession()` sort immédiatement
-  (`http-kernel.ts:1246`) : ni objet `Session`, ni lecture de store.
+  (`http-kernel.ts:1330`) : ni objet `Session`, ni lecture de store.
 - **Objet léger** — trois sacs `{}` à plat, pas de container DI par session (`session.ts:100-104`).
-- **Zéro écriture en lecture** — le dirty-tracking court-circuite `save()` (`session.ts:255`) ; le
+- **Zéro écriture en lecture** — le dirty-tracking court-circuite `save()` (`session.ts:278`) ; le
   `touch` est throttlé à une écriture par demi-vie d'idle (`session.ts:445`).
 - **GC hors requête** — timer déterministe avec jitter par process, à la place du tirage
   probabiliste hérité de PHP (`sessions-service.ts:306-312`).
@@ -676,7 +676,7 @@ plus un plafond de croissance du tas.
 > [!NOTE]
 > Les trois sacs sont des objets **littéraux** et non `Object.create(null)`. C'est délibéré :
 > `drizzle-orm` déréférence le prototype via `is()`, et un objet sans prototype ferait échouer
-> l'écriture (`session.ts:95-98`).
+> l'écriture (`session.ts:113-116`).
 
 ## 📡 Observabilité — Studio
 
@@ -719,9 +719,9 @@ SQLite quand c'est pertinent (`SessionStorage.location`,
 
 | Symptôme                                               | Cause                                                                     | Correction                                                                                                |
 | ------------------------------------------------------ | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
-| Aucun `Set-Cookie`, `session` toujours vide            | La route n'a **aucun intent** : ni `@UseSession`, ni paramètre `@Session` | Ajouter l'un des deux — l'activation est paresseuse (`http-kernel.ts:1283`)                               |
+| Aucun `Set-Cookie`, `session` toujours vide            | La route n'a **aucun intent** : ni `@UseSession`, ni paramètre `@Session` | Ajouter l'un des deux — l'activation est paresseuse (`http-kernel.ts:1314`)                               |
 | `context.session` est `null` dans un contrôleur WS     | Intent posé sur la classe au lieu de la route, ou absent                  | `@UseSession()` **sur la route** WebSocket ; `Controller.startSession()` n'existe plus                    |
-| Mutation ignorée, WARNING « READONLY SESSION mutated » | La route est en `@UseSession({ readOnly: true })`                         | Retirer `readOnly` sur les routes qui écrivent (`session.ts:255-264`)                                     |
+| Mutation ignorée, WARNING « READONLY SESSION mutated » | La route est en `@UseSession({ readOnly: true })`                         | Retirer `readOnly` sur les routes qui écrivent (`session.ts:273-282`)                                     |
 | Session détruite qui « revient » après logout          | Une requête en vol réécrit le blob supprimé                               | Déjà couvert : pierre tombale 5 min (`RevocationGuardStorage.ts:121`)                                     |
 | Sessions perdues à chaque redémarrage ou entre pods    | Store `memory` (volatil, per-pod)                                         | Déclarer une infra (`NF_DATABASE_URL`/`NF_REDIS_URL`) ou nommer le store                                  |
 | Le boot s'arrête sur « session store … inconnu »       | Nom de store explicite non enregistré, en production                      | Charger le module fournisseur, ou corriger le nom (`sessions-service.ts:258-262`)                         |
@@ -753,7 +753,7 @@ depuis vitest, jamais figés ici.
 > [!CAUTION]
 > Les suites E2E se **skippent** sans leurs variables d'infra, et un skip compte comme vert. Avant de
 > conclure « tout passe » sur les dialectes PostgreSQL/MySQL, vérifier que `NF_PG_URL`/`NF_MYSQL_URL`
-> étaient bien posées (source unique : `vitest.gates.ts` à la racine).
+> étaient bien posées (source unique : `scripts/test/vitest/gates.ts` à la racine).
 
 Skills utiles : `nodefony-load-test` (rejouer ou étendre la charge), `nodefony-check-memory-health`
 (gate mémoire), `nodefony-security-review` (fixation, timeouts, révocation).

package/docs/sse.md

@@ -0,0 +1,283 @@
+---
+title: "Flux d'événements serveur (SSE) — pousser au navigateur sur une réponse qui ne finit pas"
+navTitle: Flux SSE
+lang: fr
+module: "@nodefony/http"
+topic: sse
+section: "Cœur runtime"
+audience: [developer]
+tags:
+  [
+    sse,
+    server-sent-events,
+    event-stream,
+    eventsource,
+    streaming,
+    http2,
+    temps-réel,
+    mcp,
+    last-event-id,
+  ]
+version: "doc"
+status: stable
+updated: 2026-10-08
+source: "src/packages/@nodefony/http/docs/sse.md"
+coverageModule: http
+coverageFiles: context/http/SseStream.ts
+---
+
+📍 [Documentation](../../../../../docs/index.md) › [@nodefony/http](index.md) › **Flux SSE**
+
+# Flux d'événements serveur (SSE) — pousser au navigateur sur une réponse qui ne finit pas
+
+> Une **radio** plutôt qu'un **téléphone** : le serveur parle, le navigateur écoute, et la
+> conversation ne va que dans un sens. Une action ouvre une réponse HTTP qu'elle ne referme pas, et y
+> écrit des événements au fil de l'eau — la progression d'une tâche, la réponse d'un modèle de
+> langage qui s'écrit mot à mot, une notification. Le même code sert HTTP/1.1 et HTTP/2. Chaque fait
+> ci-dessous est ancré sur le code.
+
+## 🧠 Le modèle mental — un FORMAT de réponse, pas une méthode
+
+SSE n'est pas une route d'un genre particulier : c'est ce que l'action **décide de répondre**. La
+route reste un `GET` ou un `POST` ordinaire ; à l'exécution, l'action appelle `this.renderSse()` au
+lieu de rendre un objet, et la réponse devient un flux `text/event-stream`. Un même `POST` peut donc
+répondre en JSON à un client classique et en flux à un client qui le demande par `Accept` — c'est
+ce que fait une porte MCP.
+
+## 📖 Lexique
+
+- **SSE** — _Server-Sent Events_ : le format `text/event-stream` normalisé par le standard HTML
+  (WHATWG §9.2). Il n'a pas de RFC.
+- **Événement** — un bloc de lignes `event:`, `id:`, `data:` clos par une ligne vide.
+- **`Last-Event-ID`** — l'en-tête qu'un client renvoie en se reconnectant, pour reprendre après le
+  dernier identifiant reçu.
+- **Battement de cœur** — un commentaire (`:`) envoyé à intervalle régulier : ignoré par le client,
+  il empêche un proxy de couper une connexion qu'il croirait muette.
+
+## Qu'est-ce qu'un flux SSE, et quand le préférer au WebSocket ?
+
+| Besoin                                                        | Choisir                                    |
+| ------------------------------------------------------------- | ------------------------------------------ |
+| Le serveur pousse, le client écoute (progression, journal)    | **SSE**                                    |
+| La réponse d'une requête arrive par morceaux (modèle, export) | **SSE** sur le `POST` de la requête        |
+| Un réseau d'entreprise bloque WebSocket                       | **SSE** — c'est une réponse HTTP ordinaire |
+| Échange dans les deux sens, canaux, temps réel partagé        | **WebSocket** (`NodefonySocket`)           |
+
+> [!NOTE]
+> En HTTP/1.1, un navigateur n'ouvre qu'environ six connexions par origine : six onglets chacun
+> abonné à un flux, et les requêtes suivantes attendent leur tour (WHATWG §9.2.7). En HTTP/2, un
+> flux SSE n'est qu'un flux du multiplexage de la connexion.
+>
+> Ce plafond vaut pour l'origine que **voit le navigateur**. Derrière nginx, HAProxy ou un
+> ingress qui termine le TLS, cette origine est le proxy : c'est **lui** qui doit servir HTTP/2,
+> et `proxy:generate` le pose déjà (`http2 on`, `generateProxyConfig.ts:270`). Nodefony reçoit
+> alors du HTTP/1.1 (`proxy_http_version 1.1`, `generateProxyConfig.ts:351`) — y activer HTTP/2
+> n'y change rien. Sans proxy, c'est Nodefony qui sert HTTP/2.
+>
+> De chaque côté du proxy, un flux est une connexion qui se tait entre deux événements. Le
+> battement (`SSE_HEARTBEAT_MS`, 15 s, `SseStream.ts:77`) la garde vivante ; le délai
+> d'inactivité généré (300 s au moins) en tient vingt. Le seul piège réel : une action qui éteint
+> le battement (`heartbeat: false`) et se tait plus longtemps que ce délai se fait couper par le
+> proxy. Le guide [reverse-proxy](../../../../../docs/guides/reverse-proxy.md) détaille le reste.
+
+## 🚀 Démarrage rapide
+
+Dans une application générée par `nodefony create app`, une action pousse trois étapes puis ferme.
+
+### 1. L'action
+
+```ts
+// modules/app/nodefony/controller/ProgressController.ts
+import { Controller, controller, route } from "@nodefony/framework";
+import type { Context } from "@nodefony/http";
+
+@controller("/progress")
+class ProgressController extends Controller {
+  constructor(context: Context) {
+    super("ProgressController", context);
+  }
+
+  @route("progress-run", { path: "/run" })
+  async run() {
+    const sse = await this.renderSse();
+    for (const step of ["lecture", "calcul", "écriture"]) {
+      await sse.send({ step }, { event: "step" });
+    }
+    return sse.close();
+  }
+}
+
+export default ProgressController;
+```
+
+### 2. Le client
+
+```ts
+// frontend — la classe se lit comme EventSource
+import { NodefonySse } from "nodefony/client";
+
+const sse = new NodefonySse("/progress/run");
+sse.addEventListener("step", (e) => {
+  console.log(JSON.parse((e as MessageEvent<string>).data));
+});
+sse.addEventListener("error", () => sse.close()); // fin du flux : ne pas reconnecter
+```
+
+### 3. Observer
+
+```bash
+curl -sN -H 'Accept: text/event-stream' http://127.0.0.1:5151/progress/run
+```
+
+```text
+event: step
+data: {"step":"lecture"}
+
+event: step
+data: {"step":"calcul"}
+
+event: step
+data: {"step":"écriture"}
+```
+
+- Les en-têtes partent dès `renderSse()` : `Content-Type: text/event-stream; charset=utf-8`,
+  `Cache-Control: no-cache, no-transform`, `X-Accel-Buffering: no` (`openSseStream()`,
+  `SseStream.ts:427`).
+- `await sse.send()` freine l'action si le client lit lentement — c'est la contre-pression.
+
+## ⚙️ Les deux bouts de l'API
+
+### Côté serveur — `this.renderSse()` et l'objet `SseStream`
+
+| Membre                          | Rôle                                                                                               |
+| ------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `this.renderSse(options?)`      | ouvre le flux (`Controller.renderSse()`, `Controller.ts:665`) ; lève sur WebSocket                 |
+| `this.acceptsSse()`             | le client a-t-il demandé `text/event-stream` ? (`Controller.acceptsSse()`, `Controller.ts:649`)    |
+| `sse.send(data, { event, id })` | un événement ; texte tel quel, objet en JSON (`SseStream.send()`, `SseStream.ts:260`)              |
+| `sse.comment(text)`             | un commentaire, ignoré par le client                                                               |
+| `sse.retry(ms)`                 | impose le délai de reconnexion du client                                                           |
+| `sse.onClose(fn)`               | appelé à la fermeture, quel que soit le bout qui ferme (`SseStream.onClose()`, `SseStream.ts:306`) |
+| `sse.close()`                   | termine la requête, idempotent (`SseStream.close()`, `SseStream.ts:321`)                           |
+| `sse.closed`                    | le flux est-il fermé — à tester dans une boucle longue                                             |
+
+Options de `renderSse()` :
+
+| Option          | Rôle                                                                                  | Défaut                            |
+| --------------- | ------------------------------------------------------------------------------------- | --------------------------------- |
+| `heartbeat`     | période du battement (commentaire `:`), ms ; `false` l'éteint                         | 15 000 (`SSE_HEARTBEAT_MS`)       |
+| `retry`         | délai `retry:` envoyé à l'ouverture                                                   | aucun                             |
+| `stallTimeout`  | délai maximal d'une écriture bloquée (le client ne lit plus) avant coupure ; `false`  | 30 000 (`SSE_STALL_TIMEOUT_MS`)   |
+| `maxEventBytes` | taille maximale d'un événement, octets UTF-8 ; au-delà `send()` lève une `RangeError` | 1 048 576 (`SSE_MAX_EVENT_BYTES`) |
+| `maxDuration`   | durée de vie du flux, ms ; il est fermé ensuite et `EventSource` se reconnecte        | `false` — pas de borne            |
+
+Un délai hors de 1 à 2^31-1 ms est refusé à l'ouverture (`RangeError`) : au-delà, Node ramène un
+minuteur à 1 ms.
+
+### Même route, deux réponses — la négociation
+
+```ts
+@route("tasks-run", { path: "/tasks", requirements: { methods: ["POST"] } })
+async runTask() {
+  if (!this.acceptsSse()) return { status: "accepted" }; // JSON
+  const sse = await this.renderSse();
+  await sse.send({ status: "running" });
+  return sse.close();
+}
+```
+
+`acceptsEventStream()` (`SseStream.ts:395`) ne retient `text/event-stream` que **nommé** avec un
+poids non nul : `*/*` ne suffit pas — un client qui ne nomme pas le flux ne sait pas le lire —, et
+`q=0` est un refus (RFC 9110 §12.4.2).
+
+### Côté client — `NodefonySse`
+
+`NodefonySse` (`NodefonySse.ts:110`) reprend le vocabulaire d'`EventSource` — `onopen`,
+`onmessage`, `onerror`, `addEventListener(type)`, `readyState`, `lastEventId`, `close()`,
+reconnexion avec `Last-Event-ID` — et ajoute ce que le natif refuse : `method`, `headers` (un
+`Authorization: Bearer`), `body`. Il est bâti sur `fetch`, donc tourne aussi sous Node, où
+`EventSource` reste expérimental.
+
+| Réponse du serveur                          | Ce que fait le client                                                               |
+| ------------------------------------------- | ----------------------------------------------------------------------------------- |
+| 200 `text/event-stream`                     | `OPEN`, événements                                                                  |
+| fin du flux, coupure réseau                 | `error`, puis reconnexion après le délai `retry:`, plus une gigue jusqu'à sa moitié |
+| aucune réponse dans `connectTimeout` (10 s) | `error`, puis reconnexion — jamais figé en `CONNECTING`                             |
+| autre statut (204 compris), autre type      | `error`, `CLOSED`, **sans** reconnexion (WHATWG §9.2.3)                             |
+| événement au-delà de `maxEventSize` (4 Mi)  | `CLOSED` sans reconnexion                                                           |
+
+L'analyseur du format est `SseParser` (`SseParser.ts:61`), exporté par `nodefony/client` : c'est
+le même qui relit le flux dans les tests du serveur.
+
+## 🏗️ Architecture interne — ce que fait l'ouverture
+
+1. **La réponse est prise** (`context.sended`) : plus rien ne peut répondre à la place du flux.
+2. **La session est sauvée** s'il y en a une — ses cookies partent avec les en-têtes.
+3. **Le transport se constate** : flux HTTP/2, ou réponse HTTP/1.1 ; ni l'un ni l'autre → 500,
+   avant d'avoir rien écrit (`startSseStream()`, `SseStream.ts:485`).
+4. **Les en-têtes partent** — `respond()` en HTTP/2, `flushHeaders()` en HTTP/1.1 — et le délai
+   d'inactivité de la requête est **désarmé** : sans cela, le flux vivant prendrait un 408 au bout
+   de 30 s.
+5. **Le battement démarre** sur un minuteur `unref()`.
+
+La fin, quel que soit le bout qui ferme, passe par **un seul** nettoyage (`SseStream.ts:254`) :
+minuteur arrêté, écouteurs `close` et `drain` retirés, attente de `drain` libérée, puis les
+écouteurs `onClose`.
+
+## 🔐 Sécurité
+
+- **Injection de flux** : `event` et `id` sont refusés s'ils contiennent CR, LF ou NUL
+  (`singleLine()`, `SseStream.ts:105`) — une valeur venue d'un utilisateur ne peut pas clore
+  l'événement pour en forger un autre. Les `data` sur plusieurs lignes sont découpés en autant de
+  champs, jamais recopiés tels quels.
+- **Client** : un serveur qui n'envoie jamais de fin de ligne ferait grossir la mémoire du client
+  sans limite — `maxEventSize` (4 Mi par défaut) ferme la connexion.
+- Le flux passe par le pipeline complet : pare-feu, CSRF et `@IsGranted` s'appliquent avant
+  l'action, comme pour toute route.
+- **Les mêmes gardes qu'une socket WebSocket** — un attaquant prend le transport le plus faible :
+  - **plafond de connexions par IP** : `wsMaxConnectionsPerIp` compte les sockets WebSocket ET les
+    flux SSE, **un seul budget** (sinon N sockets plus N flux doubleraient le plafond). Au-delà, le
+    flux répond **429** avant d'écrire un octet de flux. Désactivé par défaut, comme pour le
+    WebSocket : en cloud, le plafond vit à l'ingress.
+  - **révocation** : un flux ouvert par une identité authentifiée est re-validé toutes les 30 s
+    (`REVOCATION_REVALIDATE_MS`) par la même règle que les sockets — session détruite ou passée à un
+    autre compte, jeton expiré ou annulé — et fermé si elle est morte. Une identité vivante ne
+    perd jamais son flux ; un anonyme n'est jamais re-validé.
+  - **lecteur bloqué** : le délai d'inactivité étant désarmé, `stallTimeout` le remplace — une
+    écriture qui attend un `drain` plus de 30 s coupe la connexion. Un client inactif mais qui lit
+    n'est jamais concerné : le minuteur ne s'arme que sous contre-pression.
+  - **taille d'un événement** : `maxEventBytes` refuse un événement démesuré avant de le mettre en
+    mémoire d'écriture ; le flux reste ouvert.
+
+## ⚠️ Pièges (symptôme → cause → correction)
+
+| Symptôme                                          | Cause                                                                                         | Correction                                                                    |
+| ------------------------------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| Le flux n'apparaît qu'en entier, à la fin         | un proxy (nginx) le met en tampon                                                             | `X-Accel-Buffering: no` est posé ; vérifier un `proxy_buffering on` explicite |
+| Le serveur ne voit jamais le client partir        | fermeture écoutée sur la REQUÊTE : en HTTP/1.1 elle a déjà émis `close` (corps lu, Node ≥ 16) | `sse.onClose()` — la fermeture est lue sur la RÉPONSE                         |
+| `error` en boucle côté client après la fin voulue | une fin de flux est une coupure pour `EventSource` : il reconnecte                            | `close()` dans `onerror`, ou répondre 204 pour dire « fini »                  |
+| Six onglets, et le site ne répond plus            | plafond de connexions HTTP/1.1 du navigateur envers l'origine qu'il voit                      | faire servir HTTP/2 par le proxy — ou par Nodefony s'il n'y a pas de proxy    |
+| Un flux muet coupé au bout de quelques minutes    | `heartbeat: false`, et un silence plus long que le délai d'inactivité du proxy                | garder le battement, ou allonger ce délai sur le proxy                        |
+| Le flux répond 429 sans avoir rien fait           | `wsMaxConnectionsPerIp` atteint — sockets WebSocket et flux SSE de l'IP comptent ensemble     | relever le plafond, ou fermer les connexions laissées ouvertes                |
+| `RangeError` à `send()`, le flux continue         | événement plus gros que `maxEventBytes`                                                       | découper la donnée, ou relever `maxEventBytes` pour ce flux                   |
+
+## 🧪 Tests & couverture
+
+| Type                 | Où                                                                                                                                                                                                                                |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Unitaires — format   | `src/nodefony/src/tests/SseParser.test.ts` — une règle de WHATWG §9.2.5-9.2.6 par cas, borne de taille                                                                                                                            |
+| Unitaires — client   | `src/nodefony/src/tests/NodefonySse.test.ts` — serveur `node:http` réel : ordre, `POST` + `Authorization`, reconnexion `Last-Event-ID`, 204, mauvais type, flux sans fin                                                          |
+| Unitaires — `Accept` | `unit/acceptsEventStream.test.ts`                                                                                                                                                                                                 |
+| Intégration          | `http/sse.test.ts` — serveur de développement, HTTP/1.1 ET HTTP/2 : événements dans l'ordre, en-têtes, départ du client vu (et pas avant) en `GET` et en `POST` avec corps, battement, négociation, `NodefonySse` de bout en bout |
+| Mémoire              | `http/memory.test.ts` — flux fermés par le serveur et flux abandonnés par le client : pente du tas, scopes et contextes résiduels                                                                                                 |
+
+Ces suites ont été vues échouer en débranchant le câblage : fin de ligne coupée entre deux morceaux,
+`id` contenant NUL, `Last-Event-ID` retiré, 204 reconnecté, borne de taille ignorée, poids `q=0`
+accepté, et fermeture écoutée sur la requête.
+
+Ce qui **manque** : aucun banc de débit (événements par seconde) ; la contre-pression n'est pas
+éprouvée sur un client réellement lent ; un flux en HTTP/3 n'existe pas (Node ne sert pas HTTP/3).
+
+## 🔗 Pour aller plus loin
+
+- ⬆️ **Retour au hub** : [@nodefony/http — vue du module](index.md) · [Toute la documentation](../../../../../docs/index.md)
+- 🧭 **Pages sœurs** : [Serveurs](servers.md) — HTTP/2, TLS, délais ; [Proxy inverse](reverse-proxy.md).