nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/types/oauth/protectedResource.d.ts

@@ -0,0 +1,339 @@
+/**
+ * Métadonnées publiées d'une ressource protégée — RFC 9728 §2.
+ *
+ * Les noms de champs sont ceux du registre IANA, en `snake_case` : c'est un
+ * document de protocole, pas un objet interne. Le renommer « pour la
+ * cohérence » le rendrait illisible par tout client conforme.
+ *
+ * Seul `resource` est REQUIS par la RFC. `authorization_servers` y est optionnel
+ * — mais un consommateur peut en faire une exigence (le Model Context Protocol
+ * l'impose : « MUST include the `authorization_servers` field containing at
+ * least one authorization server »), et c'est ce que
+ * {@link buildProtectedResourceMetadata} applique : sans serveur d'autorisation,
+ * le document ne mène nulle part, donc il ne se publie pas.
+ */
+export interface IProtectedResourceMetadata {
+    /** URI canonique de la ressource — l'audience que les jetons doivent porter. */
+    resource: string;
+    /** Serveurs d'autorisation capables d'émettre un jeton pour elle. */
+    authorization_servers: string[];
+    /** Scopes que la ressource comprend — guide le client (RECOMMENDED). */
+    scopes_supported?: string[];
+    /**
+     * Comment présenter le jeton. Toujours `["header"]` ici, et c'est normatif :
+     * la spécification MCP interdit la chaîne de requête (« Access tokens MUST NOT
+     * be included in the URI query string ») — une URL finit dans les journaux,
+     * l'historique et le `Referer`.
+     */
+    bearer_methods_supported?: string[];
+    /** Nom lisible, affiché par le client pendant le consentement. */
+    resource_name?: string;
+    /** Où un humain lit ce que fait cette ressource. */
+    resource_documentation?: string;
+}
+/** De quoi composer le document — ce que l'application, seule, connaît. */
+export interface IProtectedResourceInput {
+    /**
+     * URI canonique de la ressource, telle qu'un client l'atteint.
+     *
+     * 🔴 **Elle s'ÉCRIT, elle ne se dérive pas de l'en-tête `Host`.** Si l'URI
+     * publiée et l'audience attendue venaient toutes deux de la requête, un `Host`
+     * forgé obtiendrait un jeton d'audience arbitraire *et* passerait la
+     * vérification : la liaison d'audience (RFC 8707), dont c'est l'unique raison
+     * d'être, ne protégerait plus rien. Un déploiement derrière un relais doit de
+     * toute façon déclarer son URL publique.
+     */
+    resource: string;
+    /** Au moins un serveur d'autorisation — sinon le document ne mène nulle part. */
+    authorizationServers: readonly string[];
+    /** Scopes compris par la ressource (facultatif, mais recommandé). */
+    scopesSupported?: readonly string[];
+    /** Nom lisible par un humain. */
+    resourceName?: string;
+    /** URL d'une documentation destinée à un humain. */
+    resourceDocumentation?: string;
+}
+/**
+ * Normalise et contrôle une URI canonique de ressource (RFC 8707 §2).
+ *
+ * Trois refus, tous vécus comme des sources d'erreur silencieuse ailleurs :
+ * l'absence de schéma (une audience relative ne se compare à rien), un fragment
+ * (interdit — il ne voyage jamais jusqu'au serveur, donc deux URI distinctes
+ * seraient reçues identiques), et un schéma non `http(s)`.
+ *
+ * La barre oblique terminale est retirée : les deux formes sont des URI
+ * valides, mais l'audience se compare par **chaîne exacte** — publier une forme
+ * et valider l'autre produit un refus que rien n'explique.
+ *
+ * @param raw - URI telle qu'écrite en configuration
+ * @returns l'URI canonique, sans barre terminale
+ * @throws Error si l'URI ne peut pas servir d'audience
+ */
+export declare function canonicalResourceUri(raw: string): string;
+/**
+ * Compose le CHEMIN où publier les métadonnées, à partir de l'URI de la
+ * ressource (RFC 9728 §3.1).
+ *
+ * La règle est une insertion, pas une concaténation : le suffixe bien connu se
+ * place **entre l'hôte et le chemin** de la ressource. Une application qui
+ * publierait `…/nodefony/mcp/.well-known/…` servirait un document que personne
+ * ne demande jamais.
+ *
+ * @param resource - URI canonique de la ressource (ou son seul chemin)
+ * @returns le chemin absolu à servir en `GET`
+ *
+ * @example
+ * ```ts
+ * protectedResourceMetadataPath("https://app.example/nodefony/mcp");
+ * // → "/.well-known/oauth-protected-resource/nodefony/mcp"
+ * protectedResourceMetadataPath("https://app.example");
+ * // → "/.well-known/oauth-protected-resource"
+ * ```
+ */
+export declare function protectedResourceMetadataPath(resource: string): string;
+/**
+ * Compose l'URL ABSOLUE des métadonnées — celle qui part dans le défi.
+ *
+ * @param resource - URI canonique de la ressource
+ * @returns l'URL complète du document de métadonnées
+ */
+export declare function protectedResourceMetadataUrl(resource: string): string;
+/**
+ * Compose le document de métadonnées.
+ *
+ * @param input - ce que l'application déclare de sa ressource
+ * @returns le document, prêt à sérialiser
+ * @throws Error si aucun serveur d'autorisation n'est déclaré, ou si l'URI de
+ *         ressource ne peut pas servir d'audience
+ */
+export declare function buildProtectedResourceMetadata(input: IProtectedResourceInput): IProtectedResourceMetadata;
+/** Codes d'erreur d'un porteur — RFC 6750 §3.1. */
+export declare const BearerError: {
+    /**
+     * Requête mal formée (schéma inconnu, jeton absent après `Bearer`).
+     * La RFC veut **400**, pas 401 : rien n'a été présenté qu'on puisse juger.
+     */
+    readonly INVALID_REQUEST: "invalid_request";
+    /** Jeton expiré, révoqué, mal formé, ou d'une autre audience → **401**. */
+    readonly INVALID_TOKEN: "invalid_token";
+    /** Identité prouvée, droits insuffisants → **403**. */
+    readonly INSUFFICIENT_SCOPE: "insufficient_scope";
+};
+/** Un des codes de {@link BearerError}. */
+export type BearerErrorCode = (typeof BearerError)[keyof typeof BearerError];
+/** De quoi composer un défi `WWW-Authenticate`. */
+export interface IBearerChallenge {
+    /** URL du document de métadonnées — RFC 9728 §5.1. */
+    resourceMetadataUrl: string;
+    /** Scopes nécessaires à l'opération en cours. */
+    scopes?: readonly string[];
+    /** Code d'erreur, ABSENT quand la requête ne portait aucune information. */
+    error?: BearerErrorCode;
+    /** Explication lisible, jamais une cause fine (anti-oracle). */
+    description?: string;
+}
+/**
+ * Compose l'en-tête `WWW-Authenticate` d'un refus.
+ *
+ * ⭐ **C'est cet en-tête qui rend l'autorisation apprenable.** Sans lui, un
+ * refus est un mur : le client ignore qu'un jeton existe, où le demander et pour
+ * quels droits. Avec `resource_metadata`, il remonte seul jusqu'au serveur
+ * d'autorisation — c'est le seul mécanisme normalisé pour cela.
+ *
+ * 🔴 **Le code d'erreur est OMIS quand la requête ne portait aucune information
+ * d'authentification** — la RFC 6750 §3 le demande explicitement (« the resource
+ * server SHOULD NOT include an error code or other error information »). Un
+ * `invalid_token` sur une requête sans jeton ferait croire au client que son
+ * jeton est mauvais, et le pousserait à le renouveler en boucle.
+ *
+ * @param challenge - de quoi composer le défi
+ * @returns la valeur de l'en-tête `WWW-Authenticate`
+ */
+export declare function buildBearerChallenge(challenge: IBearerChallenge): string;
+/**
+ * Ce qu'une vérification de jeton RÉUSSIE établit.
+ *
+ * Il n'y a pas de drapeau `authenticated` : ce type n'existe que lorsqu'une
+ * identité a été prouvée. Un booléen aurait permis de fabriquer un principal
+ * « non authentifié » et de le passer plus loin — exactement l'erreur que le
+ * type doit rendre impossible.
+ */
+export interface IAccessPrincipal {
+    /**
+     * Émetteur VÉRIFIÉ du jeton (`iss`), sous sa forme canonique.
+     *
+     * 🔴 **Un `sub` seul ne désigne personne.** OpenID Connect ne le garantit
+     * unique et non réassigné QUE dans l'espace de son émetteur : l'identité est
+     * la paire `(iss, sub)`. Transporter le sujet sans son émetteur revient à
+     * verser des identifiants étrangers dans l'espace de noms local — et un
+     * annuaire où l'utilisateur choisit son identifiant suffit alors à réclamer
+     * `admin`.
+     *
+     * REQUIS, et non optionnel : un vérificateur incapable de dire d'où vient une
+     * identité ne doit pas pouvoir en produire une. Le rendre facultatif
+     * laisserait chaque appelant décider de s'en passer, ce qui est exactement la
+     * façon dont ce trou est né.
+     *
+     * ⚠️ C'est l'émetteur de l'ALLOWLIST — celui contre lequel la signature a été
+     * vérifiée — jamais la valeur brute lue dans le jeton.
+     */
+    issuer: string;
+    /** Sujet du jeton (`sub`) — pour l'audit, et pour borner ce qu'on rend. */
+    subject?: string;
+    /** Scopes réellement accordés. */
+    scopes: readonly string[];
+    /**
+     * Expiration du jeton (`exp`), en **secondes** epoch — RFC 7519 §4.1.4.
+     *
+     * Elle a déjà été vérifiée au moment de la validation ; si elle est ici, c'est
+     * pour ce qui vient APRÈS. Une requête HTTP se termine avant que la question
+     * se pose, mais une connexion durable — une socket ouverte au nom de ce jeton
+     * — doit pouvoir mourir avec lui. Sans cette borne transportée jusqu'à
+     * l'appelant, une identité vérifiée une fois vaut indéfiniment : le jeton
+     * expire, la connexion reste.
+     *
+     * ⚠️ **Secondes**, comme le claim JWT dont elle vient — pas des millisecondes.
+     */
+    expiresAt?: number;
+    /** Émission du jeton (`iat`), en **secondes** epoch — révocation en masse. */
+    issuedAt?: number;
+    /**
+     * Identifiant unique du jeton (`jti`) — révocation CIBLÉE avant terme.
+     *
+     * Il vient d'un émetteur étranger : il ne désigne rien dans nos registres, et
+     * ne sert qu'à interroger une liste de révocation qui, elle, peut le connaître.
+     */
+    tokenId?: string;
+}
+/**
+ * Ce qui sait valider un jeton — implémenté ailleurs, jamais ici.
+ *
+ * Le cœur ne valide aucune signature : cela demande un fournisseur de clés, une
+ * dépendance cryptographique et une politique, qui vivent dans le module de
+ * sécurité. Le contrat est ici pour que la porte n'ait pas à connaître son
+ * implémentation, et pour qu'une application puisse en fournir une autre.
+ *
+ * @param token - le jeton présenté, brut
+ * @param audience - l'URI canonique de CETTE ressource ; l'implémentation
+ *          **doit** refuser un jeton qui ne la porte pas (RFC 8707 §2) — c'est
+ *          ce qui empêche un jeton émis pour un autre service d'être rejoué ici
+ * @returns le principal établi, ou `null` — jamais une exception pour un refus
+ */
+export type IAccessTokenVerifier = (token: string, audience: string) => Promise<IAccessPrincipal | null>;
+/**
+ * Nom sous lequel un {@link IAccessTokenVerifier} se pose dans le conteneur.
+ *
+ * ⭐ **La constante vit ICI, avec le contrat, et pas ailleurs.** Le nom est le
+ * point de rendez-vous entre deux paquets qui ne se connaissent pas : celui qui
+ * POSE le vérificateur (la sécurité, qui porte la cryptographie) et ceux qui le
+ * LISENT (toute porte protégée). Écrit en dur de chaque côté, il vaut jusqu'au
+ * jour où l'un des deux le renomme — un littéral ne casse aucune compilation,
+ * et la porte cherche alors un service que personne ne pose. Importé, un
+ * renommage devient une erreur de type.
+ *
+ * Le nom est **générique** à dessein : le contrat prend l'audience en
+ * paramètre, donc une seule implémentation sert autant de ressources protégées
+ * que l'application en publie (RFC 9728 §3.1).
+ */
+export declare const ACCESS_TOKEN_VERIFIER = "accessTokenVerifier";
+/** Politique appliquée à une requête vers une ressource protégée. */
+export interface IProtectedResourcePolicy {
+    /** URI canonique de la ressource — l'audience PUBLIÉE, et la première essayée. */
+    resource: string;
+    /**
+     * Autres URI sous lesquelles CETTE MÊME ressource est joignable, et dont les
+     * jetons sont acceptés.
+     *
+     * ⭐ Une ressource peut avoir plusieurs adresses sans cesser d'être une : la
+     * même porte servie en clair sur un port et en TLS sur un autre est un cas
+     * courant en développement, et un jeton émis pour l'une était refusé sur
+     * l'autre — la liaison d'audience faisant, à juste titre, son travail. La
+     * réponse n'est pas de relâcher la liaison, c'est de DIRE quelles adresses
+     * désignent cette ressource.
+     *
+     * 🔴 Ces valeurs s'ÉCRIVENT, elles ne se dérivent jamais du `Host` de la
+     * requête : dérivées, un `Host` forgé obtiendrait un jeton d'audience
+     * arbitraire *et* passerait la vérification, ce qui viderait la liaison de sa
+     * seule raison d'être. La liste reste FERMÉE.
+     *
+     * Le document RFC 9728 ne publie que {@link IProtectedResourcePolicy.resource}
+     * — la RFC n'y admet qu'une valeur, et un client n'a besoin que d'une adresse
+     * pour demander son jeton.
+     */
+    acceptedResources?: readonly string[];
+    /** URL du document de métadonnées, citée dans chaque refus. */
+    metadataUrl: string;
+    /** Scopes annoncés au client quand on le refuse. */
+    scopes?: readonly string[];
+    /**
+     * Servir une requête sans jeton comme anonyme, au lieu de la refuser.
+     *
+     * Défaut attendu : `false`. Ouvrir est un choix qui s'écrit, jamais un
+     * comportement qu'on hérite.
+     */
+    allowAnonymous: boolean;
+}
+/** Verdict rendu à la porte — à elle de le traduire en réponse. */
+export type ProtectedResourceOutcome = 
+/** Aucun jeton, et la politique l'accepte. */
+{
+    outcome: "anonymous";
+    /**
+     * Un jeton a été présenté et REJETÉ, et la porte sert quand même
+     * l'anonyme — pour le JOURNAL seul, jamais pour le client.
+     *
+     * Sans ce champ, un jeton expiré devenait indistinguable d'une requête
+     * muette : l'agent perdait ses outils réservés sans que rien ne dise
+     * pourquoi, et l'exploitant ne voyait aucune trace d'un porteur refusé.
+     */
+    rejected?: true;
+}
+/** Jeton validé. */
+ | {
+    outcome: "authenticated";
+    principal: IAccessPrincipal;
+}
+/** Refus : statut et en-tête à poser tels quels. */
+ | {
+    outcome: "challenge";
+    status: 400 | 401;
+    wwwAuthenticate: string;
+}
+/**
+ * La ressource se dit protégée, mais rien ne peut vérifier un jeton.
+ * La porte DOIT alors refuser de servir — laisser passer reviendrait à
+ * accepter n'importe quel porteur.
+ *
+ * Deux causes, que `why` distingue POUR LE JOURNAL seul : aucun vérificateur
+ * n'est posé (faute de configuration), ou le vérificateur a ÉCHOUÉ — émetteur
+ * injoignable, jeu de clés illisible. Le client, lui, reçoit le même refus
+ * dans les deux cas : ce qui empêche de le servir ne le regarde pas.
+ */
+ | {
+    outcome: "unverifiable";
+    why?: string;
+};
+/**
+ * Décide du sort d'une requête d'après l'en-tête `Authorization`.
+ *
+ * **Fonction pure** (hors l'appel au vérificateur) : elle ne touche ni au
+ * socket, ni au conteneur, ni à l'horloge — d'où le fait que chacun de ses
+ * verdicts, statuts et en-têtes compris, s'éprouve sans démarrer de serveur.
+ *
+ * @param authorizationHeader - valeur brute de l'en-tête, ou rien
+ * @param policy - ce que la ressource exige
+ * @param verify - ce qui sait valider un jeton, s'il y a quelque chose
+ * @returns le verdict à appliquer
+ */
+export declare function authorizeProtectedResource(authorizationHeader: unknown, policy: IProtectedResourcePolicy, verify: IAccessTokenVerifier | undefined): Promise<ProtectedResourceOutcome>;
+/**
+ * L'appelant présente-t-il TOUS les scopes exigés ?
+ *
+ * « Tous », et pas « au moins un » : un scope borne un pouvoir, et les cumuler
+ * par disjonction reviendrait à accorder le plus large de la liste.
+ *
+ * @param granted - scopes accordés au porteur
+ * @param required - scopes exigés par l'opération
+ * @returns les scopes MANQUANTS — tableau vide si rien ne manque
+ */
+export declare function missingScopes(granted: readonly string[], required: readonly string[]): string[];

