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

package/docs/observabilite.md

@@ -261,14 +261,15 @@ Le contrat est `IRealtimeProbe` (`nodefony/src/realtime/platformHealth.ts#IRealt
 
 ### Fan-out — l'amplification réelle du broker
 
-| Champ                  | Ce qu'il dit                                                                                                                             |
-| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| `publishTotal`         | Appels à `publish`. **Ce que le serveur a voulu envoyer.**                                                                               |
-| `fanoutTotal`          | Livraisons effectives (`publish` × abonnés). **Ce que ça a réellement coûté.**                                                           |
-| `inboundTotal`         | Frames poussées par les clients sur les canaux entrants, via `RealtimeHub.recordInbound()` (`RealtimeHub.ts#RealtimeHub.recordInbound`). |
-| `ingressRejectedTotal` | Messages venus du **backplane** et jetés parce que leur canal n'est pas déclaré diffusable.                                              |
-| `sealRejectedTotal`    | Messages venus du **backplane** et jetés parce que leur sceau ne se vérifie pas. `0` sans bus scellé.                                    |
-| `localOnlyTotal`       | Publications restées sur ce serveur alors qu'un bus est branché (canal non diffusable). `0` sans bus.                                    |
+| Champ                          | Ce qu'il dit                                                                                                                             |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `publishTotal`                 | Appels à `publish`. **Ce que le serveur a voulu envoyer.**                                                                               |
+| `fanoutTotal`                  | Livraisons effectives (`publish` × abonnés). **Ce que ça a réellement coûté.**                                                           |
+| `inboundTotal`                 | Frames poussées par les clients sur les canaux entrants, via `RealtimeHub.recordInbound()` (`RealtimeHub.ts#RealtimeHub.recordInbound`). |
+| `ingressRejectedTotal`         | Messages venus du **backplane** et jetés parce que leur canal n'est pas déclaré diffusable.                                              |
+| `sealRejectedTotal`            | Messages venus du **backplane** et jetés parce que leur sceau ne se vérifie pas. `0` sans bus scellé.                                    |
+| `ingressUnknownDiscardedTotal` | Messages venus du **backplane** et jetés parce que d'une version **plus récente** : canal `nodefony:bus:*` ou type d'ordre inconnus.     |
+| `localOnlyTotal`               | Publications restées sur ce serveur alors qu'un bus est branché (canal non diffusable). `0` sans bus.                                    |
 
 Le rapport `fanoutTotal / publishTotal` est la mesure la plus parlante de la page : c'est la **taille
 moyenne d'un salon**. S'il vaut 1, chaque publication ne touche qu'une personne — un canal par client,
@@ -298,6 +299,21 @@ lectures possibles quand il grimpe :
 Le canal visé n'est délibérément pas exposé : un compteur d'observabilité ne doit pas devenir un
 moyen de sonder ce que le système accepte.
 
+### Messages du bus d'une version plus récente — compté à part
+
+Une version suivante peut ajouter des messages au bus : un canal du territoire `nodefony:bus:`, ou un
+nouveau type d'ordre sur le canal de contrôle. Pendant un déploiement progressif, un serveur resté sur
+l'ancienne version les reçoit sans les connaître. Il les **jette** — aucun abonné n'en reçoit rien —
+et les compte dans `ingressUnknownDiscardedTotal`, **jamais** dans `ingressRejectedTotal` : sinon
+chaque déploiement déclencherait de fausses alertes d'injection, et une vraie attaque passerait
+inaperçue dans ce bruit. Le journal le signale une seule fois par motif, en `INFO`, sans recopier le
+nom reçu.
+
+Il monte pendant un déploiement, puis s'arrête quand tous les serveurs portent la même version. S'il
+continue de monter ensuite, un serveur est resté sur une version plus ancienne. Ce qui reste
+suspect reste compté comme une injection : un autre canal de la plateforme, une variante de casse du
+territoire, un ordre d'un type connu mais de forme fausse, ou qui vise un canal de la plateforme.
+
 Un message **mal scellé** n'entre pas dans ce compteur : le transport l'écarte avant le hub, et le
 compte à part dans `sealRejectedTotal` (relayé au même niveau de la sonde, et dans
 `backplane.sealRejectedTotal`). Quand celui-là grimpe, trois lectures : une rotation du secret en
@@ -409,7 +425,10 @@ Trois champs n'apparaissent que lorsqu'ils ont un sens :
   signale une perte **volontaire** : la mémoire du processus a été préservée au prix de messages non
   relayés aux autres répliques. Il doit rester à zéro ; s'il bouge, regarder l'état du bus avant de
   relever le plafond (`backplane.maxQueueBytes`) — un plafond plus haut ne rattrape pas un bus en
-  retard, il repousse l'échéance.
+  retard, il repousse l'échéance. Les **ordres** (terminer un canal, éjecter un compte) ne sont
+  jamais abandonnés pour faire place : ils passent hors plafond. Un ordre que le bus refuse (bus
+  injoignable) est compté à part, `controlLostTotal`, et annoncé une fois par épisode — s'il bouge,
+  une éjection n'a pas été appliquée par les autres répliques.
 
 ### La couche d'identité, au-dessus
 

package/docs/protocole.md

@@ -484,16 +484,16 @@ Voici **tout** ce que le moteur produit. Les codes de la plage `-32000`…`-3209
 la norme aux erreurs applicatives serveur ; Nodefony y place son refus d'autorisation et le défaut
 de `RpcError`.
 
-| Code     | Émis par                                                                                     | Déclencheur                                            | Ce que voit le pair                                     |
-| -------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------- |
-| `-32601` | `JsonRpcPeer.handleRequest()` (`JsonRpcPeer.ts#JsonRpcPeer.handleRequest`)                   | requête vers une action non enregistrée                | `method not found: <nom>`                               |
-| `-32603` | même méthode (`JsonRpcPeer.ts#JsonRpcPeer.handleRequest`)                                    | le handler a levé une exception **ordinaire**          | `internal error` — générique, rien d'autre              |
-| `-32001` | le refus du verrou de frame (`JsonRpcPeer.ts#JsonRpcPeer.receive`)                           | `beforeDispatch` a dit non **sur une requête**         | `unauthorized`, sans jamais dire pourquoi               |
-| `-32000` | défaut du constructeur de `RpcError` (`JsonRpcPeer.ts#RpcError`)                             | le handler expose volontairement son refus             | le message ET le `data` choisis par le handler          |
-| `-32602` | le pont API, via `RpcError` (`RealtimeController.ts#RealtimeController.actionParamsWrapper`) | `api.request` appelé avec un `params.path` invalide    | message explicite (l'appel est malformé)                |
-| `-32000` | le pont API (`RealtimeController.ts#RealtimeController.invokeApiRequest`)                    | la route invoquée REFUSE : 401, 403, 404, 405, **422** | le message, `data.status` — et `data.fields` sur un 422 |
-
-Un refus de la route invoquée par le pont garde la forme d'un `fetch` dont `ok` est faux : le statut HTTP voyage dans `data.status`. Une erreur de validation — `ZodError` levée par l'action, ou entrée refusée par le `schema` de la route — est un **422** dont `data.fields` nomme chaque champ et sa partie (`{ field, message, in }`), exactement le `error.fields` du même appel en HTTP. Tout autre `throw` reste opaque (`-32603`).
+| Code     | Émis par                                                                                     | Déclencheur                                                 | Ce que voit le pair                                                                                      |
+| -------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `-32601` | `JsonRpcPeer.handleRequest()` (`JsonRpcPeer.ts#JsonRpcPeer.handleRequest`)                   | requête vers une action non enregistrée                     | `method not found: <nom>`                                                                                |
+| `-32603` | même méthode (`JsonRpcPeer.ts#JsonRpcPeer.handleRequest`)                                    | le handler a levé une exception **ordinaire**               | `internal error` — générique, rien d'autre                                                               |
+| `-32001` | le refus du verrou de frame (`JsonRpcPeer.ts#JsonRpcPeer.receive`)                           | `beforeDispatch` a dit non **sur une requête**              | `unauthorized`, sans jamais dire pourquoi                                                                |
+| `-32000` | défaut du constructeur de `RpcError` (`JsonRpcPeer.ts#RpcError`)                             | le handler expose volontairement son refus                  | le message ET le `data` choisis par le handler                                                           |
+| `-32602` | le pont API, via `RpcError` (`RealtimeController.ts#RealtimeController.actionParamsWrapper`) | `api.request` appelé avec un `params.path` invalide         | message explicite (l'appel est malformé)                                                                 |
+| `-32000` | le pont API (`RealtimeController.ts#RealtimeController.invokeApiRequest`)                    | la route invoquée REFUSE : 401, 403, 404, 405, **422**, 429 | le message, `data.status` — `data.fields` sur un 422, `data.retryAfter` si l'action a posé `Retry-After` |
+
+Un refus de la route invoquée par le pont garde la forme d'un `fetch` dont `ok` est faux : le statut HTTP voyage dans `data.status`. Une erreur de validation — `ZodError` levée par l'action, ou entrée refusée par le `schema` de la route — est un **422** dont `data.fields` nomme chaque champ et sa partie (`{ field, message, in }`), exactement le `error.fields` du même appel en HTTP. Un refus passager (429, 503) dont l'action a posé `Retry-After` (RFC 9110 §10.2.3) porte l'attente dans `data.retryAfter`, en secondes — une date HTTP y est ramenée à l'écart : une socket ouverte n'a plus d'en-tête, et le même code de contrôleur (`this.response?.setHeader("Retry-After", n)` puis le refus) sert les deux transports. Seul cet en-tête traverse : rien d'autre posé par l'action ne fuit sur une trame. Tout autre `throw` reste opaque (`-32603`).
 
 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>`

package/docs/securite.md

@@ -449,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
@@ -474,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`).
@@ -494,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                                            |
 | --------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------- |
@@ -504,14 +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
+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 par `RealtimeService.resolveChannelPolicy()`
-(`RealtimeService.ts#RealtimeService.resolveChannelPolicy`).
+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
 
@@ -808,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).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodefony/realtime",
-  "version": "10.0.0-beta.6",
+  "version": "10.0.0-beta.7",
   "nodefony": {
     "configSchema": "./dist/nodefony/config/configSchema.js"
   },
@@ -44,27 +44,27 @@
     "esm"
   ],
   "peerDependencies": {
-    "@nodefony/framework": "^10.0.0-beta.6",
-    "@nodefony/http": "^10.0.0-beta.6",
-    "nodefony": "^10.0.0-beta.6",
+    "@nodefony/framework": "^10.0.0-beta.7",
+    "@nodefony/http": "^10.0.0-beta.7",
+    "nodefony": "^10.0.0-beta.7",
     "reflect-metadata": "0.2.2",
     "zod": "^4.6.7"
   },
   "devDependencies": {
-    "@nodefony/drizzle": "^10.0.0-beta.5",
-    "@nodefony/framework": "^10.0.0-beta.6",
-    "@nodefony/http": "^10.0.0-beta.6",
-    "@nodefony/orm-core": "^10.0.0-beta.5",
-    "@nodefony/security": "^10.0.0-beta.5",
+    "@nodefony/drizzle": "^10.0.0-beta.6",
+    "@nodefony/framework": "^10.0.0-beta.7",
+    "@nodefony/http": "^10.0.0-beta.7",
+    "@nodefony/orm-core": "^10.0.0-beta.6",
+    "@nodefony/security": "^10.0.0-beta.6",
     "@types/node": "26.6.6",
     "@vitest/coverage-v8": "5.1.0",
-    "nodefony": "^10.0.0-beta.6",
+    "nodefony": "^10.0.0-beta.7",
     "reflect-metadata": "0.2.2",
     "vitest": "5.1.0"
   },
   "private": false,
   "engines": {
-    "node": ">=24.14.0"
+    "node": "^24.16.0 || >=26.0.0"
   },
   "license": "Apache-2.0",
   "dependencies": {
@@ -83,7 +83,7 @@
     "url": "git+https://github.com/nodefony/nodefony-core.git",
     "directory": "src/packages/@nodefony/realtime"
   },
-  "homepage": "https://nodefony.github.io/nodefony-core/",
+  "homepage": "https://nodefony.net/",
   "bugs": {
     "url": "https://github.com/nodefony/nodefony-core/issues"
   }