@nodefony/security 10.0.0-beta.5 → 10.0.0-beta.7

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

@@ -13,6 +13,72 @@
  */
 /** Fragment additif d'un module : directive CSP → sources à ajouter. */
 export type CspFragment = Record<string, readonly string[]>;
+/**
+ * Dit si une source CSP ouvre la directive à n'importe quel contenu.
+ *
+ * Trop large : `*`, un schéma réseau nu (`https:`, `wss:`…), un hôte joker seul
+ * (`https://*`, `*:443`). Restent acceptés : une origine exacte, un joker de
+ * sous-domaine borné (`https://*.example.com`), un mot-clé (`'self'`) et les
+ * schémas locaux (`blob:`, `data:`) — SAUF dans une directive de scripts :
+ * `data:` y exécute le code porté par l'URL, `blob:` celui qu'un script a
+ * fabriqué, et sans nonce c'est une injection de script.
+ *
+ * @param source - un jeton de source CSP.
+ * @param directive - la directive qui porte la source ; sans elle, les schémas
+ *   locaux sont acceptés.
+ * @returns `true` si la source autorise n'importe quel hôte ou contenu.
+ */
+export declare function isOverbroadSource(source: string, directive?: string): boolean;
+/**
+ * Retire d'un fragment de MODULE ses sources trop larges (cf {@link isOverbroadSource}).
+ *
+ * Moindre privilège : une contribution GLOBALE (`Firewall.registerCspOrigins`)
+ * ne déclare que SON origine, et n'ouvre pas la politique de toute l'application.
+ * Retirer plutôt que lever : la sécurité ne bloque pas le démarrage. Ne
+ * s'applique PAS à ce que l'application écrit elle-même (sa config, un `@Csp` de
+ * route) : un choix délibéré de son auteur n'est jamais contourné en silence.
+ *
+ * @param fragment - directives déclarées par un module.
+ * @returns le fragment sans les sources trop larges, et les paires retirées.
+ */
+export declare function withoutOverbroadSources(fragment: CspFragment): {
+    fragment: CspFragment;
+    dropped: Array<[string, string]>;
+};
+/**
+ * Relève les sources trop larges d'un jeu de directives (cf {@link isOverbroadSource}).
+ *
+ * @param directives - paires `[directive, sources]` (`parseCsp(csp)` ou `Object.entries(fragment)`).
+ * @returns les paires `[directive, source]` trop larges, dans l'ordre de lecture.
+ */
+export declare function findOverbroadSources(directives: Iterable<readonly [string, readonly string[]]>): Array<[string, string]>;
+/**
+ * Relève les sources de scripts d'un fragment que `'strict-dynamic'` rend inertes.
+ *
+ * Sous `'strict-dynamic'` dans `script-src`, un navigateur CSP3 ignore les hôtes
+ * et les schémas : un script n'est admis que signé, ou chargé par un script
+ * signé (W3C CSP3 § « strict-dynamic »). La source reste utile à un navigateur
+ * CSP2 ; on la garde, mais son auteur doit savoir qu'elle n'ouvre rien.
+ *
+ * @param fragment - directives déclarées par un module.
+ * @param policy - politique à laquelle le fragment s'ajoute.
+ * @returns les paires `[directive, source]` inertes ; vide sans `'strict-dynamic'`.
+ */
+export declare function findInertScriptSources(fragment: CspFragment, policy: string): Array<[string, string]>;
+/**
+ * Refuse un fragment CSP qui sortirait de la grammaire CSP3 — seule garde contre
+ * l'injection de directives par une valeur de configuration.
+ *
+ * Sans elle, une source comme `https://a.example; frame-src *` ajoute une
+ * directive que personne n'a demandée, et `https://a.example, frame-src *` coupe
+ * l'en-tête en deux politiques. Appelée là où un fragment ENTRE (enregistrement
+ * d'un module, fusion d'une route `@Csp`), jamais par requête.
+ *
+ * @param fragment - directives additionnelles (`directive → sources`).
+ * @param origin - qui déclare le fragment, pour nommer la faute.
+ * @throws BootConfigurationError si un nom ou une source sort de la grammaire.
+ */
+export declare function assertCspFragment(fragment: CspFragment, origin: string): void;
 /**
  * Parse une chaîne CSP en directives ordonnées `[nom, sources[]]`. L'ordre des
  * directives et des sources est préservé (déterminisme : header stable, tests
@@ -32,8 +98,84 @@ export declare function serializeCsp(directives: Array<[string, string[]]>): str
  * origines (jamais par requête). Le résultat repart dans `SecurityHeaders`, qui
  * re-split autour de `{{nonce}}` au boot → 1 `join` par requête (hot-path inchangé).
  *
+ * Chaque fragment passe {@link assertCspFragment} : une source hors grammaire
+ * lève au lieu d'injecter une directive. Aucune source n'est retirée ici : le
+ * filtre des sources trop larges ne vise que les contributions globales des
+ * modules ({@link withoutOverbroadSources}, appliqué à l'enregistrement).
+ *
  * @param base - CSP de configuration (peut contenir `'nonce-{{nonce}}'`).
  * @param fragments - fragments additifs (un par module enregistré).
  * @returns la chaîne CSP fusionnée.
+ * @throws BootConfigurationError si un fragment sort de la grammaire CSP3.
  */
 export declare function mergeCspFragments(base: string, fragments: Iterable<CspFragment>): string;