package/dist/types/realtime/IRealtimeSocket.d.ts

@@ -0,0 +1,142 @@
+/**
+ * IRealtimeSocket — « la socket Nodefony » : la prise temps réel **ISOMORPHE** client↔back.
+ *
+ * C'est LA brique du realtime Nodefony (cf vision « la socket Nodefony ») : un seul lien,
+ * qui a une **existence identique côté back et côté front** (fusionnel), dont le **plan de
+ * contrôle parle JSON-RPC 2.0** ({@link IRealtimePeer}) et qui **multiplexe N canaux** par
+ * souscription. Un consommateur — page front OU service back — tient **UN handle**
+ * (`subscribe / on / publish / request`) : c'est SA socket. Il ignore quel transport porte
+ * les octets, si le pair est local ou distant, et comment chaque canal est servi.
+ *
+ * Vocabulaire : la **socket** est la prise (ce qu'on tient) ; derrière elle, côté serveur,
+ * un **hub** ({@link RealtimeHub}) aiguille entre les N sockets des clients et, à terme,
+ * entre les pods (backplane Redis). La socket multiplexe des canaux ; le hub aiguille entre
+ * les sockets. La couche octets, elle, est le {@link IRealtimeTransport} (≠ « socket » ici).
+ *
+ * ── Un canal = un sous-flux nommé DUPLEX ──
+ *  Chaque canal est un tuyau bidirectionnel multiplexé sur la socket. Son **backing est
+ *  pluggable côté serveur**, transparent pour le consommateur :
+ *   - **pub/sub** (défaut) : notifications JSON-RPC (ex. `nodefony:dashboard`).
+ *   - **encapsulation de protocole** : le canal transporte un AUTRE langage tunnelé dans la
+ *     socket (ex. **SIP** sur `sip:line1`).
+ *   - **bridge** : le canal est câblé vers une autre couche de transport (**TCP/UDP**).
+ *   - **proxy** : le canal relaie vers un autre service.
+ *  Le **backplane Redis** (fan-out cross-pod cloud-native) n'est qu'UN backing parmi ceux-là.
+ *
+ * ── Sémantique des verbes (identique des deux côtés, cible différente) ──
+ *  - `publish(channel, payload)` : émet sur un canal (duplex). Côté **client** → vers le
+ *    serveur (1 pair) ; côté **serveur** → fan-out aux abonnés via le hub (+ backplane).
+ *  - `subscribe` / `unsubscribe` : DEMANDE / arrête un flux (ref-compté).
+ *  - `on` / `off` : REÇOIT (`on` ≠ `subscribe` : l'un branche le handler local, l'autre
+ *    demande au pair de pousser).
+ *  - `request(method, params?)` : RPC corrélé (`Promise` du `result`).
+ *  - `channel(name)` : renvoie un {@link IRealtimeChannel} (objet par canal) — forme
+ *    naturelle des canaux à état (SIP, bridge) et point d'accroche des futures couches
+ *    (codec, cadence AIMD, politique drop/coalesce/batch par canal).
+ *
+ * Impl de référence : {@link RealtimeClient} (navigateur). Côté serveur, le hub à canaux
+ * partagés ({@link RealtimeHub}, fan-out + backings) et une façade consommateur dériveront
+ * de ce même contrat.
+ *
+ * @see {@link IRealtimePeer} — la couche protocole (JSON-RPC 2.0) en dessous.
+ * @see {@link IRealtimeTransport} — la couche octets (le seul maillon client/serveur).
+ */
+import type { ActionsMap, DefaultActionsMap, DefaultEventsMap, EventNames, EventPayload, EventsMap, ContractParams, ContractResult } from "./RealtimeEventMap.js";
+/** Handler d'un canal pub/sub — reçoit le `params` de la notification (ou `(method, params)` sur `"*"`). */
+export type RealtimeHandler = (...args: unknown[]) => void;
+/**
+ * Compteurs d'un canal — **génériques**, calculés au point d'arrivée des frames donc
+ * fiables et réutilisables par toute app. (`RealtimeClient.MessageStats` en est l'alias.)
+ */
+export interface IChannelStats {
+    /** Méthode JSON-RPC == nom du canal pub/sub. */
+    method: string;
+    /** Total de notifications reçues sur ce canal. */
+    msgCount: number;
+    /** Timestamp (ms) de la dernière notification, `null` si aucune. */
+    lastMessage: number | null;
+    /** Débit instantané (msg/s), échantillonné 1×/s. */
+    rate: number;
+    /** Historique du débit (VU-mètre) — fenêtre glissante. */
+    series: number[];
+}
+/**
+ * Handle d'UN canal — vue par-canal d'un sous-flux duplex multiplexé sur la
+ * {@link IRealtimeSocket}. Forme naturelle des canaux à état (un appel SIP, une connexion
+ * bridgée) : il porte son nom, sa nature et son cycle de vie. C'est le **point d'accroche**
+ * des couches à venir (codec de protocole, cadence AIMD, politique `drop|coalesce|batch`) —
+ * elles enrichiront ce handle SANS retoucher la socket.
+ *
+ * N'introduit AUCUN protocole nouveau : fine liaison au-dessus des primitives de la socket
+ * (`subscribe`/`on`/`publish`).
+ */
+export interface IRealtimeChannel {
+    /** Nom du canal (clé de multiplexage == method JSON-RPC des notifications). */
+    readonly name: string;
+    /**
+     * Nature du backing serveur (`pubsub` | `protocol` | `bridge` | `proxy` | …), annoncée
+     * par le serveur. `undefined` tant qu'inconnue (ex. côté client avant découverte).
+     */
+    readonly kind?: string;
+    /** Branche un handler de réception sur ce canal. Renvoie un `dispose`. */
+    on(handler: RealtimeHandler): () => void;
+    /** Émet sur ce canal (duplex, one-way). */
+    send(payload?: unknown): void;
+    /** Ouvre le flux : `subscribe` ref-compté (demande au pair de pousser). */
+    open(): void;
+    /** Ferme : `unsubscribe` ref-compté + retire les handlers branchés via ce handle. */
+    close(): void;
+}
+/**
+ * Contrat de « la socket Nodefony » — voir le bloc de tête du fichier. Implémenté par
+ * {@link RealtimeClient} (front) et, à terme, par une façade serveur au-dessus du hub.
+ *
+ * @typeParam Emit    — canaux pub/sub SORTANTS (typage de `publish`).
+ * @typeParam Listen  — canaux pub/sub RÉCEPTIONNÉS (typage de `subscribe`/`on`/`off`).
+ * @typeParam Actions — contrat RPC bidirectionnel (typage de `request`).
+ *
+ * Défauts permissifs sur les 3 → rétro-compat 100% pour le code non paramétré.
+ *
+ * **Pattern « type conditionnel inline »** : chaque méthode a UNE signature unique
+ * paramétrée par un `K extends string`. Si `K` matche la map (`EventNames<Listen>`,
+ * `EventNames<Emit>`, `ActionNames<Actions>`) → typage strict ; sinon → fallback
+ * permissif (`unknown`/`RealtimeHandler`). Permet les noms système (`__notice__`,
+ * `*`, `subscribe`/`unsubscribe` internes) à côté du contrat applicatif typé sans
+ * 2 overloads incompatibles en variance.
+ */
+export interface IRealtimeSocket<Emit extends EventsMap = DefaultEventsMap, Listen extends EventsMap = DefaultEventsMap, Actions extends ActionsMap = DefaultActionsMap> {
+    /**
+     * S'abonne à un canal (ref-compté) : émet la demande au pair UNIQUEMENT au 1ᵉʳ
+     * consommateur ; ré-émise automatiquement à chaque (re)connexion. Ne REÇOIT pas —
+     * brancher {@link IRealtimeSocket.on} pour ça.
+     */
+    subscribe(channel: EventNames<Listen> | (string & {})): void;
+    /** Désabonne un consommateur (ref-compté) : coupe le flux réseau au DERNIER. No-op si non suivi. */
+    unsubscribe(channel: EventNames<Listen> | (string & {})): void;
+    /**
+     * Branche un handler sur un canal (réception). Renvoie un `dispose` (désabonnement
+     * local). Plusieurs handlers par canal autorisés.
+     */
+    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;
+    /**
+     * Émet sur un canal (one-way, pas de réponse). Côté client → notification au serveur ;
+     * côté serveur → fan-out aux abonnés via le hub (+ backplane). No-op si non connecté.
+     */
+    publish<K extends string>(channel: K, payload?: K extends EventNames<Emit> ? EventPayload<Emit, K> : unknown): void;
+    /** RPC corrélé — `Promise` résolue avec le `result` (rejette sur `error`/timeout). */
+    request<K extends string, T = unknown>(method: K, params?: ContractParams<Actions, K>, timeoutMs?: number): Promise<ContractResult<Actions, K, T>>;
+    /**
+     * Vue par-canal — voir {@link IRealtimeChannel}. Fine liaison sur les primitives
+     * ci-dessus ; forme cible pour SIP/bridge/proxy et les concerns par-canal.
+     */
+    channel(name: string): IRealtimeChannel;
+    /** Snapshot des compteurs par canal (refs internes — à LIRE, pas à muter). */
+    getStats(): IChannelStats[];
+    /** Compteurs d'un canal précis (== method JSON-RPC) ou `undefined`. */
+    getChannelStats(channel: string): IChannelStats | undefined;
+    /** Canaux actuellement abonnés (≥ 1 consommateur). Lecture seule. */
+    readonly subscribedChannels: string[];
+}
+export default IRealtimeSocket;

