@nodefony/realtime 10.0.0-alpha.8 → 10.0.0-beta.1

package/docs/protocole.md

@@ -106,7 +106,7 @@ Nodefony ne l'a pas inventée. Le calcul, mis à plat :
 
 > [!NOTE]
 > **Le batch est une propriété de la norme, pas du moteur Nodefony.** `JsonRpcPeer.receive()`
-> (`JsonRpcPeer.ts:371`) attend un **objet** portant `jsonrpc: "2.0"` ; un tableau de frames n'en
+> (`JsonRpcPeer.ts:390`) attend un **objet** portant `jsonrpc: "2.0"` ; un tableau de frames n'en
 > porte pas et tombe donc en `invalid`. Une frame = un objet. Le multiplexage rend le batch peu
 > utile ici : les canaux voyagent déjà dans la même connexion.
 
@@ -126,7 +126,7 @@ divergeaient ; c'est précisément la classe de bug que l'isomorphisme supprime.
 
 **Le rôle se lit sur `method`, pas sur `id`.** La lecture naïve (« `id` présent = requête ») casse
 sur les réponses, qui portent un `id` sans être des appels. `JsonRpcPeer.receive()`
-(`JsonRpcPeer.ts:371`) teste donc `method` d'abord, puis la présence d'un `id`. Une frame `id` seul
+(`JsonRpcPeer.ts:390`) teste donc `method` d'abord, puis la présence d'un `id`. Une frame `id` seul
 est une **réponse** et ne déclenche jamais `-32601` à tort.
 
 **Un échec ne raconte rien par défaut.** Un handler qui lève une exception ordinaire produit un
@@ -246,7 +246,7 @@ Sur le fil, dans l'inspecteur réseau du navigateur, exactement cinq frames :
 ```jsonc
 // 1. serveur → client : l'accueil, aussitôt après le handshake
 {"jsonrpc":"2.0","method":"realtime:welcome","params":{
-  "ts":1770000000000,"protocol":"jsonrpc-2.0",
+  "ts":1770000000000,"protocol":"jsonrpc-2.0","env":"development",
   "channels":["chat:room-42"],"methods":["chat:history"],
   "identity":{"type":"anonymous","authenticated":false,
               "userIdentifier":"anonymous","roles":["ROLE_ANONYMOUS"],"scopes":[]}}}
@@ -264,9 +264,11 @@ Sur le fil, dans l'inspecteur réseau du navigateur, exactement cinq frames :
 {"jsonrpc":"2.0","method":"chat:room-42","params":{"text":"salut"}}
 ```
 
-L'accueil porte **cinq** champs : `ts`, `protocol`, `channels`, `methods`, `identity`
-(`IRealtimeWelcome`, `RealtimeEventMap.ts:204`), émis par le contrôleur au handshake
-(`RealtimeController.ts:8`). Il n'y a pas de champ `version`.
+L'accueil porte cinq champs — `ts`, `protocol`, `channels`, `methods`, `identity`
+(`IRealtimeWelcome`, `RealtimeEventMap.ts:231`) — plus un sixième, `env`, **uniquement hors
+production** (`welcomeEnv()`, `welcomeEnv.ts:19`) : c'est lui que porte l'exemple ci-dessus, capturé
+en développement. Émis par le contrôleur au handshake (`peer.notify("realtime:welcome")`,
+`RealtimeController.ts:708`). Il n'y a pas de champ `version`.
 
 ## 🔌 Anatomie d'une frame, champ par champ
 
@@ -335,19 +337,19 @@ ouvertes à l'application. Colonne `id` : présent = requête (réponse due), ab
 
 | Méthode            | Direction     | `id` ?  | Rôle                                                                  | Ancrage                     |
 | ------------------ | ------------- | :-----: | --------------------------------------------------------------------- | --------------------------- |
-| `subscribe`        | client→server |   non   | « pousse-moi ce canal » — `params.channel`                            | `RealtimeController.ts:459` |
-| `unsubscribe`      | client→server |   non   | « arrête » — dernier abonné, le producteur est libéré                 | `RealtimeController.ts:687` |
-| `ping`             | client→server |   non   | Battement de cœur — **no-op serveur**, aucun pong                     | `RealtimeClient.ts:740`     |
-| `<canal>`          | server→client |   non   | Push d'un message : le **nom du canal est la `method`**               | `RealtimeController.ts:612` |
-| `<canal entrant>`  | client→server |   non   | Le client pousse sur un canal déclaré entrant                         | `RealtimeController.ts:694` |
-| `realtime:welcome` | server→client |   non   | L'accueil : 5 champs, dont l'identité résolue                         | `RealtimeController.ts:579` |
-| `realtime:denied`  | server→client |   non   | Rend OBSERVABLE le refus d'une notification                           | `RealtimeController.ts:433` |
-| `api.request`      | client→server | **oui** | Pont API — rejoue une route HTTP sur la socket (désactivé par défaut) | `RealtimeController.ts:498` |
+| `subscribe`        | client→server |   non   | « pousse-moi ce canal » — `params.channel`                            | `RealtimeController.ts:522` |
+| `unsubscribe`      | client→server |   non   | « arrête » — dernier abonné, le producteur est libéré                 | `RealtimeController.ts:775` |
+| `ping`             | client→server |   non   | Battement de cœur — **no-op serveur**, aucun pong                     | `RealtimeClient.ts:882`     |
+| `<canal>`          | server→client |   non   | Push d'un message : le **nom du canal est la `method`**               | `RealtimeController.ts:972` |
+| `<canal entrant>`  | client→server |   non   | Le client pousse sur un canal déclaré entrant                         | `RealtimeController.ts:736` |
+| `realtime:welcome` | server→client |   non   | L'accueil : 5 champs, dont l'identité résolue                         | `RealtimeController.ts:693` |
+| `realtime:denied`  | server→client |   non   | Rend OBSERVABLE le refus d'une notification                           | `RealtimeController.ts:496` |
+| `api.request`      | client→server | **oui** | Pont API — rejoue une route HTTP sur la socket (désactivé par défaut) | `RealtimeController.ts:582` |
 | `<action>`         | client→server | **oui** | Toute action déclarée par `@RealtimeAction`                           | `realtimeDecorators.ts:101` |
 
 > [!TIP]
 > **L'accueil est ta carte du territoire.** `methods` et `channels` sont construits à partir de ce
