@nodefony/realtime 10.0.0-beta.5 → 10.0.0-beta.7

package/docs/securite.md

@@ -310,7 +310,13 @@ n'est jamais traitée.
 3. Résolution de l'authenticator par `RealtimeHub.resolveAuthenticator()` (`RealtimeHub.ts#RealtimeHub.resolveAuthenticator`) :
    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).
+   connexion : lire un store est acceptable ici, jamais par frame), et **borné** par
+   `authenticateTimeoutMs` (10 s par défaut, `admissionBudget.ts#AdmissionBudget.authenticateWithin`).
+   Au-delà, la socket est fermée en `1013` « try again later » : le client recule puis revient, et une
+   identité arrivée après coup est ignorée. Ni `onFailure` ni `4001` — une base en panne n'est pas un
+   refus d'identité, et un code définitif arrêterait un client légitime à chaque panne. Compteur
+   `authenticateTimedOutTotal`, un `WARNING` par fenêtre de 10 s. Un client parti pendant
+   l'authentification n'est jamais inscrit au hub.
 5. Pose du token sur la WeakMap `peer → token` via `RealtimeHub.setTokenForPeer()`
    (`RealtimeHub.ts#RealtimeHub.setTokenForPeer`), **avant** l'envoi du `welcome` : le lookup est garanti dès la première
    frame.
@@ -443,9 +449,9 @@ mémoire : le token déjà résolu, et la cible de la frame.
 | Frame | Contrôle appliqué |
 | --- | --- |
 | `api.request {path}` | Re-match de zone HTTP : zone protégée + anonyme → refus |
-| `subscribe {channel}` | Plancher système, puis policy métier déclarée sur le canal |
-| notification `method` = canal inbound | Même politique que `subscribe` (on ne pousse pas sur un canal protégé) |
-| action `@RealtimeAction` | Authentifié **par défaut** ; rôle/scope si déclarés ; ouverte seulement si `{ authenticated: false }` est écrit |
+| `subscribe {channel}` | Plancher système, puis policy de **LECTURE** déclarée sur le canal |
+| notification `method` = canal inbound | Policy de lecture **ET** policy d'**ÉCRITURE** du même nom (on ne pousse pas sur un canal qu'on n'a pas le droit de lire) |
+| action `@RealtimeAction` | Lecture **ET** écriture du nom. Sans politique : la lecture d'un canal homonyme si elle est déclarée, sinon authentifié **par défaut** ; 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#authorizeApiRequest`) laisse
@@ -468,6 +474,22 @@ peut **resserrer**, jamais desserrer.
 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.
 
+**Les suffixes `:health` et `:stats` sont réservés dans TOUT espace de noms**, pas seulement sous
+`nodefony:`. C'est la convention transverse des canaux de santé et de mesures : `net:health` est
+donc refusé à quiconque ne porte pas `ROLE_NODEFONY_ADMIN`, même si l'application ne déclare rien
+sur ce canal. Le hub, lui, ne réserve que `nodefony:` — d'où la surprise. Le refus le dit : sa
+phrase nomme le suffixe, le rôle exigé et la règle qui le surcharge (`frameAuthorizer.ts#explainReservedSuffix`).
+Pour ouvrir un tel canal à l'application, déclarer une **règle de préfixe** — placée avant les
+défauts, elle gagne et la convention n'est plus consultée :
+
+```ts
+use("@nodefony/security", {
+  realtimeChannels: [{ pattern: "net:", authenticated: true }],
+});
+```
+
+La règle ne descend pas sous ce qu'elle déclare : ici, `net:health` reste fermé à l'anonyme.
+
 Trois durcissements méritent d'être connus :
 
 - **Match insensible à la casse, sans allocation** — `startsWithCI()` (`frameAuthorizer.ts#buildSystemRules`).
@@ -488,9 +510,41 @@ jamais de canal d'audit non gardé.
 
 ### La policy métier — déclarer sur le canal
 
-`@RealtimeChannel(name, policy)` (`realtimeDecorators.ts#RealtimeChannel`) et `@RealtimeInbound(name, policy)`
-(`realtimeDecorators.ts#RealtimeInbound`) attachent un `IChannelPolicy` au **nom** du canal. Les trois axes sont
-cumulatifs (ET) ; un axe absent n'impose rien :
+Deux politiques par **nom** de canal, chacune un `IChannelPolicy` :
+
+- la **LECTURE** — `@RealtimeChannel(name, policy)` (`realtimeDecorators.ts#RealtimeChannel`) — exigée au
+  `subscribe` ;
+- l'**ÉCRITURE** — `@RealtimeInbound(name, policy)` (`realtimeDecorators.ts#RealtimeInbound`),
+  `@RealtimeAction(name, policy)` — exigée **en plus** de la lecture sur toute trame entrante.
+
+Ce qui n'est pas déclaré s'hérite, quel que soit l'ordre des méthodes : une lecture absente reprend
+l'écriture (un canal gardé par `@RealtimeInbound` seul reste protégé en lecture), une action sans
+politique reprend la lecture déclarée sous son nom, sinon le défaut fermé. Un canal que tout le monde
+lit et que seuls certains écrivent s'écrit donc :
+
+```typescript
+@RealtimeChannel("chat:typing", { authenticated: false }) // tout le monde voit « Untel écrit… »
+typing(): () => void {
+  return () => {};
+}
+@RealtimeInbound("chat:typing", { authenticated: true }) // seuls les connectés écrivent
+onTyping(): void {}
+```
+
+Deux déclarations **contradictoires** d'une même sorte sur un nom — dans une classe, ou dans deux
+classes — refusent le démarrage en nommant le canal : une seule s'appliquerait, l'autre
+disparaîtrait. Une sous-classe qui redéclare la politique de son parent la surcharge. `allow` est
+une règle de lecture : posé sur une écriture distincte de la lecture, il refuse le démarrage.
+
+Avec des **motifs** (`room:*`), la lecture d'un nom appartient à la déclaration la plus spécifique
+qui déclare quelque chose sur lui (le nom exact, sinon le motif au littéral le plus long) ; l'écriture
+vient de la plus spécifique qui en déclare une, motifs compris. Une écriture de famille réservée
+s'applique donc aussi à un nom exact qui n'a déclaré que sa lecture, et une commande déclarée par
+`@RealtimeInbound("task:start")` sous une famille `task:*` à `allow` reste une commande. Le canal
+personnel `user:<id>` garde sa règle « son canal seulement » tant qu'aucune déclaration ne vise
+explicitement `user:` : un motif attrape-tout (`*`) ne la retire pas.
+
+Les trois axes d'une politique sont cumulatifs (ET) ; un axe absent n'impose rien :
 
 | Axe             | Sens                                                                          | Évalué par                                            |
 | --------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------- |