package/dist/types/realtime/IRealtimeTransport.d.ts

@@ -0,0 +1,50 @@
+/**
+ * IRealtimeTransport — le SEUL maillon qui diffère client/serveur.
+ *
+ * Le protocole ({@link JsonRpcPeer}) et les « smarts » (stats, pub/sub) sont
+ * isomorphes ; seule la façon dont les **octets** entrent et sortent change. On
+ * isole donc le transport derrière cette interface : un même endpoint compose
+ * N transports.
+ *
+ * Implémentations :
+ *  - `BrowserWsTransport` (navigateur, `WebSocket` + reconnect géré au-dessus)
+ *  - `WsConnectionTransport` (serveur, wrap d'une connexion `ws` — P… RealtimeController)
+ *  - futurs P13 : `Tcp`/`Udp`/`Redis`/`SipTransport` (RealtimeService / IRealtimeHub)
+ *
+ * Les états suivent les constantes `WebSocket` (0..3) pour rester universels —
+ * voir {@link TransportState}.
+ *
+ * ── Sens des flux ──
+ *  Sortant : `send` (frame brute déjà sérialisée), `close`.
+ *  Entrant : le owner branche `onMessage` (chaque frame reçue) ; `onOpen`/`onClose`/
+ *  `onError` pilotent le cycle de vie (l'orchestration reconnect/heartbeat vit
+ *  AU-DESSUS, dans l'endpoint — le transport reste « bête »).
+ */
+/** États d'un transport — alignés sur les constantes `WebSocket`. */
+export declare const TransportState: {
+    readonly CONNECTING: 0;
+    readonly OPEN: 1;
+    readonly CLOSING: 2;
+    readonly CLOSED: 3;
+};
+export type TransportStateValue = (typeof TransportState)[keyof typeof TransportState];
+export interface IRealtimeTransport {
+    /** Ouvre le transport (asynchrone — l'ouverture effective est signalée par `onOpen`). */
+    connect(): void;
+    /** Envoie une frame brute (déjà sérialisée). No-op si non ouvert. */
+    send(raw: string): void;
+    /** Ferme le transport (déclenche `onClose`). */
+    close(code?: number, reason?: string): void;
+    /** État courant (0..3, cf {@link TransportState}). */
+    readonly readyState: number;
+    /** Branche le handler d'ouverture (le owner relance subscribe/heartbeat). */
+    onOpen(cb: () => void): void;
+    /** Branche le pump entrant : appelé pour chaque frame brute reçue. */
+    onMessage(cb: (raw: string) => void): void;
+    /** Branche la fermeture (le owner relance le backoff ou nettoie). */
+    onClose(cb: (code: number, reason: string) => void): void;
+    /** Branche les erreurs transport (la fermeture qui suit gère le reconnect). */
+    onError(cb: (err: unknown) => void): void;
+}
+/** Fabrique d'un transport pour une URL — injectable (tests, transports alternatifs). */
+export type RealtimeTransportFactory = (url: string) => IRealtimeTransport;