-> que l'endpoint expose réellement (`RealtimeController.ts:641`) : un client peut activer ou griser
+> que l'endpoint expose réellement (`RealtimeController.ts:710`) : un client peut activer ou griser
 > ses commandes sans rien coder en dur. Côté navigateur, ils se lisent en `socket.serverMethods` et
 > `socket.serverChannels`.
 
@@ -357,12 +359,12 @@ Les quatre formes de frame circulent en permanence sous tes yeux — ce schéma
 > `nodefony:kernel:ping` et `nodefony:kernel:gc` (`StudioRealtimeController.ts:114`) sont des exemples d'actions,
 > **pas des méthodes du cœur temps réel** : elles sont déclarées par le contrôleur
 > d'administration de `@nodefony/studio`. Un endpoint applicatif ne les expose pas. Le helper
-> `RealtimeClient.ping()` (`RealtimeClient.ts:740`) mesure le RTT en les appelant — il suppose donc
+> `RealtimeClient.ping()` (`RealtimeClient.ts:878`) mesure le RTT en les appelant — il suppose donc
 > un endpoint qui les déclare, contrairement à la notification `ping` du battement de cœur, qui
 > n'attend jamais de réponse.
 
 `subscribe` et `unsubscribe` ne sont **pas** des actions enregistrées : elles sont traitées dans
-`onRealtimeNotification()` (`RealtimeController.ts:675`). Envoyées avec un `id`, elles seraient
+`onRealtimeNotification()` (`RealtimeController.ts:784`). Envoyées avec un `id`, elles seraient
 classées « requête », ne trouveraient aucun handler et récolteraient un `-32601`.
 
 ## Une conversation type, de bout en bout
@@ -396,11 +398,11 @@ de `RpcError`.
 
 | Code     | Émis par                                                   | Déclencheur                                         | Ce que voit le pair                            |
 | -------- | ---------------------------------------------------------- | --------------------------------------------------- | ---------------------------------------------- |
-| `-32601` | `JsonRpcPeer.handleRequest()` (`JsonRpcPeer.ts:489`)       | requête vers une action non enregistrée             | `method not found: <nom>`                      |
+| `-32601` | `JsonRpcPeer.handleRequest()` (`JsonRpcPeer.ts:499`)       | requête vers une action non enregistrée             | `method not found: <nom>`                      |
 | `-32603` | même méthode (`JsonRpcPeer.ts:528`)                        | le handler a levé une exception **ordinaire**       | `internal error` — générique, rien d'autre     |
 | `-32001` | le refus du verrou de frame (`JsonRpcPeer.ts:400`)         | `beforeDispatch` a dit non **sur une requête**      | `unauthorized`, sans jamais dire pourquoi      |
 | `-32000` | défaut du constructeur de `RpcError` (`JsonRpcPeer.ts:74`) | le handler expose volontairement son refus          | le message ET le `data` choisis par le handler |