+/** Directive réservée aux réponses servies en TLS (ADR-0024 §C6). */
+export declare const UPGRADE_INSECURE_REQUESTS = "upgrade-insecure-requests";
+/**
+ * Retire une directive d'une politique, sans toucher au reste.
+ *
+ * Sert à composer, au démarrage, la variante EN CLAIR d'une politique qui porte
+ * `upgrade-insecure-requests` : sur une page servie en `http`, la directive
+ * réécrirait chaque sous-ressource en `https`, que le serveur ne sert pas.
+ *
+ * @param csp - politique (peut contenir `'nonce-{{nonce}}'`).
+ * @param name - nom de la directive, insensible à la casse.
+ * @returns la politique sans la directive ; la MÊME chaîne si elle n'y est pas.
+ */
+export declare function withoutDirective(csp: string, name: string): string;
+/**
+ * Traduit la valeur de `X-Frame-Options` en source de `frame-ancestors`.
+ *
+ * Un seul réglage, `http.securityHeaders.frameOptions`, pilote les DEUX en-têtes :
+ * un navigateur CSP ignore `X-Frame-Options` dès que `frame-ancestors` est
+ * présent (W3C CSP3 § « `frame-ancestors` »), et l'inverse vaut pour un ancien
+ * navigateur. Deux réglages distincts finiraient par dire deux choses.
+ *
+ * @param frameOptions - valeur émise de `X-Frame-Options` (`null` = non émis).
+ * @returns `'none'` pour `DENY`, `'self'` pour `SAMEORIGIN`, `null` sinon
+ *   (en-tête coupé, ou valeur que `frame-ancestors` ne sait pas traduire).
+ */
+export declare function frameAncestorsFor(frameOptions: string | null): string | null;
+/**
+ * Ajoute à une politique la directive `frame-ancestors` dérivée de
+ * `X-Frame-Options` (cf {@link frameAncestorsFor}).
+ *
+ * L'application garde la main : une politique qui déclare DÉJÀ
+ * `frame-ancestors` est rendue telle quelle — c'est le geste qui autorise
+ * l'encadrement par une origine tierce. Une politique vide le reste (pas de CSP
+ * voulue). Appelée à la composition de la politique de base, jamais par requête.
+ *
+ * @param csp - politique de base (config `security.headers.csp`).
+ * @param frameOptions - valeur émise de `X-Frame-Options` (`null` = non émis).
+ * @returns la politique, complétée de `frame-ancestors` si besoin.
+ */
+export declare function withFrameAncestors(csp: string, frameOptions: string | null): string;
+/**
+ * Demande à une politique ses rapports de violation : `report-uri` (lu par
+ * tous les navigateurs, en http comme en https) ET `report-to` (Reporting API,
+ * que le navigateur n'honore que vers une origine sûre — https ou localhost).
+ * ADR-0024 §C7.
+ *
+ * L'application garde la main : une politique qui déclare DÉJÀ `report-uri` ou
+ * `report-to` est rendue telle quelle — elle a son collecteur. Une politique
+ * vide le reste.
+ *
+ * @param csp - politique de base.
+ * @param url - où poster les rapports (chemin absolu ou URL https).
+ * @param group - nom du groupe `report-to`, déclaré par `Reporting-Endpoints`.
+ * @returns la politique, et `added` vrai si les directives ont été posées ici —
+ *   c'est alors à l'appelant d'émettre `Reporting-Endpoints`.
+ */
+export declare function withViolationReports(csp: string, url: string, group: string): {
+    csp: string;
+    added: boolean;
+};
+/**
+ * Valide l'URL d'un collecteur de rapports écrite par l'application : un
+ * chemin absolu (`/csp`) ou une URL `https:` / `http:`, sans rien qu'un en-tête
+ * ou une directive CSP ne puisse porter (espace, `;`, `,`, guillemet).
+ *
+ * @param url - valeur de `headers.cspReport`.
+ * @returns la cause du refus, ou `null` si l'URL est utilisable.
+ */
+export declare function reportUrlProblem(url: string): string | null;

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

