@nodefony/realtime 10.0.0-alpha.1

package/dist/nodefony/src/server/ServerRealtimeSocket.js

@@ -0,0 +1,168 @@
+import { getRealtimeHub } from "./RealtimeHub.js";
+//#region nodefony/src/server/ServerRealtimeSocket.ts
+/**
+* **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.
+*/
+var ServerRealtimeSocket = class {
+	hub;
+	#handlers = null;
+	#sinks = null;
+	#subs = null;
+	#stats = null;
+	constructor(hub = getRealtimeHub()) {
+		this.hub = hub;
+	}
+	/** Émet sur un canal — fan-out aux abonnés via le hub (+ backplane si broadcast). */
+	publish(channel, payload) {
+		this.hub.publish(channel, payload);
+	}
+	/**
+	* 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) {
+		const c = channel;
+		const subs = this.#subs ??= /* @__PURE__ */ new Map();
+		const n = (subs.get(c) ?? 0) + 1;
+		subs.set(c, n);
+		if (n !== 1) return;
+		const sink = (payload) => this.#receive(c, payload);
+		(this.#sinks ??= /* @__PURE__ */ new Map()).set(c, sink);
+		this.hub.listen(c, sink);
+	}
+	/** Désabonne (ref-compté) : coupe le sink du hub au DERNIER consommateur. */
+	unsubscribe(channel) {
+		const c = channel;
+		const cur = this.#subs?.get(c);
+		if (!cur) return;
+		if (cur > 1) {
+			this.#subs.set(c, cur - 1);
+			return;
+		}
+		this.#subs.delete(c);
+		const sink = this.#sinks?.get(c);
+		if (sink) {
+			this.hub.unsubscribe(c, sink);
+			this.#sinks.delete(c);
+		}
+	}
+	/** Branche un handler de réception sur un canal. Renvoie un `dispose`. */
+	on(channel, handler) {
+		const handlers = this.#handlers ??= /* @__PURE__ */ new Map();
+		let set = handlers.get(channel);
+		if (!set) {
+			set = /* @__PURE__ */ new Set();
+			handlers.set(channel, set);
+		}
+		set.add(handler);
+		return () => this.off(channel, handler);
+	}
+	/** Retire un handler d'un canal. */
+	off(channel, handler) {
+		this.#handlers?.get(channel)?.delete(handler);
+	}
+	/**
+	* **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(_method, _params, _timeoutMs) {
+		return Promise.reject(/* @__PURE__ */ new Error("ServerRealtimeSocket.request: pas de pair unique côté hub (multi-clients). Pour un RPC serveur→client 1-1, utiliser RealtimeController.requestClient."));
+	}
+	/** Vue par-canal ({@link IRealtimeChannel}) — fine liaison sur les primitives. */
+	channel(name) {
+		const hub = this;
+		const disposers = /* @__PURE__ */ new Set();
+		return {
+			name,
+			on(handler) {
+				const dispose = hub.on(name, handler);
+				disposers.add(dispose);
+				return () => {
+					dispose();
+					disposers.delete(dispose);
+				};
+			},
+			send(payload) {
+				hub.publish(name, payload);
+			},
+			open() {
+				hub.subscribe(name);
+			},
+			close() {
+				for (const d of disposers) d();
+				disposers.clear();
+				hub.unsubscribe(name);
+			}
+		};
+	}
+	/** Snapshot des compteurs par canal (refs internes — à LIRE). */
+	getStats() {
+		return this.#stats ? Array.from(this.#stats.values()) : [];
+	}
+	/** Compteurs d'un canal précis ou `undefined`. */
+	getChannelStats(channel) {
+		return this.#stats?.get(channel);
+	}
+	/** Canaux actuellement abonnés (≥ 1 consommateur). */
+	get subscribedChannels() {
+		return this.#subs ? Array.from(this.#subs.keys()) : [];
+	}
+	/** Dispatch d'une charge fan-outée par le hub : stats + handlers locaux + wildcard. */
+	#receive(channel, payload) {
+		const stats = this.#stats ??= /* @__PURE__ */ new Map();
+		let st = stats.get(channel);
+		if (!st) {
+			st = {
+				method: channel,
+				msgCount: 0,
+				lastMessage: null,
+				rate: 0,
+				series: []
+			};
+			stats.set(channel, st);
+		}
+		st.msgCount++;
+		st.lastMessage = Date.now();
+		this.#handlers?.get(channel)?.forEach((h) => {
+			try {
+				h(payload);
+			} catch {}
+		});
+		this.#handlers?.get("*")?.forEach((h) => {
+			try {
+				h(channel, payload);
+			} catch {}
+		});
+	}
+};
+/** Crée un handle serveur ({@link ServerRealtimeSocket}) sur le hub courant. */
+function serverSocket() {
+	return new ServerRealtimeSocket(getRealtimeHub());
+}
+//#endregion
+export { ServerRealtimeSocket, ServerRealtimeSocket as default, serverSocket };