-| `-32602` | le pont API, via `RpcError` (`RealtimeController.ts:678`)  | `api.request` appelé avec un `params.path` invalide | message explicite (l'appel est malformé)       |
+| `-32602` | le pont API, via `RpcError` (`RealtimeController.ts:787`)  | `api.request` appelé avec un `params.path` invalide | message explicite (l'appel est malformé)       |
 
 Et un échec qui n'est **pas** une frame : l'expiration. `startCall()` ne reçoit rien dans le délai
 imparti, supprime l'entrée en attente et rejette localement avec `RPC timeout: <méthode>`
@@ -419,7 +421,7 @@ porte** ici :
 
 Le choix est délibéré : une frame cassée n'a pas d'`id` digne de confiance, donc pas de corrélation
 possible ; et répondre systématiquement à du bruit offre à un attaquant un amplificateur gratuit.
-Le refus reste **traçable** — c'est le motif `invalid` de `FrameAuditReason` (`JsonRpcPeer.ts:143`),
+Le refus reste **traçable** — c'est le motif `invalid` de `FrameAuditReason` (`JsonRpcPeer.ts:155`),
 qui alimente le journal d'audit avec le pair concerné.
 
 ### Le refus d'une notification n'est pas une erreur
@@ -431,12 +433,12 @@ radicalement :
 | La frame refusée est… | Ce qui part                                                     | Pourquoi                                             |
 | --------------------- | --------------------------------------------------------------- | ---------------------------------------------------- |
 | une **requête**       | `-32001 "unauthorized"` (`JsonRpcPeer.ts:413`)                  | Un `id` existe : il y a un canal de réponse          |
-| une **notification**  | la notification `realtime:denied` (`RealtimeController.ts:433`) | Aucun `id` : sans elle, le client se croirait abonné |
+| une **notification**  | la notification `realtime:denied` (`RealtimeController.ts:496`) | Aucun `id` : sans elle, le client se croirait abonné |
 
-`IRealtimeDenied` (`RealtimeEventMap.ts:228`) porte deux champs, `channel` et `reason` — et le motif
+`IRealtimeDenied` (`RealtimeEventMap.ts:269`) porte `channel` et `reason` — plus un `detail` optionnel, posé hors production seulement — et le motif
 est **générique**. Jamais « il te manque `ROLE_ADMIN` » : ce serait un oracle d'autorisation, un
 attaquant y lirait la carte des droits. Deux motifs circulent : `forbidden` (le verrou a dit non) et
-`limit` (le plafond de canaux de la connexion est atteint, `RealtimeController.ts:718`). Côté client,
+`limit` (le plafond de canaux de la connexion est atteint, `RealtimeController.ts:811`). Côté client,
 `onDenied()` (`RealtimeClient.ts:469`) branche un handler dessus.
 
 > [!CAUTION]
@@ -467,14 +469,14 @@ décrits dans [la page sécurité](./securite.md).
 | Symptôme                                                         | Cause                                                                                                           | Correction                                                                        |
 | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
 | `subscribe` répond `-32601 method not found`                     | Envoyé **avec un `id`** : classé requête, or c'est une notification (`RealtimeController.ts:592`)               | L'émettre sans `id` — `socket.subscribe(canal)`                                   |
-| Le handler passé à `subscribe` n'est jamais appelé               | `RealtimeClient.subscribe()` prend **un seul** argument (`RealtimeClient.ts:430`)                               | `subscribe(canal)` **et** `on(canal, handler)`, deux gestes distincts             |
+| Le handler passé à `subscribe` n'est jamais appelé               | `RealtimeClient.subscribe()` prend **un seul** argument (`RealtimeClient.ts:532`)                               | `subscribe(canal)` **et** `on(canal, handler)`, deux gestes distincts             |
 | `request()` expire immédiatement, ou ignore le délai             | Signature **positionnelle** `(méthode, params, ms)` (`RealtimeClient.ts:727`) — un objet d'options n'est pas lu | `request(m, p, 5000)` ; le défaut est 30 000 ms                                   |
 | Un tableau de frames n'obtient aucune réponse                    | Le batch n'est pas implémenté : un tableau n'a pas de `jsonrpc` → `invalid` (`JsonRpcPeer.ts:371`)              | Une frame = un objet ; le multiplexage remplace le batch                          |
 | Une frame malformée ne renvoie **aucune** erreur                 | Ni `-32700` ni `-32600` ne sont émis — silence + audit (`JsonRpcPeer.ts:396`)                                   | Lire le motif `invalid` côté serveur, pas la réponse                              |
 | L'exception du serveur n'arrive jamais au client                 | Zero Trust : tout throw ordinaire devient `-32603` générique (`JsonRpcPeer.ts:528`)                             | Lever une `RpcError` pour exposer volontairement code et `data`                   |
-| Une notification refusée disparaît sans trace côté client        | Sans `id`, aucune réponse possible (`beforeDispatch`, `JsonRpcPeer.ts:151`)                                     | Écouter `realtime:denied` via `onDenied()` (`RealtimeClient.ts:386`)              |
+| Une notification refusée disparaît sans trace côté client        | Sans `id`, aucune réponse possible (`beforeDispatch`, `JsonRpcPeer.ts:151`)                                     | Écouter `realtime:denied` via `onDenied()` (`RealtimeClient.ts:471`)              |
 | `nodefony:kernel:ping` répond `-32601` sur mon endpoint          | L'action `nodefony:kernel:ping` est déclarée par `@nodefony/studio` (`StudioRealtimeController.ts:114`)         | Déclarer la sienne, ou lire `serverMethods` avant d'appeler                       |
-| Le battement de cœur ne renvoie aucun pong                       | La notification `ping` est un no-op serveur (`RealtimeController.ts:661`)                                       | Pour mesurer un RTT, utiliser une action RPC — `ping()` (`RealtimeClient.ts:740`) |
+| Le battement de cœur ne renvoie aucun pong                       | La notification `ping` est un no-op serveur (`RealtimeController.ts:791`)                                       | Pour mesurer un RTT, utiliser une action RPC — `ping()` (`RealtimeClient.ts:878`) |
 | Une réponse reçue est ignorée sans message                       | Corrélation sur `id` **numériques** seulement (`JsonRpcPeer.ts:537`)                                            | Ne pas fabriquer soi-même de réponse à `id` chaîne                                |
 | Les premières frames envoyées après `connect()` semblent perdues | Le transport n'est branché qu'une fois le handshake terminé                                                     | Attendre `realtime:welcome` — le client le fait déjà                              |
 

package/docs/securite.md

@@ -93,16 +93,16 @@ Les étapes 1 et 2 appartiennent à `@nodefony/http` et `@nodefony/security` : l
 Une WebSocket authentifiée est une cible de choix : elle porte une identité, vit longtemps et
 diffuse en continu.
 
-| Attaque                                                                                                | Ce qui la bloque                                                   | Où                                                           |
-| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ | ------------------------------------------------------------ |
-| **CSWSH** — `evil.com` fait `new WebSocket("wss://app.exemple.com/rt")`, le navigateur joint le cookie | Contrôle d'`Origin` same-origin par défaut, puis allowlist stricte | `@nodefony/http` transport, puis `csrf.checkOrigin` realtime |
-| **Écoute des flux internes** — un visiteur s'abonne à `nodefony:syslog` et lit les logs du pod         | Plancher des namespaces réservés (authentifié + `ROLE_ADMIN`)      | Verrou de frame `@nodefony/security`                         |
-| **Élévation par canal métier** — un `ROLE_USER` s'abonne au canal admin d'un autre module              | Policy déclarée sur le canal, évaluée avec la hiérarchie de rôles  | `@RealtimeChannel(name, { roles })` + verrou de frame        |
-| **Pont API plus permissif que REST** — `api.request {path}` pour contourner un 401 HTTP                | Re-match de la MÊME zone firewall que `GET {path}`                 | Verrou de frame, surface `api.request`                       |
-| **Socket zombie** — un admin se déconnecte, sa socket continue de diffuser                             | Re-validation périodique de l'identité, fermeture `4001`           | Tick de révocation du hub                                    |
-| **DoS mémoire par abonnements** — une connexion ouvre des milliers de canaux                           | Plafond de canaux par connexion (256 par défaut)                   | `limits.maxChannelsPerConnection`                            |
-| **DoS mémoire par lenteur** — un client ne lit pas, la file d'envoi enfle jusqu'à l'OOM                | Jet de frames à 1 MiB, fermeture `1013` à 8 MiB                    | Back-pressure du transport WS                                |
-| **Oracle d'autorisation** — sonder les canaux pour cartographier les droits                            | Motif de refus **générique** (`forbidden`), jamais le détail       | `realtime:denied`                                            |
+| Attaque                                                                                                | Ce qui la bloque                                                       | Où                                                           |
+| ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- | ------------------------------------------------------------ |
+| **CSWSH** — `evil.com` fait `new WebSocket("wss://app.exemple.com/rt")`, le navigateur joint le cookie | Contrôle d'`Origin` same-origin par défaut, puis allowlist stricte     | `@nodefony/http` transport, puis `csrf.checkOrigin` realtime |
+| **Écoute des flux internes** — un visiteur s'abonne à `nodefony:syslog` et lit les logs du pod         | Plancher des namespaces réservés (authentifié + `ROLE_NODEFONY_ADMIN`) | Verrou de frame `@nodefony/security`                         |
+| **Élévation par canal métier** — un `ROLE_USER` s'abonne au canal admin d'un autre module              | Policy déclarée sur le canal, évaluée avec la hiérarchie de rôles      | `@RealtimeChannel(name, { roles })` + verrou de frame        |
+| **Pont API plus permissif que REST** — `api.request {path}` pour contourner un 401 HTTP                | Re-match de la MÊME zone firewall que `GET {path}`                     | Verrou de frame, surface `api.request`                       |
+| **Socket zombie** — un admin se déconnecte, sa socket continue de diffuser                             | Re-validation périodique de l'identité, fermeture `4001`               | Tick de révocation du hub                                    |
+| **DoS mémoire par abonnements** — une connexion ouvre des milliers de canaux                           | Plafond de canaux par connexion (256 par défaut)                       | `limits.maxChannelsPerConnection`                            |
+| **DoS mémoire par lenteur** — un client ne lit pas, la file d'envoi enfle jusqu'à l'OOM                | Jet de frames à 1 MiB, fermeture `1013` à 8 MiB                        | Back-pressure du transport WS                                |
+| **Oracle d'autorisation** — sonder les canaux pour cartographier les droits                            | Motif de refus **générique** (`forbidden`), jamais le détail           | `realtime:denied`                                            |
 
 > [!IMPORTANT]
 > Les lignes 2 à 5 supposent `@nodefony/security` chargé **avec au moins une zone protégée**. Sans
@@ -118,7 +118,7 @@ politiques.**
   `security/nodefony/config/config.ts:109`). L'opt-out est explicite ; un opt-in aurait été
   _fail-open_ (une zone qui oublie le flag laisserait le WS anonyme).
 - Le verrou de frame consulte la **même** fonction de match que le HTTP, `Firewall.matchPath()`
-  (`firewall.ts:712`), et la **même** hiérarchie de rôles, `Firewall.hasRole()`
+  (`firewall.ts:719`), et la **même** hiérarchie de rôles, `Firewall.hasRole()`
   (`firewall.ts:482`). Invariant par construction : `api.request {path}` n'accorde jamais plus que
   `GET {path}`.
 - L'identité du handshake est celle du firewall HTTP : `FirewallRealtimeAuthenticator`
@@ -261,13 +261,13 @@ Nodefony pose **deux barrières successives**, à deux étages différents.
 | Allowlist stricte    | `@nodefony/realtime` | **inactif** (`enabled: false`)      | configurable  | `close 4003` |
 
 **Barrière 1 — transport, active sans rien faire.** `HttpKernel.checkWebsocketOrigin()`
-(`http-kernel.ts:599`) exige que l'`Origin` du handshake corresponde au `Host` servi, avec tolérance
+(`http-kernel.ts:621`) exige que l'`Origin` du handshake corresponde au `Host` servi, avec tolérance
 loopback en développement et une allowlist optionnelle (`allowedOrigins`,
 `http/nodefony/config/config.ts:552`) acceptant le hostname exact ou un wildcard à un label. Une
 requête **sans** `Origin` est acceptée : un attaquant non-navigateur n'a pas besoin de CSWSH.
 
 **Barrière 2 — module realtime, opt-in et plus stricte.** `RealtimeHub.checkOrigin()`
-(`RealtimeHub.ts:970`) consulte une garde compilée une fois au boot par `buildOriginGuard()`
+(`RealtimeHub.ts:986`) consulte une garde compilée une fois au boot par `buildOriginGuard()`
 (`RealtimeService.ts:313`) depuis `checkOriginSchema` (`realtime/nodefony/config/config.ts:162`).
 Trois différences comptent :
 
@@ -292,18 +292,18 @@ n'est jamais traitée.
 
 ### Le pipeline exact
 
-`RealtimeController.onHandshake()` (`RealtimeController.ts:328`) exécute, une fois par connexion :
+`RealtimeController.onHandshake()` (`RealtimeController.ts:374`) exécute, une fois par connexion :
 
 1. Construction d'un DTO neutre `IRealtimeHandshake` par `buildHandshakeFromContext()`
-   (`RealtimeController.ts:1113`) — headers, cookies aplatis, url, origin, sous-protocoles. Aucune
+   (`RealtimeController.ts:1198`) — headers, cookies aplatis, url, origin, sous-protocoles. Aucune
    dépendance à `@nodefony/security` dans le contrat.
 2. Contrôle d'origine (verrou 1).
-3. Résolution de l'authenticator par `RealtimeHub.resolveAuthenticator()` (`RealtimeHub.ts:945`) :
+3. Résolution de l'authenticator par `RealtimeHub.resolveAuthenticator()` (`RealtimeHub.ts:961`) :
    les matchers sont testés dans l'ordre d'enregistrement, **le premier qui matche capture**.
 4. `authenticator.authenticate(handshake)` — **async autorisé** (on est en cold path, une fois par
    connexion : lire un store est acceptable ici, jamais par frame).
 5. Pose du token sur la WeakMap `peer → token` via `RealtimeHub.setTokenForPeer()`
-   (`RealtimeHub.ts:936`), **avant** l'envoi du `welcome` : le lookup est garanti dès la première
+   (`RealtimeHub.ts:1018`), **avant** l'envoi du `welcome` : le lookup est garanti dès la première
    frame.
 
 Un `throw` de `authenticate()` ferme la socket en `4001` « unauthorized », après un log `WARNING`
@@ -312,8 +312,8 @@ d'audit défectueux ne peut pas empêcher la fermeture.
 
 ### Les matchers — quelle porte, quel vigile
 
-`RealtimeHub.useAuthenticator()` (`RealtimeHub.ts:927`) associe un sélecteur à une stratégie.
-`compileMatcher()` (`RealtimeHub.ts:1402`) le compile une fois :
+`RealtimeHub.useAuthenticator()` (`RealtimeHub.ts:943`) associe un sélecteur à une stratégie.
+`compileMatcher()` (`RealtimeHub.ts:1418`) le compile une fois :
 
 - `pattern` chaîne → RegExp **préfixe ancrée**, méta-caractères échappés par `RegExp.escape`.
   `"/admin/"` matche `/admin/` et `/admin/foo`, littéralement.
@@ -321,16 +321,16 @@ d'audit défectueux ne peut pas empêcher la fermeture.
 - `host` optionnel → comparaison **stricte** (insensible à la casse) sur l'en-tête `Host`, sans
   wildcard.
 - Le match porte sur le **path**, query comprise, jamais sur l'URL absolue : `handshakePath()`
-  (`RealtimeController.ts:1105`) extrait `pathname + search` du `WebsocketContext.url`, qui est
+  (`RealtimeController.ts:1250`) extrait `pathname + search` du `WebsocketContext.url`, qui est
   absolu. Sans cette extraction, un matcher `^/nodefony/…` ne se déclencherait jamais.
 
 `@nodefony/security` enregistre ces matchers automatiquement dans `Firewall.#wireRealtime()`
-(`firewall.ts:253`) : **une instance d'authenticator par zone protégée**, car le hub dédoublonne par
+(`firewall.ts:279`) : **une instance d'authenticator par zone protégée**, car le hub dédoublonne par
 identité d'instance et une instance partagée n'enregistrerait que le premier matcher.
 
 ### Zero Trust — il y a toujours un token
 
-`RealtimeHub.getTokenForPeer()` (`RealtimeHub.ts:1014`) ne renvoie **jamais** `null` : à défaut de
+`RealtimeHub.getTokenForPeer()` (`RealtimeHub.ts:1030`) ne renvoie **jamais** `null` : à défaut de
 token posé, c'est `ANONYMOUS_REALTIME_TOKEN` (`AnonymousRealtimeToken.ts:18`), singleton gelé,
 `isAuthenticated() === false`, `roles: ["ROLE_ANONYMOUS"]`. Le code consommateur (verrou, audit)
 n'a jamais à écrire « et s'il n'y a pas de token ? ».
@@ -439,9 +439,9 @@ mémoire : le token déjà résolu, et la cible de la frame.
 | action `@RealtimeAction` | Authentifié **par défaut** ; rôle/scope si déclarés ; ouverte seulement si `{ authenticated: false }` est écrit |
 | `ping`, `unsubscribe` | **passent** — pas de surface de données |
 
-Deux détails évitent des faux refus : `authorizeApiRequest()` (`frameAuthorizer.ts:316`) laisse
+Deux détails évitent des faux refus : `authorizeApiRequest()` (`frameAuthorizer.ts:330`) laisse
 passer une frame au `path` invalide (le handler renverra `-32602` — le verrou ne duplique pas la
-validation), et `authorizeChannel()` (`frameAuthorizer.ts:309`) laisse passer un `channel`
+validation), et `authorizeChannel()` (`frameAuthorizer.ts:359`) laisse passer un `channel`
 non-chaîne (`startChannel` ignore de toute façon un canal absent).
 
 ### Le plancher système — les namespaces réservés