@@ -0,0 +1,73 @@
+import type { ICspReportsSnapshot } from "nodefony";
+/** Sévérité d'une ligne du journal, au vocabulaire du syslog Nodefony. */
+type LogSeverity = "WARNING" | "NOTICE";
+/** Options d'un {@link CspReportCollector}. */
+export interface ICspReportCollectorOptions {
+    /** URL que la politique désigne (rendue par la lecture). */
+    endpoint: string;
+    /** Violations distinctes gardées au plus. */
+    capacity?: number;
+    /** Rapports acceptés par adresse et par minute. */
+    perMinute?: number;
+    /** Adresses suivies au plus par le quota (borne mémoire). */
+    maxTrackedClients?: number;
+    /** Violations NEUVES journalisées au plus par minute, toutes adresses confondues. */
+    logPerMinute?: number;
+    /** Journal ; une violation neuve y part une fois, jamais à chaque répétition. */
+    log?: (message: string, severity: LogSeverity) => void;
+    /** Horloge injectable (ms), pour les tests. */
+    now?: () => number;
+}
+/** Ce que devient un rapport reçu — l'émetteur n'en saura rien (204 toujours). */
+export type CspReportOutcome = "stored" | "duplicate" | "limited" | "unsupported" | "malformed";
+/**
+ * Reçoit, expurge, dédoublonne et garde EN MÉMOIRE les rapports de violation
+ * CSP (ADR-0024 §C7). La porte qui les livre est publique — le navigateur
+ * n'envoie aucun identifiant — donc tout ce qui entre est traité comme écrit
+ * par un attaquant :
+ *
+ * - **quota par adresse** (fenêtre d'une minute, le limiteur de `@nodefony/http`) ;
+ * - **deux types de contenu seulement** : `application/csp-report` (`report-uri`)
+ *   et `application/reports+json` (`report-to`) ;
+ * - **URL expurgées** de leur requête, de leur fragment et de leurs identifiants
+ *   (la norme ne retire pas la requête : elle peut porter un jeton) ; une URL
+ *   qui n'est pas HTTP(S) se réduit à son schéma ;
+ * - **l'extrait de code n'est jamais gardé** — c'est une chaîne de l'attaquant ;
+ * - **mémoire bornée** : au plus `capacity` violations distinctes, la moins
+ *   récemment vue évincée d'abord ; une répétition incrémente un compteur ;
+ * - **journal dédoublonné et borné** : une violation neuve y part une fois, et
+ *   pas plus de `logPerMinute` lignes par minute.
+ *
+ * Rien n'est écrit sur disque : le journal centralisé voit déjà ce qui compte.
+ */
+export declare class CspReportCollector {
+    #private;
+    /** URL que la politique désigne. */
+    readonly endpoint: string;
+    /** Violations distinctes gardées au plus. */
+    readonly capacity: number;
+    /**
+     * @param options - URL désignée, bornes, journal, horloge.
+     */
+    constructor(options: ICspReportCollectorOptions);
+    /**
+     * Traite un corps de rapport déjà lu (et déjà borné par l'appelant).
+     *
+     * @param contentType - type de contenu de la requête, paramètres compris ou non.
+     * @param body - le corps, octets ou texte.
+     * @param client - adresse cliente résolue (proxy de confiance compris) ;
+     *   `null` = inconnue, non comptée (jamais une clé commune à tous).
+     * @param userAgent - en-tête `User-Agent`, gardé tronqué.
+     * @returns ce que le rapport est devenu — pour le journal et les tests ;
+     *   l'émetteur reçoit 204 quoi qu'il arrive.
+     */
+    receive(contentType: string | null | undefined, body: Uint8Array | string, client: string | null, userAgent?: string | null): CspReportOutcome;
+    /**
+     * Photo des violations gardées, la plus récemment vue d'abord — ce que rend
+     * le plan d'administration.
+     *
+     * @returns une copie : la modifier ne touche pas le collecteur.
+     */
+    snapshot(): ICspReportsSnapshot;
+}
+export {};

package/dist/types/nodefony/src/net/fetchPublic.d.ts

