@nodefony/security 10.0.0-beta.4 → 10.0.0-beta.6

package/dist/types/nodefony/service/webhooks.d.ts

@@ -17,7 +17,10 @@ export interface IWebhookRegisterInput {
     readonly enabled?: boolean;
     /** Identité de l'admin créateur (traçabilité). */
     readonly createdBy?: string | null;
-    /** Slot multi-tenant (réservé). */
+    /**
+     * Périmètre d'un locataire — réservé, **refusé s'il est rempli** tant que le
+     * multi-tenant n'existe pas (ADR-0023 W2). Absent ou `null` : abonnement sans périmètre.
+     */
     readonly tenantId?: string | null;
     /** Métadonnées extensibles. */
     readonly metadata?: Record<string, unknown>;
@@ -79,6 +82,9 @@ declare class WebhookService extends Service {
      * (la seule occasion de le lire pour le copier).
      *
      * @throws SsrfError si l'URL est invalide / cible non publique.
+     * @throws Error si un motif de `events` porte plus de trois `*` (ADR-0023 W1).
+     * @throws Error si `tenantId` est rempli : le périmètre d'un locataire n'est pas
+     * encore appliqué à la livraison (ADR-0023 W2) — l'accepter le rendrait trompeur.
      */
     register(input: IWebhookRegisterInput): Promise<IWebhookSecretReveal>;
     /**

package/dist/types/nodefony/src/admin/SecurityAdminApi.d.ts

@@ -52,6 +52,9 @@ export declare function parseAuditQuery(query: Readonly<Record<string, string |
  *  - `GET /nodefony/security/api/firewall` — introspection du firewall (zones,
  *    authenticators montés, défenses) — état RUNTIME, secrets exclus.
  *  - `GET /nodefony/security/api/roleHierarchy` — hiérarchie de rôles + résolution.
+ *  - `GET /nodefony/security/api/csp-reports` — violations CSP reçues (ADR-0024
+ *    §C7), dédoublonnées, la plus récente d’abord ; champs écrits par le
+ *    navigateur, donc à afficher comme du texte.
  *  - `GET /nodefony/security/api/apikeys` — toutes les clés API (gouvernance),
  *    `GET …/apikeys/status` — backend du token store (« où on écrit »),
  *    `POST …/apikeys/{id}/revoke` — révocation par id (réponse à incident).

package/dist/types/nodefony/src/authenticator/ExternalSubjectResolver.d.ts

@@ -6,6 +6,17 @@ import type { ISecurityConfig } from "../../config/defineModuleConfig.js";
 import { type IProviderRoleMapping } from "../oauth/providerRoles.js";
 /** Comment le sujet d'un jeton devient un utilisateur de cette application. */
 export type ExternalSubjectPolicy = "require" | "ephemeral";
+/**
+ * Cet utilisateur a-t-il été fabriqué pour un appelant machine SANS compte local (mode `ephemeral`) ?
+ *
+ * L'identité d'admission temps réel en tire `account: false` : rien ne
+ * pourrait relire cet appelant par son `id` (`<émetteur>#<sujet>`), et un
+ * abonnement durable ne doit pas s'y adosser (ADR-0021 §S10 point 6). Lu sur
+ * le FAIT (l'objet vient du résolveur), jamais déduit de la forme de `id`.
+ *
+ * @param user - utilisateur résolu par le pare-feu.
+ */
+export declare function isEphemeralSubject(user: IUser): boolean;
 /** Un émetteur reconnu, et la façon dont ses sujets entrent chez nous. */
 export interface IExternalIssuerBinding {
     /** Émetteur de confiance, sous sa forme canonique. */

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/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

@@ -39,7 +39,7 @@ export interface ISystemChannelRule {
  * hot-path WS. Le firewall fournit l'implémentation (closure sur son container) ;
  * absent par défaut (verrou pur, testable sans audit).
  *
- * @param surface - cible refusée : pont API souverain (`api.request`) ou canal
+ * @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`).
@@ -159,7 +159,7 @@ export declare function buildSystemRules(prefixes: readonly string[]): readonly
  * (api.request) ou la politique du canal (subscribe/inbound).
  *
  * Trois surfaces gardées :
- *  - `api.request {path}` (pont API souverain) : re-match de zone HTTP → zone
+ *  - `api.request {path}` (pont socket) : re-match de zone HTTP → zone
  *    protégée + anonyme = refus (autorisation de ZONE, identique à `GET {path}` ;
  *    la méthode/action est gardée en aval par le router + `@IsGranted`).
  *  - `subscribe {channel}` : politique de canal (système plancher + déclaration

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

@@ -1,3 +1,4 @@
+import type { 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é à
@@ -76,25 +92,17 @@ export interface IRealtimeAuthenticatorMatcher {
  */
 export type FrameAuthorizer = (frame: unknown, token: IRealtimeToken) => boolean;
 /**
- * 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 };
 /**
  * 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

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). */

package/dist/types/nodefony/testing/index.d.ts

@@ -0,0 +1,57 @@
+import { type IChannelPolicyResolver } from "../src/realtime/frameAuthorizer.js";
+import type { FrameAuthorizer, IRealtimeToken } from "../src/realtime/realtimeContracts.js";
+/** L'identité d'essai : qui se connecte, avec quels droits. */
+export interface ITestIdentityOptions {
+    /** Identifiant de l'utilisateur (défaut `"alice"`). */
+    readonly identifier?: string;
+    /**
+     * Identifiant IMMUABLE du compte (défaut : `identifier`) — l'`id` que lit la
+     * règle `allow` d'un canal, distinct du login comme au runtime. Le poser quand
+     * l'appartenance se relit par la clé primaire de l'entité.
+     */
+    readonly id?: string;
+    /** Rôles portés (défaut `["ROLE_USER"]`) — ceux qu'aurait résolus le pare-feu. */
+    readonly roles?: readonly string[];
+    /** Scopes portés (défaut aucun) — l'axe des jetons d'API, pas de la session. */
+    readonly scopes?: readonly string[];
+    /**
+     * L'utilisateur rendu par `@CurrentUser()` et `RequestContext.getUser()`
+     * (défaut `{ identifier, roles }`). Passer l'entité de l'application quand
+     * l'action en lit d'autres champs.
+     */
+    readonly user?: unknown;
+}
+/**
+ * Une identité de connexion AUTHENTIFIÉE, telle que le pare-feu l'aurait posée
+ * au handshake.
+ *
+ * Pour éprouver un visiteur anonyme, ne rien passer au harnais : il pose alors
+ * le jeton anonyme, comme le repli Zero Trust du runtime.
+ *
+ * @param options - identifiant, rôles, scopes, utilisateur.
+ * @returns un jeton à passer en `identity` au harnais temps réel.
+ */
+export declare function createTestIdentity(options?: ITestIdentityOptions): IRealtimeToken;
+/** Écarts au pare-feu d'essai. */
+export interface ITestFrameAuthorizerOptions {
+    /**
+     * Hiérarchie de rôles, à la forme de `roleHierarchy` de la configuration de
+     * sécurité (défaut : aucune). La reprendre de l'application quand un rôle en
+     * couvre un autre — `{ ROLE_ADMIN: ["ROLE_USER"] }`.
+     */
+    readonly roleHierarchy?: Record<string, readonly string[]>;
+}
+/**
+ * Le VRAI verrou de frame du pare-feu, pour le harnais temps réel.
+ *
+ * C'est lui qui applique `@RealtimeChannel(nom, { roles })`,
+ * `@RealtimeAction(nom, { roles })` et les canaux système : sans lui, une
+ * politique déclarée n'est appliquée par personne — en test comme au runtime.
+ *
+ * @param channels - ce qui connaît les politiques déclarées : le hub temps réel
+ *   (`getRealtimeHub()`), lu à CHAQUE frame — les politiques que le controller
+ *   enregistre à sa construction y sont donc vues.
+ * @param options - hiérarchie de rôles de l'application.
+ * @returns le verrou à passer en `frameAuthorizer` au harnais.
+ */
+export declare function createTestFrameAuthorizer(channels: IChannelPolicyResolver, options?: ITestFrameAuthorizerOptions): FrameAuthorizer;

package/docs/api-keys.md

@@ -279,7 +279,9 @@ jamais par le préfixe.
 
 ### Émission — `ApiKeyService.createForSubject()`
 
-`ApiKeyService.createForSubject()` (`apiKeys.ts#ApiKeyService.createForSubject`) est le seul chemin d'émission. Dans l'ordre :
+`ApiKeyService.createForSubject()` (`apiKeys.ts#ApiKeyService.createForSubject`) est le seul chemin d'émission. Un `tenantId` rempli est refusé d'entrée (`ApiKeyError` 400) : le
+multi-tenant n'existe pas, aucun lecteur ne cloisonne sur ce champ, et une clé « rattachée à un
+locataire » verrait tout. Il sera accepté le jour où il sera appliqué. Ensuite, dans l'ordre :
 
 1. **Validation du nom** — non vide, ≤ 100 caractères ; sinon `ApiKeyError` 400 (`#normalizeName()`,
    `apiKeys.ts#ApiKeyService.#normalizeName`).

package/docs/authenticators.md

@@ -270,8 +270,9 @@ Credential = l'**identifiant** posé dans le blob de session, jamais un secret.
   partagés avec `AuthFlow.me()` : `isLocked()`/`isActive()` → rejet (`sessionIdentity.ts#resolveSessionIdentity`).
 - `onSuccess()` pose l'identifiant sur le contexte — la persistance de session lie le blob au
   principal courant (`SessionAuthenticator.ts#SessionAuthenticator.onSuccess`).
-- **Pas de `challenge()`** : session absente = 401 nu → le front redirige vers son écran de login,
-  jamais une popup Basic (`SessionAuthenticator.ts#SessionAuthenticator`).
+- **Pas de `challenge()`** : session absente = 401 portant le défi de repli du pare-feu,
+  `Session realm="nodefony"` (RFC 9110 §15.5.2) — schéma inconnu des navigateurs, jamais une popup ;
+  le front redirige vers son écran de login (`SessionAuthenticator.ts#SessionAuthenticator`).
 
 ### `jwt` — Bearer signé pour les API (RFC 6750 + BCP RFC 8725)
 
@@ -348,8 +349,9 @@ l'ALS. `FirewallRealtimeAuthenticator.supports()` ne fait que le constater
   ouverte (logout, changement de compte, `jti` denylisté). En mode session,
   `buildSessionRevalidator()` re-lit `storage.read(id)` et compare l'identifiant ; toute erreur de
   lecture invalide, fail-closed (`FirewallRealtimeAuthenticator.ts#SessionLike.storage`). En mode jeton porteur, la
-  preuve est autre : `exp`, `jti` denylisté, `invalidBefore`
-  (`FirewallRealtimeAuthenticator.ts#FirewallRealtimeAuthenticator.#buildBearerRevalidator`).
+  preuve est autre : `jti` denylisté, `invalidBefore`, puis `exp` — dans cet ordre, car révoqué
+  l'emporte sur expiré — et la cause est rendue : un jeton expiré ferme la socket en `4006`, un jeton
+  révoqué en `4001` (`FirewallRealtimeAuthenticator.ts#FirewallRealtimeAuthenticator.#buildBearerStatus`).
 
 > [!NOTE]
 > **Asymétrie de révocation HTTP↔WS (assumée)** : le jeton realtime est figé au handshake (les