package/dist/nodefony/src/server/deniedDetail.js

@@ -0,0 +1,29 @@
+//#region nodefony/src/server/deniedDetail.ts
+/**
+* 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.
+*/
+function deniedDetail(env, detail) {
+	if (!env || env === "production") return {};
+	return { detail };
+}
+//#endregion
+export { deniedDetail };

package/dist/nodefony/src/server/syslogUplink.js

@@ -0,0 +1,105 @@
+import { BROWSER_ORIGIN, Pdu } from "nodefony";
+//#region nodefony/src/server/syslogUplink.ts
+/**
+* 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.
+*/
+/**
+* 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.
+*/
+const MAX_CLIENT_SEVERITY = 3;
+/** Chaîne bornée, ou `undefined` si ce n'en est pas une. */
+function str(v, max) {
+	if (typeof v !== "string") return void 0;
+	return v.length <= max ? v : v.slice(0, max);
+}
+/**
+* `requestId` accepté seulement s'il ressemble à un identifiant : imprimable, sans
+* espace, borné. On ne vérifie pas qu'il EXISTE (ce serait une lecture par entrée sur le
+* chemin chaud) — seulement qu'il ne peut pas servir à injecter autre chose.
+*/
+function safeRequestId(v, max) {
+	if (typeof v !== "string" || v.length === 0 || v.length > max) return void 0;
+	for (let i = 0; i < v.length; i += 1) {
+		const c = v.charCodeAt(i);
+		if (c <= 32 || c >= 127) return void 0;
+	}
+	return v;
+}
+/**
+* Sévérité ramenée dans les bornes : un entier RFC 5424 valide, jamais plus grave que
+* {@link MAX_CLIENT_SEVERITY}. Tout ce qui n'est pas un nombre exploitable devient
+* `ERROR` — une entrée arrivée jusqu'ici a été jugée digne d'être envoyée.
+*/
+function clampSeverity(v) {
+	if (typeof v !== "number" || !Number.isInteger(v)) return 3;
+	if (v <= 3) return 3;
+	if (v === 4) return 4;
+	if (v === 5) return 5;
+	if (v === 6) return 6;
+	return 7;
+}
+/**
+* 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()`.
+*/
+function createSyslogUplinkHandler(opts) {
+	const { syslog, maxEntriesPerBatch = 50, maxEntriesPerWindow = 300, windowMs = 1e4, maxStringLength = 4096, maxRequestIdLength = 128 } = opts;
+	let windowStart = 0;
+	let windowCount = 0;
+	return function onSyslogUplink(params) {
+		if (params === null || typeof params !== "object") return;
+		const batch = params;
+		const entries = batch.entries;
+		if (!Array.isArray(entries) || entries.length === 0) return;
+		const pageId = safeRequestId(batch.pageId, maxRequestIdLength);
+		if (pageId === void 0) return;
+		const now = Date.now();
+		if (now - windowStart > windowMs) {
+			windowStart = now;
+			windowCount = 0;
+		}
+		const limit = Math.min(entries.length, maxEntriesPerBatch);
+		for (let i = 0; i < limit; i += 1) {
+			if (windowCount >= maxEntriesPerWindow) return;
+			windowCount += 1;
+			const raw = entries[i];
+			if (raw === null || typeof raw !== "object") continue;
+			const severity = clampSeverity(raw.severity);
+			const msgid = str(raw.msgid, 64) ?? "";
+			const msg = str(raw.msg, maxStringLength) ?? "";
+			const timeStamp = typeof raw.timeStamp === "number" && Number.isFinite(raw.timeStamp) ? raw.timeStamp : now;
+			const pdu = new Pdu(raw.payload, severity, BROWSER_ORIGIN, msgid, msg, timeStamp);
+			pdu.requestId = safeRequestId(raw.requestId, maxRequestIdLength) ?? pageId;
+			syslog.log(pdu);
+		}
+	};
+}
+//#endregion
+export { BROWSER_ORIGIN, MAX_CLIENT_SEVERITY, createSyslogUplinkHandler };