@@ -0,0 +1,73 @@
+import { type IncomingHttpHeaders } from "node:http";
+import { type DnsResolver } from "./ssrfGuard.js";
+/**
+ * Requête sortante vers un site TIERS, sûre par construction — la primitive que
+ * tout code de Nodefony (webhooks, aperçu de lien, agents, RAG) appelle quand
+ * l'adresse vient d'un humain.
+ *
+ * Guide pour un agent : n'écris jamais `fetch(urlUtilisateur)`. Appelle
+ * {@link fetchPublic} ; la règle de cible vit dans `assertPublicUrl`
+ * (`ssrfGuard.ts`) et n'est jamais recopiée ici.
+ */
+/** Options de {@link fetchPublic}. */
+export interface IFetchPublicOptions {
+    /** Méthode HTTP. Défaut : `GET` (`POST` si un corps est fourni). */
+    readonly method?: string;
+    /** En-têtes ajoutés. Ni `Cookie` ni `Authorization` ne sont posés d'office. */
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Corps de la requête (texte UTF-8 ou octets). */
+    readonly body?: string | Uint8Array;
+    /** Redirections suivies au plus. Défaut : `0` (un 3xx est rendu tel quel). */
+    readonly maxRedirects?: number;
+    /** Octets du corps de réponse lus au plus. Défaut : 1 Mio. */
+    readonly maxBytes?: number;
+    /** Délai TOTAL (résolution, connexions, redirections, lecture), en ms. Défaut : 10 000. */
+    readonly timeoutMs?: number;
+    /** Autorise `http:` en plus de `https:`. Défaut : `false`. */
+    readonly allowHttp?: boolean;
+    /** Autorise les cibles non publiques (dev/test seulement). Défaut : `false`. */
+    readonly allowPrivate?: boolean;
+    /** Résolveur DNS injectable (tests). Défaut : `node:dns`. */
+    readonly resolver?: DnsResolver;
+    /**
+     * IP DÉJÀ vérifiées par `assertPublicUrl` pour l'adresse de départ : la
+     * connexion y est épinglée sans nouvelle résolution. Pour un appelant qui a
+     * contrôlé l'adresse plus tôt (webhooks) ; les redirections, elles, sont
+     * toujours revérifiées.
+     */
+    readonly vettedAddresses?: readonly string[];
+}
+/** Réponse de {@link fetchPublic}. */
+export interface IFetchPublicResult {
+    /** Code de statut HTTP de la réponse finale. */
+    readonly status: number;
+    /** En-têtes de la réponse finale. */
+    readonly headers: IncomingHttpHeaders;
+    /** Corps reçu, NON décodé (`Content-Encoding` n'est jamais appliqué). */
+    readonly body: Uint8Array;
+    /** `true` si `maxBytes` a coupé la lecture (la connexion a alors été détruite). */
+    readonly truncated: boolean;
+    /** Adresse de la réponse finale (après redirections). */
+    readonly url: URL;
+    /** Nombre de redirections suivies. */
+    readonly redirects: number;
+}
+/**
+ * Lit une URL fournie par un humain sans jamais atteindre le réseau interne.
+ *
+ * À CHAQUE saut (adresse de départ comme redirections) : protocole, absence
+ * d'identifiants et IP sont jugés par `assertPublicUrl`, puis la connexion est
+ * ÉPINGLÉE sur l'IP vérifiée (aucune seconde résolution : un rebinding DNS ne
+ * mène nulle part). Le délai est TOTAL — un serveur qui goutte un octet par
+ * seconde est coupé — et la lecture s'arrête à `maxBytes` en détruisant la
+ * connexion. Aucun cookie, aucun `Authorization` n'est ajouté ni conservé à
+ * travers une redirection, et le corps n'est jamais décodé (pas de bombe de
+ * décompression).
+ *
+ * @param rawUrl - adresse à lire.
+ * @param options - méthode, corps, bornes et politique de cible.
+ * @returns la réponse finale, corps borné et non décodé.
+ * @throws SsrfError si la cible, ou une redirection, est interdite.
+ * @throws FetchPublicError si le délai total, le nombre de redirections ou le réseau échoue.
+ */
+export declare function fetchPublic(rawUrl: string, options?: IFetchPublicOptions): Promise<IFetchPublicResult>;

package/dist/types/nodefony/src/oauth/oauthProviderRegistry.d.ts

@@ -75,6 +75,13 @@ export interface IOAuthProviderRegistration {
      * émetteur. Absent : l'émetteur est facultatif (connu d'avance, ou inutile).
      */
     readonly requiresIssuer?: boolean;
+    /**
+     * Sources d'où le fournisseur sert les images du profil (avatars) —
+     * déclarées dans `img-src` de la politique de contenu quand, et seulement
+     * quand, le fournisseur est configuré. Origines exactes ; un joker de
+     * sous-domaine (`https://*.googleusercontent.com`) au plus.
+     */
+    readonly imageSources?: readonly string[];
 }
 /**
  * Enregistre (ou remplace) la fabrique d'un fournisseur OAuth. Appelée par les
@@ -85,6 +92,14 @@ export interface IOAuthProviderRegistration {
  * @param registration - exigences de configuration, vérifiées au démarrage.
  */
 export declare function registerOAuthProvider(name: string, factory: OAuthProviderFactory, registration?: IOAuthProviderRegistration): void;
+/**
+ * Sources d'images (avatars) des fournisseurs nommés, sans doublon — ce que
+ * `img-src` doit autoriser pour afficher leurs photos de profil.
+ *
+ * @param names - fournisseurs configurés ; un nom inconnu ne rend rien
+ * @returns les sources déclarées par leurs enregistrements
+ */
+export declare function oauthProviderImageSources(names: Iterable<string>): string[];
 /** Fabrique d'un fournisseur par nom, ou `undefined` si inconnu. */
 export declare function getOAuthProviderFactory(name: string): OAuthProviderFactory | undefined;
 /** `true` si le fournisseur nommé a déclaré exiger un émetteur en configuration. */

package/dist/types/nodefony/src/realtime/UserRealtimeToken.d.ts

@@ -1,5 +1,17 @@
+import type { ISubscriberIdentity, TokenStatus } from "nodefony";
 import type { IUser } from "@nodefony/user";
 import type { IRealtimeToken } from "./realtimeContracts.js";