@@ -498,11 +552,17 @@ cumulatifs (ET) ; un axe absent n'impose rien :
 | `roles`         | un des rôles suffit, **hiérarchie comprise**                                  | `Firewall.hasRole()` (`firewall.ts#Firewall.hasRole`) |
 | `scopes`        | un des scopes suffit — axe API (JWT, clé API), une session BFF n'en porte pas | comparaison directe                                   |
 
-Une policy **vide** n'est pas enregistrée : `definePolicy()` (`realtimeDecorators.ts#definePolicy`) ignore un
-objet sans contrainte — le canal reste libre, le registre reste vide. Les déclarations sont publiées
-au hub **au handshake**, pas au boot (`RealtimeHub.registerChannelPolicy()`, `RealtimeHub.ts#RealtimeHub.registerChannelPolicy`,
-idempotent) ; le décideur les relit par `RealtimeService.resolveChannelPolicy()`
-(`RealtimeService.ts#RealtimeService.resolveChannelPolicy`).
+Une policy **vide** n'est pas enregistrée : `declarePolicy()` (`realtimeDecorators.ts#declarePolicy`) ignore un
+objet sans contrainte — le canal reste libre, le registre reste vide. Les déclarations sont inscrites
+au hub **au démarrage** (`channelPolicyRegistry.ts#registerControllerPolicies`, à `onKernelReady`) :
+un exemplaire qui n'a encore vu aucune poignée de main a déjà ses politiques — celui qui n'émet
+que des webhooks aussi. Un contrôleur échappé au démarrage s'inscrit à sa première poignée de main
+(`RealtimeHub.registerChannelPolicy()`, `RealtimeHub.ts#RealtimeHub.registerChannelPolicy`, idempotent) ;
+le décideur les relit en une résolution par `RealtimeService.resolveChannelPolicies()`
+(`RealtimeService.ts#RealtimeService.resolveChannelPolicies`). Un refus d'écriture est audité sous
+le motif `channel_write_policy`, distinct de `channel_policy` (lecture). Un verrou qui ne sait pas
+juger l'écriture (il ne déclare pas `judgesWrite`) refuse le démarrage dès qu'une écriture distincte
+est déclarée : versions de `@nodefony/realtime` et `@nodefony/security` à aligner.
 
 ### ⚠️ Une policy est attachée à un nom EXACT — les canaux dérivés n'héritent pas
 
@@ -539,6 +599,213 @@ Deux façons de fermer, selon l'intention :
 > Le nom exact l'emporte sur un motif ; entre deux motifs, le plus spécifique gagne. Un `*` dans un
 > nom souscrit est refusé : il désigne un motif de politique, jamais un canal.
 