@@ -449,12 +449,12 @@ non-chaîne (`startChannel` ignore de toute façon un canal absent).
 Certains namespaces exposent l'intérieur du pod. Ils portent une politique par défaut que la config
 peut **resserrer**, jamais desserrer.
 
-| Cible                                      | Politique par défaut                                          |
-| ------------------------------------------ | ------------------------------------------------------------- |
-| `nodefony:audit`                           | authentifié + `ROLE_NODEFONY_ADMIN` (`frameAuthorizer.ts:99`) |
-| tout le reste de `nodefony:`               | authentifié + `ROLE_ADMIN` (`frameAuthorizer.ts:70`)          |
-| tout canal contenant `:health` ou `:stats` | authentifié + `ROLE_ADMIN`                                    |
-| tout le reste                              | libre, sauf policy déclarée                                   |
+| Cible                                      | Politique par défaut                                           |
+| ------------------------------------------ | -------------------------------------------------------------- |
+| `nodefony:audit`                           | authentifié + `ROLE_NODEFONY_ADMIN` (`frameAuthorizer.ts:120`) |
+| tout le reste de `nodefony:`               | authentifié + `ROLE_NODEFONY_ADMIN` (`frameAuthorizer.ts:89`)  |
+| tout canal contenant `:health` ou `:stats` | authentifié + `ROLE_NODEFONY_ADMIN` (`frameAuthorizer.ts:253`) |
+| tout le reste                              | libre, sauf policy déclarée                                    |
 
 Le journal d'audit est un **canal précis**, pas un namespace : sa règle est posée devant celle du
 territoire (premier match gagnant), et elle n'existe que si le hub réserve bien ce territoire.