+/**
+ * Ce que l'identité d'admission tient du jeton d'ORIGINE et que l'utilisateur ne dit pas : son émetteur, et l'existence d'un compte local relisible.
+ */
+export interface IRealtimeAdmissionSource {
+    /** `iss` du jeton vérifié ; `null` sans jeton (session, clé d'API). */
+    readonly issuer: string | null;
+    /** `false` pour un appelant machine sans compte local (`<émetteur>#<sujet>`). */
+    readonly account: boolean;
+}
+/** Une session ou une clé d'API : aucun émetteur, un compte local — figé et partagé. */
+export declare const LOCAL_ACCOUNT: IRealtimeAdmissionSource;
 /**
  * Adaptateur `IUser` → `IRealtimeToken` (jeton realtime).
  *
@@ -32,8 +44,12 @@ export declare class UserRealtimeToken implements IRealtimeToken {
      * @param type - mode d'authentification réel (défaut `"session"`).
      * @param scopes - scopes délégués du jeton d'origine (défaut aucun).
      * @param confirmAccount - relecture du compte, payée sur `api.request` seul.
+     * @param status - la CAUSE de l'état, pour un jeton porteur (expiré ou révoqué) ;
+     *   `null` pour une session, qui n'a qu'un verdict.
+     * @param admission - émetteur et compte local du jeton d'origine (défaut :
+     *   aucun émetteur, compte local — une session).
      */
-    constructor(user: IUser, revalidate?: ((nowMs?: number) => Promise<boolean>) | null, type?: string, scopes?: readonly string[], confirmAccount?: (() => Promise<boolean>) | null);
+    constructor(user: IUser, revalidate?: ((nowMs?: number) => Promise<boolean>) | null, type?: string, scopes?: readonly string[], confirmAccount?: (() => Promise<boolean>) | null, status?: ((nowMs?: number) => Promise<TokenStatus>) | null, admission?: IRealtimeAdmissionSource);
     /**
      * Zero Trust : l'identité qui a ouvert cette socket est-elle TOUJOURS vivante ?
      *
@@ -47,6 +63,14 @@ export declare class UserRealtimeToken implements IRealtimeToken {
      *   sans dépendre de l'horloge de la machine.
      */
     isValid(nowMs?: number): Promise<boolean>;
+    /**
+     * La cause de l'état de l'identité — `expired` ferme la socket en 4006, `revoked`
+     * en 4001 (ADR-0021 §S11). Sans cause câblée (session), dérivée de
+     * {@link isValid} : `false` vaut `revoked`.
+     *
+     * @param nowMs - horloge injectable (epoch ms) ; par défaut l'heure courante.
+     */
+    status(nowMs?: number): Promise<TokenStatus>;
     /**
      * Le compte qui a ouvert la socket existe-t-il toujours, actif, et sous le
      * même `id` immuable ? `true` si aucune confirmation n'est câblée.
@@ -63,6 +87,16 @@ export declare class UserRealtimeToken implements IRealtimeToken {
      * « tous les droits », elle veut dire « aucun scope » — donc refus.
      */
     getScopes(): string[];
+    /**
+     * Identité d'admission gelée de la connexion — la donnée plate que reçoit la règle `allow` d'un canal (ADR-0021 §S10).
+     *
+     * Construite une fois, au premier appel, puis rendue par RÉFÉRENCE : les rôles
+     * y sont copiés et gelés une seule fois (là où {@link getRoles} recopie à
+     * chaque appel), si bien que ni le `welcome` ni l'admission ne recopient
+     * plus rien. Gelée : une règle `allow` ne peut pas s'ajouter un rôle.
+     * `id` est l'identifiant immuable du compte, jamais son login.
+     */
+    getIdentity(): ISubscriberIdentity;
     getAttribute<T = unknown>(key: string): T | undefined;
 }
 export default UserRealtimeToken;

package/dist/types/nodefony/src/realtime/frameAuthorizer.d.ts

@@ -1,4 +1,4 @@
-import type { FrameAuthorizer, IChannelPolicy, IRealtimeToken } from "./realtimeContracts.js";
+import type { FrameAuthorizer, IChannelPolicies, IChannelPolicy, IRealtimeToken } from "./realtimeContracts.js";
 /**
  * Surface MINIMALE du firewall consommée par le verrou de frame : matcher une
  * zone par pathname ET vérifier un rôle (hiérarchie comprise). `Firewall` la
@@ -21,6 +21,12 @@ export interface IFrameAuthorizerFirewall {
  */
 export interface IChannelPolicyResolver {
     resolveChannelPolicy?(channel: string): IChannelPolicy | null;
+    /**
+     * Lecture ET écriture distincte d'un nom, en une résolution (ADR-0022 §6,
+     * décision 1 quater). Préférée quand elle existe ; un hub d'une version
+     * antérieure ne l'expose pas, et ne porte alors aucune écriture distincte.
+     */
+    resolveChannelPolicies?(channel: string): IChannelPolicies | null;
 }
 /**
  * Règle de canal **système** (plateforme) — un préfixe de namespace réservé et
@@ -42,7 +48,9 @@ export interface ISystemChannelRule {
  * @param surface - cible refusée : pont socket (`api.request`) ou canal
  *   (subscribe/inbound).
  * @param target  - pathname (api.request) ou nom de canal refusé.
- * @param reason  - raison machine stable (`zone_protected` | `channel_policy`).
+ * @param reason  - raison machine stable (`zone_protected` | `channel_policy`
+ *   | `channel_write_policy` — l'écriture distincte du canal a refusé, la
+ *   lecture était satisfaite).
  * @param token   - jeton WS de l'acteur (lu pour `getUserIdentifier()`).
  */
 export type FrameDenyReporter = (surface: "api.request" | "channel", target: string, reason: string, token: IRealtimeToken) => void;

