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

package/dist/types/nodefony/contracts/IWebhookPayload.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Corps JSON d'une livraison webhook, tel que le destinataire le reçoit — le type à poser sur le `JSON.parse` du récepteur.
+ *
+ * Signé avec ses en-têtes (`webhook-id`, `webhook-timestamp`, `webhook-signature`,
+ * convention Standard Webhooks) : vérifier la signature AVANT de lire le corps.
+ *
+ * @typeParam T - la forme de `data` ; `unknown` tant que le récepteur ne l'a pas vérifiée.
+ */
+export interface IWebhookPayload<T = unknown> {
+    /**
+     * Identifiant du MESSAGE, égal à l'en-tête `webhook-id` et stable d'un réessai à l'autre : la clé de déduplication du récepteur.
+     */
+    readonly id: string;
+    /**
+     * Heure de la TENTATIVE de livraison (ISO 8601), pas celle de l'événement : un réessai porte une heure plus tardive.
+     *
+     * L'heure de l'événement vit dans `data` (`ts` pour un événement d'audit).
+     */
+    readonly timestamp: string;
+    /** Nom de l'événement — l'action d'audit, ex. `"login.success"` ; c'est lui que filtrent les motifs d'abonnement. */
+    readonly type: string;
+    /** L'événement lui-même ; pour l'audit, un `IAuditEvent`. */
+    readonly data: T;
+}

package/dist/types/nodefony/errors/FetchPublicError.d.ts

@@ -0,0 +1,15 @@
+import { nodefonyError } from "nodefony";
+/** Cause d'un échec de {@link FetchPublicError}. */
+export type FetchPublicFailure = "timeout" | "too-many-redirects" | "network";
+/**
+ * Échec d'une requête sortante vers un site tiers (`fetchPublic`) qui n'est PAS
+ * un refus de cible : délai total dépassé (`504`), trop de redirections ou
+ * échec réseau (`502`). Une cible interdite lève `SsrfError` (422), pas
+ * celle-ci — l'appelant distingue ainsi « tu n'as pas le droit d'y aller » de
+ * « le site n'a pas répondu ».
+ */
+export declare class FetchPublicError extends nodefonyError {
+    /** Cause de l'échec, stable et exploitable sans lire le message. */
+    readonly reason: FetchPublicFailure;
+    constructor(reason: FetchPublicFailure, message: string);
+}

package/dist/types/nodefony/errors/SsrfError.d.ts

@@ -8,6 +8,13 @@ import { nodefonyError } from "nodefony";
  * d'un webhook invalide).
  */
 export declare class SsrfError extends nodefonyError {
-    constructor(message?: string | Error);
+    /**
+     * `forbidden` : la cible est interdite (protocole, identifiants, IP non
+     * publique). `unresolvable` : l'hôte n'a aucune adresse — rien d'interne n'est
+     * visé, le site est simplement injoignable ; un appelant qui rend ces deux cas
+     * à l'utilisateur les distingue par ce champ, jamais par le texte du message.
+     */
+    readonly reason: "forbidden" | "unresolvable";
+    constructor(message?: string | Error, reason?: "forbidden" | "unresolvable");
 }
 export default SsrfError;

package/dist/types/nodefony/errors/StaleSessionError.d.ts

@@ -0,0 +1,17 @@
+import { AuthenticationError } from "./AuthenticationError.js";
+/**
+ * Session PÉRIMÉE — elle ne désigne plus personne de valide : compte supprimé,
+ * verrouillé, désactivé, recréé sous le même identifiant, mot de passe changé
+ * depuis son ouverture, ou blob vidé. C'est un ÉTAT à purger, pas une preuve
+ * fausse présentée par un tiers : le `SessionAuthenticator` la détruit côté
+ * serveur ET côté navigateur (cookie expiré, RFC 6265 §5.3), puis le firewall
+ * poursuit comme si aucune session n'avait été présentée — une page ouverte
+ * aux anonymes s'affiche, une zone fermée redemande la connexion.
+ *
+ * Jamais levée pour une PANNE de la source d'identité : une base injoignable
+ * ne dit rien de la session, qui doit survivre à l'incident.
+ */
+export declare class StaleSessionError extends AuthenticationError {
+    constructor(message?: string | Error);
+}
+export default StaleSessionError;

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

@@ -1,9 +1,12 @@
 export { AuthenticationError } from "./AuthenticationError.js";
