@nodefony/realtime 10.0.0-alpha.1

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

@@ -0,0 +1,516 @@
+import { JsonRpcPeer, isPlatformChannel } from "nodefony";
+import type { RealtimePublish } from "../../interfaces/IRealtimeController.js";
+import type { IClientLogsLimits } from "../../interfaces/IClientLogsLimits.js";
+import type { IChannelPolicy } from "../../interfaces/IChannelPolicy.js";
+import type { IRealtimeConnProbe, IRealtimeProbe } from "../../interfaces/IRealtimeProbe.js";
+import type { IBackplane } from "../../interfaces/IBackplane.js";
+import type { IRealtimeAuthenticator } from "../../interfaces/IRealtimeAuthenticator.js";
+import type { IRealtimeAuthenticatorMatcher } from "../../interfaces/IRealtimeAuthenticatorMatcher.js";
+import type { IRealtimeHandshake } from "../../interfaces/IRealtimeHandshake.js";
+import type { IRealtimeToken } from "../../interfaces/IRealtimeToken.js";
+/**
+ * Fonction de filtrage Origin — `true` = upgrade autorisée. Posée par
+ * `RealtimeService.init()` depuis `defineRealtimeConfig().csrf.checkOrigin`.
+ * `null` = aucune politique (rétrocompat : tout passe — équivalent
+ * `enabled: false`).
+ */
+export type OriginGuard = (origin: string | undefined) => boolean;
+/**
+ * **Verrou de frame (seam #1 → P6)** — décide si une frame entrante (`api.request`,
+ * `subscribe`…) est AUTORISÉE, à partir du {@link IRealtimeToken} déjà résolu au
+ * handshake (cold path) et caché sur le peer. `true` = autorisée.
+ *
+ * Lecture O(1) du token en cache — **JAMAIS de re-authentification ni de lecture
+ * base par frame** : l'identité (coûteuse) est figée 1× au handshake, le verrou ne
+ * fait que matcher la cible de la frame (path/canal) contre la zone. Posé par
+ * `@nodefony/security` au boot via {@link RealtimeService.setFrameAuthorizer}.
+ * Doctrine SYNC stricte (cf `JsonRpcPeerOptions.beforeDispatch`) : un `await` par
+ * frame coûterait une microtask et sérialiserait le pipeline RPC du peer.
+ */
+export type FrameAuthorizer = (frame: unknown, token: IRealtimeToken) => boolean;
+/**
+ * Seuil d'alerte slow-consumer (octets de `bufferedAmount`). Au-delà, la connexion
+ * est comptée comme « lente » par la sonde (PAS encore de drop/close — la sonde MESURE
+ * avant qu'on optimise : stringify unique → seuil de drop → coalescing). 1 MiB =
+ * `websocket.maxPayload` par défaut : une file qui dépasse une frame max pleine est
+ * déjà anormale pour des canaux d'ÉTAT (latest-wins).
+ */
+export declare const SLOW_CONSUMER_BYTES: number;
+/**
+ * **Namespace de canaux RÉSERVÉ À LA PLATEFORME** — un seul préfixe, `nodefony:`.
+ *
+ * Les canaux qu'il couvre exposent l'état interne du pod : journaux, requêtes de
+ * base, métriques process, supervision, contrôle du noyau, journal d'audit. Aucun
+ * n'appartient au métier d'une application — ils décrivent le serveur lui-même.
+ *
+ * La liste reste exposée **ici** (au pluriel, sous forme de tableau) parce que le hub
+ * est propriétaire de l'espace de nommage des canaux : c'est lui qui les sert.
+ * `@nodefony/security`, quand il est chargé, y attache des POLITIQUES (quels rôles)
+ * qu'il lit sur cette liste via la surface de service — il ne la redéclare pas. Deux
+ * listes auraient divergé au premier namespace ajouté. Le tableau survit à la
+ * réduction à une entrée : la forme est un contrat public (`reservedSystemPrefixes()`),
+ * et rien n'interdit qu'un jour un second namespace de plateforme apparaisse.
+ *
+ * Le nom des canaux, lui, vient de la table `PLATFORM_CHANNELS` du cœur (isomorphe) :
+ * le navigateur doit connaître les mêmes noms que le serveur.
+ *
+ * Sans module de sécurité, ces canaux sont **fermés** aux connexions clientes
+ * (cf {@link RealtimeHub.subscribeClient}) : aucune identité n'existe alors, donc
+ * personne ne peut prouver qu'il a le droit de les lire.
+ */
+export declare const RESERVED_SYSTEM_PREFIXES: readonly ["nodefony:"];
+/**
+ * Le canal appartient-il au namespace réservé à la plateforme ?
+ *
+ * Alias de {@link isPlatformChannel} (cœur isomorphe) sous le nom que porte cette
+ * notion côté hub : le hub raisonne en « canal réservé », le client en « surface de
+ * plateforme ». Une seule implémentation — la comparaison est insensible à la casse,
+ * sinon `NODEFONY:syslog` échapperait au plancher que `nodefony:syslog` subit.
+ *
+ * @param channel - nom du canal demandé (suffixes de cadence et de forage inclus).
+ */
+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).
+ */
+export declare const REVOCATION_REVALIDATE_MS = 30000;
+/**
+ * Connexion à identité RÉVOCABLE inscrite au registre de re-validation (F4). Ne
+ * porte QUE ce qu'il faut pour re-valider puis fermer : le token (avec `isValid`) et
+ * un `close` fermant la socket brute. 1 entrée = 1 connexion à identité révocable
+ * (session BFF relue, ou jeton porteur à borne/denylist).
+ */
+export interface IRevocableConnection {
+    readonly token: IRealtimeToken;
+    readonly close: (code: number, reason: string) => void;
+}
+/**
+ * Sink d'un canal : pousse une charge vers UNE connexion abonnée (son `peer.notify`).
+ * 1 sink = 1 connexion. Le hub fan-out la charge à tous les sinks d'un canal.
+ *
+ * `serialized` n'est fourni que si le canal a déclaré un {@link ChannelSerializer}
+ * ET qu'il a plusieurs abonnés : la frame ayant été sérialisée une fois pour tous,
+ * le sink peut l'envoyer telle quelle au lieu de refaire le travail. Absent, le
+ * sink se débrouille comme avant — un sink historique à un seul paramètre ignore
+ * simplement l'argument.
+ */
+export type ChannelSink = (payload: unknown, serialized?: string) => void;
+/**
+ * Sérialiseur de la frame d'un canal, fourni par l'abonné (le hub ignore tout du
+ * protocole). Appelé **au plus une fois par publication**, jamais par abonné.
+ */
+export type ChannelSerializer = (payload: unknown) => string;
+/**
+ * Fabrique le provider PARTAGÉ d'un canal (listener/ticker qui pousse via `publish`).
+ * Appelée UNE fois, au 1ᵉʳ abonné. Renvoie son `dispose` (appelé au dernier
+ * désabonné) ou `null` si le canal est inconnu. Le provider doit capturer des deps
+ * **long-lived** (kernel/syslog/broker, valeurs simples) — JAMAIS la connexion qui
+ * a déclenché la création (elle peut fermer alors que le provider partagé survit).
+ */
+export type ChannelFactory = (channel: string, publish: RealtimePublish) => (() => void) | null;
+/**
+ * RealtimeHub — broker temps réel **PAR INSTANCE** (1 pod = 1 process = 1 hub local).
+ *
+ * Élève le realtime serveur du modèle **per-connexion** (chaque connexion son propre
+ * ticker/listener = N fois le même travail) au modèle **canaux PARTAGÉS** : un canal a
+ * **UN provider** créé au 1ᵉʳ abonné et un **fan-out** vers tous les abonnés. C'est le
+ * gain cloud-native (1 ticker/canal/pod) ET le **seam du backplane Redis** (le cross-pod
+ * se branchera dans {@link publish} : fan-out local + forward Redis, l'ingress backplane
+ * ne refaisant QUE du fan-out local — règle anti-boucle). Cf vision « la socket Nodefony ».
+ *
+ * Périmètre actuel : canaux **broadcast** (même flux pour tous les abonnés — stats,
+ * syslog, orm…). Les canaux **privés/par-connexion** (ex. une ligne SIP par user) =
+ * seam futur (le provider serait per-connexion, pas partagé).
+ *
+ * Perf (règle ABSOLUE) : map des canaux **lazy** (rien alloué tant qu'aucun abonné) ;
+ * provider créé au 1ᵉʳ abonné, **disposé au dernier** (aucun timer/listener orphelin) ;
+ * fan-out isolé (une connexion fautive ne casse pas la diffusion). Le hub lui-même est
+ * **sans dépendance** : ce sont les *factories* (fournies par les contrôleurs) qui
+ * portent les deps.
+ *
+ * Vocabulaire : la **socket** ({@link IRealtimeSocket}) est la prise que tient le métier ;
+ * ce **hub** est le broker serveur caché derrière (registre + fan-out local). La socket
+ * 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.
+ */
+export declare class RealtimeHub {
+    #private;
+    /**
+     * Abonnement demandé par une **connexion cliente** — même chose que
+     * {@link subscribe}, plus le plancher des canaux de plateforme.
+     *
+     * Pourquoi deux portes : un service du serveur qui écoute ses propres journaux
+     * est légitime ; une connexion distante qui demande `nodefony:syslog` alors
+     * qu'aucun module de sécurité n'est chargé ne l'est pas. Le hub ne peut pas
+     * deviner l'origine d'un appel — le contrôleur, lui, sait qu'il traite une
+     * frame venue du réseau, et passe donc par ici.
+     *
+     * Le plancher ne s'applique **que** sans verrou de frame. Dès qu'un module de
+     * sécurité en pose un, c'est lui qui décide (avec les rôles, ce que le hub ne
+     * sait pas faire) et le plancher s'efface.
+     *
+     * @returns `true` si abonné, `false` si canal inconnu ou fermé par le plancher.
+     */
+    subscribeClient(channel: string, sink: ChannelSink, factory: ChannelFactory, serialize?: ChannelSerializer): boolean;
+    /**
+     * Abonne un consommateur qui **répond du canal** : il apporte la `factory`, donc
+     * la réponse à « ce canal existe-t-il, et qui le produit ? ». Le provider partagé
+     * est créé au 1ᵉʳ abonné de ce genre. Le sink est inscrit AVANT l'appel à
+     * `factory` → le 1ᵉʳ paquet immédiat éventuel du provider (ex. tick initial de
+     * `createBrokerTicker`) atteint bien cet abonné.
+     *
+     * Un canal en état **passif** (ouvert par des écouteurs seuls, cf {@link listen})
+     * n'est PAS considéré comme existant : la fabrique est rejouée et tranche. Un
+     * refus laisse les écouteurs en place — ils n'ont jamais prétendu le produire.
+     *
+     * @returns `true` si abonné, `false` si canal inconnu (`factory` a renvoyé `null`).
+     */
+    subscribe(channel: string, sink: ChannelSink, factory: ChannelFactory, serialize?: ChannelSerializer): boolean;
+    /**
+     * **Écoute passive** — un service du serveur reçoit ce qui passe sur un canal
+     * sans prétendre le produire. C'est la porte de {@link ServerRealtimeSocket} :
+     * un service back qui `subscribe` sur sa façade écoute, il n'ouvre rien.
+     *
+     * Différence avec {@link subscribe} : aucune fabrique, donc aucun provider et
+     * **aucune revendication d'existence**. Si le canal n'a pas encore de
+     * propriétaire, l'état créé est marqué passif ; la première connexion cliente
+     * qui le demandera fera trancher la fabrique du controller. Un canal déjà
+     * ouvert est simplement rejoint (le provider partagé n'est pas touché).
+     *
+     * Un écouteur n'échoue jamais : il entendra si — et quand — quelqu'un publie.
+     * Cold path (abonnement d'un service, pas une frame réseau).
+     */
+    listen(channel: string, sink: ChannelSink): void;
+    /**
+     * Le canal a-t-il un propriétaire (une fabrique a fourni son provider) ?
+     * `false` = inconnu, ou tenu par de seuls écouteurs ({@link listen}).
+     */
+    isChannelOwned(channel: string): boolean;
+    /**
+     * Désabonne une connexion d'un canal. Au **dernier** abonné, `dispose()` le provider
+     * et retire le canal (libère timers/listeners). No-op si non abonné.
+     */
+    unsubscribe(channel: string, sink: ChannelSink): void;
+    /**
+     * Publie une charge sur un canal : **fan-out local** **+** propagation conditionnelle
+     * au {@link IBackplane} (autres workers/pods). C'est le point d'entrée des providers
+     * locaux (tickers, listeners) ET de tout code serveur.
+     *
+     * Forward **opt-in par canal** : la charge ne traverse le backplane que si le canal
+     * est déclaré **broadcast** ({@link markBroadcastChannel}). Par défaut un canal est
+     * **instance-local** (per-instance : observabilité, état du pod) → il reste dans le
+     * process. Le flag est mis en cache dans l'état du canal (lu en O(1)) ; pour un
+     * `publish` serveur sans abonné local (pas d'état), la politique est évaluée à la volée.
+     *
+     * Anti-boucle : un message **reçu** du backplane ne repasse PAS par ici (il appelle
+     * `publishLocal` directement) → aucune ré-émission cross-process, pas de tempête.
+     */
+    publish(channel: string, payload: unknown): void;
+    /**
+     * Fan-out d'une charge aux **seuls abonnés locaux** d'un canal (process courant).
+     * NE propage PAS au backplane → c'est la voie d'**ingress** d'un message venu d'un
+     * autre pair (le hub câble `backplane.onMessage` dessus dans {@link setBackplane}) :
+     * réinjection locale sans reboucler. Aussi appelable directement pour un push
+     * strictement local (jamais propagé).
+     */
+    publishLocal(channel: string, payload: unknown): void;
+    /**
+     * Déclare un **préfixe** de canal **broadcast** : ses publications traversent le
+     * {@link IBackplane} (cross-process). Tout le reste demeure instance-local (défaut sûr).
+     * Le préfixe couvre la granularité de cadence (`chat:` matche `chat:room1:1000`).
+     *
+     * Idempotent ; cold-path (appelé au handshake/boot d'un endpoint realtime, jamais
+     * sur le chemin chaud). Réévalue les canaux DÉJÀ actifs → l'ordre déclaration/abonnement
+     * n'a pas d'importance.
+     *
+     * @param prefix - préfixe de canal à forwarder (ex. `"chat:"`, `"presence:"`).
+     */
+    markBroadcastChannel(prefix: string): void;
+    /**
+     * Branche le {@link IBackplane} cross-process (cluster IPC, Redis…) et câble son
+     * ingress ({@link #admitFromBackplane}) : un message reçu d'un autre pair est
+     * réinjecté en **fan-out local uniquement** ({@link publishLocal}) — barrière
+     * anti-boucle côté hub (le backplane filtre déjà son propre echo). Remplace un
+     * backplane précédent (l'appelant est responsable de `stop()` l'ancien). Démarre
+     * le transport.
+     *
+     * @returns le backplane branché (chaînage).
+     */
+    setBackplane(backplane: IBackplane): IBackplane;
+    /** Backplane cross-process branché, ou `null` en mono-process (lecture/tests/sonde). */
+    get backplane(): IBackplane | null;
+    /** Nombre d'abonnés locaux d'un canal (observabilité / tests). */
+    subscriberCount(channel: string): number;
+    /**
+     * Inscrit une connexion au registre de la sonde (au handshake). Lazy : alloue le
+     * Set au 1ᵉʳ appel. Le hub ne lit ces connexions QUE dans {@link probe} (jamais
+     * sur le chemin chaud). À équilibrer par {@link unregisterConnection} au close.
+     */
+    registerConnection(conn: IRealtimeConnProbe): void;
+    /** Retire une connexion du registre de la sonde (au close). No-op si absente. */
+    unregisterConnection(conn: IRealtimeConnProbe): void;
+    /**
+     * Inscrit une connexion à identité RÉVOCABLE au registre de
+     * re-validation (F4, revue 0.6). Démarre le tick au 1ᵉʳ inscrit (timer `unref`,
+     * 0 timer au repos). À équilibrer par {@link unregisterRevocable} au close.
+     * N'inscrire QUE les tokens portant `isValid` (le controller filtre) : une identité
+     * non révocable (anonyme/JWT sans revalidation) ne doit pas y entrer.
+     */
+    registerRevocable(entry: IRevocableConnection): void;
+    /**
+     * Retire une connexion du registre de révocation (au close). Arrête le tick dès que
+     * le registre est vide (0 timer au repos). No-op si absente.
+     */
+    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.
+     */
+    revalidateRevocable(): Promise<void>;
+    /**
+     * Compte une frame entrante full-duplex (canaux gated SIP/bridge). Appelé par le
+     * contrôleur quand un handler `realtimeInbound` traite un message client.
+     */
+    recordInbound(): void;
+    /**
+     * Snapshot d'auto-observabilité de la socket (per-instance). Lecture PURE (aucune
+     * alloc sur le chemin chaud, jamais throw) : agrège canaux + fan-out + connexions +
+     * **backpressure** (`bufferedAmount`, risque #1). Appelé à la demande (endpoint HTTP)
+     * ou par le ticker hub `nodefony:socket`. Les cumuls sont monotones → débit dérivé
+     * côté lecteur. Cf {@link IRealtimeProbe}.
+     */
+    probe(): IRealtimeProbe;
+    /** Canaux actifs (≥ 1 abonné). Lecture seule. */
+    get activeChannels(): string[];
+    /**
+     * **Seam #2 (P13 → P6)** — enregistre un authenticator pour les handshakes
+     * WS dont l'URL matche `matcher`. Ordre d'enregistrement préservé : le
+     * **1ʳᵉ** matcher qui capture la connexion gagne. Convention : enregistrer
+     * les patterns les plus spécifiques en premier.
+     *
+     * Idempotent par couple `(matcher, authenticator)` — appel multiple = même
+     * effet (push si pas déjà présent). Cold-path (boot via P6/userland).
+     *
+     * @param matcher        sélecteur (pattern URL + vhost optionnel)
+     * @param authenticator  stratégie d'auth réseau (handshake → IRealtimeToken)
+     */
+    useAuthenticator(matcher: IRealtimeAuthenticatorMatcher, authenticator: IRealtimeAuthenticator): void;
+    /**
+     * Résout l'authenticator capturant ce handshake (1ʳᵉ matcher qui matche),
+     * ou `null` si aucun (le RealtimeController posera un token anonyme).
+     * Cold path (1× par upgrade) — lecture array.
+     */
+    resolveAuthenticator(handshake: IRealtimeHandshake): IRealtimeAuthenticator | null;
+    /**
+     * **Seam #4 (P13 → P6)** — pose la politique Origin (RFC 6455 §10.2).
+     * `null` = aucune politique (toutes origines acceptées). Posée 1× par
+     * `RealtimeService.init()` depuis `defineRealtimeConfig().csrf.checkOrigin`.
+     */
+    setOriginGuard(guard: OriginGuard | null): void;
+    /**
+     * Vérifie qu'une origin est autorisée (politique CSRF). `true` si aucune
+     * politique posée (rétrocompat). Cold path (1× par upgrade).
+     */
+    checkOrigin(origin: string | undefined): boolean;
+    /**
+     * F6a (revue 0.6) — plafond de canaux par connexion (anti-OOM). Posé 1× au
+     * boot par `RealtimeService.init()` depuis
+     * `defineRealtimeConfig().limits.maxChannelsPerConnection`. `null` = illimité.
+     */
+    setMaxChannelsPerConnection(max: number | null): void;
+    /** Plafond courant de canaux par connexion (`null` = illimité). Lu par `startChannel`. */
+    get maxChannelsPerConnection(): number | null;
+    /**
+     * F9 (revue 0.6) — pose le seuil de comptage des consommateurs lents (`probe()`).
+     * Posé 1× au boot par `RealtimeService.init()` depuis
+     * `defineRealtimeConfig().slowConsumer.bytes` (sinon la clé de config serait morte).
+     */
+    setSlowConsumerBytes(bytes: number): void;
+    /**
+     * Associe un token au peer (posé par `RealtimeController.onHandshake()` après
+     * succès `authenticator.authenticate()` ou fallback anonyme). Lazy alloc de
+     * la `WeakMap` au 1ᵉʳ appel (0 coût si aucun authenticator enregistré).
+     */
+    setTokenForPeer(peer: JsonRpcPeer, token: IRealtimeToken): void;
+    /**
+     * Renvoie le token associé au peer, ou `ANONYMOUS_REALTIME_TOKEN` si aucun
+     * (cas Zero Trust : la lecture ne renvoie JAMAIS `null` — slot #6 audit
+     * lookup garanti, voters P6 ne se posent jamais la question « actor ? »).
+     */
+    getTokenForPeer(peer: JsonRpcPeer): IRealtimeToken;
+    /**
+     * **Seam #1 (P13 → P6)** — pose le verrou de frame (cf {@link FrameAuthorizer}).
+     * `null` retire la politique (bypass total). Posé 1× au boot par
+     * `@nodefony/security` depuis les zones `realtime: true`. Cold path.
+     */
+    setFrameAuthorizer(authorizer: FrameAuthorizer | null, options?: {
+        readonly silentProbe?: FrameAuthorizer | null;
+    }): void;
+    /**
+     * Un verrou de frame est-il posé ?
+     *
+     * Sert au DIAGNOSTIC (`hasUnenforcedChannelPolicies`, introspection, tests) —
+     * **plus** à décider si on arme le verrou sur une connexion : le contrôleur
+     * l'arme toujours, précisément pour qu'une politique posée après coup garde
+     * les sockets déjà ouvertes.
+     */
+    hasFrameAuthorizer(): boolean;
+    /**
+     * Branche l'alerte du plancher système — tirée **une seule fois**, au premier
+     * canal de plateforme refusé faute de module de sécurité.
+     *
+     * Posée par le contrôleur : le hub est sans dépendance (aucun journal), et une
+     * fermeture silencieuse serait exactement la dégradation muette qu'on cherche
+     * à interdire.
+     *
+     * @param notify - reçoit le message à journaliser (niveau avertissement).
+     */
+    onPlatformNotice(notify: (message: string, severity: "WARNING" | "INFO") => void): void;
+    /**
+     * Ce canal serait-il fermé par le plancher système ? Lecture PURE (ni compteur,
+     * ni alerte) — elle sert à expliquer un refus au client plutôt qu'à le décider.
+     *
+     * Sans elle, un abonnement refusé resterait sans réponse : le client attendrait
+     * indéfiniment des données qui ne viendront pas, ce qui est exactement la
+     * dégradation muette que ce plancher est censé faire disparaître.
+     */
+    isClosedBySystemFloor(channel: string): boolean;
+    /**
+     * F1 (revue 0.6) — des politiques de canal sont-elles DÉCLARÉES (`@RealtimeChannel`
+     * avec `roles`/`scopes`/`authenticated`) sans `frameAuthorizer` pour les faire
+     * respecter ? `true` = **dégradation silencieuse** : un canal se croit gardé mais
+     * aucun décideur n'est câblé → un subscribe passe non gardé. Vrai uniquement sans
+     * `@nodefony/security` (ou toutes les zones en `realtime: false`). Lu par le
+     * RealtimeController pour émettre un WARNING au boot (fail-loud, jamais silencieux).
+     */
+    hasUnenforcedChannelPolicies(): boolean;
+    /**
+     * **Seam #1b** — déclare la politique d'autorisation d'un canal/méthode
+     * (`@RealtimeChannel`/`@RealtimeInbound` avec opts). Appelé au handshake par
+     * le controller pour CHAQUE canal décoré (idempotent : même nom = écrase, les
+     * controllers d'un même endpoint déclarent la même policy). Cold path.
+     *
+     * Deux formes de nom, et la seconde garde une FAMILLE :
+     *
+     * - un nom **exact** (`chat:room`) — lecture O(1) au `subscribe` ;
+     * - un **motif** (`chat:room:*`) — il couvre tout canal dérivé servi par une
+     *   fabrique dynamique (`chat:room:1000`), ce qu'un nom exact ne faisait pas.
+     *   Le `*` remplace n'importe quelle suite de caractères ; tout le reste du
+     *   motif est littéral (échappé), y compris `.` et `(`.
+     *
+     * Précédence : le nom **exact** l'emporte toujours — c'est ainsi qu'on ouvre
+     * une exception dans une famille gardée. Entre deux motifs, le plus
+     * **spécifique** gagne (littéral le plus long).
+     *
+     * @param name   - nom exact du canal (subscribe), de la méthode inbound, ou
+     *   MOTIF de famille s'il contient `*`.
+     * @param policy - exigences ({@link IChannelPolicy}) lues par security.
+     */
+    registerChannelPolicy(name: string, policy: IChannelPolicy): void;
+    /**
+     * Nombre maximum de `*` dans un motif.
+     *
+     * Ce n'est pas une limite de confort : chaque `*` devient un `.*` dans
+     * l'expression compilée, et plusieurs `.*` sur une chaîne qui NE matche pas
+     * font revenir le moteur sur ses pas — un coût qui explose avec leur nombre.
+     * Un motif de canal en demande un, deux au pire ; au-delà, c'est une erreur
+     * de déclaration, et on le DIT plutôt que d'exposer un chemin coûteux à ce
+     * qu'un client peut nommer.
+     */
+    static readonly MAX_PATTERN_WILDCARDS = 3;
+    /**
+     * Politique déclarée pour ce canal/méthode, ou `null` si aucune. Lu par
+     * `@nodefony/security` (`resolveChannelPolicy` de la surface DI) au moment de
+     * la frame `subscribe`/inbound. O(1), 0 alloc quand le registre est vide.
+     */
+    resolveChannelPolicy(name: string): IChannelPolicy | null;
+    /** Des politiques de canal sont-elles déclarées (au moins une) ? */
+    hasChannelPolicies(): boolean;
+    /**
+     * Avertit — **une seule fois** — qu'un canal servi par une fabrique
+     * DYNAMIQUE n'est couvert par aucune politique déclarée, alors que d'autres
+     * canaux du module en portent une.
+     *
+     * Le registre des politiques est indexé par nom **EXACT** : `@RealtimeChannel`
+     * déclare `"chat:room"`, mais un canal dérivé (`chat:room:1000` — cadence,
+     * forage, suffixe) est servi par la fabrique dynamique et **ne matche pas**.
+     * L'auteur croit alors son canal gardé ; il ne l'est pas, et rien ne le lui
+     * dit. C'est ce silence qu'on ferme ici — et depuis qu'une politique peut se
+     * déclarer par MOTIF (`chat:room:*`), cet avertissement ne parle plus que des
+     * canaux qu'aucun motif ne couvre : il désigne un vrai trou, pas une limite
+     * de l'outil.
+     *
+     * Appelé par le contrôleur, seul à savoir par quelle voie le canal a été
+     * servi. Muet si aucune politique n'est déclarée (module aux canaux libres :
+     * il n'y a alors aucune promesse à trahir).
+     *
+     * @param channel - le canal servi dynamiquement, cité en exemple dans l'alerte.
+     */
+    noticeUnguardedDynamicChannel(channel: string): void;
+    /**
+     * Enregistre la **factory d'un canal système** (plateforme) — un module bas
+     * niveau (ex. `@nodefony/security` : `nodefony:audit`) déclare au boot comment
+     * produire le provider d'un canal, SANS qu'aucun `RealtimeController` ne le
+     * connaisse. `subscribe` consulte ce registre quand la factory du controller
+     * renvoie `null` → le canal devient servable par TOUT endpoint (présent/futur),
+     * zéro couplage à Studio. La factory garde la sémantique lazy du hub (créée au
+     * 1ᵉʳ abonné, `dispose` au dernier).
+     *
+     * @param channel - nom EXACT du canal système (match exact, pas un préfixe).
+     * @param factory - {@link ChannelFactory} qui crée le provider partagé.
+     */
+    registerSystemChannel(channel: string, factory: ChannelFactory): void;
+    /**
+     * Pont hot-path entre `JsonRpcPeer.beforeDispatch` et le verrou métier : lit
+     * le token déjà caché du peer (O(1), 0 lecture base) puis délègue à
+     * l'authorizer. `true` (autorisée) si aucun verrou posé (bypass 0-coût) —
+     * mais en pratique `beforeDispatch` n'est branché que si `hasFrameAuthorizer()`.
+     *
+     * @param frame - frame JSON-RPC entrante (brute) à autoriser.
+     * @param peer  - peer émetteur (clé du mapping `peer → token`).
+     * @returns `true` si la frame peut être dispatchée, `false` si refusée.
+     */
+    /**
+     * Ouvre (ou referme) la réception des journaux du navigateur, avec ses bornes.
+     *
+     * @param limits - bornes de débit et de taille, ou `null` pour refermer le canal.
+     */
+    setClientLogsLimits(limits: IClientLogsLimits | null): void;
+    /** Bornes en vigueur, ou `null` si le canal montant est fermé. */
+    get clientLogsLimits(): IClientLogsLimits | null;
+    runAuthorizer(frame: unknown, peer: JsonRpcPeer): boolean;
+    /**
+     * Ce peer pourrait-il s'abonner à ce canal ? — même décision que `subscribe`,
+     * sans trace ni effet de bord.
+     *
+     * Rend `true` quand aucune sonde n'est posée : sans sécurité chargée, aucun
+     * canal n'est refusé, et l'absence de sonde ne doit jamais faire DISPARAÎTRE
+     * des canaux d'un welcome. Un filtre qui échoue doit échouer ouvert ici —
+     * c'est le verrou, pas l'annonce, qui protège l'accès.
+     *
+     * @param channel - le canal interrogé.
+     * @param peer - la connexion, d'où l'on tire le jeton résolu au handshake.
+     * @returns `true` si un `subscribe` sur ce canal serait accepté.
+     */
+    probeChannel(channel: string, peer: JsonRpcPeer): boolean;
+    /** Authenticators enregistrés (debug / tests). Lecture seule. */
+    get registeredAuthenticators(): ReadonlyArray<IRealtimeAuthenticator>;
+    /** Dispose tous les providers et vide le hub (arrêt process / reset de test). */
+    clear(): void;
+}
+/** Renvoie le hub realtime du process (singleton lazy). */
+export declare function getRealtimeHub(): RealtimeHub;
+export default RealtimeHub;

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