package/dist/types/nodefony/src/realtime/realtimeContracts.d.ts

@@ -1,3 +1,4 @@
+import type { IChannelPolicies, IChannelPolicy, ISubscriberIdentity, TokenStatus } from "nodefony";
 /**
  * Miroirs STRUCTURELS des contrats `@nodefony/realtime` — **zéro import** du
  * module realtime (ni runtime ni type-only).
@@ -32,12 +33,27 @@ export interface IRealtimeToken {
      * (absent = valide). Appelé par le pont `api.request` avant l'action data plane.
      */
     isValid?(nowMs?: number): boolean | Promise<boolean>;
+    /**
+     * La CAUSE de l'état de l'identité, quand elle est connaissable : `active`,
+     * `expired` (jeton porteur arrivé à `exp`) ou `revoked` (révoqué l'emporte sur
+     * expiré). Le hub en tire le code de fermeture d'une socket ouverte : `expired` →
+     * `TOKEN_EXPIRED_CLOSE_CODE` (4006), sinon `IDENTITY_DEAD_CLOSE_CODE` (4001) —
+     * ADR-0021 §S11. Optionnel : absent, `isValid` décide et son `false` vaut 4001
+     * (une session ne sait pas dire si elle a expiré ou été détruite).
+     */
+    status?(nowMs?: number): TokenStatus | Promise<TokenStatus>;
     /**
      * Le compte de la socket existe-t-il toujours, actif, sous le même `id` ?
      * (miroir de `IRealtimeToken.confirmAccount` realtime). Optionnel (absent =
      * confirmé). Relit l'annuaire : payé sur `api.request` seul, jamais au tick.
      */
     confirmAccount?(): Promise<boolean>;
+    /**
+     * Identité d'admission gelée de la connexion (miroir de
+     * `IRealtimeToken.getIdentity` realtime) — ce que reçoit la règle `allow`
+     * d'un canal. Absente, la connexion n'entre sur aucun canal à `allow`.
+     */
+    getIdentity?(): ISubscriberIdentity;
 }
 /**
  * Données de handshake WS (miroir de `IRealtimeHandshake`) — DTO neutre passé à
@@ -73,28 +89,30 @@ export interface IRealtimeAuthenticatorMatcher {
 /**
  * Verrou de frame (miroir de `FrameAuthorizer`) — SYNC : `true` = frame
  * autorisée. Lit le token déjà résolu au handshake (0 lecture base par frame).
+ *
+ * `judgesWrite` : le verrou juge l'écriture distincte d'un canal (ADR-0022 §6,
+ * décision 1 quater) ; un hub refuse de démarrer face à un verrou qui ne le
+ * déclare pas dès qu'une telle écriture est inscrite.
+ *
+ * `explain` : la phrase qui dit pourquoi une trame a été refusée, ou `null` —
+ * lue par le hub après un refus seulement (chemin froid).
  */
-export type FrameAuthorizer = (frame: unknown, token: IRealtimeToken) => boolean;
+export type FrameAuthorizer = ((frame: unknown, token: IRealtimeToken) => boolean) & {
+    readonly judgesWrite?: true;
+    readonly explain?: (frame: unknown, token: IRealtimeToken) => string | null;
+};
 /**
- * Politique d'autorisation d'un **canal** (miroir de `ChannelPolicy` realtime) —
- * exigences à satisfaire pour `subscribe`/inbound. Toutes les contraintes posées
- * sont cumulatives (ET) ; un champ absent = pas de contrainte sur cet axe. Une
- * politique entièrement vide = canal libre (équivaut à `null`).
+ * Politique d'autorisation d'un canal — déclaration UNIQUE au cœur (`nodefony`), que le
+ * hub realtime transporte et que ce module juge. Plus de miroir structurel : la
+ * copie dérivait en silence, chacune passant ses propres tests.
  *
- * Résolue 1× au `subscribe` (cold path : un client s'abonne rarement), comparée
- * au token déjà chargé au handshake → 0 lecture base. Deux origines : déclaration
- * **métier** (`@RealtimeChannel(name, opts)`, portée par le hub realtime) et
- * **plateforme** (`defineSecurityConfig().realtimeChannels` + namespaces système
- * réservés, portée par security — cf {@link buildFrameAuthorizer}).
+ * Résolue au `subscribe`/inbound (chemin froid), comparée au jeton déjà chargé
+ * à la poignée de main → 0 lecture base. Deux origines : déclaration MÉTIER
+ * (`@RealtimeChannel(nom, politique)`, portée par le hub) et PLATEFORME
+ * (`defineSecurityConfig().realtimeChannels` + namespaces système réservés —
+ * cf {@link buildFrameAuthorizer}).
  */