+### 📬 Le canal personnel `user:<id>` — fourni, rien à déclarer
+
+Livrer un message à **une** personne — sur tous ses onglets, sur tous les serveurs, et à personne
+d'autre — est une brique du framework. L'application n'écrit ni canal, ni règle, ni déclaration de
+diffusion :
+
+```typescript
+// côté serveur — un service, un job, un contrôleur
+getRealtimeHub<ChatContract>().publishToUser(bob.id, message);
+
+// côté navigateur — cet onglet s'abonne quand son écran écoute
+useEffect(() => chat.onUser((m) => addPrivate(m)), []);
+```
+
+La forme du message se déclare dans le contrat, par la clé gabarit du canal personnel :
+
+```typescript
+interface ChatContract extends IRealtimeContract {
+  serverToClient: {
+    [channel: `user:${string}`]: { from: string; text: string };
+  };
+}
+```
+
+Ce que le framework garantit, écrit une fois :
+
+| Garantie                  | Comment                                                                                                                                                                                                    |
+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Toi seul**              | Politique intégrée : connexion authentifiée, admission par **égalité de chaîne** avec `user:<ton id>` (`userChannel.ts#isOwnUserChannel`). Jamais un découpage : l'identité `4` n'entre pas sur `user:42`. |
+| **Aucun oracle**          | Le verrou passe avant la fabrique, et la règle ne lit que l'identité du demandeur, jamais une base : `user:999` (inexistant) et `user:bob` (pas le tien) reçoivent le **même** `forbidden`.                |
+| **Tous les serveurs**     | Dès qu'un bus est branché, le préfixe `user:` est diffusé par le framework (`RealtimeHub.ts#RealtimeHub.setBackplane`).                                                                                    |
+| **Sans sécurité chargée** | La règle s'applique quand même : `allow` ne fait que retirer des abonnés.                                                                                                                                  |
+| **Jamais d'office**       | Rien n'est ouvert à la connexion : une application qui n'appelle jamais `onUser` ne paie rien. Mesuré : 494 octets par onglet abonné, envoi ~60 ns.                                                        |
+
+L'`id` est l'identifiant **stable** du compte (`RealtimeIdentity.id`), jamais le login : un login
+libéré se réattribue, et le nouveau compte recevrait les messages de l'ancien. Un appelant sans
+compte local (`<émetteur>#<sujet>`, connexion d'un fournisseur d'identité) a lui aussi son canal ;
+un **anonyme** n'en a pas — il n'a pas d'identifiant qui survive à une reconnexion. Le support
+anonyme passe par un salon privé de l'application (`support:<conversation>` + `allow`, ci-dessous).
+
+**Le prix assumé** : un compte supprimé garde son abonnement jusqu'à son éjection explicite. Et une
+publication sans abonné est perdue sans erreur — c'est une diffusion, pas une boîte aux lettres :
+l'historique d'une conversation vit dans la base de l'application.
+
+**Surcharger la règle** : une politique que l'application écrit sur `user:…` (nom exact ou motif)
+l'emporte sur la règle intégrée — c'est ainsi qu'on ouvre `user:public` à tous. Une telle
+déclaration remplace la garantie « toi seul » : à n'écrire qu'en connaissance de cause.
+
+### 🪪 `allow` — admettre un abonné par SON identité
+
+Les trois axes décrivent une **classe** d'identité : « un administrateur », « un service qui porte
+`metrics:read` ». Ils ne savent pas dire « **ce** compte, et lui seul, sur **ce** canal » — la boîte
+aux lettres `user:42`, la salle d'une partie, le tableau de bord d'une seule usine. C'est le rôle
+d'`allow` : une règle qui reçoit le canal demandé et l'identité de l'abonné, et répond oui ou non.
+Elle se joue au `subscribe`, une fois, dans le contrôleur
+(`RealtimeController.ts#RealtimeController.startChannel`) ; la règle elle-même est un contrat du cœur
+(`channelAdmission.ts#IChannelAdmission`), isomorphe : rien n'y dépend de la socket.
+
+> L'exemple ci-dessous écrit à la main la règle de `user:*` pour montrer la mécanique. Pour le canal
+> personnel lui-même, **ne rien écrire** : le framework le fournit (section précédente), et une
+> politique écrite ainsi remplacerait la sienne.
+
+**La forme courte — une flèche, pour une règle qui ne lit rien :**
+
+```typescript
+// nodefony/controllers/InboxRealtimeController.ts
+import { controller, route } from "@nodefony/framework";
+import { Context } from "@nodefony/http";
+import { RealtimeChannel, RealtimeController } from "@nodefony/realtime";
+import type { RealtimePublish } from "@nodefony/realtime";
+
+@controller("/rt")
+class InboxRealtimeController extends RealtimeController {
+  constructor(context: Context) {
+    super("InboxRealtimeController", context);
+  }
+
+  @route("inbox-ws", {
+    path: "/inbox",
+    requirements: { methods: ["WEBSOCKET"] },
+  })
+  async realtime(message: string | Buffer | null): Promise<void> {
+    this.handleRealtime(message);
+  }
+
+  // La règle du MOTIF : `user:42` n'est ouvert qu'au compte 42.
+  @RealtimeChannel("user:*", {
+    allow: (channel, who) => channel === `user:${who.id}`,
+  })
+  inbox(): () => void {
+    return () => {};
+  }
+
+  // Un producteur décoré ne sert que son nom exact : les canaux `user:<id>`
+  // sont servis par la fabrique dynamique.
+  override createRealtimeChannel(
+    channel: string,
+    publish: RealtimePublish,
+  ): (() => void) | null {
+    if (!channel.startsWith("user:")) return null;
+    publish(channel, { unread: 0 });
+    return () => {};
+  }
+}
+
+export default InboxRealtimeController;
+```
+
+Le compte 42 reçoit `realtime:subscribed` pour `user:42` ; le compte 43 et l'anonyme reçoivent
+`realtime:denied`, motif `forbidden` — prouvé de bout en bout, vrai client et vrai verrou, par
+`realtimeChannelAuth.e2e.test.ts`.
+
+**La forme longue — une classe, dès que la règle lit les données de l'application.** Ses services lui
+arrivent par le constructeur, comme à tout service ; elle se déclare dans `@services([…])` de son
+module, et le décorateur la nomme :
+
+```typescript
+// nodefony/services/RoomAdmission.ts
+import { Inject, Module, Service, injectable } from "nodefony";
+import type { IChannelAdmission, ISubscriberIdentity } from "nodefony";
+import type RoomMembersService from "./RoomMembersService";
+
+@injectable()
+class RoomAdmission extends Service implements IChannelAdmission {
+  constructor(
+    module: Module,
+    @Inject("RoomMembersService") private readonly members: RoomMembersService,
+  ) {
+    super(
+      "roomAdmission",
+      module.container ?? undefined,
+      module.notificationsCenter,
+    );
+  }
+
+  // `room:<partie>` n'est ouvert qu'aux joueurs de la partie.
+  async allow(channel: string, who: ISubscriberIdentity): Promise<boolean> {
+    if (who.id === null) return false;
+    return this.members.isPlayer(channel.slice("room:".length), who.id);
+  }
+}
+
+export default RoomAdmission;
+
+// Dans le contrôleur :
+//   @RealtimeChannel("room:*", { allow: RoomAdmission })
+```
+
+Le démarrage résout la classe une fois et journalise « canal room:\*, admission RoomAdmission,
+résolue » (`channelPolicyRegistry.ts#createAdmissionResolver`). Une dépendance absente, une portée
+autre que singleton, une classe sans méthode `allow` font **échouer le démarrage** en nommant la
+classe et le canal — jamais un refus silencieux de 100 % des abonnés en production. Une seule
+instance sert tous les abonnés en même temps : elle ne garde **aucun état par abonné**.
+
+Un **module npm** livre sa politique de la même façon : la classe vit dans le module, déclarée dans
+ses `@services([…])`, son contrôleur la nomme. L'application qui l'installe n'écrit rien.
+
+**Le contrat, en six règles :**
+
+| Règle                                         | Pourquoi                                                                                                                                                                                                                                              |
+| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Ses arguments, et rien d'autre**            | ni contexte de requête, ni session : à l'émission d'un webhook il n'y en a pas. Une règle qui les lirait passerait tous ses tests sur la socket, puis refuserait tout ailleurs                                                                        |
+| **`who.id`, jamais le login**                 | un e-mail change, un login libéré se réattribue ; `id` est l'identifiant stable du compte, `null` pour l'anonyme                                                                                                                                      |
+| **Seul `true` admet**                         | `1`, `"yes"`, un objet refusent — une réponse ambiguë ne vaut pas un oui                                                                                                                                                                              |
+| **L'anonyme est refusé d'office**             | sans même appeler la règle, sauf `anonymous: true` dans la politique ; un authentificateur qui ne fournit pas d'identité d'admission (`getIdentity`) n'entre sur aucun canal à `allow`                                                                |
+| **Elle s'ajoute aux trois axes**              | `authenticated`, `roles`, `scopes` d'abord (le verrou), puis `allow` (l'abonnement). Une politique plus spécifique remplace celle du motif EN ENTIER, `allow` compris : `@RealtimeChannel("user:public", { authenticated: false })` ouvre ce canal-là |
+| **Une fois par abonnement, jamais par trame** | admis, les trames entrantes du canal passent sans la rappeler ; une trame entrante sur un canal à `allow` SANS abonnement préalable est refusée                                                                                                       |
+
+Le `realtime:welcome` annonce un canal à `allow` sur le seul verdict du verrou : la règle n'est
+jamais jouée à la poignée de main — elle coûterait un appel par canal déclaré et par connexion, pour
+annoncer un motif dont aucun nom concret n'est connu.
+
+**Quand la règle est lente ou en panne** — la base qu'elle lit ne répond plus :
+
+<!-- prettier-ignore -->
+| Situation | L'abonné reçoit | Le serveur |
+| --- | --- | --- |
+| la règle lève, ou sa promesse est rejetée | `realtime:denied` `forbidden` (fermé par défaut) | un `WARNING` par fenêtre de 10 s |
+| aucune réponse dans `allowTimeoutMs` (5 s) | `unavailable` | `allowTimedOutTotal` ; un verdict arrivé après coup est ignoré, jamais une admission |
+| plus de `maxPendingAllowsPerConnection` (8) appels en vol sur la connexion | rien : la demande **attend son tour** | — le rejeu de tous les abonnements au `welcome` n'en perd aucun |
+| plus de `maxPendingAllowsTotal` (512) appels en vol sur l'exemplaire | `unavailable`, sans appel | `allowSaturatedTotal` |
+| 50 délais dépassés en 5 s | `unavailable` et `retryAfterMs`, sans appel, pendant 5 s (coupe-circuit) | `allowSaturatedTotal` |
+
+Un délai dépassé n'est **pas** un refus de droit : le client réessaie `unavailable` au plus trois
+fois, avec un recul exponentiel à gigue complète, après `retryAfterMs` quand il est donné.
+`forbidden` et `limit` ne se réessaient jamais. Le tout reste borné : 300 passerelles qui rejouent
+10 000 abonnements contre une base **bloquée** déclenchent environ 1 600 appels de la règle, jamais
+plus de 512 à la fois, et la tempête s'éteint en moins d'une minute
+(`admissionStorm.e2e.test.ts`). Réglages : [`configuration.md`](./configuration.md) ; compteurs :
+[`observabilite.md`](./observabilite.md).
+
+**Le prix assumé — une réponse retenue.** Une admission ne se périme pas seule : un membre retiré
+d'une salle reste abonné tant que sa connexion vit, la règle n'est pas rejouée. Pour couper tout de
+suite, on retire son appartenance (là où la règle la lit), PUIS on l'éjecte :
+`getRealtimeHub().evictUser(canal, compte)` coupe tous ses onglets, sur tous les serveurs
+(`realtime:closed { reason: "evicted" }`). L'éjection seule ne suffit pas — son navigateur rejoue
+`subscribe` au rechargement, et c'est la règle qui tranche alors. Détail :
+[canaux à membres](./canaux-a-membres.md). Fermer la connexion entière, c'est la révocation
+([verrou 4](#-verrou-4--la-révocation--une-socket-survit-à-sa-session)).
+
+**`room:*` et `pattern: "room:"` — deux grammaires, une même famille.** Le décorateur écrit un motif
+(`"room:*"`) ; la configuration de `@nodefony/security` écrit un préfixe
+(`realtimeChannels: [{ pattern: "room:", roles }]`). Ils couvrent les mêmes canaux. La règle de
+configuration est jugée par le verrou AVANT la politique du décorateur et la remplace de ce côté —
+c'est ainsi qu'une exploitation durcit un namespace sans toucher au code ; elle ne porte jamais
+d'`allow`, qui reste déclaré sur le décorateur et s'applique toujours à l'abonnement.
+
 ### ⚠️ La condition d'activation — le point critique
 
 Le verrou n'existe que si quelqu'un le pose. Deux conditions doivent être vraies **en même temps** :
@@ -592,7 +859,10 @@ Le refus doit être observable sans devenir un oracle. Nodefony tranche ainsi :
 | Canal sans aucun producteur         | `realtime:denied { channel, reason: "unknown" }`                                                            |
 
 Le message est **générique** dans les trois cas : jamais « il te manque `ROLE_ADMIN` », jamais le nom
-de la zone. Sans `realtime:denied`, une notification refusée serait droppée en silence (elle n'a pas
+de la zone. Hors production seulement, un champ `detail` ajoute la phrase qui aide le développeur
+(`deniedDetail.ts#deniedDetail`) ; quand le verrou sait dire pourquoi il a refusé — un suffixe
+`:health`/`:stats` réservé à la plateforme —, `detail` EST cette explication
+(`RealtimeHub.ts#RealtimeHub.explainDenial`). Le journal du serveur la porte, lui, dans tous les modes. Sans `realtime:denied`, une notification refusée serait droppée en silence (elle n'a pas
 de canal de réponse) et le client se croirait abonné. **Aucun abonnement ne reste sans réponse** :
 un canal que personne ne produit — nom mal orthographié, module non chargé — rend `unknown`, qui
 n'ouvre aucun oracle (un canal gardé est tranché en amont, donc `forbidden` qu'il existe ou non).
@@ -623,27 +893,58 @@ ou changée → `-32000` avec `status: 401`, et le client bascule sur un `fetch`
 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#RealtimeController.onHandshake`) — anonymes et JWT n'y entrent jamais, coût nul.
+`isValid` (`RealtimeController.ts#RealtimeController.onHandshake`). Une connexion anonyme n'y entre jamais,
+coût nul. Toute connexion authentifiée par le pare-feu y entre : sa session est relue, ou, pour un
+jeton porteur (`jwt`, `external-jwt`, `apikey`), son expiration (`exp`), la révocation de son `jti` et
+la révocation en masse de son identité (`invalidBefore`).
 `RealtimeHub.registerRevocable()` (`RealtimeHub.ts#RealtimeHub.registerRevocable`) 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#channelFamily`), 30 s, alignée sur le heartbeat WS.
 
 Ce que `realtimeRevocation.attack.test.ts` prouve exactement :
 
-| Cas                                        | Comportement prouvé                                      |
-| ------------------------------------------ | -------------------------------------------------------- |
-| `isValid()` renvoie `false`                | `close(4001, "session revoked")`                         |
-| `isValid()` renvoie `true`                 | socket **intacte** (contrôle positif, pas de faux refus) |
-| `isValid()` **throw** (store indisponible) | socket fermée — fail-closed, parité avec `api.request`   |
-| déjà révoqué                               | retiré du registre avant le close → aucun re-close       |
-| déconnexion propre                         | `unregisterRevocable` → plus jamais re-validé            |
-| registre vide                              | tick no-op, aucun crash                                  |
+| Cas                                        | Comportement prouvé                                       |
+| ------------------------------------------ | --------------------------------------------------------- |
+| `isValid()` renvoie `false`                | `close(4001, "session revoked")`                          |
+| `status()` rend `expired` (jeton porteur)  | `close(4006, "token expired")`                            |
+| `status()` rend `revoked`                  | `close(4001, "session revoked")`, même si `exp` est passé |
+| `isValid()` renvoie `true`                 | socket **intacte** (contrôle positif, pas de faux refus)  |
+| `isValid()` **throw** (store indisponible) | socket fermée — fail-closed, parité avec `api.request`    |
+| déjà révoqué                               | retiré du registre avant le close → aucun re-close        |
+| déconnexion propre                         | `unregisterRevocable` → plus jamais re-validé             |
+| registre vide                              | tick no-op, aucun crash                                   |
 
 La source de vérité côté security est `buildSessionRevalidator()`
 (`FirewallRealtimeAuthenticator.ts#buildSessionRevalidator`) : 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é.
 
+**Le code de fermeture dit la cause** (`realtime/closeCodes.ts`, ADR-0021 §S11). Un jeton porteur
+sait pourquoi il est mort : `IRealtimeToken.status()` rend `expired` ou `revoked`, et la
+révocation l'emporte — la liste de refus est interrogée avant de conclure à l'expiration.
+
+| Cause sur une socket OUVERTE                                  | Code                                   | Client 10.0          |
+| ------------------------------------------------------------- | -------------------------------------- | -------------------- |
+| jeton porteur arrivé à `exp`                                  | `4006` (`TOKEN_EXPIRED_CLOSE_CODE`)    | s'arrête (définitif) |
+| jeton porteur révoqué (`jti`, `invalidBefore`), expiré ou non | `4001` (`IDENTITY_DEAD_CLOSE_CODE`)    | s'arrête             |
+| session expirée ou détruite (la cause n'est pas connaissable) | `4001`                                 | s'arrête             |
+| droits changés, identité vivante                              | `4005` (`IDENTITY_REFRESH_CLOSE_CODE`) | revient aussitôt     |
+| refus à la poignée de main, quel qu'il soit                   | 401 uniforme → `1008`                  | s'arrête             |
+| authentification sans réponse dans `authenticateTimeoutMs`    | `1013` (`TRY_AGAIN_LATER_CLOSE_CODE`)  | revient, avec recul  |
+| client qui ne vide plus sa file (contre-pression)             | `1013`                                 | revient, avec recul  |
+
+> [!IMPORTANT]
+> **Jamais de `4006` à la poignée de main.** Un refus distinct y dirait à qui tient un jeton volé
+> qu'il a été émis par l'application : un jeton expiré présenté à l'entrée reçoit le même 401 que
+> n'importe quel autre refus.
+
+**Recette — un jeton d'une heure sur une socket de sept jours.** La socket vit plus longtemps que son
+jeton : au bout d'une heure, elle est fermée en `4006`, et le client 10.0 ne revient pas seul. C'est
+à l'application de **recréer sa socket avec un jeton neuf avant `exp`** — par exemple obtenir un
+nouveau jeton cinq minutes avant l'échéance, ouvrir la nouvelle socket, puis fermer l'ancienne.
+Un client qui saura obtenir un jeton frais de lui-même viendra dans une version 10.x, sans que le
+serveur change.
+
 **Un changement de rôles coupe sur-le-champ, sans attendre le tick.** Quand une mise à jour du compte
 touche ses rôles, le hub ferme toutes les sockets de cette identité avec le code **4005**
 (`realtime/closeCodes.ts#IDENTITY_REFRESH_CLOSE_CODE`, `RealtimeHub.ts#RealtimeHub.#revocation`). À la
@@ -658,18 +959,23 @@ Aucune lecture de base par tick ni par frame : le coût n'existe qu'à la mise
 > 1. **Fenêtre de 30 s.** Entre le logout et le tick suivant, les flux continuent. Pour une coupure
 >    immédiate, fermer la socket explicitement côté serveur. (Un changement de **rôles**, lui, coupe
 >    immédiatement — ci-dessus.)
-> 2. **Best-effort si la session est illisible au handshake.** Si l'id ou le store ne sont pas
->    accessibles, `buildSessionRevalidator()` renvoie `null` ; `UserRealtimeToken.isValid()`
->    (`UserRealtimeToken.ts#UserRealtimeToken.isValid`) répond alors toujours `true`. La connexion **est** inscrite au
->    registre (le token expose bien `isValid`) mais ne sera **jamais** révoquée. Choix assumé pour
->    éviter les faux refus — à connaître, car cela ne se voit pas.
-> 3. **Les identités sans `isValid` ne sont pas révocables du tout** : anonyme, JWT, clé API. Pour
->    un JWT, la révocation reste portée par son `exp` et par la reconnexion.
+> 2. **Une identité qu'on ne pourra pas re-valider ferme la socket.** Si la session est illisible au
+>    handshake (ni id ni store exploitable), `buildSessionRevalidator()`
+>    (`FirewallRealtimeAuthenticator.ts#buildSessionRevalidator`) rend un revalidateur qui répond
+>    toujours `false` : la socket est fermée en 4001 au premier tick, et un `WARNING` le dit. Même
+>    règle pour un jeton porteur qui n'a ni `exp`, ni de quoi interroger le store de révocation
+>    (`jti`, `iat`). Un refus visible plutôt qu'une connexion que rien ne pourrait plus couper.
+> 3. **Un jeton porteur n'est jugé sur sa signature qu'à l'ouverture.** Le tick relit `exp`, `jti` et
+>    `invalidBefore`, jamais la clé ni l'émetteur : une clé retirée du jeu publié par l'émetteur laisse
+>    la socket vivre jusqu'à `exp`, et un émetteur retiré de `resourceServer.issuers` ne compte qu'à
+>    la connexion suivante — la liste ne change qu'au redémarrage, qui ferme les sockets. Une
+>    connexion anonyme, elle, n'est pas révocable du tout.
 
 ## 🚧 Plafonds anti-abus — borner une connexion
 
 Une connexion ouverte est une ressource. Trois bornes existent ; il faut aussi savoir ce qui **n'est
-pas** borné.
+pas** borné. Les appels en vol de la règle `allow` ont leurs propres plafonds, par connexion et par
+exemplaire : voir [`allow` — quand la règle est lente](#-allow--admettre-un-abonné-par-son-identité).
 
 ### Canaux par connexion
 
@@ -783,16 +1089,16 @@ n'est pas appliquée.
 
 ## 📜 Normes appliquées
 
-| Norme                                 | Application                                                                                  |
-| ------------------------------------- | -------------------------------------------------------------------------------------------- |
-| **RFC 6455 §10.2** (Origin)           | Contrôle d'origine à l'upgrade, aux deux étages                                              |
-| **RFC 6455 §7.4.2** (codes 4000-4999) | `4001` unauthorized / session revoked, `4003` origin not allowed                             |
-| **RFC 6455 §7.4.1 / registre IANA**   | `1008` Policy Violation (origine transport), `1009` Message Too Big, `1013` Try Again Later  |
-| **RFC 6455 §4.1**                     | `Sec-WebSocket-Protocol` normalisé en liste dans le DTO de handshake                         |
-| **RFC 9110 §7.2**                     | Comparaison du `Host` par le matcher d'authenticator                                         |
-| **JSON-RPC 2.0 §5.1**                 | `-32001` (plage `Server error`) pour une requête refusée, `-32602` pour des params invalides |
-| **OWASP WSTG-CLNT-10**                | Anti-CSWSH : validation d'`Origin` obligatoire, les navigateurs n'appliquent pas CORS aux WS |
-| **Zero Trust / OWASP A01**            | Zone protégée + anonyme = refus ; token toujours présent, jamais `null`                      |
+| Norme                                 | Application                                                                                                                                  |
+| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| **RFC 6455 §10.2** (Origin)           | Contrôle d'origine à l'upgrade, aux deux étages                                                                                              |
+| **RFC 6455 §7.4.2** (codes 4000-4999) | `4001` unauthorized / session revoked, `4003` origin not allowed, `4006` token expired                                                       |
+| **RFC 6455 §7.4.1 / registre IANA**   | `1008` Policy Violation (origine transport), `1009` Message Too Big, `1013` Try Again Later (contre-pression, authentification sans réponse) |
+| **RFC 6455 §4.1**                     | `Sec-WebSocket-Protocol` normalisé en liste dans le DTO de handshake                                                                         |
+| **RFC 9110 §7.2**                     | Comparaison du `Host` par le matcher d'authenticator                                                                                         |
+| **JSON-RPC 2.0 §5.1**                 | `-32001` (plage `Server error`) pour une requête refusée, `-32602` pour des params invalides                                                 |
+| **OWASP WSTG-CLNT-10**                | Anti-CSWSH : validation d'`Origin` obligatoire, les navigateurs n'appliquent pas CORS aux WS                                                 |
+| **Zero Trust / OWASP A01**            | Zone protégée + anonyme = refus ; token toujours présent, jamais `null`                                                                      |
 
 ## 📡 Observabilité — Studio
 
@@ -821,7 +1127,7 @@ n'est pas appliquée.
 | Le client se croit abonné, ne reçoit rien                                | Refus d'autorisation, plafond atteint, **ou nom de canal sans producteur** (pas de réponse RPC)        | Écouter `realtime:denied` : `forbidden` (droits), `limit` (borne), `unknown` (le nom ne désigne rien) |
 | `slowConsumer.bytes` augmenté, les frames sont toujours jetées à 4 MiB   | Cette clé pilote le **comptage** de la sonde, pas les seuils de drop/close du transport                | Régler `websocket.maxBackpressure` / `.backpressureCloseAfterDrops` dans `@nodefony/http`             |
 | Deux déploiements se parlent en cross-talk                               | Pas de `backplane.namespace` sur un Redis mutualisé (la base Redis ne cloisonne pas le pub/sub)        | Poser un `namespace` explicite par déploiement                                                        |
-| Le fan-out cross-pod s'arrête après avoir posé un secret                 | `backplane.secret` différent d'un pod à l'autre : les messages sont scellés, aucun ne se vérifie       | Le **même** secret sur tous les pods (`NF_REALTIME_BACKPLANE_SECRET`) ; suivre `ingressRejectedTotal` |
+| Le fan-out cross-pod s'arrête après avoir posé un secret                 | `backplane.secret` différent d'un pod à l'autre : les messages sont scellés, aucun ne se vérifie       | Le **même** secret sur tous les pods (`NF_REALTIME_BACKPLANE_SECRET`) ; suivre `sealRejectedTotal`    |
 | Un canal broadcast ne reçoit rien des autres pods                        | Le préfixe n'est pas déclaré côté receveur → l'entrée refuse le canal (compté)                         | Déclarer le préfixe (`broadcast` du controller) sur **tous** les pods, pas seulement l'émetteur       |
 
 ## 🧪 Tests & couverture

package/docs/vocabulaire.md

@@ -305,7 +305,8 @@ front**. Une différence assumée : `request()` n'y est pas supporté — au-des
 ### `accueil` (welcome) — la première frame
 
 La notification `realtime:welcome`, poussée par le serveur juste après le handshake. Elle annonce le
-protocole, les canaux que ce visiteur peut obtenir, les actions de l'endpoint, et l'identité résolue. Un client
+protocole, les canaux que ce visiteur peut obtenir, les actions de l'endpoint, l'identité résolue et, quand
+le client en a offert un, le codec de trame retenu (`codec`, absent = JSON-RPC texte). Un client
 attend cette frame avant de pousser quoi que ce soit.
 
 `IRealtimeWelcome` (`RealtimeEventMap.ts#IRealtimeWelcome`).
@@ -480,7 +481,7 @@ et de ses handlers. Aucune dépendance Node — le même fichier tourne dans le
 Le geste du pair sur une frame entrante : décider de sa nature, trouver le handler, l'appeler,
 renvoyer la réponse s'il en faut une. Ce n'est pas une méthode publique — c'est un **moment**, et
 c'est précisément là que se greffe le [verrou de frame](#verrou-de-frame--la-décision-par-frame),
-par le crochet `beforeDispatch` (`JsonRpcPeer.ts#JsonRpcPeerOptions.beforeDispatch`).
+par le crochet `beforeDispatch` (`JsonRpcPeer.ts#IJsonRpcPeerHooks.beforeDispatch`).
 
 ### `transport` — la couche octets
 
@@ -583,7 +584,7 @@ L'identifiant **unique dans le cluster** du process émetteur, joint à chaque m
 du nom du pod ou de l'hôte, jamais du seul identifiant de processus : deux conteneurs peuvent tous
 deux être le processus n° 1.
 
-`resolveBackplaneOriginId()` (`originId.ts#resolveBackplaneOriginId`), champ `IBackplane.originId` (`IBackplane.ts#IBackplaneInfo.kind`).
+`resolveBackplaneOriginId()` (`originId.ts#resolveBackplaneOriginId`), champ `IBackplane.originId` (`nodefony/src/realtime/platformHealth.ts#IBackplaneInfo.kind`).
 
 ### `anti-écho` — ne pas rejouer sa propre voix
 
@@ -608,7 +609,7 @@ L'information que chaque driver déclare sur lui-même : sait-il franchir la mac
 dans la carte d'identité du backplane, journalisée au démarrage et lisible dans la sonde — c'est ce
 qui permet de vérifier en une ligne qu'un déploiement diffuse bien au-delà d'un pod.
 
-`IBackplaneInfo` (`IBackplane.ts#IBackplaneInfo`).
+`IBackplaneInfo` (`nodefony/src/realtime/platformHealth.ts#IBackplaneInfo`).
 
 ## 🔐 La sécurité — qui parle, qui a le droit
 
@@ -667,7 +668,7 @@ un refus a donc toujours un auteur identifiable.
 Les exigences déclarées d'un canal : authentifié, rôles, scopes. Elles s'attachent au **nom** du
 canal, pas à la méthode qui l'implémente — parce que c'est le nom que le pare-feu résout.
 
-`IChannelPolicy` (`IChannelPolicy.ts#IChannelPolicy`), déclaration par `@RealtimeChannel`
+`IChannelPolicy` (`nodefony/src/realtime/channelAdmission.ts#IChannelPolicy`), déclaration par `@RealtimeChannel`
 (`realtimeDecorators.ts#RealtimeChannel`), résolution `resolveChannelPolicy()` (`RealtimeHub.ts#RealtimeHub.resolveChannelPolicy`).
 
 ### `verrou de frame` — la décision par frame
@@ -712,7 +713,7 @@ Le signal émis sur les événements protocolaires qui méritent une trace : fra
 refusée, méthode inconnue, erreur interne. Émis sans attente, avec le pair — ce qui permet de
 retrouver **qui** a été refusé, pas seulement d'où venait le paquet.
 
-`FrameAuditReason` (`JsonRpcPeer.ts#FrameAuditReason`), crochet `onFrameAudit` (`JsonRpcPeer.ts#JsonRpcPeerOptions.onFrameAudit`).
+`FrameAuditReason` (`JsonRpcPeer.ts#FrameAuditReason`), crochet `onFrameAudit` (`JsonRpcPeer.ts#IJsonRpcPeerHooks.onFrameAudit`).
 
 ### `seam` — le point de greffe
 
@@ -720,8 +721,8 @@ Littéralement une **couture** : un point prévu dans une couche basse pour qu'u
 greffe du comportement **sans modifier la couche basse**. Le module en expose cinq, et c'est ce qui
 permet à la couche sécurité de se brancher sans qu'aucune ligne de realtime ne la connaisse.
 
-Les deux du protocole sont `beforeDispatch` (`JsonRpcPeer.ts#JsonRpcPeerOptions.beforeDispatch`) et `onFrameAudit`
-(`JsonRpcPeer.ts#JsonRpcPeerOptions.onFrameAudit`) ; les trois du hub sont l'authenticator, le matcher et le contrôle d'origine.
+Les deux du protocole sont `beforeDispatch` (`JsonRpcPeer.ts#IJsonRpcPeerHooks.beforeDispatch`) et `onFrameAudit`
+(`JsonRpcPeer.ts#IJsonRpcPeerHooks.onFrameAudit`) ; les trois du hub sont l'authenticator, le matcher et le contrôle d'origine.
 
 → [Sécurité](./securite.md) pour le détail de chacun.
 
@@ -751,7 +752,7 @@ L'oscilloscope du module : « voici mon état, maintenant ». Canaux et abonnés
 livraisons, connexions, octets, back-pressure, carte d'identité du backplane. Lecture **pure**, sans
 allocation sur le chemin chaud.
 
-`RealtimeHub.probe()` (`RealtimeHub.ts#RealtimeHub.probe`) rend un `IRealtimeProbe` (`IRealtimeProbe.ts#IRealtimeProbe`).
+`RealtimeHub.probe()` (`RealtimeHub.ts#RealtimeHub.probe`) rend un `IRealtimeProbe` (`nodefony/src/realtime/platformHealth.ts#IRealtimeProbe`).
 
 > [!WARNING]
 > `IRealtimeProbe` est la **forme des données**, pas une interface à implémenter avec une méthode
@@ -774,7 +775,7 @@ Une connexion dont le back-pressure dépasse le seuil de comptage. C'est une **m
 sanction : le seuil de comptage se règle indépendamment des seuils d'action.
 
 `slowConsumer.bytes` (`config.ts#slowConsumerSchema`), champ `backpressure.slowConsumers`
-(`IRealtimeProbe.ts#IRealtimeProbe.backpressure`).
+(`nodefony/src/realtime/platformHealth.ts#IRealtimeProbe.backpressure`).
 
 ### `compteurs de canal` — mesurés à l'arrivée
 
@@ -782,7 +783,7 @@ Nombre de messages, date du dernier, débit instantané, historique glissant —
 point d'arrivée des frames, donc réutilisables par n'importe quelle application.
 
 `IChannelStats` (`IRealtimeSocket.ts#IChannelStats.method`), côté serveur `IRealtimeChannelStat`
-(`IRealtimeProbe.ts#IRealtimeChannelStat`).
+(`nodefony/src/realtime/platformHealth.ts#IRealtimeChannelStat`).
 
 ### `santé agrégée` — la vue du pod entier
 
@@ -790,7 +791,7 @@ En multi-worker, chaque process a **sa** sonde. La vue du pod est leur fusion :
 maxima repris au plus haut, instances listées une à une.
 
 `mergeClusterHealth()` (`ClusterProbeClient.ts#mergeClusterHealth`), forme `IRealtimeClusterHealth`
-(`IRealtimeProbe.ts#IRealtimeClusterHealth`).
+(`nodefony/src/realtime/platformHealth.ts#IRealtimeClusterHealth`).
 
 ### `plan de données admin` — la sonde servie à Studio