@@ -0,0 +1,63 @@
+import { type IRealtimeSocket, type IRealtimeChannel, type IChannelStats, type RealtimeHandler, type EventsMap, type ActionsMap, type DefaultEventsMap, type DefaultActionsMap, type EventNames, type EventPayload, type ContractParams, type ContractResult } from "nodefony";
+/**
+ * **L4 — façade serveur « la socket Nodefony ».** Un handle SERVEUR qui implémente
+ * le contrat ISOMORPHE {@link IRealtimeSocket} au-dessus du {@link RealtimeHub} : un
+ * service back code **comme une page front** (`publish` / `subscribe` / `on` /
+ * `channel`) — il tient UN handle, ignore le fan-out et le backplane.
+ *
+ * Tient la promesse North Star « un consommateur — front OU back — tient UN handle ».
+ *
+ * ── Sémantique côté serveur ──
+ *  - `publish(channel, payload)` : **fan-out** aux abonnés via le hub (+ backplane si
+ *    le canal est broadcast). C'est le cas d'usage principal (un service pousse des
+ *    events que les clients reçoivent).
+ *  - `subscribe`/`on` : le service ÉCOUTE un canal (sink interne) — **écoute passive**
+ *    (`RealtimeHub.listen`). Écouter n'ouvre PAS le canal : s'il n'a pas de provider,
+ *    l'état créé est passif, et c'est la fabrique du controller qui tranchera quand
+ *    une connexion cliente le demandera. Un service n'invente donc jamais un canal
+ *    pour les autres.
+ *  - `request` : **non supporté** — un handle au-dessus du hub n'a PAS de pair unique
+ *    (le hub est multi-clients). Pour un RPC serveur→client 1-1, utiliser
+ *    `RealtimeController.requestClient` (par connexion, L1).
+ *
+ * Lazy : aucune structure allouée tant que le service n'`on`/`subscribe`/`publish` pas.
+ *
+ * @typeParam Emit   — canaux pub/sub SORTANTS (`publish`) = ServerToClient.
+ * @typeParam Listen — canaux pub/sub RÉCEPTIONNÉS (`subscribe`/`on`) = ClientToServer.
+ */
+export declare class ServerRealtimeSocket<Emit extends EventsMap = DefaultEventsMap, Listen extends EventsMap = DefaultEventsMap, Actions extends ActionsMap = DefaultActionsMap> implements IRealtimeSocket<Emit, Listen, Actions> {
+    #private;
+    private readonly hub;
+    constructor(hub?: import("./RealtimeHub.js").RealtimeHub);
+    /** Émet sur un canal — fan-out aux abonnés via le hub (+ backplane si broadcast). */
+    publish<K extends string>(channel: K, payload?: K extends EventNames<Emit> ? EventPayload<Emit, K> : unknown): void;
+    /**
+     * S'abonne (ref-compté) à un canal pour le RECEVOIR. Au 1ᵉʳ consommateur, pose un
+     * sink d'**écoute passive** auprès du hub : le service reçoit ce qui passe, sans
+     * ouvrir le canal à qui que ce soit d'autre.
+     */
+    subscribe(channel: EventNames<Listen> | (string & {})): void;
+    /** Désabonne (ref-compté) : coupe le sink du hub au DERNIER consommateur. */
+    unsubscribe(channel: EventNames<Listen> | (string & {})): void;
+    /** Branche un handler de réception sur un canal. Renvoie un `dispose`. */
+    on<K extends string>(channel: K, handler: K extends EventNames<Listen> ? (payload: EventPayload<Listen, K>) => void : RealtimeHandler): () => void;
+    /** Retire un handler d'un canal. */
+    off<K extends string>(channel: K, handler: K extends EventNames<Listen> ? (payload: EventPayload<Listen, K>) => void : RealtimeHandler): void;
+    /**
+     * **Non supporté.** Un handle au-dessus du hub n'a pas de pair unique
+     * (multi-clients). Pour un RPC serveur→client 1-1, utiliser
+     * `RealtimeController.requestClient` (par connexion, L1).
+     */
+    request<K extends string, T = unknown>(_method: K, _params?: ContractParams<Actions, K>, _timeoutMs?: number): Promise<ContractResult<Actions, K, T>>;
+    /** Vue par-canal ({@link IRealtimeChannel}) — fine liaison sur les primitives. */
+    channel(name: string): IRealtimeChannel;
+    /** Snapshot des compteurs par canal (refs internes — à LIRE). */
+    getStats(): IChannelStats[];
+    /** Compteurs d'un canal précis ou `undefined`. */
+    getChannelStats(channel: string): IChannelStats | undefined;
+    /** Canaux actuellement abonnés (≥ 1 consommateur). */
+    get subscribedChannels(): string[];
+}
+/** Crée un handle serveur ({@link ServerRealtimeSocket}) sur le hub courant. */
+export declare function serverSocket<Emit extends EventsMap = DefaultEventsMap, Listen extends EventsMap = DefaultEventsMap, Actions extends ActionsMap = DefaultActionsMap>(): ServerRealtimeSocket<Emit, Listen, Actions>;
+export default ServerRealtimeSocket;

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