-export interface IChannelPolicy {
-    /** Exige une connexion authentifiée (token non anonyme). */
-    readonly authenticated?: boolean | undefined;
-    /** Un de ces rôles suffit (évalué AVEC la hiérarchie de rôles du firewall). */
-    readonly roles?: readonly string[] | undefined;
-    /** Un de ces scopes suffit (axe API : JWT/clé API ; session BFF n'en porte pas). */
-    readonly scopes?: readonly string[] | undefined;
-}
+export type { IChannelPolicy, IChannelPolicies };
 /**
  * Surface consommée du `realtimeService` (miroir partiel de `RealtimeService`) —
  * seulement les seams que security câble/lit au boot et au dispatch. Résolu par
@@ -123,6 +141,12 @@ export interface IRealtimeService {
      * hub d'une version antérieure ne l'expose pas → traité comme `undefined`.
      */
     resolveChannelPolicy?(channel: string): IChannelPolicy | null;
+    /**
+     * Seam #1b — lecture ET écriture distincte d'un nom, en une résolution
+     * (ADR-0022 §6, décision 1 quater). Optionnel : un hub d'une version
+     * antérieure ne l'expose pas, et ne porte alors aucune écriture distincte.
+     */
+    resolveChannelPolicies?(channel: string): IChannelPolicies | null;
     /**
      * Namespaces de canaux **réservés à la plateforme**, tels que le hub les connaît
      * (`syslog:`, `orm:`, `kernel:`…). Le firewall y accroche ses politiques au lieu

package/dist/types/nodefony/src/token/jwtRuntime.d.ts

@@ -9,7 +9,11 @@ import type { ISecurityConfig } from "../../config/defineModuleConfig.js";
 export interface IJwtRuntime {
     /** Émetteur (`iss`). */
     readonly issuer: string;
-    /** Audiences acceptées au verify ; la première sert d'`aud` à l'émission. */
+    /**
+     * Liste blanche des audiences ÉMETTABLES (RFC 8707) ; la première est
+     * l'audience par défaut. Ce n'est pas ce qu'une zone accepte : une zone `jwt`
+     * n'accepte que SA ressource, ou l'audience par défaut si elle n'en a pas.
+     */
     readonly audiences: string[];
     /** TTL access token (s). */
     readonly accessTtlS: number;
