@nodefony/realtime 10.0.0-beta.1 → 10.0.0-beta.3

package/dist/types/nodefony/decorators/realtimeDecorators.d.ts

@@ -140,8 +140,25 @@ export declare function RealtimeChannel(channel: string, policy?: IChannelPolicy
  *   }
  */
 export declare function RealtimeInbound(method: string, policy?: IChannelPolicy): MethodDecorator;
-/** Lecture (lazy, au handshake) du registre des actions décorées. */
-export declare function getRealtimeActions(instance: object): Record<string, RpcActionHandler> | null;
+/**
+ * Méthode d'action liée à son instance, appelable avec ses arguments réels —
+ * plusieurs quand ses paramètres sont décorés (`@Body`, `@CurrentUser`…).
+ */
+export type RealtimeActionMethod = (...args: unknown[]) => unknown;
+/**
+ * Enveloppe posée sur une action décorée au handshake : reçoit la méthode liée
+ * et son nom de propriété, rend le handler JSON-RPC à enregistrer.
+ */
+export type RealtimeActionWrapper = (method: RealtimeActionMethod, propertyKey: string | symbol) => RpcActionHandler;
+/**
+ * Lecture (lazy, au handshake) du registre des actions décorées.
+ *
+ * @param instance - le contrôleur de la connexion
+ * @param wrap - enveloppe optionnelle de chaque action (résolution des
+ *   paramètres décorés) ; sans elle, l'action reçoit la charge JSON-RPC brute
+ * @returns les handlers par nom d'action, ou `null` si aucune n'est décorée
+ */
+export declare function getRealtimeActions(instance: object, wrap?: RealtimeActionWrapper): Record<string, RpcActionHandler> | null;
 /** Lecture (lazy, au handshake) du registre des canaux décorés. */
 export declare function getRealtimeChannels(instance: object): Record<string, RealtimeChannelFactory> | null;
 /** Lecture (lazy, au handshake) du registre des canaux inbound décorés. */

package/dist/types/nodefony/interfaces/IRealtimeController.d.ts

