nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/client/types/src/realtime/JsonRpcPeer.d.ts

@@ -0,0 +1,251 @@
+/**
+ * JsonRpcPeer — moteur protocole **JSON-RPC 2.0 ISOMORPHE** (client ET serveur).
+ *
+ * Client et serveur sont des **pairs** : le protocole (classer une frame, router,
+ * corréler les réponses) est identique des deux côtés. Cette classe l'implémente
+ * **une seule fois** ; chaque côté l'enrobe de son transport (`send`) et de ses
+ * handlers. → fin de la duplication client/serveur (la discrimination request /
+ * notification / response vivait à 2 endroits qui divergeaient).
+ *
+ * Transport-agnostique : on injecte `send(frame)` ; le peer ignore WebSocket/TCP/…
+ * Aucune dépendance Node (browser-safe) : seulement `setTimeout`/`clearTimeout`.
+ *
+ * ── La RÈGLE de discrimination (le cœur) ──
+ *  Le RÔLE d'une frame se lit sur `method`, PAS sur `id` :
+ *   - `method` + `id`        → **requête** entrante  → handler enregistré → réponse `result`/`error`
+ *   - `method` seul          → **notification**      → `onNotification` (pas de réponse)
+ *   - `id` sans `method`     → **réponse**           → résout/rejette un `pending` sortant
+ *  `id` autorisé string OU number (JSON-RPC 2.0 §id). Méthode inconnue → `-32601` ;
+ *  handler qui throw → `-32603` (message GÉNÉRIQUE au pair, détail via `onError` = Zero Trust).
+ *
+ * ── Types partagés (pattern Socket.IO) ────────────────────────────────────
+ *  3 génériques (`Emit`, `Listen`, `Actions`) avec **défauts permissifs**
+ *  ({@link DefaultEventsMap}, {@link DefaultActionsMap}) : code non paramétré
+ *  → comportement pré-types inchangé (rétro-compat 100%). Cf {@link EventsMap},
+ *  {@link ActionsMap} et le détail dans `RealtimeEventMap.ts`.
+ */
+import type { ActionNames, ActionParams, ActionResult, ActionsMap, DefaultActionsMap, DefaultEventsMap, EventNames, EventPayload, EventsMap, TypedRpcActionHandler } from "./RealtimeEventMap.js";
+/** Erreur JSON-RPC 2.0 (objet `error` d'une réponse). */
+export interface JsonRpcErrorObject {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+/**
+ * Erreur RPC **applicative** — l'exception VOLONTAIRE au principe « throw →
+ * `-32603` générique » : un handler qui rejette avec une `RpcError` choisit
+ * explicitement d'exposer `code`/`message`/`data` au pair (404 d'un path
+ * invoqué, 403 d'un voter…). Tout autre throw reste opaque (Zero Trust).
+ *
+ * Isomorphe : côté serveur le handler la lève ; côté client `request()` rejette
+ * avec — `code` et `data` (ex. `{ status: 404 }`) sont lisibles par l'appelant,
+ * symétrie d'un `fetch` qui expose son statut HTTP.
+ *
+ * Plage de codes : `-32000` à `-32099` (« Server error », réservée applicatif
+ * par JSON-RPC 2.0 §5.1). Défaut `-32000`.
+ */
+export interface RpcError {
+    /** Code JSON-RPC 2.0 (`-32000`…`-32099` applicatif, ou codes protocole). */
+    code: number;
+}
+export declare class RpcError extends Error {
+    readonly name = "RpcError";
+    readonly data?: unknown;
+    constructor(message: string, code?: number, data?: unknown);
+}
+/**
+ * Métadonnées **serveur** d'une réponse RPC — transportées À CÔTÉ du `result`,
+ * jamais dedans (le `result` d'`api.request` doit rester identique à ce que
+ * rendrait la même route en REST : « snapshot ≡ GET REST » par construction).
+ *
+ * Aujourd'hui : `requestId` (dev) = la clé du profil de la frame dans le
+ * Profiler → le client peut aller chercher sa radiographie. Champ ouvert :
+ * un pair qui n'en connaît pas les clés l'ignore (rétro-compatible).
+ */
+export interface RpcMeta {
+    /** Identifiant du profil de CETTE invocation (`<connexion>.<n° de frame>`). */
+    requestId?: string;
+    [key: string]: unknown;
+}
+/**
+ * Réponse d'un handler qui veut JOINDRE des métadonnées serveur à son résultat.
+ *
+ * Un handler retourne normalement sa valeur nue (elle devient `result`). Quand
+ * il retourne une enveloppe, le peer la déballe : `result` reste la valeur nue,
+ * et `meta` voyage dans un champ frère de la trame JSON-RPC. Coût pour ceux qui
+ * ne l'utilisent pas : un `instanceof` par frame.
+ */
+export declare class RpcEnvelope<T = unknown> {
+    readonly result: T;
+    readonly meta: RpcMeta;
+    constructor(result: T, meta: RpcMeta);
+}
+/** Résultat d'un appel sortant tracé : la valeur + la méta serveur. */
+export interface RpcTracedResult<T = unknown> {
+    result: T;
+    meta?: RpcMeta;
+}
+/** Handler d'une action (requête→réponse). Sync ou async ; throw → `-32603`. */
+export type RpcActionHandler = (params: unknown) => unknown | Promise<unknown>;
+/**
+ * Handler des notifications entrantes (pas de réponse). Paramétrable par `Listen`
+ * (map des notifications REÇUES par ce peer). Défaut permissif → comportement
+ * pré-types-partagés inchangé.
+ */
+export type RpcNotificationHandler<Listen extends EventsMap = DefaultEventsMap> = <K extends EventNames<Listen>>(method: K, params: EventPayload<Listen, K>) => void;
+/** Nature d'une frame entrante (renvoyée par {@link JsonRpcPeer.handleFrame}). */
+export type JsonRpcFrameKind = "request" | "notification" | "response" | "invalid";
+/**
+ * Frame de notification sortante (JSON-RPC 2.0, sans `id` : aucune réponse
+ * attendue). Type nommé parce que cette frame **sort du peer** : le fan-out d'un
+ * canal diffusé la sérialise une fois pour tous ses abonnés.
+ */
+export interface JsonRpcNotification {
+    jsonrpc: "2.0";
+    method: string;
+    params?: unknown;
+}
+/**
+ * Motif d'un évènement audit protocolaire (consommé par P6.14 `AuditEventEntity`) :
+ *  - `invalid`           : frame non conforme JSON-RPC 2.0 (pas d'objet, `jsonrpc`≠"2.0", `method` non string sans `id` valide).
+ *  - `denied`            : frame entrante refusée par `beforeDispatch` (Zero Trust realtime — voter P6 a dit non).
+ *  - `method_not_found`  : requête entrante pour une action non enregistrée (`-32601` envoyée).
+ *  - `internal_error`    : handler d'action a throw (`-32603` envoyée, détail loggé via `onError` — Zero Trust : pas renvoyé au pair).
+ */
+export type FrameAuditReason = "invalid" | "denied" | "method_not_found" | "internal_error";
+export interface JsonRpcPeerOptions<Emit extends EventsMap = DefaultEventsMap, Listen extends EventsMap = DefaultEventsMap, Actions extends ActionsMap = DefaultActionsMap> {
+    /**
+     * Envoie une frame sérialisable sur le transport (le peer ignore le transport).
+     *
+     * Un transport qui sait que la frame **n'est pas partie** (socket fermée,
+     * reconnexion en cours) doit retourner `false` : le peer rejette alors la
+     * requête corrélée immédiatement, au lieu de laisser l'appelant attendre son
+     * timeout pour une frame jamais émise. `void`/`true` = considéré comme émis
+     * (comportement historique des transports qui ne savent pas répondre).
+     */
+    send: (frame: unknown) => boolean | void;
+    /** Notifications entrantes (`method` sans `id`) : pub/sub côté client, subscribe/unsubscribe côté serveur. */
+    onNotification?: RpcNotificationHandler<Listen>;
+    /** Erreur interne d'un handler — détail JAMAIS renvoyé au pair (loggé ici). */
+    onError?: (context: string, err: unknown) => void;
+    /**
+     * **Seam sécurité 1/5 (P13 → P6)** — gate `beforeDispatch` appelé AVANT le
+     * dispatch d'une frame entrante (request ET notification — pas les responses,
+     * passives). `false` → frame BLOQUÉE (audit `denied`, et pour une requête,
+     * réponse `-32001 unauthorized` ; notification = drop silencieux). `true` →
+     * dispatch normal. `undefined` (cas client par défaut) → bypass 0-coût.
+     *
+     * SYNC uniquement (voters P6 = lecture metadata + jeton décodé en cache = ~µs).
+     * L'async serait une fausse économie : ajouter `await` sur le hot-path d'une WS
+     * coûte une microtask PAR FRAME (~50 ns) y compris quand non-async (Promise.resolve)
+     * + sérialise les frames per-peer. Si un voter doit attendre une lookup distante,
+     * pré-cacher la décision côté authenticator au handshake.
+     *
+     * Branchement P6 : reading metadata `@IsGranted` du handler + voters → `boolean`.
+     */
+    beforeDispatch?: (frame: unknown, peer: IRealtimePeer<Emit, Actions>) => boolean;
+    /**
+     * **Seam audit 5/5 (P13 → P6.14)** — fire-and-forget sur évènements
+     * protocolaires notables (cf {@link FrameAuditReason}). Sync (pas de
+     * back-pressure : un audit lent ne doit pas ralentir le pipeline RPC).
+     * `undefined` (cas client par défaut) → bypass 0-coût.
+     *
+     * Le `peer` est passé pour permettre au consommateur (typiquement
+     * `RealtimeHub` côté serveur) de retrouver l'**actor** associé à la
+     * connexion via son mapping `peer → IRealtimeToken` (slot #6 forward-audit
+     * P6 : « qui a été refusé » exige l'identité, pas juste l'IP du paquet).
+     *
+     * Branchement P6.14 : alimente le journal `AuditEventEntity` (qui agit, qui a
+     * été refusé, qui appelle une méthode inconnue — traçabilité Zero Trust).
+     */
+    onFrameAudit?: (reason: FrameAuditReason, frame: unknown, peer: IRealtimePeer<Emit, Actions>) => void;
+}
+/**
+ * Surface BIDIRECTIONNELLE d'un endpoint temps réel — **contrat ISOMORPHE**,
+ * identique back et front. `RealtimeClient` (navigateur) ET la connexion serveur
+ * l'exposent, en composant le même {@link JsonRpcPeer}. Du code métier écrit
+ * contre cette interface tourne des deux côtés (le pari isomorphe de Nodefony).
+ *
+ * Sortant : `request` (attend une réponse), `notify` (fire-and-forget).
+ * Entrant : `receive` (le transport y pousse chaque frame). Callee : `register`.
+ */
+/**
+ * @typeParam Emit    — notifications SORTANTES (typage de `notify`).
+ * @typeParam Actions — contrat RPC bidirectionnel (typage de `request`/`register`).
+ *
+ * Note : `Listen` (notifications ENTRANTES) n'est PAS sur cette interface raw —
+ * il est consommé par `JsonRpcPeerOptions.onNotification` et par `RealtimeClient.on()`.
+ */
+export interface IRealtimePeer<Emit extends EventsMap = DefaultEventsMap, Actions extends ActionsMap = DefaultActionsMap> {
+    /** Requête sortante → `Promise` du `result` (rejette sur `error`/timeout). */
+    request<K extends ActionNames<Actions>>(method: K, params?: ActionParams<Actions, K>, timeoutMs?: number): Promise<ActionResult<Actions, K>>;
+    /** Notification sortante (pas de réponse). */
+    notify<K extends EventNames<Emit>>(method: K, params?: EventPayload<Emit, K>): void;
+    /** Expose une action appelable par le pair (requête entrante → `result`). */
+    register<K extends ActionNames<Actions>>(method: K, handler: TypedRpcActionHandler<Actions, K>): void;
+    /** Retire une action. */
+    unregister<K extends ActionNames<Actions>>(method: K): void;
+    /** Ingestion d'une frame ENTRANTE (déjà parsée) → classe + route. */
+    receive(frame: unknown): JsonRpcFrameKind;
+    /** Actions exposées (découverte). */
+    readonly methods: string[];
+    /** Annule les requêtes en attente (fermeture transport). */
+    dispose(reason?: string): void;
+}
+export declare class JsonRpcPeer<Emit extends EventsMap = DefaultEventsMap, Listen extends EventsMap = DefaultEventsMap, Actions extends ActionsMap = DefaultActionsMap> implements IRealtimePeer<Emit, Actions> {
+    private readonly opts;
+    private nextId;
+    private pending;
+    private actions;
+    constructor(opts: JsonRpcPeerOptions<Emit, Listen, Actions>);
+    /** Expose une action (requête entrante `method`+`id` → `result`). Idempotent. */
+    register<K extends ActionNames<Actions>>(method: K, handler: TypedRpcActionHandler<Actions, K>): void;
+    /** Retire une action. */
+    unregister<K extends ActionNames<Actions>>(method: K): void;
+    /** Liste des actions exposées (pour annoncer au handshake, découverte côté pair). */
+    get methods(): string[];
+    /** Requête SORTANTE — `Promise` résolue avec le `result` (rejette sur `error`/timeout). */
+    request<K extends ActionNames<Actions>>(method: K, params?: ActionParams<Actions, K>, timeoutMs?: number): Promise<ActionResult<Actions, K>>;
+    /**
+     * Requête SORTANTE **tracée** — rend `{ result, meta }` au lieu du `result` nu.
+     *
+     * Même appel que {@link request} : la seule différence est que l'appelant
+     * garde la méta serveur (en dev, le `requestId` du profil de la frame → sa
+     * radiographie). Un serveur qui n'en émet pas laisse simplement `meta`
+     * absent.
+     */
+    requestTraced<K extends ActionNames<Actions>>(method: K, params?: ActionParams<Actions, K>, timeoutMs?: number): Promise<RpcTracedResult<ActionResult<Actions, K>>>;
+    /**
+     * Frame d'une notification sortante — **source unique** de sa forme.
+     *
+     * Extraite pour que le fan-out d'un canal diffusé puisse sérialiser la frame
+     * **une seule fois** pour N abonnés, sans jamais risquer de diverger du format
+     * qu'émet {@link notify} : les deux voies passent par ici.
+     *
+     * @param method - nom de la méthode (côté canal : le nom du canal).
+     * @param params - charge applicative ; omise de la frame si `undefined`.
+     * @returns la frame JSON-RPC 2.0, prête à sérialiser.
+     */
+    static buildNotification(method: string, params?: unknown): JsonRpcNotification;
+    /**
+     * Notification SORTANTE (pas de réponse attendue).
+     *
+     * @returns `false` si le transport a signalé qu'il n'a pas émis. Une
+     * notification n'attend rien en retour : sans cette valeur, une frame perdue
+     * ne laisserait aucune trace chez l'appelant. Les appels qui se rattrapent
+     * seuls (ré-abonnement au reconnect) peuvent l'ignorer.
+     */
+    notify<K extends EventNames<Emit>>(method: K, params?: EventPayload<Emit, K>): boolean;
+    /**
+     * Ingestion d'une frame ENTRANTE déjà parsée → classe (request/notification/
+     * response) et route. Renvoie la nature (utile log/tests). Ne lève jamais.
+     * (Le pendant sortant = `request`/`notify` ; le `send` brut est injecté.)
+     */
+    receive(msg: unknown): JsonRpcFrameKind;
+    /** Annule tous les pending (fermeture du transport). */
+    dispose(reason?: string): void;
+    private startCall;
+    private handleRequest;
+    private handleResponse;
+}
+export default JsonRpcPeer;

package/dist/client/types/src/realtime/RealtimeEventMap.d.ts

@@ -0,0 +1,269 @@
+/**
+ * Types partagés pour le contrat **realtime** Nodefony — pattern « typed events »
+ * (Socket.IO §emitter-typing) appliqué à JSON-RPC 2.0.
+ *
+ * Le contrat (canaux pub/sub + RPC) est déclaré UNE fois côté partagé, puis injecté
+ * en générique sur `IRealtimePeer<Emit, Listen, Actions>`, `JsonRpcPeer<...>` et
+ * `RealtimeClient<...>`. Bénéfices : autocomplétion IDE, refactor safe (rename canal
+ * → erreur compile partout), doc-as-code. **0 coût runtime** — génériques effacés
+ * à la compile.
+ *
+ * Convention :
+ * - `Emit`     = ce que CE peer ENVOIE (notifications sortantes).
+ * - `Listen`   = ce que CE peer REÇOIT (notifications entrantes).
+ * - `Actions`  = contrat RPC bidirectionnel (les 2 pairs respectent la même map :
+ *                `request()` typé sortant + `register()` typé entrant).
+ *
+ * Pour un échange `client ↔ serveur` : symétrie naturelle.
+ * Côté client : `Emit = ClientToServer`, `Listen = ServerToClient`.
+ * Côté serveur : `Emit = ServerToClient`, `Listen = ClientToServer`.
+ */
+/**
+ * Map des canaux pub/sub — nom de canal → forme du payload.
+ *
+ * @example
+ * ```ts
+ * interface ServerToClient extends EventsMap {
+ *   "chat:room42":  { ts: number; msg: string };
+ *   "presence":     { user: string; online: boolean };
+ * }
+ * ```
+ */
+export type EventsMap = Record<string, unknown>;
+/**
+ * Map des RPC — nom de méthode → `{ in: paramètres, out: résultat }`.
+ *
+ * Utilisée par `request()` (sortant) ET `register()` (entrant) : les 2 pairs
+ * respectent le même contrat (JSON-RPC 2.0 est symétrique).
+ *
+ * @example
+ * ```ts
+ * interface ChatActions extends ActionsMap {
+ *   "chat:ping":  { in: void;          out: { pong: boolean; ts: number } };
+ *   "chat:fetch": { in: { id: string }; out: { msg: string } };
+ * }
+ * ```
+ */
+export type ActionsMap = Record<string, {
+    in?: unknown;
+    out: unknown;
+}>;
+/**
+ * Défaut **permissif** pour `EventsMap` — toute clé `string`, payload `unknown`.
+ * Code instancié sans paramétrage (`new JsonRpcPeer(opts)`) → comportement
+ * pré-types-partagés inchangé. **Sécurité rétro-compat 100%**.
+ */
+export interface DefaultEventsMap {
+    [event: string]: unknown;
+}
+/** Défaut **permissif** pour `ActionsMap` (rétro-compat). */
+export interface DefaultActionsMap {
+    [method: string]: {
+        in?: unknown;
+        out: unknown;
+    };
+}
+/**
+ * Retire l'index signature (`[k: string]: …`) d'un type, en ne gardant que les
+ * clés LITTÉRALES déclarées.
+ *
+ * Indispensable ici : la convention documentée est `interface App extends
+ * ActionsMap`, or `extends` fait HÉRITER le `[k: string]` de `Record<string, …>`.
+ * Sans ce filtre, `keyof App` vaut `string` — donc tout nom inconnu passe la
+ * compile, et la branche « hors map » des types conditionnels devient
+ * INATTEIGNABLE (`K extends EventNames<M>` toujours vrai). C'est ce qui typait le
+ * handler wildcard `on("*")` à UN argument alors que le runtime l'appelle avec
+ * `(method, params)`.
+ *
+ * Les maps par défaut ({@link DefaultEventsMap}, {@link DefaultActionsMap}) n'ont
+ * QUE l'index signature → elles se réduisent à `never`, ce qui fait tomber le
+ * code non paramétré dans la branche permissive : rétro-compat préservée.
+ */
+type RemoveIndexSignature<T> = {
+    [K in keyof T as string extends K ? never : number extends K ? never : symbol extends K ? never : K]: T[K];
+};
+/**
+ * Clés LITTÉRALES d'une map, ou `never` si elle n'en déclare aucune (map
+ * purement permissive comme {@link DefaultEventsMap}).
+ */
+type LiteralKeys<M> = keyof RemoveIndexSignature<M> & string;
+/**
+ * Nom valide dans une `EventsMap`.
+ *
+ * Map qui DÉCLARE des canaux → union stricte de ses noms (autocomplétion, et un
+ * nom inconnu est refusé). Map SANS aucune clé littérale (les défauts permissifs)
+ * → `string` : le code non paramétré garde son comportement d'avant les types
+ * partagés. Le `[…] extends […]` en tuple empêche la distribution du conditionnel
+ * sur `never` (qui rendrait `never` au lieu de `string`).
+ */
+export type EventNames<M extends EventsMap> = [LiteralKeys<M>] extends [never] ? string : LiteralKeys<M>;
+/** Payload typé d'un canal. */
+export type EventPayload<M extends EventsMap, K extends keyof M> = M[K];
+/** Nom valide dans une `ActionsMap` — même règle que {@link EventNames}. */
+export type ActionNames<M extends ActionsMap> = [LiteralKeys<M>] extends [never] ? string : LiteralKeys<M>;
+/**
+ * Paramètres entrants d'une RPC, lus sur le `in` de la déclaration.
+ *
+ * On teste la PRÉSENCE de la clé (`"in" extends keyof M[K]`) avant d'inférer, au
+ * lieu de `M[K] extends { in: infer I }` : un `in` **optionnel** ne satisfait pas
+ * une contrainte qui l'exige, et {@link DefaultActionsMap} déclare précisément
+ * `in?`. La forme naïve retombait donc sur `undefined` pour tout peer NON
+ * paramétré — impossible de passer le moindre paramètre, alors que ce défaut
+ * promet une rétro-compat permissive. Zéro impact runtime (types effacés), d'où
+ * la survie du trou jusqu'au type-check des tests.
+ *
+ * - `{ in: { id: string } }` → `{ id: string }`
+ * - `{ in: void }` → `void` (appel sans argument)
+ * - `{ out: X }` (pas de `in`) → `undefined` (la RPC ne prend rien)
+ * - `DefaultActionsMap` (`in?: unknown`) → `unknown` (permissif)
+ */
+export type ActionParams<M extends ActionsMap, K extends keyof M> = "in" extends keyof M[K] ? M[K] extends {
+    in?: infer I;
+} ? I : undefined : undefined;
+/** Résultat attendu d'une RPC (`out`). */
+export type ActionResult<M extends ActionsMap, K extends keyof M> = M[K]["out"];
+/**
+ * Noms d'actions RÉELLEMENT déclarés par le contrat — `never` quand la map n'en
+ * déclare aucune ({@link DefaultActionsMap}).
+ *
+ * ⚠️ À ne pas confondre avec {@link ActionNames}, qui vaut `string` sur une map
+ * non paramétrée : ce repli est ce qu'il faut pour une CONTRAINTE (accepter
+ * n'importe quelle méthode), mais il rend toujours VRAIE la condition d'un type
+ * conditionnel — la branche permissive devient alors inatteignable et le type de
+ * résultat demandé par l'appelant est écrasé en `unknown`.
+ */
+export type ContractActionNames<M extends ActionsMap> = LiteralKeys<M>;
+/**
+ * `params` d'une RPC : dictés par le contrat quand `K` lui appartient, libres
+ * sinon. Règle UNIQUE — `IRealtimeSocket`, `RealtimeClient` et
+ * `ServerRealtimeSocket` la partagent au lieu de la recopier.
+ */
+export type ContractParams<M extends ActionsMap, K> = K extends ContractActionNames<M> ? ActionParams<M, K & keyof M> : unknown;
+/**
+ * Résultat d'une RPC : dicté par le contrat quand `K` lui appartient, sinon le
+ * `T` que l'appelant demande. Pendant de {@link ContractParams}.
+ */
+export type ContractResult<M extends ActionsMap, K, T> = K extends ContractActionNames<M> ? ActionResult<M, K & keyof M> : T;
+/**
+ * Handler typé pour une RPC entrante (côté qui expose via `register`).
+ * Sync ou async — JSON-RPC 2.0 §5.1 : throw → réponse `-32603 internal_error`.
+ */
+export type TypedRpcActionHandler<M extends ActionsMap, K extends keyof M & string> = (params: ActionParams<M, K>) => ActionResult<M, K> | Promise<ActionResult<M, K>>;
+/**
+ * Assertion type **compile-time** : `expectType<T>(value)` échoue à la compilation
+ * si `value` n'est pas assignable à `T`. **0 coût runtime** (fonction vide).
+ *
+ * @example
+ * ```ts
+ * const x = peer.request("chat:ping");
+ * expectType<Promise<{ pong: boolean }>>(x); // ✅
+ * expectType<Promise<string>>(x);            // ❌ TS error
+ * ```
+ */
+export declare function expectType<T>(_value: T): void;
+/**
+ * Identité d'une connexion temps réel, telle que **résolue par le serveur au
+ * handshake** (token neutre `IRealtimeToken` côté back) et **annoncée au client**
+ * dans la notification système `realtime:welcome`.
+ *
+ * Le client la lit pour savoir QUI il est **sans taper une route** : anonyme →
+ * écran de login (au lieu de deviner via un 401), authentifié → app. Rafraîchie à
+ * chaque (re)connexion (un nouveau welcome ⇒ une nouvelle identité). C'est une vue
+ * « sur soi » (équivalent `/auth/me`) — **aucun secret** : seulement l'état d'auth
+ * et les rôles/scopes du porteur, qu'il connaît déjà.
+ */
+export interface RealtimeIdentity {
+    /** Type de token résolu (`"anonymous"`, `"session"`, `"jwt"`, …) — discriminator. */
+    type: string;
+    /** `false` pour un visiteur anonyme (Zero Trust : toujours présent, jamais `null`). */
+    authenticated: boolean;
+    /** Identifiant logique du porteur (`"anonymous"`, `"user-42"`, …). */
+    userIdentifier: string;
+    /** Rôles **plats** (RBAC, sans hiérarchie résolue) — `["ROLE_ANONYMOUS"]` si anonyme. */
+    roles: string[];
+    /** Scopes accordés (clés API / OAuth) — `[]` en session BFF web. */
+    scopes: string[];
+}
+/**
+ * Payload de la notification système `realtime:welcome` — **1ʳᵉ frame** poussée par
+ * le serveur juste après le handshake. Annonce le protocole, les canaux/actions
+ * **découvrables** de l'endpoint et l'{@link RealtimeIdentity} résolue de la
+ * connexion. Cold path (1×/connexion).
+ */
+export interface IRealtimeWelcome {
+    /** Timestamp serveur (ms epoch). */
+    ts: number;
+    /** Étiquette de protocole (`"jsonrpc-2.0"`). */
+    protocol: string;
+    /** Canaux pub/sub annoncés par l'endpoint (découverte). */
+    channels: string[];
+    /** Actions RPC exposées par l'endpoint (découverte). */
+    methods: string[];
+    /** Identité résolue de CETTE connexion (cf {@link RealtimeIdentity}). */
+    identity: RealtimeIdentity;
+    /**
+     * Mode d'exécution du serveur — **posé UNIQUEMENT hors production**.
+     *
+     * Il existe parce que le client ne dispose sinon que de `import.meta.env.DEV`,
+     * qui dit le mode du BUNDLE : une application bâtie pour la production mais
+     * servie par un serveur de développement (banc, cluster local, image testée
+     * sur le poste) restait muette dans la console alors qu'on avait tout intérêt
+     * à la faire parler. Le serveur, lui, sait.
+     *
+     * ⚠️ **Une absence vaut production, jamais l'inverse.** Un serveur publié
+     * n'émet pas ce champ : ce n'est pas un réglage qu'on lit, c'est une
+     * permission de parler — et on ne l'accorde pas par défaut.
+     */
+    env?: string;
+}
+/**
+ * Payload de la notification système `realtime:denied` — poussée par le serveur
+ * quand une frame `subscribe`/inbound est REFUSÉE par le verrou d'autorisation
+ * (P6). Rend le refus OBSERVABLE côté client (une notification, contrairement à
+ * une requête, serait sinon droppée en silence → le client resterait aveugle).
+ *
+ * Contrat de PROTOCOLE **isomorphe** : un seul type, le serveur l'émet
+ * (`@nodefony/realtime`), le client le parse (core → notice + event `onDenied`).
+ * Zero Trust : `reason` est GÉNÉRIQUE (jamais le rôle/scope manquant — pas
+ * d'oracle d'autorisation). Cold path (un refus est rare).
+ */
+export interface IRealtimeDenied {
+    /** Canal (ou méthode inbound) refusé(e). */
+    channel: string;
+    /** Motif générique (cf {@link RealtimeDeniedReason}) — jamais le détail de la policy. */
+    reason: RealtimeDeniedReason;
+    /**
+     * Ce qui s'est passé, en clair — **hors production UNIQUEMENT**.
+     *
+     * `reason` est fermé et générique par construction : c'est ce qui empêche
+     * d'en faire un oracle. Mais un développeur qui reçoit `forbidden` n'a alors
+     * aucun moyen de savoir LEQUEL des cas il tient — rôle insuffisant, ou
+     * plancher de plateforme fermé faute de module de sécurité — ni quoi
+     * regarder. Il lui reste à deviner, et un signal qu'on ne sait pas lire ne
+     * vaut guère mieux qu'un silence.
+     *
+     * Ce champ porte donc la phrase utile, et il est posé par
+     * {@link deniedDetail}, sur le modèle EXACT de `welcomeEnv` : **absent en
+     * production**, où la même phrase deviendrait précisément l'oracle que
+     * `reason` refuse d'être. Une absence vaut production, jamais l'inverse.
+     */
+    detail?: string;
+}
+/**
+ * Motif d'un `realtime:denied`. Fermé exprès : le client doit pouvoir traiter
+ * TOUS les cas (le compilateur le lui rappelle), et un motif inventé côté
+ * serveur ne doit pas atteindre un écran qui ne sait pas le dire.
+ *
+ * - `"forbidden"` — décision d'AUTORISATION : le verrou de frame a refusé
+ *   (rôle/scope insuffisant), ou le plancher du namespace de plateforme est
+ *   fermé faute de module de sécurité. Générique par construction : dire
+ *   lequel des deux, ou quel rôle manque, serait un oracle.
+ * - `"limit"` — garde de RESSOURCE : le plafond de canaux de cette connexion
+ *   est atteint. Une borne n'est pas un secret, elle se nomme.
+ * - `"unknown"` — le canal n'a AUCUN producteur sur ce pod (nom mal orthographié,
+ *   module non chargé). Ce n'est pas un refus d'accès, et le distinguer ne
+ *   révèle rien : un canal gardé est tranché en amont, donc rendu `"forbidden"`
+ *   qu'il existe ou non.
+ */
+export type RealtimeDeniedReason = "forbidden" | "limit" | "unknown";
+export {};

package/dist/client/types/src/realtime/channelRate.d.ts

@@ -0,0 +1,55 @@
+/**
+ * channelRate — granularité (cadence) d'un canal realtime, **convention isomorphe**
+ * partagée par les deux bords de la socket.
+ *
+ * La cadence d'un canal à état (stats, supervision) vit dans son **nom** : `base` nu =
+ * cadence serveur par défaut ; `base:<ms>` = cadence explicite. Conséquence voulue (cf
+ * vision « la socket Nodefony ») : **1 canal = 1 cadence = 1 ref-count** — `nodefony:orm:health:2000`
+ * et `nodefony:orm:health:5000` sont deux tickers distincts, jamais réconciliés.
+ *
+ * Avant ce module la convention était **dupliquée** : le front fabriquait `base:${ms}` à la
+ * main (3×) et le serveur la re-parsait+bornait à la main (3×) → dérive garantie (un bord
+ * change la borne, l'autre pas). Ici elle est **centralisée et testée** : le front fabrique
+ * via {@link rateChannel}, le serveur résout via {@link parseRate} — même fichier, même règle.
+ *
+ * Pur (aucune allocation hors la string résultat, uniquement quand un suffixe est requis) et
+ * appelé au `subscribe` (chemin froid), jamais par frame.
+ *
+ * @see {@link IRealtimeChannel} — le handle par-canal, futur point d'accroche de la cadence
+ *   AIMD (re-subscribe adaptatif), qui s'appuiera sur cette même convention de nommage.
+ */
+/** Bornes de cadence d'un canal cadencé (toutes en millisecondes). */
+export interface RateBounds {
+    /** Cadence par défaut — celle du canal de base nu (sans suffixe). */
+    readonly default: number;
+    /** Borne basse (cadence minimale autorisée, anti-DoS event-loop). */
+    readonly min: number;
+    /** Borne haute (cadence maximale autorisée). */
+    readonly max: number;
+}
+/**
+ * Construit le nom d'un canal cadencé à partir de sa base et de la cadence demandée.
+ *
+ * `intervalMs` omis OU égal à `defaultMs` → renvoie `base` nu : on **n'émet pas** de suffixe
+ * pour la cadence par défaut, ce qui évite de fragmenter le canal de base entre consommateurs
+ * qui veulent tous la valeur par défaut (ils partagent alors un seul ticker ref-compté).
+ *
+ * @param base - canal de base (ex. `"nodefony:orm:health"`).
+ * @param intervalMs - cadence demandée (ms). Omise → canal de base.
+ * @param defaultMs - cadence par défaut du canal ; `intervalMs === defaultMs` ⇒ canal de base.
+ * @returns `base` ou `base:<ms>`.
+ */
+export declare function rateChannel(base: string, intervalMs?: number, defaultMs?: number): string;
+/**
+ * Résout la cadence (ms) d'un canal cadencé connu, côté serveur. Le serveur connaît la `base`
+ * qu'il vient de matcher ; ce helper en extrait le suffixe `:<ms>`, **borne** dans `bounds` et
+ * retombe sur `bounds.default` pour le canal de base nu ou un suffixe invalide.
+ *
+ * @param channel - canal reçu (`base` ou `base:<ms>`).
+ * @param base - canal de base déjà identifié par l'appelant.
+ * @param bounds - cadence par défaut + bornes min/max.
+ * @returns cadence effective (ms), garantie dans `[bounds.min, bounds.max]` (ou `bounds.default`).
+ */
+export declare function parseRate(channel: string, base: string, bounds: RateBounds): number;
+/** Vrai si `channel` est le canal de base nu OU une de ses variantes cadencées `base:<ms>`. */
+export declare function isRateChannel(channel: string, base: string): boolean;