+export { StaleSessionError } from "./StaleSessionError.js";
 export { AccessDeniedError } from "./AccessDeniedError.js";
 export { ThrottledError } from "./ThrottledError.js";
 export { UnverifiableTokenError } from "./UnverifiableTokenError.js";
 export { InvalidTargetError } from "./InvalidTargetError.js";
 export { CsrfError } from "./CsrfError.js";
 export { SsrfError } from "./SsrfError.js";
+export { FetchPublicError } from "./FetchPublicError.js";
+export type { FetchPublicFailure } from "./FetchPublicError.js";
 export { WebAuthnError } from "./WebAuthnError.js";
 export { InsecureTransportError } from "./InsecureTransportError.js";

package/dist/types/nodefony/keycloak/scaffold.d.ts

@@ -7,13 +7,13 @@ export declare const APP_KEYCLOAK_REALM_FILE = "docker/keycloak/import/realm.jso
 export declare const APP_KEYCLOAK_THEMES_DIR = "docker/keycloak/themes";
 export declare const APP_KEYCLOAK_THEME_DIR = "docker/keycloak/themes/nodefony";
 /**
- * Ressource de l'API partenaire d'une application neuve en développement :
- * ce que rend `partnerResource()` du gabarit `complete` sans `NF_JWT_ISSUER`
- * ni `NF_PORT_HTTPS` — le port HTTPS par défaut, comme les URL de retour du
- * realm. Deux paquets, une valeur : le test de contribution compare le
- * gabarit rendu à cette constante.
+ * Ressource de l'API partenaire de la démo en développement : le chemin de sa
+ * zone (`/demo/api/partner`) rendu absolu contre l'émetteur de développement
+ * — le port HTTPS par défaut, comme les URL de retour du realm. Deux paquets,
+ * une valeur : le test de contribution la confronte à une application
+ * `--demo` réellement rendue.
  */
-export declare const APP_PARTNER_DEV_RESOURCE = "https://localhost:5152/api/partner";
+export declare const APP_PARTNER_DEV_RESOURCE = "https://localhost:5152/demo/api/partner";
 /** Les types de thème que le realm sait déclarer, et la clé qui les porte. */
 declare const THEME_TYPES: readonly ["login", "account", "email", "admin"];
 type TThemeType = (typeof THEME_TYPES)[number];
@@ -68,6 +68,12 @@ export declare function devMachineSecret(appName: string): string;
  * rôle client `admin` (`roleMapping: { admin: "ROLE_ADMIN" }`), et les
  * audiences des zones `external-jwt` que la configuration rendue déclare.
  *