@@ -24,8 +28,23 @@ export interface IJwtRuntime {
  * Dérive les paramètres effectifs depuis la config sécurité. `issuer` omis →
  * `"nodefony"` (DEVRAIT être surchargé en prod) ; `audiences` vide → l'app est sa
  * propre audience (`[issuer]`).
+ *
+ * La ressource d'une ZONE (`areas.<zone>.resource`) entre aussi dans la liste,
+ * APRÈS les audiences déclarées : c'est une ressource que ce serveur protège, et
+ * la redéclarer dans `jwt.audiences` était une seconde écriture de la même
+ * valeur — celle qu'on oublie, et dont le seul symptôme est un `invalid_target`
+ * à l'émission. Ajoutée en fin de liste, elle ne change jamais l'audience par
+ * défaut ({@link defaultAudience}).
+ *
+ * Elle n'ouvre rien de plus à la VÉRIFICATION : chaque zone, `jwt` comme
+ * `external-jwt`, exige SA ressource (l'audience par défaut pour une zone `jwt`
+ * qui n'en déclare pas) — un jeton émis pour une zone n'en ouvre pas une autre.
+ *
+ * @param jwt - section `jwt` de la config validée
+ * @param areas - zones du pare-feu ; omises, seules les audiences déclarées comptent
+ * @returns les paramètres partagés par l'émetteur et les vérificateurs
  */
-export declare function resolveJwtRuntime(jwt: ISecurityConfig["jwt"]): IJwtRuntime;
+export declare function resolveJwtRuntime(jwt: ISecurityConfig["jwt"], areas?: ISecurityConfig["areas"]): IJwtRuntime;
 /**
  * Audience inscrite dans un jeton quand aucune ressource n'est demandée : la
  * première de la liste blanche. La liste n'est jamais vide après

package/dist/types/nodefony/src/token/tokenTimeClaims.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Bornes temporelles qu'un jeton d'accès JWT DOIT porter : `exp` et `iat`
+ * (RFC 9068 §2.2, l'un et l'autre REQUIRED).
+ *
+ * UNE règle pour les deux chemins de vérification — jeton de l'application
+ * (`JwtAuthenticator`) et jeton d'un émetteur tiers (`RemoteJwtVerifier`). Sans
+ * `exp`, une connexion ouverte avec le jeton n'a plus de borne propre : le
+ * revalidateur d'une socket ne sait alors la fermer que par le store de
+ * révocation, et une clé volée suffit à signer un accès éternel.
+ */
+export declare const REQUIRED_TIME_CLAIMS: readonly string[];
+/**
+ * Tolérance d'horloge entre l'émetteur et ce serveur, en secondes : appliquée à
+ * `exp`/`nbf` par jose, et à `iat` par {@link isIssuedInFuture}.
+ */
+export declare const CLOCK_TOLERANCE_S = 5;
+/**
+ * Le jeton se dit-il émis dans le futur, au-delà de la tolérance d'horloge ?
+ *
+ * jose ne contrôle `iat` que lorsqu'un âge maximal est imposé (`maxTokenAge`),
+ * ce que Nodefony ne fait pas. Or un `iat` daté du futur rend inopérante la
+ * révocation en masse (`invalidBefore`), qui compare `iat` à un seuil passé :
+ * un jeton forgé à `iat = maintenant + 10 ans` ne serait jamais « émis avant ».
+ *
+ * @param payload - claims VÉRIFIÉS du jeton (signature déjà contrôlée)
+ * @param nowS - instant présent, en secondes epoch
+ * @param toleranceS - écart d'horloge admis, en secondes
+ * @returns `true` si `iat` dépasse `nowS + toleranceS`
+ */
+export declare function isIssuedInFuture(payload: {
+    readonly iat?: unknown;
+}, nowS: number, toleranceS: number): boolean;

package/dist/types/nodefony/src/webhook/WebhookDispatcher.d.ts

@@ -2,8 +2,36 @@ import type { IAuditEvent } from "../../contracts/IAuditEvent.js";
 import type { IWebhookEndpoint } from "../../contracts/IWebhookEndpoint.js";
 import type { IWebhookDeliveryPolicy } from "../../service/webhooks.js";
 import type { IDeliveryResult } from "./webhookDelivery.js";
-/** Une souscription matche-t-elle une action d'audit ? `*` = toutes, `x.*` = préfixe. */
+/**
+ * Rend les motifs compilés d'une liste d'abonnement, compilés à sa première lecture puis relus du cache.
+ *
+ * Deux appels sur le MÊME tableau rendent la même liste : c'est ce qui garantit
+ * qu'un abonnement n'est jamais recompilé par événement. Un motif trop large
+ * (refusé par `compileChannelPattern`) n'y figure pas.
+ *
+ * @param patterns - les motifs de l'abonnement (`IWebhookEndpoint.events`).
+ * @returns les expressions compilées, une par motif valide.
+ */
+export declare function compiledPatterns(patterns: readonly string[]): readonly RegExp[];
+/**
+ * Dit si un abonnement webhook désigne une action d'audit, selon la grammaire commune aux canaux et aux webhooks (ADR-0023 W1).
+ *
+ * `*` vaut n'importe quelle suite de caractères : `*` désigne tout, `login.*` les
+ * actions qui commencent par `login.`, `commande:*` aussi bien que `*:créée`
+ * (`compileChannelPattern`, cœur). Chaque liste n'est compilée qu'une fois.
+ *
+ * @param patterns - les motifs de l'abonnement (`IWebhookEndpoint.events`).
+ * @param action - le nom de l'action d'audit.
+ * @returns `true` si un motif au moins désigne l'action.
+ */
 export declare function matchesSubscription(patterns: readonly string[], action: string): boolean;
+/**
+ * Refuse une liste d'abonnement dont un motif porte trop de `*`, en le nommant.
+ *
+ * @param patterns - les motifs proposés à l'enregistrement ou à la mise à jour.
+ * @throws Error si un motif dépasse `MAX_CHANNEL_PATTERN_WILDCARDS` étoiles.
+ */
+export declare function assertSubscriptionPatterns(patterns: readonly string[]): void;
 /**
  * Classe le résultat d'une livraison : 2xx = succès ; réseau/timeout/429/408/5xx =
  * réessayable ; 3xx/4xx (config cliente erronée) = échec définitif (pas de retry).
@@ -29,6 +57,13 @@ export interface IWebhookDispatcherDeps {
     endpointCount(): number;
     /** Snapshot des endpoints (n'est lu que si `endpointCount() > 0`). */
     getSnapshot(): IWebhookEndpoint[];
+    /**
+     * L'abonnement tel qu'il est MAINTENANT, ou `null` s'il a été supprimé — relu à
+     * chaque tentative. Un réessai part jusqu'à plusieurs minutes après le premier
+     * envoi : sans cette relecture, il partirait vers une URL retirée, signé d'un
+     * secret révoqué, pour un abonnement supprimé ou désactivé.
+     */
+    currentEndpoint(id: string): IWebhookEndpoint | null;
     /** Secret de signature en clair (`whsec_…`) d'un endpoint. */
     secretOf(endpoint: IWebhookEndpoint): string;
     /** Politique de livraison (tolérance/retries/timeout/concurrence/file). */