@@ -463,29 +463,29 @@ Trois durcissements méritent d'être connus :
 
 - **Match insensible à la casse, sans allocation** — `startsWithCI()` (`frameAuthorizer.ts:181`).
   Un `NODEFONY:syslog` ne contourne pas le plancher `nodefony:` par un changement de casse.
-- **Plancher irréductible** — `floorReserved()` (`frameAuthorizer.ts:255`) : une règle de config qui
+- **Plancher irréductible** — `floorReserved()` (`frameAuthorizer.ts:269`) : une règle de config qui
   tenterait d'ouvrir un namespace réservé (`{ authenticated: false }`) se voit ré-imposer
   `authenticated: true`. Le test porte sur le **namespace du canal**, pas sur le préfixe de la règle
   qui a matché : un préfixe de config plus court ou altéré ne contourne rien.
 - **La config passe avant les défauts** — les règles de `realtimeChannels`
-  (`security/nodefony/config/config.ts:1124`) sont placées en tête, premier match gagnant. On peut
+  (`security/nodefony/config/config.ts:1130`) sont placées en tête, premier match gagnant. On peut
   donc re-cibler `nodefony:syslog` sur `ROLE_SECURITY_AUDITOR` ; on ne peut pas l'ouvrir à l'anonyme.
 
 Le canal du journal d'audit (`nodefony:audit`) est enregistré comme **canal système** sur le hub