+ * Le client « machine » (`<app>-machine`, `client_credentials`) n'existe que
+ * s'il a une audience à recevoir : une application neuve n'ouvre aucune zone à
+ * jeton tiers (#746), et un client que rien n'accepte serait un secret de plus
+ * à garder pour rien. La démo, qui apporte l'API entre programmes, le fait
+ * naître en déclarant sa ressource.
+ *
  * @param appName - nom de l'application (= realm = identifiant de client)
  * @param themes - types de thème à déclarer
  * @param ids - `sub` des comptes de démonstration, FIXÉS dans le fichier :

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

@@ -49,6 +49,9 @@ declare class ApiKeyService extends Service {
      * @param roles - rôles du porteur tels que son compte les porte ; omis =
      *   aucun rôle, donc tout scope réservé est refusé (fail-closed).
      * @throws ApiKeyError 400 — nom vide/trop long, scope hors catalogue, expiry invalide.
+     * @throws ApiKeyError 400 — `tenantId` rempli : le périmètre d'un locataire n'est
+     *   pas encore appliqué (aucun lecteur ne cloisonne sur lui) — l'accepter rendrait
+     *   la clé trompeuse, et l'appliquer un jour lui retirerait des accès (rupture).
      * @throws ApiKeyError 403 — scope réservé à des rôles que le porteur n'a pas.
      * @throws ApiKeyError 409 — plafond `maxPerSubject` atteint.
      * @throws ApiKeyError 403 — aucun compte sous cet identifiant (la clé est liée

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

@@ -132,8 +132,8 @@ declare class AuthFlow extends Service {
      * (mêmes contrôles que le `SessionAuthenticator` — source unique).
      *
      * @returns la projection publique, ou `null` (pas de session, session
-     *   orpheline, compte verrouillé/désactivé) — le handler répond `200`
-     *   `{ user: null }`.
+     *   orpheline, compte verrouillé/désactivé — la session périmée est alors
+     *   détruite, cookie compris) — le handler répond `200` `{ user: null }`.
      */
     me(context: ContextType): Promise<ISafeUser | null>;
     /**

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

@@ -8,6 +8,12 @@ import type { IFirewall } from "../contracts/IFirewall.js";
 import type { IAuthenticator } from "../contracts/IAuthenticator.js";
 import type { ISecuredArea } from "../contracts/ISecuredArea.js";
 import type { IFirewallDescription, IRoleHierarchyDescription } from "../contracts/IFirewallDescription.js";
+/**
+ * `Cache-Control` par défaut d'une réponse dont la CSP porte un nonce : jamais
+ * gardée par un cache partagé (le nonce y serait servi à plusieurs visiteurs),
+ * toujours redemandée avant réutilisation (ADR-0024 §C2).
+ */
+export declare const NONCED_DOCUMENT_CACHE_CONTROL = "private, no-cache";
 /**
  * Orchestrateur de sécurité Nodefony — refonte 2026 (P6).
  *
@@ -27,7 +33,7 @@ import type { IFirewallDescription, IRoleHierarchyDescription } from "../contrac
  *
  * Conformité : tout 401 porte un challenge `WWW-Authenticate` (RFC 9110
  * §15.5.2) — celui du premier authenticator de la zone qui en déclare un, sinon
- * le défi de repli {@link FALLBACK_CHALLENGE}.
+ * le défi de repli {@link SESSION_AUTH_CHALLENGE}.
  *
  * CORS, CSRF et autorisation par décorateurs viennent se brancher en S4/S5.
  * Toutes les structures sont **lazy** (perf : une app sans zone = zéro alloc).
@@ -141,20 +147,35 @@ declare class Firewall extends Service implements IFirewall {
     /**
      * En-têtes de sécurité APPLICATIFS (P6 J5) — CSP, Referrer-Policy, isolation
      * cross-origin (COOP/COEP/CORP), Origin-Agent-Cluster, Permissions-Policy.
-     * Posés sur toute réponse du pipeline (branché dans `handleHttp`). Complète le
-     * socle transport de `@nodefony/http` (nosniff/frame/HSTS, posé à l'entrée brute)
-     * SANS le ré-émettre. No-op si désactivé ou réponse non-HTTP (WS).
+     * Appelé par la réponse juste avant son `writeHead`, une fois son type fixé :
+     * la politique suit ce type (ADR-0024 §C11). Complète le socle transport de
+     * `@nodefony/http` (nosniff/frame/HSTS) SANS le ré-émettre. No-op si désactivé
+     * ou réponse non-HTTP (WS).
      *
      * En-têtes constants = table figée pré-calculée au boot (0 alloc/concat). Le CSP
-     * nonce/req (étape B) ajoute 1 `join` + 1 `setHeader` UNIQUEMENT si activé.
+     * nonce/req ajoute 1 `join` + 1 `setHeader`, sur un document seulement.
+     *
+     * @param context - contexte de la réponse.
+     * @param contentType - `Content-Type` de la réponse ; `null` = sans contenu ;
+     *   omis = type inconnu, servi comme un document (politique complète).
+     * @param servedAsFile - le corps est servi tel quel (fichier statique,
+     *   relais) : aucun gabarit ne l'a écrit, il ne peut pas porter de nonce. Un
+     *   document reçoit alors la politique sans nonce ni `'strict-dynamic'`
+     *   (ADR-0024 §C1) ; les autres types n'en changent pas.
      */
-    applySecurityHeaders(context: ContextType): void;
+    applySecurityHeaders(context: ContextType, contentType?: string | null, servedAsFile?: boolean): void;
     /**
      * Déclare des directives CSP additionnelles pour `moduleName` (cf `IFirewall`).
      * No-op si les en-têtes applicatifs sont désactivés (pas de CSP à étendre).
      * Recompose `#securityHeaders` (merge + re-split nonce) — hors hot-path.
      */
-    registerCspOrigins(moduleName: string, fragment: CspFragment): void;
+    registerCspOrigins(moduleName: string, declared: CspFragment): void;
+    /**
+     * Le noyau HTTP a recalculé ses en-têtes de transport (édition à chaud de sa
+     * config) : la politique suit `frameOptions`, qui pilote aussi
+     * `frame-ancestors` (ADR-0024 §C5). Hors chemin chaud.
+     */
+    onTransportHeadersChanged(): void;
     /** Retire les directives CSP de `moduleName` et recompose si nécessaire. */
     unregisterCspOrigins(moduleName: string): void;
     log(pci: unknown, severity?: Severity, msgid?: Msgid, msg?: Message): Pdu;

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

@@ -1,10 +1,26 @@
 import { type CspFragment } from "../src/csp.js";
+/**
+ * Famille d'une réponse au regard de la politique de contenu (ADR-0024 §C11) :
+ * `document` (HTML, XHTML, SVG — politique complète avec nonce et
+ * `Permissions-Policy`), `script` (JavaScript — politique complète SANS nonce,
+ * celle que prend un worker), `other` (tout le reste — politique courte figée).
+ */
+export type ResponseKind = "document" | "script" | "other";
+/**
+ * Range une réponse dans sa famille d'après son `Content-Type`.
+ *
+ * @param contentType - valeur de `Content-Type` (paramètres admis) ; `null` =
+ *   réponse sans contenu ; `undefined` = type INCONNU de l'appelant, traité en
+ *   document — la politique la plus complète, jamais une plus faible par défaut.
+ * @returns la famille dont la réponse reçoit la politique.
+ */
+export declare function responseKindOf(contentType: string | null | undefined): ResponseKind;
 /**
  * Sous-ensemble APPLICATIF de la config `headers` (cf defineSecurityConfig).
  *
  * `hsts` / `frameguard` / `noSniff` n'y figurent PAS volontairement : ces trois
- * en-têtes « transport » sont posés par `@nodefony/http` à l'entrée brute
- * (`onHttpRequest`, AVANT le pipeline) pour couvrir AUSSI les fichiers statiques,
+ * en-têtes « transport » sont posés par `@nodefony/http` sur toute réponse
+ * (`HttpKernel.transportHeaders`, figés au démarrage) pour couvrir AUSSI les fichiers statiques,
  * les erreurs précoces et un serveur sans module security (secure-by-default).
  * `@nodefony/security` ne les ré-émet pas → une seule source par en-tête.
  */
@@ -18,6 +34,12 @@ export interface ISecurityHeadersOptions {
     corp?: string | undefined;
     originAgentCluster?: boolean | undefined;
     permissionsPolicy?: string | undefined;
+    /**
+     * Valeur de `Reporting-Endpoints` (`groupe="url"`), quand la politique
+     * désigne un groupe `report-to` composé par le framework (ADR-0024 §C7).
+     * Posé là où la politique complète part : document, script, fichier servi.
+     */
+    reportingEndpoints?: string | null | undefined;
 }
 /**
  * En-têtes de sécurité **applicatifs** de Nodefony (couche `@nodefony/security`,
@@ -26,19 +48,65 @@ export interface ISecurityHeadersOptions {
  * cross-origin COOP/COEP/CORP, Origin-Agent-Cluster, Permissions-Policy) → zéro
  * alloc, zéro concat par requête (le firewall la pose telle quelle).
  *
- * **Étape A+B** : en-têtes constants pré-calculés au boot (Referrer/COOP/…). Pour le
- * CSP, deux régimes mutuellement exclusifs : **statique** (posé tel quel via `headers`,
- * 0 alloc/req) OU **nonce par requête** (`cspNonces` + placeholder `{{nonce}}` dans le
- * CSP) → segments pré-split au boot, recomposés par requête via `cspFor(nonce)` (1
- * `join`, aucun parse/regex dans le hot-path). Le nonce lui-même vit sur `Context`.
+ * Pour le CSP, deux régimes mutuellement exclusifs : **statique** (posé tel quel via
+ * `headers`, 0 alloc/req) OU **nonce par requête** (`cspNonces` + placeholder
+ * `{{nonce}}`) → segments pré-split au boot, recomposés par requête via
+ * `cspFor(nonce)` (1 concaténation, aucun parse/regex dans le hot-path).
+ *
+ * **Deux variantes, composées au boot** (ADR-0024 §C6) : la politique telle
+ * qu'écrite, servie en TLS, et la même SANS `upgrade-insecure-requests`, servie
+ * en clair — sur une page `http`, la directive réécrirait les sous-ressources en
+ * `https`, que le serveur ne sert pas. Sans la directive, les deux variantes sont
+ * le MÊME objet : par requête, un booléen choisit, rien de plus.
  *
  * @see Fetch Metadata · W3C CSP Level 3 · WHATWG (COOP/COEP/CORP).
  */
 export declare class SecurityHeaders {
     #private;
-    constructor(o: ISecurityHeadersOptions);
-    /** Table d'en-têtes applicatifs CONSTANTS (figée), posée telle quelle par le firewall. */
+    /**
+     * @param o - options des en-têtes (config `security.headers`, CSP déjà fusionnée).
+     * @param onRejectedExtra - appelé quand les directives `@Csp` d'une route sortent
+     *   de la grammaire CSP3 : la route sert alors la politique de base.
+     */
+    constructor(o: ISecurityHeadersOptions, onRejectedExtra?: (error: unknown) => void);
+    /**
+     * Table d'en-têtes figée d'un DOCUMENT servi tel quel — fichier statique,
+     * réponse relayée — dont le corps ne passe par aucun gabarit et ne peut donc
+     * pas porter de nonce (ADR-0024 §C1) : politique complète sans nonce ni
+     * `'strict-dynamic'` orphelin, et tous les en-têtes d'un document.
+     *
+     * @param tls - la page est servie en `https` (garde `upgrade-insecure-requests`).
+     * @returns la table à poser telle quelle.
+     */
+    headersForServedFile(tls: boolean): Readonly<Record<string, string>>;
+    /**
+     * Table d'en-têtes figée d'une réponse qui n'est pas un document (ADR-0024
+     * §C11) : JavaScript (politique complète sans nonce, Referrer-Policy, COEP,
+     * CORP) ou reste (politique courte `default-src 'none'`, Referrer-Policy,
+     * CORP). Ni l'une ni l'autre ne porte de nonce ; COOP, Origin-Agent-Cluster
+     * et Permissions-Policy, lus sur un document seulement, n'y figurent pas.
+     *
+     * @param kind - famille de la réponse (cf {@link responseKindOf}).
+     * @param tls - la page est servie en `https` (garde `upgrade-insecure-requests`).
+     * @returns la table à poser telle quelle.
+     */
+    headersForResource(kind: Exclude<ResponseKind, "document">, tls: boolean): Readonly<Record<string, string>>;
+    /** Table d'en-têtes applicatifs CONSTANTS (figée) d'une réponse en clair. */
     get headers(): Readonly<Record<string, string>>;
+    /**
+     * Table constante SANS la CSP statique d'une réponse en clair — pour une
+     * réponse qui pose sa propre politique (route `@Csp`), afin que la CSP ne
+     * soit écrite qu'une fois.
+     */
+    get headersWithoutCsp(): Readonly<Record<string, string>>;
+    /**
+     * Table d'en-têtes constants selon le transport de la réponse.
+     *
+     * @param tls - la page est servie en `https` (proxy de confiance compris).
+     * @param withoutCsp - omettre la CSP statique (route `@Csp` qui pose la sienne).
+     * @returns la table figée à poser telle quelle.
+     */
+    headersFor(tls: boolean, withoutCsp?: boolean): Readonly<Record<string, string>>;
     /** `true` si le CSP est recomposé par requête avec un nonce (→ `cspFor`). */
     get hasNonce(): boolean;
     /**
@@ -48,9 +116,11 @@ export declare class SecurityHeaders {
      * `'`/`;`/espace) → aucune évasion possible du token CSP.
      *
      * @param nonce - nonce base64 de la requête (`Context.cspNonce`).
+     * @param tls - la page est servie en `https` : la politique garde
+     *   `upgrade-insecure-requests`. Défaut : en clair.
      * @returns la valeur `Content-Security-Policy` à poser sur la réponse.
      */
-    cspFor(nonce: string): string;
+    cspFor(nonce: string, tls?: boolean): string;
     /**
      * Recompose le CSP en fusionnant ADDITIVEMENT les directives `extra` d'une
      * route (`@Csp`) dans le CSP de base, PUIS en substituant le `nonce`. Le merge
@@ -60,8 +130,9 @@ export declare class SecurityHeaders {
      *
      * @param nonce - nonce base64 de la requête (ignoré si le CSP n'a pas de nonce).
      * @param extra - directives additionnelles de la route (`directive → sources`).
+     * @param tls - la page est servie en `https`. Défaut : en clair.
      * @returns la valeur `Content-Security-Policy` à poser sur la réponse.
      */
-    cspForExtra(nonce: string, extra: CspFragment): string;
+    cspForExtra(nonce: string, extra: CspFragment, tls?: boolean): string;
 }
 export default SecurityHeaders;

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

@@ -143,3 +143,16 @@ declare class WebAuthnService extends Service {
 }
 export default WebAuthnService;
 export { WebAuthnService };
+/**
+ * Origines WebAuthn rendues en ASCII (punycode), forme sous laquelle le
+ * navigateur les présente — `https://café.example` → `https://xn--caf-dma.example`.
+ *
+ * Une entrée qui n'est pas une origine (`scheme://hôte[:port]`) est écartée et
+ * signalée : la garder ferait échouer CHAQUE cérémonie, sans que personne ne
+ * sache pourquoi.
+ *
+ * @param origins - origines telles qu'écrites dans la config.
+ * @param onInvalid - appelé pour chaque entrée écartée.
+ * @returns les origines valides, sérialisées en ASCII, dans l'ordre reçu.
+ */
+export declare function asciiOrigins(origins: readonly string[], onInvalid: (origin: string) => void): string[];

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/audit/AuditRefusalAggregator.d.ts

@@ -0,0 +1,55 @@
+import type { IAuditEventDraft } from "../../contracts/IAuditEvent.js";
+/** Réglages de l'agrégation des refus (section `security.audit.aggregate`). */
+export interface IAuditAggregateOptions {
+    /** Durée d'une fenêtre, en ms, ouverte au premier refus d'une clé. */
+    windowMs: number;
+    /** Refus d'une clé écrits tels quels par fenêtre ; les suivants sont comptés. */
+    burst: number;
+    /** Clés suivies au plus ; au-delà, les refus se regroupent sans l'IP. */
+    maxKeys: number;
+}
+/**
+ * Agrège les REFUS du journal d'audit par source, pour qu'un flot ne se paie pas
+ * d'une ligne par requête (OWASP Logging Cheat Sheet : la journalisation ne doit
+ * pas épuiser les ressources ni le journal de la base).
+ *
+ * Clé : catégorie, action, motif, ressource et IP — l'IP résolue par le contexte
+ * (`trustProxy`), donc non forgeable par le client. L'acteur n'entre PAS dans la
+ * clé : un bourrage d'identifiants change d'acteur à chaque essai, c'est sa
+ * source qui le trahit.
+ *
+ * Par clé et par fenêtre (ouverte au premier refus) : les `burst` premiers refus
+ * sont écrits tels quels — l'enquêteur voit les premiers essais, acteur compris ;
+ * les suivants sont seulement comptés, et la fenêtre close émet UNE ligne de
+ * synthèse (`metadata.aggregated`). Mémoire bornée : au-delà de `maxKeys` clés,
+ * les refus se regroupent sous l'IP `*`.
+ *
+ * Pur : l'horloge est passée à chaque appel, la synthèse part par `emit`. Les
+ * succès n'y passent jamais (l'appelant les écarte).
+ */
+export declare class AuditRefusalAggregator {
+    #private;
+    /**
+     * @param options - fenêtre, rafale écrite telle quelle, borne de clés.
+     * @param emit - écrit une ligne de synthèse dans le journal.
+     */
+    constructor(options: IAuditAggregateOptions, emit: (draft: IAuditEventDraft) => void);
+    /** Nombre de clés suivies (fenêtres ouvertes). */
+    get size(): number;
+    /**
+     * Compte un refus.
+     *
+     * @param draft - l'événement de refus.
+     * @param now - horloge, en ms.
+     * @returns `true` : l'écrire tel quel ; `false` : il est compté dans la synthèse.
+     */
+    admit(draft: IAuditEventDraft, now: number): boolean;
+    /**
+     * Ferme les fenêtres échues : émet leur synthèse et libère leurs clés.
+     *
+     * @param now - horloge, en ms.
+     */
+    sweep(now: number): void;
+    /** Émet la synthèse de toutes les fenêtres ouvertes (arrêt) et vide la table. */
+    flush(): void;
+}

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/authenticator/JwtAuthenticator.d.ts

@@ -3,7 +3,7 @@ import type { ContextType } from "@nodefony/http";
 import type { IUser } from "@nodefony/user";
 import type { IAuthenticator } from "../../contracts/IAuthenticator.js";
 import type { IToken } from "../../contracts/IToken.js";
-import type { IJwtRuntime } from "../token/jwtRuntime.js";
+import { type IJwtRuntime } from "../token/jwtRuntime.js";
 /**
  * Authentification par **JWT Bearer** (RFC 6750) — réservée API service↔service /
  * agents (le web utilise la session BFF). Vérifie un access token EdDSA signé par
@@ -15,7 +15,8 @@ import type { IJwtRuntime } from "../token/jwtRuntime.js";
  *  - **clé par `kid` depuis le keyset LOCAL** (`createLocalJWKSet`) — jamais
  *    `jku`/`jwk` de l'en-tête (injection de clé / SSRF, §3.5).
  *  - **`aud` (§3.9) + `iss` (§3.8) obligatoires** + `typ:"at+jwt"` (§3.11, sépare
- *    access et refresh) + `exp`/`nbf` (jose).
+ *    access et refresh) + `exp`/`nbf` (jose). L'audience est celle de la ZONE
+ *    (`resource`, ou l'audience par défaut), jamais toute la liste `jwt.audiences`.
  *  - **révocation** : denylist `jti` + seuil `invalidBefore` par porteur (le JWT
  *    est auto-porté et non révocable sans état serveur).
  *  - **sujet revérifié** (§3.10) : `loadUserByIdentifier(sub)` → compte disparu,
@@ -48,12 +49,25 @@ export declare class JwtAuthenticator implements IAuthenticator {
      * qu'un credential qui disparaîtrait sans laisser de trace.
      */
     supports(context: ContextType): boolean;
-    /** Extrait le token brut (non vérifié) → porté par un `UserToken` type `"jwt"`. */
+    /**
+     * Extrait le token brut (non vérifié) → porté par un `UserToken` type `"jwt"`,
+     * avec la ressource de la zone quand elle en déclare une.
+     *
+     * L'audience transite par le token parce que `authenticate()` ne reçoit pas
+     * le contexte (même patron que `ExternalJwtAuthenticator`). Rien n'est posé
+     * pour une zone sans ressource : l'audience par défaut s'y applique.
+     */
     createToken(context: ContextType): Promise<IToken>;
     /**
      * Vérifie la signature + les claims du JWT, applique la révocation et résout le
      * sujet — ou lève un 401 au message uniforme.
      *
+     * L'audience exigée est celle de la ZONE, jamais la liste blanche d'émission
+     * entière (RFC 8707, RFC 9068 §4) : la `resource` de la zone si elle en
+     * déclare une, sinon l'audience par défaut — l'application elle-même. Un
+     * jeton émis pour la porte MCP, ou pour la ressource d'une autre zone, figure
+     * dans `jwt.audiences` sans pour autant ouvrir celle-ci.
+     *
      * @throws AuthenticationError (401) — token absent/invalide/expiré/révoqué, ou
      *   sujet disparu/banni.
      * @throws Error (câblage : keystore/store/users absents) — logguée ERROR par le

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

@@ -57,8 +57,10 @@ export declare class SessionAuthenticator implements IAuthenticator {
      * token. Les contrôles d'état (existe, actif, non verrouillé) vivent dans
      * {@link resolveSessionIdentity} — partagés avec `AuthFlow.me()`.
      *
-     * @throws AuthenticationError (401, message uniforme) — session orpheline,
-     *   compte verrouillé ou désactivé.
+     * @throws StaleSessionError (401, message uniforme) — session orpheline,
+     *   compte verrouillé ou désactivé, liaison au compte rompue : un état à
+     *   purger ({@link onFailure}). Une PANNE de la source d'identité remonte
+     *   telle quelle, et ne purge rien.
      */
     authenticate(token: IToken): Promise<IToken>;
     /**
@@ -66,7 +68,12 @@ export declare class SessionAuthenticator implements IAuthenticator {
      * (`saveSession`) lie le blob au principal courant (string attendu).
      */
     onSuccess(context: ContextType, token: IToken): Promise<void>;
-    /** Slot audit (P6.14). Le 401 est posé par le firewall. */
-    onFailure(_context: ContextType, _error: Error): Promise<void>;
+    /**
+     * Une session périmée est DÉTRUITE, côté serveur (entrée du stockage) et
+     * côté navigateur (cookie expiré, RFC 6265 §5.3) — sans quoi le navigateur la
+     * renvoie à chaque requête et chaque page lui répond 401, sans issue pour
+     * l'utilisateur. Le firewall poursuit ensuite la chaîne de la zone.
+     */
+    onFailure(context: ContextType, error: Error): Promise<void>;
 }
 export default SessionAuthenticator;