@@ -22,7 +22,7 @@ export type RealtimeInboundHandler = (params: unknown, reply: (payload: unknown)
  * (Les hooks `realtimeActions()` / `realtimeChannels()` sont `protected` sur la base
  * — détail d'implémentation surchargeable, hors contrat public.)
  *
- * Côté client, le pendant n'est PAS un controller mais `RealtimeClient` — tous deux
+ * Côté client, le pendant n'est PAS un controller mais `NodefonySocket` — tous deux
  * composent le même peer ; cf vision « la socket Nodefony ».
  */
 export interface IRealtimeController {

package/dist/types/nodefony/interfaces/IRealtimeHandshake.d.ts

@@ -12,7 +12,7 @@
  * @see IRealtimeAuthenticator
  */
 export interface IRealtimeHandshake {
-    /** En-têtes de la requête upgrade (clés en lowercase RFC 7230 §3.2). */
+    /** En-têtes de la requête upgrade (clés en lowercase RFC 9110 §5.1). */
     readonly headers: Readonly<Record<string, string | string[] | undefined>>;
     /** Cookies parsés depuis `Cookie:` (vide si en-tête absent ou mal formé). */
     readonly cookies: ReadonlyMap<string, string>;

package/dist/types/nodefony/src/backplane/RedisBackplane.d.ts

@@ -83,6 +83,13 @@ export interface IRedisSubscriber {
  * Le listener Redis est conservé pour un `unsubscribe(channel, listener)` ciblé
  * (n'arrache pas d'éventuels autres abonnés du même client).
  */
+/**
+ * Vrai si la valeur expose la surface d'un client Redis publisher — vérifié au
+ * démarrage, sur le client que rend le service `redis`.
+ */
+export declare function isRedisPublisher(value: unknown): value is IRedisPublisher;
+/** Vrai si la valeur expose la surface d'un client Redis subscriber dédié. */
+export declare function isRedisSubscriber(value: unknown): value is IRedisSubscriber;
 export declare function createRedisServiceTransport(publisher: IRedisPublisher, subscriber: IRedisSubscriber): IRedisBackplaneTransport;
 /**
  * Réglages optionnels du driver — regroupés en objet pour ne pas allonger une

package/dist/types/nodefony/src/backplane/bootNotices.d.ts

@@ -0,0 +1,25 @@
+import type { IBootNotice } from "nodefony";
+/**
+ * Le temps réel ne dépasse pas ce processus : aucun backplane actif (driver
+ * `loopback`, `cluster` hors d'un worker, ou fabrique inactive ici).
+ *
+ * Simple information en développement mono-processus — c'est le cas normal —
+ * mais à savoir avant de déployer plusieurs exemplaires : un message publié
+ * sur l'un n'atteindrait pas les clients connectés aux autres.
+ *
+ * @param driver - le driver déclaré.
+ * @returns le point à déclarer.
+ */
+export declare function realtimeLocalOnlyNotice(driver: string): IBootNotice;
+/**
+ * Le backplane déclaré n'a pas pu démarrer — le hub est retombé en local.
+ *
+ * Distinct de {@link realtimeLocalOnlyNotice} : ici, l'application a DEMANDÉ
+ * un fan-out entre exemplaires et ne l'a pas. Deux pods servent alors deux
+ * mondes temps réel disjoints, sans erreur visible.
+ *
+ * @param driver - le driver déclaré.
+ * @param reason - la cause (message de l'échec).
+ * @returns le point à déclarer.
+ */
+export declare function realtimeBackplaneDownNotice(driver: string, reason: string): IBootNotice;

package/dist/types/nodefony/src/guards.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Gardes de type internes au paquet — elles remplacent une conversion (`as`)
+ * par une vérification faite à l'exécution, pour qu'une valeur d'une autre
+ * forme soit écartée au lieu de traverser le code sous un type qui ment.
+ *
+ * Non exportées par le paquet : ce sont des détails d'implémentation.
+ */
+/**
+ * Vrai si la valeur est un objet non nul : ses propriétés se lisent alors,
+ * typées `unknown`, et chacune se vérifie avant usage.
+ *
+ * @param value - valeur venue du réseau, d'une métadonnée ou du conteneur
+ * @returns `true` pour tout objet (tableau compris), `false` pour `null` et les primitives
+ */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * Vrai si la valeur est une fonction. Toute fonction JavaScript s'appelle avec
+ * n'importe quels arguments et rend une valeur inconnue : la signature annoncée
+ * ne promet rien de plus que ce que `typeof` a vérifié.
+ *
+ * @param value - valeur lue par son nom (métadonnée, propriété dynamique)
+ * @returns `true` si la valeur est appelable
+ */
+export declare function isCallable(value: unknown): value is (...args: unknown[]) => unknown;
+/**
+ * Vrai si la valeur se comporte comme une promesse (transport asynchrone) —
+ * un client Redis rend une promesse, un faux transport de test rend `void`.
+ *
+ * @param value - retour d'un transport
+ * @returns `true` si la valeur porte une méthode `then`
+ */
+export declare function isThenable(value: unknown): value is Promise<unknown>;

package/dist/types/nodefony/src/server/AnonymousRealtimeToken.d.ts

@@ -1,3 +1,16 @@
 import type { IRealtimeToken } from "../../interfaces/IRealtimeToken.js";
+/**
+ * Token realtime ANONYME — fallback Zero Trust quand aucun matcher
+ * `IRealtimeAuthenticatorMatcher` ne capture le handshake.
+ *
+ * Singleton gelé (`Object.freeze`) — 0 alloc par connexion non authentifiée.
+ * Aligné sur le pattern `AnonymousToken` de `@nodefony/security` S1 (même
+ * surface logique, type `"anonymous"`, `roles = ["ROLE_ANONYMOUS"]`).
+ *
+ * Stocké par le hub sur la map `peer → token` au handshake si aucun
+ * authenticator ne capture la connexion. Les voters P6 (futur) verront un
+ * token avec `isAuthenticated() === false` et appliqueront leur politique
+ * (Zero Trust : zone protégée → frame refusée par `beforeDispatch`).
+ */
 export declare const ANONYMOUS_REALTIME_TOKEN: IRealtimeToken;
 export default ANONYMOUS_REALTIME_TOKEN;

package/dist/types/nodefony/src/server/RealtimeController.d.ts

@@ -11,7 +11,7 @@ import type { IRealtimeController, RealtimePublish, RealtimeInboundHandler } fro
  * — écrit UNE fois, partagé par tous les modules. Un contrôleur concret ne déclare que
  * son métier : {@link createRealtimeChannel} (providers de canaux) + {@link realtimeActions}.
  *
- * Chaque connexion compose un `JsonRpcPeer` (le MÊME que `RealtimeClient` côté navigateur
+ * Chaque connexion compose un `JsonRpcPeer` (le MÊME que `NodefonySocket` côté navigateur
  * — symétrie isomorphe) branché sur un {@link WsConnectionTransport}.
  *
  * Usage : le sous-classe garde sa route WS et délègue —
@@ -111,13 +111,13 @@ export declare abstract class RealtimeController<Emit extends EventsMap = Defaul
      * est structurel, pas un choix : c'est au client d'attendre `realtime:welcome`
      * avant de pousser.
      *
-     * ⚠️ Cette phrase a longtemps ajouté « ce que `RealtimeClient` fait nativement ».
+     * ⚠️ Cette phrase a longtemps ajouté « ce que le client fait nativement ».
      * C'était FAUX : le client rejouait ses abonnements dès l'ouverture de la socket,
      * si bien qu'un `subscribe` posé avant le démarrage et TOUS ceux d'après une
      * reconnexion étaient perdus ici même, sans un mot des deux côtés. Un contrat écrit
      * d'un seul côté du fil n'est pas tenu ; il l'est désormais par
-     * `RealtimeClient.replaySubscriptions` et les deux cas « la fenêtre où le serveur
-     * écoute (welcome) » de `RealtimeClientCoverage.test.ts`.
+     * `NodefonySocket.replaySubscriptions` et les deux cas « la fenêtre où le serveur
+     * écoute (welcome) » de `NodefonySocketCoverage.test.ts`.
      */
     protected handleRealtime(message: string | Buffer | null): void;
     /**
@@ -166,6 +166,26 @@ export declare abstract class RealtimeController<Emit extends EventsMap = Defaul
     private onRealtimeNotification;
     /** Abonne la connexion à un canal via le hub partagé (idempotent par connexion). */
     private startChannel;
+    /**
+     * Enveloppe des actions `@RealtimeAction` dont un paramètre est décoré
+     * (`@Body`, `@CurrentUser`…) : l'action reçoit ses arguments comme une route,
+     * résolus par la fonction du framework et non par une copie.
+     *
+     * L'identité ne change PAS : un message est déjà traité dans la bulle
+     * `RequestContext` du handshake (`WebsocketContext` lie son écouteur par
+     * `AsyncResource.bind`), où le pare-feu a posé `user` et `token`. La bulle
+     * ouverte ici HÉRITE de ce store et n'y ajoute que la charge (`body`, que
+     * `@Body` lit dans l'ALS comme pour `api.request`) — une écriture
+     * `RequestContext.set()` dans l'action reste ainsi propre à l'appel.
+     *
+     * Une action sans paramètre décoré est rendue telle quelle : rien ne change
+     * pour elle, ni comportement ni coût. Les métadonnées se lisent ICI, une fois
+     * par connexion.
+     *
+     * @param ctx - le contexte de la connexion
+     * @returns l'enveloppe passée à {@link getRealtimeActions}
+     */
+    private actionParamsWrapper;
     /**
      * Handler de la méthode RPC `api.request {path}` — le **pont API souverain**
      * (POC Ph.3) : résout le path porté par le message via le Router

package/dist/types/nodefony/src/server/RealtimeHub.d.ts

@@ -71,16 +71,13 @@ export declare const RESERVED_SYSTEM_PREFIXES: readonly ["nodefony:"];
  */
 export declare const isReservedSystemChannel: typeof isPlatformChannel;
 /**
- * Période de re-validation des identités RÉVOCABLES — F4 (revue 0.6).
- * Le verrou de frame est SYNC par doctrine (identité figée au handshake, cf
- * {@link FrameAuthorizer}) → il ne peut pas re-lire la session par frame. Un socket
- * survivrait donc à sa session (`subscribe` garderait ses flux après un logout HTTP),
- * là où `api.request` re-valide déjà par requête (`isValid()`). Ce tick ferme
- * l'écart : toutes les `REVOCATION_REVALIDATE_MS`, les tokens révocables sont
- * re-validés et la connexion fermée si l'identité n'est plus valide (≤ 1 fenêtre de
- * délai). Ordre de grandeur aligné sur le heartbeat WS (`keepaliveInterval` 20 s).
+ * Période de re-validation des identités RÉVOCABLES — F4 (revue 0.6). Le verrou
+ * de frame est SYNC (identité figée au handshake) : ce tick ferme l'écart avec
+ * `api.request`, qui re-valide par requête. Définie par le cœur, qui porte le
+ * registre partagé avec les flux SSE ; ré-exportée ici pour les consommateurs
+ * du hub.
  */
-export declare const REVOCATION_REVALIDATE_MS = 30000;
+export { REVOCATION_REVALIDATE_MS } from "nodefony";
 /**
  * Le MOTIF de famille d'un canal — son dernier segment remplacé par `*`.
  *
@@ -156,7 +153,7 @@ export type ChannelFactory = (channel: string, publish: RealtimePublish) => (()
  * multiplexe des canaux ; le hub aiguille entre les sockets. La façade *consommateur*
  * côté serveur EXISTE — {@link ServerRealtimeSocket} (`subscribe/on/publish`), exportée
  * par le barrel du module : c'est elle qu'un service back tient, jamais ce hub
- * directement. Même rôle que `RealtimeClient` côté navigateur.
+ * directement. Même rôle que `NodefonySocket` côté navigateur.
  */
 export declare class RealtimeHub {
     #private;
@@ -288,14 +285,23 @@ export declare class RealtimeHub {
      */
     unregisterRevocable(entry: IRevocableConnection): void;
     /**
-     * Tick de re-validation (F4) : re-lit l'identité de chaque connexion révocable
-     * (`token.isValid()`) et FERME la socket (`4001`) si l'identité est morte : session
-     * détruite ou passée à un autre compte, jeton expiré ou révoqué.
-     * Fail-closed : une re-validation qui throw ferme aussi (parité `invokeApiRequest`).
-     * Snapshot du registre AVANT les `await` (le `close` mute le registre via le cleanup
-     * `onFinish`). Exposé (public) pour un test déterministe sans fake timers.
+     * Re-valide toutes les connexions révocables et ferme (`4001`) celles dont
+     * l'identité est morte : session détruite ou passée à un autre compte, jeton
+     * expiré ou révoqué. Fail-closed : une re-validation qui lève ferme aussi. Le
+     * registre est celui des flux SSE ({@link RevocationWatch}) — une garde, deux
+     * transports. Exposé (public) pour un test déterministe sans faux minuteur.
      */
     revalidateRevocable(): Promise<void>;
+    /**
+     * Ferme tout de suite les connexions qui ont figé cette identité — ses droits
+     * ont changé (`IDENTITY_CHANGED_EVENT`). Code {@link IDENTITY_REFRESH_CLOSE_CODE},
+     * reconnectable : le client revient avec ses rôles frais. Le registre est
+     * celui des flux SSE — une règle, deux transports.
+     *
+     * @param identifier - identifiant de connexion de l'identité changée.
+     * @returns le nombre de connexions fermées.
+     */
+    refreshIdentity(identifier: string): number;
     /**
      * Compte une frame entrante full-duplex (canaux gated SIP/bridge). Appelé par le
      * contrôleur quand un handler `realtimeInbound` traite un message client.

package/dist/types/nodefony/src/service/RealtimeService.d.ts

@@ -2,7 +2,7 @@ import { Service, Module, type JsonRpcPeer } from "nodefony";
 import { type RealtimeHub, type ChannelFactory, type ChannelSink, type FrameAuthorizer } from "../server/RealtimeHub.js";
 import type { IBackplane } from "../../interfaces/IBackplane.js";
 import type { IRealtimeProbe } from "../../interfaces/IRealtimeProbe.js";
-import type { IRealtimeConfig } from "../../config/defineModuleConfig.js";
+import { type IRealtimeConfig } from "../../config/defineModuleConfig.js";
 import type { IRealtimeAuthenticator } from "../../interfaces/IRealtimeAuthenticator.js";
 import type { IRealtimeAuthenticatorMatcher } from "../../interfaces/IRealtimeAuthenticatorMatcher.js";
 import type { IRealtimeToken } from "../../interfaces/IRealtimeToken.js";

package/dist/types/nodefony/testing/index.d.ts

@@ -12,7 +12,7 @@
  *
  * Le harnais pilote le **côté serveur** : il injecte des frames JSON-RPC 2.0
  * telles qu'un client les enverrait, et lit celles qui sortent. Il n'embarque
- * PAS `RealtimeClient` — le client est un artefact navigateur du cœur, et le
+ * PAS `NodefonySocket` — le client est un artefact navigateur du cœur, et le
  * tirer ici le ferait entrer dans le paquet serveur publié. Ce qu'on veut
  * prouver d'un controller (ses canaux, ses actions, son plein-duplex, son
  * nettoyage) s'observe entièrement aux frames.
@@ -29,7 +29,7 @@
  *
  * @packageDocumentation
  */
-import type { IRealtimeDenied } from "nodefony";
+import { type IRealtimeDenied } from "nodefony";
 import type { ContextType } from "@nodefony/http";
 import type { RealtimeController } from "../src/server/RealtimeController.js";
 import { type RealtimeHub, type FrameAuthorizer } from "../src/server/RealtimeHub.js";

package/docs/actions.md

@@ -117,7 +117,7 @@ attendre trop longtemps et repartir.
 
 Techniquement, ce numéro est le champ `id` de la frame JSON-RPC 2.0. Le pair l'attribue, garde
 l'appel en attente dans une table, arme une minuterie, et résout la `Promise` quand la réponse
-portant cet `id` revient (`JsonRpcPeer.handleResponse()`, `JsonRpcPeer.ts:556`). Une frame sans
+portant cet `id` revient (`JsonRpcPeer.handleResponse()`, `JsonRpcPeer.ts:579`). Une frame sans
 `id` ne crée aucune de ces trois choses — c'est pourquoi une publication ne coûte rien au repos.
 
 ## La vision Nodefony — un nom, un handler, une découverte
@@ -126,18 +126,18 @@ Trois partis pris distinguent les actions Nodefony d'une couche RPC classique.
 
 **Il n'y a pas de couche RPC séparée.** Une action est une **méthode de contrôleur**, dans la même
 classe que tes canaux et — si tu le veux — que tes routes HTTP. Pas de service dédié, pas de
-schéma à compiler : `@RealtimeAction("orders:quote")` (`realtimeDecorators.ts:101`) suffit, et le
+schéma à compiler : `@RealtimeAction("orders:quote")` (`realtimeDecorators.ts:191`) suffit, et le
 retour de la méthode devient le `result` de la réponse.
 
 **Le contrat du handler est minuscule, volontairement.** Une action reçoit **un seul argument**,
 les paramètres bruts du client, et rend une valeur — `RpcActionHandler`
-(`JsonRpcPeer.ts:118`). Pas de contexte injecté dans la signature : le `this` est lié à
+(`JsonRpcPeer.ts:153`). Pas de contexte injecté dans la signature : le `this` est lié à
 l'instance du contrôleur au handshake, ce qui donne accès au noyau, aux services et à la
 connexion sans élargir le contrat.
 
 **L'endpoint s'annonce lui-même.** La liste des actions exposées voyage dans la frame d'accueil —
 `IRealtimeWelcome` (`RealtimeController.ts:12`) — et se lit côté client par
-`RealtimeClient.serverMethods` (`RealtimeClient.ts:597`). Une interface n'écrit donc jamais un nom d'action en dur : elle
+`NodefonySocket.serverMethods` (`NodefonySocket.ts:800`). Une interface n'écrit donc jamais un nom d'action en dur : elle
 n'active un bouton que si le serveur a déclaré savoir le servir.
 
 **Le compromis, dit franchement** : une action est **un aller-retour**, point. Elle ne diffuse pas,
@@ -199,7 +199,7 @@ export default OrdersRealtimeController;
 
 ```ts
 // frontend/src/orders.ts
-import { RealtimeClient } from "nodefony/client";
+import { NodefonySocket } from "nodefony/client";
 
 interface IQuote {
   orderId: string;
@@ -207,7 +207,7 @@ interface IQuote {
   currency: string;
 }
 
-const socket = RealtimeClient.shared({
+const socket = NodefonySocket.shared({
   url: "wss://127.0.0.1:5152/orders/realtime",
 });
 
@@ -276,18 +276,18 @@ Le trajet complet d'une requête, des étapes qu'elle traverse aux branches par
 
 | Voie                                                   | Quand la choisir                                            |
 | ------------------------------------------------------ | ----------------------------------------------------------- |
-| `@RealtimeAction("nom")` (`realtimeDecorators.ts:101`) | le cas courant — un nom fixe, une méthode, déclaratif       |
-| `realtimeActions()` (`RealtimeController.ts:236`)      | la table est **calculée** (noms dynamiques, boucle, config) |
+| `@RealtimeAction("nom")` (`realtimeDecorators.ts:191`) | le cas courant — un nom fixe, une méthode, déclaratif       |
+| `realtimeActions()` (`RealtimeController.ts:281`)      | la table est **calculée** (noms dynamiques, boucle, config) |
 
 Les deux sont fusionnées au handshake, et **l'override gagne** en cas de conflit de nom : une
 classe peut ainsi remplacer une action héritée sans toucher au parent
-(`RealtimeController.ts:453`). Un endpoint sans aucune action ne paie rien — la table du pair est
+(`RealtimeController.ts:598`). Un endpoint sans aucune action ne paie rien — la table du pair est
 allouée au premier enregistrement seulement.
 
 ### Ce que ton `return` et ton `throw` deviennent sur le fil
 
 Le retour du handler est envoyé tel quel en `result`. Les erreurs, elles, suivent une règle Zero
-Trust stricte, appliquée dans `JsonRpcPeer.handleRequest()` (`JsonRpcPeer.ts:499`) :
+Trust stricte, appliquée dans `JsonRpcPeer.handleRequest()` (`JsonRpcPeer.ts:526`) :
 
 | Côté serveur                    | Ce que reçoit le client                  | Pourquoi                                        |
 | ------------------------------- | ---------------------------------------- | ----------------------------------------------- |
@@ -299,7 +299,7 @@ Trust stricte, appliquée dans `JsonRpcPeer.handleRequest()` (`JsonRpcPeer.ts:49
 
 > [!WARNING]
 > **Le temps réel n'a qu'UNE erreur, et elle vient du cœur.** Pour choisir ce que voit le client,
-> c'est `RpcError` (`JsonRpcPeer.ts:71`), importée depuis `nodefony` — son `code` est un entier
+> c'est `RpcError` (`JsonRpcPeer.ts:101`), importée depuis `nodefony` — son `code` est un entier
 > JSON-RPC et son `data` traverse le fil. Toute autre exception donne un `-32603` opaque. Ne pas
 > chercher d'erreur maison dans `@nodefony/realtime` : il n'y en a pas, et
 > `tests/unit/errorSurface.test.ts` refuse d'en exporter une que personne ne lève.
@@ -360,21 +360,55 @@ donc réservée, quoi qu'en dise son décorateur. À savoir avant de nommer une
 
 Pour exiger un rôle sur tes propres actions, on déclare une règle de préfixe dans la
 configuration de sécurité — la même liste que pour les canaux
-(`realtimeChannels`, `security/nodefony/config/config.ts:1130`) :
+(`realtimeChannels`, `security/nodefony/config/config.ts:1447`) :
 
 ```ts ignore
 use("@nodefony/security", {
   realtimeChannels: [
     // Couvre AUSSI bien le canal `orders:feed` que l'action `orders:quote` :
     // le verrou résout une politique par NOM, sans savoir ce qu'il garde.
-    {
-      prefix: "orders:",
-      policy: { authenticated: true, roles: ["ROLE_USER"] },
-    },
+    { pattern: "orders:", authenticated: true, roles: ["ROLE_USER"] },
   ],
 });
 ```
 
+### Savoir QUI appelle — `@CurrentUser` et les paramètres décorés
+
+Une action authentifiée sait que l'appelant est identifié ; elle peut aussi savoir **qui** il est.
+Les décorateurs de paramètres d'une route y prennent le même sens
+(`actionParamsWrapper`, `RealtimeController.ts:1007`) :
+
+```ts ignore
+import { Body, CurrentUser } from "@nodefony/framework";
+import type { IUser } from "@nodefony/user";
+
+// Le client : socket.request("chat:send", { text: "salut" })
+@RealtimeAction("chat:send")
+send(@Body("text") text: string, @CurrentUser() user: IUser) {
+  // L'auteur vient du SERVEUR : le client ne peut pas mentir dessus.
+  return { author: user.identifier, text };
+}
+```
+
+| Décorateur                                | Ce qu'il reçoit dans une action                             |
+| ----------------------------------------- | ----------------------------------------------------------- |
+| `@Body()` / `@Body("clé")`                | la charge de l'appel (`params`), ou l'une de ses clés       |
+| `@CurrentUser()`                          | l'utilisateur de la connexion, `undefined` pour un anonyme  |
+| `@Query()` / `@Param()`                   | un objet vide — une action n'a ni URL ni variables de route |
+| `@Headers()` / `@Cookie()` / `@Session()` | ceux de la requête d'ouverture de la socket                 |
+
+Une action **sans** paramètre décoré reçoit la charge brute en premier argument, comme avant —
+rien ne change pour elle, ni comportement ni coût.
+
+> [!IMPORTANT]
+> **L'identité est celle de l'ouverture de la socket.** Elle n'est pas relue à chaque appel : le
+> hub la revalide toutes les 30 secondes (`REVOCATION_REVALIDATE_MS`, `RealtimeHub.ts:112`) et
+> ferme la socket en `4001` si la session est morte (`RealtimeHub.ts:842`). Après une
+> déconnexion, une action peut donc encore voir l'ancien utilisateur pendant cette fenêtre. Pour
+> une écriture sensible — paiement, droits, suppression — passe par une route
+> `POST + WEBSOCKET` appelée par `socket.mutate()` : ce pont revalide l'identité à **chaque**
+> appel et porte la clé d'idempotence.
+
 ### La règle DEV-only
 
 Une action réservée au développement se contrôle **dans le handler, côté serveur** — jamais par un
@@ -394,7 +428,7 @@ drapeau d'interface. Cacher un bouton n'empêche personne de forger la frame. Le
 ### Le délai d'expiration est la seule libération automatique
 
 `request()` prend le délai en **troisième argument positionnel**, en millisecondes — il n'y a pas
-d'objet d'options (`RealtimeClient.request()`, `RealtimeClient.ts:727`) :
+d'objet d'options (`NodefonySocket.request()`, `NodefonySocket.ts:936`) :
 
 ```ts ignore
 await socket.request("orders:quote", { orderId }); // 30 000 ms par défaut
@@ -403,12 +437,12 @@ await socket.request("orders:export", { scope }, 120_000); // action longue
 
 | Défaut    | Valeur    | Ancrage              |
 | --------- | --------- | -------------------- |
-| `request` | 30 000 ms | `JsonRpcPeer.ts:319` |
+| `request` | 30 000 ms | `JsonRpcPeer.ts:353` |
 
 À l'expiration, l'entrée en attente est **retirée** et la `Promise` rejetée avec
-`RPC timeout: <méthode>` (`JsonRpcPeer.ts:455`). Conséquence à connaître : une réponse qui
+`RPC timeout: <méthode>` (`JsonRpcPeer.ts:502`). Conséquence à connaître : une réponse qui
 arriverait après coup ne trouve plus personne et est ignorée en silence
-(`JsonRpcPeer.ts:539`) — pas de résolution tardive, pas de fuite.
+(`JsonRpcPeer.ts:584`) — pas de résolution tardive, pas de fuite.
 
 ### Abandonner : ce qui existe vraiment
 
@@ -422,8 +456,8 @@ Trois leviers existent, et ils ne font pas la même chose :
 
 1. **Le délai d'expiration** — libère le client, laisse le serveur travailler.
 2. **La fermeture de la connexion** — `dispose()` rejette **tous** les appels en attente d'un
-   coup (`JsonRpcPeer.ts:453`), appelé au nettoyage de la socket
-   (`RealtimeController.ts:553`). Là encore : côté client seulement.
+   coup (`JsonRpcPeer.ts:480`), appelé au nettoyage de la socket
+   (`RealtimeController.ts:749`). Là encore : côté client seulement.
 3. **Une action compagnon** — la seule vraie annulation. On expose une seconde action qui prend
    l'identifiant du travail et l'interrompt côté serveur. Le modèle du dépôt est
    `nodefony:scaffold:cancel` (`StudioRealtimeController.ts:159`), pendant de `nodefony:scaffold:run`.
@@ -444,7 +478,7 @@ fois ? »**.
 | une mutation (`socket.mutate`) | **non** par nature             | oui, **avec une clé d'idempotence**  |
 
 Pour les mutations passant par le pont API, la clé n'est pas une convention : elle est **exigée
-par la signature** de `mutate()` (`RealtimeClient.ts:797`), et c'est la garde `@Idempotent`
+par la signature** de `mutate()` (`NodefonySocket.ts:1009`), et c'est la garde `@Idempotent`
 (`routerDecorators.ts:1171`) qui, côté serveur, reconnaît le rejeu et rend la réponse déjà calculée
 au lieu de refaire l'effet.
 
@@ -485,7 +519,7 @@ prudente est donc de **s'abonner avant** de lancer l'appel.
 
 Nodefony a choisi la garantie côté serveur plutôt que la discipline côté client : le producteur du
 canal **rejoue son historique** au nouvel abonné, de sorte qu'un arrivant tardif voit tout depuis
-le début (`ScaffoldService.subscribe()`, `ScaffoldService.ts:425`). C'est ce qui autorise le front
+le début (`ScaffoldService.subscribe()`, `ScaffoldService.ts:456`). C'est ce qui autorise le front
 à faire l'appel d'abord et à s'abonner ensuite, sans rien perdre.
 
 > [!TIP]
@@ -495,7 +529,7 @@ le début (`ScaffoldService.subscribe()`, `ScaffoldService.ts:425`). C'est ce qu
 
 ### Et le streaming du protocole ?
 
-**Il n'y en a pas.** Une action rend **une** valeur (`RpcActionHandler`, `JsonRpcPeer.ts:118`), que
+**Il n'y en a pas.** Une action rend **une** valeur (`RpcActionHandler`, `JsonRpcPeer.ts:153`), que
 le pair emballe en une réponse unique. Pour tout ce qui progresse — une réponse mot à mot d'un
 modèle de langage, un export qui avance, un traitement long — la voie est le motif
 **« travail + canal »** : l'action accuse réception, et la progression arrive sur un canal.
@@ -510,32 +544,32 @@ il sera conçu avec son premier consommateur réel.
 Un cas particulier mérite d'être connu avant d'écrire une action : **elle existe peut-être déjà en
 HTTP**. Le pont API expose la méthode `api.request`, qui rejoue une route de contrôleur sur la
 socket, avec la même garde et le même résultat qu'en REST — `invokeApiRequest()`
-(`RealtimeController.ts:949`). Il est **désactivé par défaut** et s'active en surchargeant
-`realtimeApiRequest()` (`RealtimeController.ts:276`).
+(`RealtimeController.ts:1070`). Il est **désactivé par défaut** et s'active en surchargeant
+`realtimeApiRequest()` (`RealtimeController.ts:321`).
 
 ```ts ignore
 const modules = await socket.request("/nodefony/kernel/api/modules");
 ```
 
 La forme se discrimine toute seule : un chemin commence par `/`, jamais un nom d'action —
-`RealtimeClient.request()` (`RealtimeClient.ts:727`). Écris une action RPC pour ce qui n'a de sens **que** sur la socket ;
+`NodefonySocket.request()` (`NodefonySocket.ts:936`). Écris une action RPC pour ce qui n'a de sens **que** sur la socket ;
 passe par le pont pour tout ce qui est déjà une route. Le détail du pont vit dans le
 [vocabulaire](./vocabulaire.md) et l'[architecture](./architecture.md).
 
 ## ⚠️ Pièges
 
-| Symptôme                                                     | Cause                                                                              | Correction                                                                         |
-| ------------------------------------------------------------ | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
-| `RPC timeout: <méthode>` alors que le serveur a bien répondu | le handler dure plus que 30 s, le défaut                                           | passer le délai en **3ᵉ argument** : `request(m, p, 120_000)`                      |
-| Le client attend indéfiniment, aucune erreur                 | le handler ne rend jamais (il publie au lieu de retourner) — pas de frame `result` | toujours `return` une valeur ; publier **en plus**, jamais **à la place**          |
-| `-32601 method not found`                                    | nom mal orthographié, ou action déclarée sur un **autre** endpoint                 | vérifier `socket.serverMethods` — c'est la liste réelle de CETTE connexion         |
-| `-32603 internal error` sans détail                          | un `throw` ordinaire est rendu opaque au client (Zero Trust)                       | lever une `RpcError` avec un code et un message publiables                         |
-| `-32001 unauthorized` sur une action légitime                | le nom commence par `nodefony:`, le namespace réservé à la plateforme              | renommer hors de `nodefony:`, ou obtenir `ROLE_NODEFONY_ADMIN`                     |
-| Une action sensible est appelable par un anonyme             | une action applicative est **libre** tant qu'aucune politique ne la couvre         | ajouter une règle de préfixe (`security/nodefony/config/config.ts:906`)            |
-| Un travail relancé crée deux jobs                            | action non idempotente rejouée après une reconnexion                               | action compagnon d'annulation, ou identifiant fourni par l'appelant + mémorisation |
-| `abort()` introuvable sur la socket                          | il n'existe pas — et n'arrêterait pas le serveur de toute façon                    | exposer une action d'annulation qui prend l'identifiant du travail                 |
-| Les premières lignes d'un job manquent                       | abonnement au canal après le début de la production, sans historique rejoué        | s'abonner **avant** de lancer, ou faire rejouer l'historique par le producteur     |
-| Toutes les `Promise` rejettent d'un coup                     | la connexion s'est fermée : `dispose()` vide la table des appels en attente        | attendu ; relancer après reconnexion, l'appel n'a pas survécu                      |
+| Symptôme                                                            | Cause                                                                              | Correction                                                                                   |
+| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `RPC timeout: <méthode>` alors que le serveur a bien répondu        | le handler dure plus que 30 s, le défaut                                           | passer le délai en **3ᵉ argument** : `request(m, p, 120_000)`                                |
+| Le client attend indéfiniment, aucune erreur                        | le handler ne rend jamais (il publie au lieu de retourner) — pas de frame `result` | toujours `return` une valeur ; publier **en plus**, jamais **à la place**                    |
+| `-32601 method not found`                                           | nom mal orthographié, ou action déclarée sur un **autre** endpoint                 | vérifier `socket.serverMethods` — c'est la liste réelle de CETTE connexion                   |
+| `-32603 internal error` sans détail                                 | un `throw` ordinaire est rendu opaque au client (Zero Trust)                       | lever une `RpcError` avec un code et un message publiables                                   |
+| `-32001 unauthorized` sur une action légitime                       | le nom commence par `nodefony:`, le namespace réservé à la plateforme              | renommer hors de `nodefony:`, ou obtenir `ROLE_NODEFONY_ADMIN`                               |
+| Une action est refusée à un anonyme alors qu'on la croyait publique | une action est fermée par défaut (`{ authenticated: true }`)                       | déclarer `{ authenticated: false }` pour l'ouvrir ; un rôle se pose par une règle de préfixe |
+| Un travail relancé crée deux jobs                                   | action non idempotente rejouée après une reconnexion                               | action compagnon d'annulation, ou identifiant fourni par l'appelant + mémorisation           |
+| `abort()` introuvable sur la socket                                 | il n'existe pas — et n'arrêterait pas le serveur de toute façon                    | exposer une action d'annulation qui prend l'identifiant du travail                           |
+| Les premières lignes d'un job manquent                              | abonnement au canal après le début de la production, sans historique rejoué        | s'abonner **avant** de lancer, ou faire rejouer l'historique par le producteur               |
+| Toutes les `Promise` rejettent d'un coup                            | la connexion s'est fermée : `dispose()` vide la table des appels en attente        | attendu ; relancer après reconnexion, l'appel n'a pas survécu                                |
 
 ## 🧪 Tests & couverture
 
@@ -548,7 +582,7 @@ vivent dans la carte de l'aperçu, régénérée depuis les résultats réels, j
 - **Unitaires, déclaration** (`realtimeDecorators.test.ts`) : `@RealtimeAction` enregistre bien le
   nom et lie le `this` ; (`RealtimeController.test.ts`) : fusion décorateurs + override et
   annonce dans l'accueil.
-- **Unitaires, client** (`RealtimeClientCoverage.test.ts`) : formes de `request`, contrat de
+- **Unitaires, client** (`NodefonySocketCoverage.test.ts`) : formes de `request`, contrat de
   streaming, rejet des appels en attente au `dispose`.
 - **Attaque, autorisation** (`realtimeFrameLock.test.ts`) : `nodefony:kernel:ping` et `nodefony:kernel:gc` refusés à
   l'anonyme **et** à l'utilisateur authentifié, acceptés à l'administrateur — la preuve que le
@@ -559,6 +593,55 @@ vivent dans la carte de l'aperçu, régénérée depuis les résultats réels, j
   fan-out, pas celui des appels corrélés). Pour en monter un, voir le skill
   `nodefony-load-test` ; pour la mémoire, `nodefony-check-memory-health`.
 
+### Éprouver SON action — le harnais, identité comprise
+
+Une application teste ses actions sans serveur ni navigateur avec `createRealtimeHarness`
+(`@nodefony/realtime/testing`, `nodefony/testing/index.ts:206`) : il monte le contrôleur sur une
+fausse connexion, envoie les frames qu'un client enverrait et rend celles qui sortent. Sans option,
+la connexion est **anonyme** — le repli Zero Trust. Une action qui lit `@CurrentUser()` s'éprouve
+donc avec l'identité qu'aurait posée le pare-feu au handshake, passée en `identity`
+(`nodefony/testing/index.ts:93`) :
+
+```ts ignore
+import { describe, it, expect, afterEach } from "vitest";
+import { getRealtimeHub } from "@nodefony/realtime";
+import type { IRealtimeToken } from "@nodefony/realtime";
+import { createRealtimeHarness } from "@nodefony/realtime/testing";
+import ChatController from "../nodefony/controllers/ChatController";
+
+describe("ChatController — actions", () => {
+  afterEach(() => getRealtimeHub().clear());
+
+  it("l'action reçoit son appelant par @CurrentUser", async () => {
+    const alice = { identifier: "alice" };
+    const attributes = new Map<string, unknown>([["user", alice]]);
+    const identity: IRealtimeToken = {
+      type: "session",
+      getUserIdentifier: () => alice.identifier,
+      isAuthenticated: () => true,
+      getRoles: () => ["ROLE_USER"],
+      getScopes: () => [],
+      getAttribute: <T>(key: string) => attributes.get(key) as T | undefined,
+    };
+    const h = createRealtimeHarness((ctx) => new ChatController(ctx), {
+      identity,
+    });
+    await h.connect();
+    const me = await h.call<{ identifier: string }>("chat:whoami");
+    expect(me.identifier).toBe("alice");
+    h.dispose();
+  });
+});
+```
+
+C'est l'attribut `user` du jeton que `@CurrentUser()` rend. Pour éprouver un **refus** (`@IsGranted`,
+`policy` de canal), il faut en plus le verrou de frame de `@nodefony/security`, passé en
+`frameAuthorizer` : `@nodefony/realtime` ne connaît pas la sécurité, et sans ce verrou une règle
+déclarée n'est appliquée par personne — en test comme en production. La table des membres du
+harnais et l'exemple de refus sont dans le `README.md` du paquet, section « Tester un controller ».
+`nodefony create controller --kind realtime` génère ce test, identité comprise, quand l'application
+porte la sécurité.
+
 Couverture : `npm run coverage` dans `@nodefony/realtime`.
 
 ## 🔗 Pour aller plus loin