-(`RealtimeHub.registerSystemChannel()`, `RealtimeHub.ts:1281`) : il devient servable par n'importe
+(`RealtimeHub.registerSystemChannel()`, `RealtimeHub.ts:1297`) : il devient servable par n'importe
 quel endpoint realtime, sans qu'aucun controller ne le connaisse — et il est gardé par sa règle
 dédiée. Son enregistrement est **couplé** à la pose du verrou (même condition), donc il n'existe
 jamais de canal d'audit non gardé.
 
 ### La policy métier — déclarer sur le canal
 
-`@RealtimeChannel(name, policy)` (`realtimeDecorators.ts:142`) et `@RealtimeInbound(name, policy)`
-(`realtimeDecorators.ts:182`) attachent un `IChannelPolicy` au **nom** du canal. Les trois axes sont
+`@RealtimeChannel(name, policy)` (`realtimeDecorators.ts:192`) et `@RealtimeInbound(name, policy)`
+(`realtimeDecorators.ts:231`) attachent un `IChannelPolicy` au **nom** du canal. Les trois axes sont
 cumulatifs (ET) ; un axe absent n'impose rien :
 
 | Axe             | Sens                                                                          | Évalué par                               |
 | --------------- | ----------------------------------------------------------------------------- | ---------------------------------------- |