package/dist/nodefony/src/server/welcomeEnv.js

@@ -0,0 +1,25 @@
+//#region nodefony/src/server/welcomeEnv.ts
+/**
+* Le mode d'exécution annoncé — ou non — dans `realtime:welcome`.
+*
+* Le client ne dispose sinon que d'`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 essayée sur le poste) restait
+* muette dans la console alors qu'on avait tout intérêt à la faire parler.
+*
+* ⚠️ **En production, le champ est ABSENT** — et c'est la raison d'être de cette
+* fonction, isolée pour être éprouvée dans les deux sens. Ce n'est pas un
+* réglage que le client lit, c'est une permission de parler dans la console de
+* quelqu'un : on ne l'accorde pas par défaut, et une absence vaut production,
+* jamais l'inverse.
+*
+* @param env - le mode du kernel serveur (`kernel.environment`), s'il est connu.
+* @returns le fragment à étaler dans le welcome : `{ env }` hors production,
+*   sinon un objet vide.
+*/
+function welcomeEnv(env) {
+	if (!env || env === "production") return {};
+	return { env };
+}
+//#endregion
+export { welcomeEnv };

package/dist/nodefony/src/service/RealtimeService.js

@@ -0,0 +1,240 @@
+import { RESERVED_SYSTEM_PREFIXES, getRealtimeHub } from "../server/RealtimeHub.js";
+import { applyDeclaredBroadcastPrefixes } from "../../decorators/realtimeDecorators.js";
+import { Service } from "nodefony";
+//#region nodefony/src/service/RealtimeService.ts
+const serviceName = "realtimeService";
+/**
+* Façade DI publique de la **socket Nodefony** côté serveur.
+*
+* Wrapper mince autour du singleton {@link RealtimeHub} : expose
+* `publish`/`subscribe`/`probe` à travers le container DI, applique au boot le
+* backplane custom éventuel (config `backplane.instance` OU service DI nommé
+* `realtimeBackplane`), expose la config gelée pour Studio / introspection.
+*
+* Ce service ne **remplace pas** le hub singleton (consommé par les
+* controllers, l'admin API et les WS handlers via `getRealtimeHub()`) ; il en
+* est l'API stable consommable côté userland. La Module class garde la main
+* sur le wiring `ClusterBackplane` (lié au lifecycle `onCluster` kernel,
+* pré-`onPreBoot`) — orthogonal au backplane custom userland.
+*
+* @example
+* ```ts
+* class MyService extends Service {
+*   constructor(public module: Module) {
+*     super(...);
+*     this.realtime = this.get<RealtimeService>("realtimeService");
+*   }
+*   notify(payload: unknown) {
+*     this.realtime?.publish("my-app:event", payload);
+*   }
+* }
+* ```
+*/
+var RealtimeService = class extends Service {
+	module;
+	#config = null;
+	#hub = null;
+	constructor(module) {
+		super(serviceName, module.container, module.notificationsCenter, module.options);
+		this.module = module;
+	}
+	/**
+	* Initialise le service au moment où le Module l'enregistre via `addService`
+	* (phase `onPreBoot`). Pose la config validée + applique l'éventuel backplane
+	* custom userland. Idempotent.
+	*
+	* Source du backplane custom (priorité décroissante) :
+	*  1. `realtimeConfig.backplane.instance` posée par la Module class via le
+	*     container (mode "config typée" : `defineRealtimeConfig({}, { backplane })`)
+	*  2. Service DI nommé `realtimeBackplane` (mode "userland enregistre une
+	*     instance dans son module via container.set")
+	*
+	* Si aucun n'est fourni → le hub reste avec son backplane par défaut (null =
+	* Loopback implicite, ou ClusterBackplane si le worker IPC a déjà été câblé
+	* par la Module class). Aucun warn — c'est le cas commun.
+	*/
+	async init(_module) {
+		this.#config = this.module.config;
+		if (!this.#config) throw new Error(`${serviceName}: realtimeConfig absente (this.module.config vide) — la Module class doit la valider à onKernelRegister`);
+		if (!this.#config.enabled) {
+			this.log("realtime enabled:false → service inerte (hub non câblé)", "INFO");
+			return this;
+		}
+		const hub = this.getHub();
+		const custom = this.#config.backplane.instance ?? this.get("realtimeBackplane");
+		if (custom && hub.backplane === null) {
+			hub.setBackplane(custom);
+			this.log(`Backplane custom branché (driver déclaré=${this.#config.backplane.driver})`, "INFO");
+		}
+		hub.setOriginGuard(buildOriginGuard(this.#config));
+		hub.setMaxChannelsPerConnection(this.#config.limits.maxChannelsPerConnection);
+		hub.setSlowConsumerBytes(this.#config.slowConsumer.bytes);
+		hub.setClientLogsLimits(this.#config.clientLogs.enabled ? {
+			maxEntriesPerBatch: this.#config.clientLogs.maxEntriesPerBatch,
+			maxEntriesPerWindow: this.#config.clientLogs.maxEntriesPerWindow,
+			windowMs: this.#config.clientLogs.windowMs,
+			maxStringLength: this.#config.clientLogs.maxStringLength
+		} : null);
+		applyDeclaredBroadcastPrefixes(hub);
+		return this;
+	}
+	/** Configuration realtime gelée (lue par Studio / introspection). */
+	getConfig() {
+		if (!this.#config) throw new Error(`${serviceName}: not initialized`);
+		return this.#config;
+	}
+	/** Hub singleton (broker fan-out canaux PARTAGÉS du process courant). */
+	getHub() {
+		return this.#hub ??= getRealtimeHub();
+	}
+	/** Backplane actuellement branché sur le hub (ou null = Loopback implicite). */
+	getBackplane() {
+		return this.getHub().backplane;
+	}
+	/**
+	* Publie une charge sur un canal — fan-out local + propagation backplane si
+	* canal broadcast. Délégué à `RealtimeHub.publish`.
+	*/
+	publish(channel, payload) {
+		this.getHub().publish(channel, payload);
+	}
+	/**
+	* Abonne un sink à un canal partagé — factory invoquée au 1ᵉʳ abonné, dispose
+	* appelé au dernier désabonné. Délégué à `RealtimeHub.subscribe`.
+	*
+	* @returns `true` si abonné, `false` si la factory a refusé (canal inconnu).
+	*/
+	subscribe(channel, sink, factory) {
+		return this.getHub().subscribe(channel, sink, factory);
+	}
+	/**
+	* Désabonne un sink — appelle `dispose` du provider partagé au dernier abonné.
+	* Délégué à `RealtimeHub.unsubscribe`. No-op si non abonné.
+	*/
+	unsubscribe(channel, sink) {
+		this.getHub().unsubscribe(channel, sink);
+	}
+	/**
+	* Enregistre la factory d'un **canal système** (plateforme) — délégué à
+	* {@link RealtimeHub.registerSystemChannel}. Un module bas niveau
+	* (`@nodefony/security` → `nodefony:audit`) déclare au boot comment produire le
+	* provider, sans qu'aucun `RealtimeController` ne le connaisse ; tout endpoint
+	* le sert alors (lazy : créé au 1ᵉʳ abonné, disposé au dernier).
+	*/
+	registerSystemChannel(channel, factory) {
+		this.getHub().registerSystemChannel(channel, factory);
+	}
+	/**
+	* Namespaces de canaux **réservés à la plateforme** — la liste que le hub ferme
+	* lui-même en l'absence de module de sécurité.
+	*
+	* Exposée pour qu'un module de sécurité y attache ses politiques **sans
+	* redéclarer la liste** : deux inventaires auraient divergé au premier namespace
+	* ajouté, et la divergence serait passée inaperçue (un namespace neuf resterait
+	* simplement sans politique). Ici, le hub possède la liste, la sécurité possède
+	* les rôles.
+	*/
+	reservedSystemPrefixes() {
+		return RESERVED_SYSTEM_PREFIXES;
+	}
+	/** Snapshot d'observabilité du hub local (consommé par `/nodefony/realtime/api/health`). */
+	probe() {
+		return this.getHub().probe();
+	}
+	/**
+	* Marque un préfixe de canal comme **broadcast** (cross-process via le
+	* backplane). Sans appel, tout canal reste instance-local. Délégué à
+	* `RealtimeHub.markBroadcastChannel`.
+	*/
+	markBroadcastChannel(prefix) {
+		this.getHub().markBroadcastChannel(prefix);
+	}
+	/**
+	* **Seam #2/#3 (P13 → P6)** — enregistre un authenticator pour les
+	* handshakes WS dont l'URL matche `matcher`. Ordre d'enregistrement
+	* préservé (1ʳᵉ match capture). Cold path (boot via P6/userland).
+	*
+	* @example
+	* ```ts
+	* // À brancher par @nodefony/security (P6) au boot, depuis les areas
+	* // de `defineSecurityConfig()` filtrées sur `realtime: true`.
+	* realtimeService.useAuthenticator(
+	*   { pattern: "/admin/", host: "admin.example.com" },
+	*   jwtRealtimeAuthenticator,
+	* );
+	* ```
+	*/
+	useAuthenticator(matcher, authenticator) {
+		this.getHub().useAuthenticator(matcher, authenticator);
+	}
+	/**
+	* **Seam #1 (P13 → P6)** — pose le verrou de frame (hot-path `beforeDispatch`).
+	* `null` retire la politique. À brancher 1× au boot par `@nodefony/security`
+	* depuis les zones `realtime: true`. L'authorizer lit le token déjà résolu au
+	* handshake (0 lecture base par frame). Délégué à `RealtimeHub.setFrameAuthorizer`.
+	*
+	* `options.silentProbe` porte la MÊME décision sans rapporter de refus : elle
+	* répond « ce visiteur pourrait-il s'abonner ici ? » pour l'annonce des canaux
+	* du `realtime:welcome`, qui interroge N canaux par connexion sans que
+	* personne n'ait rien demandé. Elle se pose par CE MÊME appel pour qu'aucun
+	* câblage ne puisse poser l'un sans l'autre.
+	*
+	* @example
+	* ```ts
+	* // @nodefony/security au boot :
+	* realtimeService.setFrameAuthorizer((frame, token) => {
+	*   // api.request {path} ≤ GET {path} : zone protégée → exige authentifié
+	*   return isFrameAllowed(frame, token);
+	* });
+	* ```
+	*/
+	setFrameAuthorizer(authorizer, options) {
+		this.getHub().setFrameAuthorizer(authorizer, options);
+	}
+	/**
+	* **Seam #1b** — politique d'autorisation déclarée pour un canal/méthode
+	* (`@RealtimeChannel`/`@RealtimeInbound` avec opts), agrégée par le hub au
+	* handshake. Lu par `@nodefony/security` au moment de la frame `subscribe`/
+	* inbound pour appliquer rôles/scopes. `null` = aucune politique métier (le
+	* canal est alors soumis à la seule politique plateforme de security).
+	*
+	* @param channel - nom EXACT du canal ou de la méthode inbound.
+	* @returns la politique déclarée, ou `null`.
+	*/
+	resolveChannelPolicy(channel) {
+		return this.getHub().resolveChannelPolicy(channel);
+	}
+	/**
+	* Renvoie le token associé à un peer (posé au handshake par le hub). Jamais
+	* `null` (Zero Trust : `ANONYMOUS_REALTIME_TOKEN` si aucun authenticator n'a
+	* capturé la connexion). Lookup O(1) via WeakMap interne. Branchement P6 :
+	* voters / `@IsGranted` realtime lisent l'identité par cette méthode.
+	*/
+	getTokenForPeer(peer) {
+		return this.getHub().getTokenForPeer(peer);
+	}
+};
+/**
+* Construit la fonction de garde Origin (RFC 6455 §10.2) depuis la config CSRF.
+* `null` quand le check est désactivé → hub bypass total (rétrocompat). Cold
+* path (1× par boot).
+*
+* Politique fail-closed :
+*  - `enabled: false`                 → `null` (toutes origines acceptées).
+*  - `enabled: true`, Origin absent   → accepté si `allowMissingOrigin: true`,
+*                                       sinon refusé.
+*  - `enabled: true`, Origin présent  → accepté **uniquement** si exact dans
+*                                       `allowList` (pas de wildcard).
+*/
+function buildOriginGuard(config) {
+	const c = config.csrf?.checkOrigin;
+	if (!c || c.enabled !== true) return null;
+	const allowSet = new Set(c.allowList ?? []);
+	const allowMissing = c.allowMissingOrigin === true;
+	return (origin) => {
+		if (origin === void 0 || origin === "") return allowMissing;
+		return allowSet.has(origin);
+	};
+}
+//#endregion
+export { RealtimeService, RealtimeService as default };

package/dist/nodefony/src/transport/WsConnectionTransport.js

@@ -0,0 +1,94 @@
+import { TransportState } from "nodefony";
+import { decideSend } from "@nodefony/http";
+//#region nodefony/src/transport/WsConnectionTransport.ts
+/**
+* Contre-pression WS — **la règle vit dans `@nodefony/http`**, ce transport ne
+* fait que l'appliquer (`decideSend`). Deux implémentations de la même
+* protection avaient déjà divergé en silence : 4 MiB côté `http`, 1 MiB ici.
+*
+* Réglage = config du serveur WebSocket (`websocket.maxBackpressure`,
+* `.backpressurePolicy`, `.backpressureCloseAfterDrops`) — une seule source pour
+* `send`/`broadcast` HTTP **et** pour le realtime.
+*
+* ⚠️ NE PAS confondre avec `slowConsumer.bytes` (config realtime) : celle-ci ne
+* règle QUE le seuil de COMPTAGE de la sonde, jamais l'action.
+*/
+/**
+* WsConnectionTransport — transport {@link IRealtimeTransport} CÔTÉ SERVEUR :
+* wrap d'une connexion `ws` (1 par client connecté). Pendant serveur du
+* `BrowserWsTransport` → la connexion serveur compose le MÊME `JsonRpcPeer` que
+* le client (symétrie isomorphe).
+*
+* Particularité serveur : l'inbound n'est PAS piloté par un event socket mais par
+* le **pipeline framework** (la route WS appelle `feed(raw)` à chaque message) ;
+* la fermeture est signalée par `fireClose()` (hook `onFinish` du Context). Le
+* `connect`/`onOpen` sont des no-op (la connexion est déjà ouverte au handshake).
+*/
+var WsConnectionTransport = class {
+	conn;
+	_onMessage = null;
+	_onClose = null;
+	_bytesSent = 0;
+	_messagesSent = 0;
+	_dropped = 0;
+	_max;
+	_policy;
+	_closeAfterDrops;
+	constructor(conn, limits) {
+		this.conn = conn;
+		this._max = limits?.max ?? 0;
+		this._policy = limits?.policy ?? "drop";
+		this._closeAfterDrops = limits?.closeAfterDrops ?? 0;
+	}
+	connect() {}
+	send(raw) {
+		if (this.conn.readyState !== TransportState.OPEN) return;
+		if (decideSend(this.conn, this._max, this._policy, this._closeAfterDrops) !== "send") {
+			this._dropped += 1;
+			return;
+		}
+		this._bytesSent += raw.length;
+		this._messagesSent += 1;
+		this.conn.send(raw, () => {});
+	}
+	close(code, reason) {
+		this.conn.close(code, reason);
+	}
+	get readyState() {
+		return this.conn.readyState;
+	}
+	/** Octets en file d'envoi non drainés (`ws.bufferedAmount`) — risque #1. `0` si mock. */
+	get bufferedAmount() {
+		return this.conn.bufferedAmount ?? 0;
+	}
+	/** Cumul d'octets envoyés sur cette connexion (monotone). */
+	get bytesSent() {
+		return this._bytesSent;
+	}
+	/** Cumul de frames envoyées sur cette connexion (monotone). */
+	get messagesSent() {
+		return this._messagesSent;
+	}
+	/** Cumul de frames jetées par back-pressure (drop + close slow-consumer) — monotone. */
+	get dropped() {
+		return this._dropped;
+	}
+	onOpen() {}
+	onMessage(cb) {
+		this._onMessage = cb;
+	}
+	onClose(cb) {
+		this._onClose = cb;
+	}
+	onError() {}
+	/** Pump entrant : le pipeline framework pousse ici chaque message reçu. */
+	feed(raw) {
+		this._onMessage?.(raw);
+	}
+	/** Fermeture : appelée par le owner sur `onFinish` (close WS). */
+	fireClose(code = 1e3, reason = "") {
+		this._onClose?.(code, reason);
+	}
+};
+//#endregion
+export { WsConnectionTransport, WsConnectionTransport as default };