@@ -0,0 +1,25 @@
+/**
+ * Le détail d'un `realtime:denied` — dit au développeur, tu à l'utilisateur.
+ *
+ * `RealtimeDeniedReason` est fermé et générique par construction : `forbidden`
+ * ne dit pas si c'est un rôle qui manque ou le plancher de plateforme qui est
+ * clos, et c'est ce qui l'empêche d'être un oracle. Le prix de cette prudence
+ * est payé par le développeur : il reçoit un refus qu'il ne sait pas lire, et
+ * il lui reste à deviner ce qu'il faut regarder.
+ *
+ * Cette fonction pose donc la phrase utile — **et seulement hors production**,
+ * où la même phrase serait exactement l'oracle que `reason` refuse d'être.
+ *
+ * Isolée pour la même raison que {@link welcomeEnv}, dont elle copie la règle :
+ * noyée dans la composition du refus, son inversion ne casserait aucun test et
+ * livrerait le détail d'une politique aux visiteurs d'un serveur publié. Une
+ * absence vaut production, jamais l'inverse.
+ *
+ * @param env - le mode du kernel serveur (`kernel.environment`), s'il est connu.
+ * @param detail - la phrase à dire, déjà rédigée par l'appelant.
+ * @returns le fragment à étaler dans le refus : `{ detail }` hors production,
+ *   sinon un objet vide.
+ */
+export declare function deniedDetail(env: string | undefined | null, detail: string): {
+    detail?: string;
+};

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