-| `authenticated` | token non anonyme                                                             | `satisfies()` (`frameAuthorizer.ts:240`) |
+| `authenticated` | token non anonyme                                                             | `satisfies()` (`frameAuthorizer.ts:290`) |
 | `roles`         | un des rôles suffit, **hiérarchie comprise**                                  | `Firewall.hasRole()` (`firewall.ts:482`) |
 | `scopes`        | un des scopes suffit — axe API (JWT, clé API), une session BFF n'en porte pas | comparaison directe                      |
 
@@ -531,21 +531,21 @@ Le verrou n'existe que si quelqu'un le pose. Deux conditions doivent être vraie
 1. `@nodefony/security` est chargé, et
 2. au moins une zone a `security: true` **et** `realtime: true`.
 
-C'est exactement le test de `Firewall.#wireRealtime()` (`firewall.ts:253`) : sans zone qualifiante,
+C'est exactement le test de `Firewall.#wireRealtime()` (`firewall.ts:279`) : sans zone qualifiante,
 `wired` reste faux, `setFrameAuthorizer` n'est jamais appelé, et **aucune** policy de canal n'est
 évaluée — ni métier, ni système. `nodefony:syslog` redevient un canal ordinaire.
 
 Deuxième subtilité : `beforeDispatch` n'est branché sur une connexion que si le verrou est **déjà**