@@ -0,0 +1,58 @@
+/**
+ * Réception des journaux **remontés par un navigateur** : le pendant serveur du
+ * transport client (`nodefony/client` → `installSyslogUplink`).
+ *
+ * Un canal entrant qui écrit dans le journal du pod est une **surface d'écriture**, et
+ * c'est la seule chose qui compte pour sa conception. Trois bornes, non négociables :
+ *
+ * 1. **L'origine est FORCÉE.** Le `moduleName` que le client prétend n'est jamais repris :
+ *    le `Pdu` réinjecté porte {@link BROWSER_ORIGIN}. Sans quoi une page pourrait se faire
+ *    passer pour le noyau et fabriquer des pistes de diagnostic.
+ * 2. **La taille et le débit sont bornés**, par connexion. Un onglet ouvert ne doit pas
+ *    pouvoir noyer le journal d'exploitation — ni par un lot géant, ni par la répétition.
+ * 3. **La sévérité est plafonnée.** Un client ne déclenche pas une alerte d'exploitation :
+ *    tout ce qu'il envoie de plus grave que {@link MAX_CLIENT_SEVERITY} y est ramené.
+ *
+ * Ce que ces bornes ne couvrent PAS, et qu'il faut savoir en lisant le journal : le
+ * `requestId` d'une entrée est **déclaré par le client**. On le valide en forme, jamais en
+ * fond — un client peut donc rattacher ses lignes à une requête qui n'est pas la sienne.
+ * L'impact est une piste de diagnostic polluée, jamais une élévation de droit ; et le
+ * `moduleName` forcé dit au lecteur que la ligne vient d'un navigateur, donc qu'elle est
+ * déclarative. C'est le prix d'une corrélation front↔back, et il s'énonce.
+ */
+import { BROWSER_ORIGIN, Syslog } from "nodefony";
+import type { RealtimeInboundHandler } from "../../interfaces/IRealtimeController.js";
+export { BROWSER_ORIGIN };
+/**
+ * Sévérité la plus grave qu'un client puisse obtenir (3 = ERROR). Au-dessus vivent
+ * CRITIC, ALERT et EMERGENCY — des niveaux d'exploitation qu'un onglet ne décide pas.
+ */
+export declare const MAX_CLIENT_SEVERITY = 3;
+/** Les seules sévérités qu'une entrée cliente peut porter, une fois plafonnée. */
+export type ClientSeverity = 3 | 4 | 5 | 6 | 7;
+export interface SyslogUplinkHandlerOptions {
+    /** Le journal du pod où réinjecter. */
+    syslog: Syslog;
+    /** Entrées retenues par lot. Défaut `50` ; le surplus est ignoré et compté. */
+    maxEntriesPerBatch?: number;
+    /** Entrées retenues par fenêtre et par connexion. Défaut `300`. */
+    maxEntriesPerWindow?: number;
+    /** Durée de la fenêtre de débit, en ms. Défaut `10000`. */
+    windowMs?: number;
+    /** Longueur maximale d'une chaîne acceptée. Défaut `4096`. */
+    maxStringLength?: number;
+    /** Longueur maximale d'un `requestId` accepté. Défaut `128`. */
+    maxRequestIdLength?: number;
+}
+/**
+ * Fabrique le handler du canal montant des journaux.
+ *
+ * **Un handler par connexion** : `RealtimeController.realtimeInbound()` est invoqué au
+ * handshake, donc le compteur de débit qu'il capture est per-connexion — ce qui est le
+ * seul découpage utile (borner globalement laisserait un onglet bavard museler tous les
+ * autres).
+ *
+ * @param opts - journal cible et bornes.
+ * @returns le handler à déclarer dans `realtimeInbound()`.
+ */
+export declare function createSyslogUplinkHandler(opts: SyslogUplinkHandlerOptions): RealtimeInboundHandler;