-posé au moment de son handshake (`RealtimeController.ts:429`, via
-`RealtimeHub.hasFrameAuthorizer()` — `RealtimeHub.ts:1042`). Choix de performance délibéré (un hub
+posé au moment de son handshake (`RealtimeController.ts:504`, via
+`RealtimeHub.hasFrameAuthorizer()` — `RealtimeHub.ts:1058`). Choix de performance délibéré (un hub
 non sécurisé garde un coût nul par frame), mais avec une conséquence : **une connexion ouverte avant
 la pose du verrou n'est jamais gardée**, et ce jusqu'à sa fermeture. En fonctionnement normal le
 firewall se construit au boot, avant tout trafic ; le cas ne se présente qu'en appelant
 `setFrameAuthorizer()` à chaud.
 
 **Le refus de dégrader en silence.** Quand des policies sont déclarées sans décideur câblé,
-`RealtimeHub.hasUnenforcedChannelPolicies()` (`RealtimeHub.ts:1101`) renvoie `true` et le controller
-émet un WARNING explicite, une seule fois par process (`RealtimeController.ts:522`) :
+`RealtimeHub.hasUnenforcedChannelPolicies()` (`RealtimeHub.ts:1117`) renvoie `true` et le controller
+émet un WARNING explicite, une seule fois par process (`RealtimeController.ts:558`) :
 
 ```text
 Realtime channel policies declared but NO frame authorizer is wired —
@@ -571,7 +571,7 @@ Le refus doit être observable sans devenir un oracle. Nodefony tranche ainsi :
 
 | Type de frame refusée               | Réponse au client                                                                |
 | ----------------------------------- | -------------------------------------------------------------------------------- |
-| Requête (avec `id`)                 | `-32001 "unauthorized"` — `JsonRpcPeer.receive()` (`JsonRpcPeer.ts:400`)         |
+| Requête (avec `id`)                 | `-32001 "unauthorized"` — `JsonRpcPeer.receive()` (`JsonRpcPeer.ts:390`)         |
 | Notification (`subscribe`, inbound) | `realtime:denied { channel, reason: "forbidden" }` (`RealtimeController.ts:432`) |
 | Dépassement du plafond de canaux    | `realtime:denied { channel, reason: "limit" }`                                   |
 | Canal sans aucun producteur         | `realtime:denied { channel, reason: "unknown" }`                                 |
@@ -600,16 +600,16 @@ Nodefony ferme l'écart par deux mécanismes de granularité différente.
 
 | Surface                     | Re-validation        | Fenêtre d'exposition | Où                                                                    |
 | --------------------------- | -------------------- | -------------------- | --------------------------------------------------------------------- |
-| `api.request` (data plane)  | **à chaque frame**   | nulle                | `RealtimeController.invokeApiRequest()` (`RealtimeController.ts:878`) |
-| `subscribe` / flux de canal | **périodique**, 30 s | ≤ 30 s               | `RealtimeHub.revalidateRevocable()` (`RealtimeHub.ts:810`)            |
+| `api.request` (data plane)  | **à chaque frame**   | nulle                | `RealtimeController.invokeApiRequest()` (`RealtimeController.ts:949`) |
+| `subscribe` / flux de canal | **périodique**, 30 s | ≤ 30 s               | `RealtimeHub.revalidateRevocable()` (`RealtimeHub.ts:826`)            |
 
 **Sur `api.request`**, `token.isValid()` est appelé avant l'exécution de l'action ; identité périmée
 ou changée → `-32000` avec `status: 401`, et le client bascule sur un `fetch` HTTP porteur du cookie
 courant. Une erreur de re-validation vaut refus (fail-closed).
 
 **Sur les canaux**, le hub n'inscrit au registre de révocation que les connexions dont le token porte
-`isValid` (`RealtimeController.ts:550`) — anonymes et JWT n'y entrent jamais, coût nul.
-`RealtimeHub.registerRevocable()` (`RealtimeHub.ts:778`) démarre un `setInterval` `unref` au premier
+`isValid` (`RealtimeController.ts:659`) — anonymes et JWT n'y entrent jamais, coût nul.
+`RealtimeHub.registerRevocable()` (`RealtimeHub.ts:794`) démarre un `setInterval` `unref` au premier
 inscrit et l'arrête dès que le registre se vide : zéro timer au repos. Période :
 `REVOCATION_REVALIDATE_MS` (`RealtimeHub.ts:111`), 30 s, alignée sur le heartbeat WS.
 
@@ -625,7 +625,7 @@ Ce que `realtimeRevocation.attack.test.ts` prouve exactement :
 | registre vide                              | tick no-op, aucun crash                                  |
 
 La source de vérité côté security est `buildSessionRevalidator()`
-(`FirewallRealtimeAuthenticator.ts:227`) : il relit la session BFF **par son id capturé au handshake**
+(`FirewallRealtimeAuthenticator.ts:240`) : il relit la session BFF **par son id capturé au handshake**
 et vérifie qu'elle est toujours vivante **et toujours celle du même utilisateur** — ce second point
 attrape le changement de compte sur un navigateur partagé.
 
@@ -652,12 +652,12 @@ pas** borné.
 Chaque canal ouvert coûte un provider, un ticker et une entrée de Map. Sans borne, une connexion
 peut abonner jusqu'à l'OOM — un déni de service mémoire déclenché par **un seul** client.
 
-`RealtimeController.startChannel()` (`RealtimeController.ts:706`) refuse au-delà de
+`RealtimeController.startChannel()` (`RealtimeController.ts:815`) refuse au-delà de
 `limits.maxChannelsPerConnection` (`realtime/nodefony/config/config.ts:142`), défaut **256**,
 `null` pour illimité. Points prouvés par `realtimeChannelCap.attack.test.ts` :
 
 - le plafond est actif **même sans `RealtimeService`** — le hub porte le défaut 256
-  (`RealtimeHub.ts:315`), il n'y a pas de fenêtre où la garde n'existerait pas ;
+  (`RealtimeHub.ts:374`), il n'y a pas de fenêtre où la garde n'existerait pas ;
 - au-delà, le hub **n'est jamais appelé** : le canal n'est pas ouvert, aucun provider ne démarre ;
 - le refus est **observable** (`realtime:denied`, motif `limit`) ;
 - un re-`subscribe` d'un canal déjà tenu **ne consomme pas de slot** (l'idempotence est vérifiée
@@ -672,7 +672,7 @@ amplificateur.
 
 Un onglet en arrière-plan, un mobile en zone blanche, une fenêtre TCP pleine : la file d'envoi
 grossit sans borne, et le multiplexage concentre le risque (une socket lente bloque tous ses
-canaux). `WsConnectionTransport.send()` (`WsConnectionTransport.ts:76`) applique deux seuils :
+canaux). `WsConnectionTransport.send()` (`WsConnectionTransport.ts:82`) applique deux seuils :
 
 | `bufferedAmount`                                                                                 | Action                                                                                                                      |
 | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
@@ -681,7 +681,7 @@ canaux). `WsConnectionTransport.send()` (`WsConnectionTransport.ts:76`) applique
 
 ### Taille des messages entrants
 
-Portée par `@nodefony/http` : `websocket.maxPayload` (`http/nodefony/config/config.ts:516`), défaut
+Portée par `@nodefony/http` : `websocket.maxPayload` (`http/nodefony/config/config.ts:543`), défaut
 **1 MiB**, au-delà fermeture RFC 6455 `1009` « Message Too Big ». C'est un durcissement par rapport
 au défaut de la librairie `ws`.
 
@@ -693,7 +693,7 @@ au défaut de la librairie `ws`.
 | Limite de **fréquence** des frames entrantes | Un client authentifié peut inonder le peer ; seul le coût CPU le freine |
 | Limite de **connexions par IP ou par utilisateur** | Rien n'empêche N sockets par client au niveau du module |
 | Plafond **global** de canaux du process | Le plafond est par connexion ; M connexions × 256 canaux reste possible |
-| Seuils de back-pressure **configurables** | `slowConsumer.bytes` ne pilote que le **comptage** de la sonde, pas les seuils de drop/close (`WsConnectionTransport` est construit sans override, `RealtimeController.ts:373`) |
+| Seuils de back-pressure **configurables** | `slowConsumer.bytes` ne pilote que le **comptage** de la sonde, pas les seuils de drop/close (`WsConnectionTransport` est construit sans override, `RealtimeController.ts:421`) |
 
 ## ⚙️ Configuration de sécurité
 
@@ -773,10 +773,10 @@ n'est pas appliquée.
 ## 📡 Observabilité — Studio
 
 - **Santé de la socket** : `/nodefony/realtime/api/health`, alimenté par `RealtimeHub.probe()`
-  (`RealtimeHub.ts:775`) — canaux, abonnés, fan-out, connexions, back-pressure et carte d'identité
+  (`RealtimeHub.ts:865`) — canaux, abonnés, fan-out, connexions, back-pressure et carte d'identité
   du backplane. Un `drops` qui grimpe signale des clients en souffrance ; un `slowConsumers` non nul
   précède souvent une fermeture `1013`. Même snapshot en flux sur le canal `nodefony:socket`
-  (namespace réservé : `ROLE_ADMIN`).
+  (namespace réservé : `ROLE_NODEFONY_ADMIN`).
 - **Journal d'audit** : les refus de frame arrivent sur le canal `nodefony:audit`
   (`ROLE_NODEFONY_ADMIN`) et dans le data plane d'audit de `@nodefony/security`.
 - **Page module** : `/nodefony/modules/realtime` — la config effective (dont `csrf.checkOrigin` et