@nodefony/security 10.0.0-alpha.1

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

@@ -0,0 +1,17 @@
+import { nodefonyError } from "nodefony";
+/**
+ * Erreur de **gestion** d'un credential WebAuthn (enrôlement) — porte un `code`
+ * HTTP que l'adaptateur framework mappe par duck-typing (il n'importe jamais les
+ * classes de `@nodefony/security`).
+ *
+ *  - `409` — plafond `passkeys.maxPerUser` atteint.
+ *
+ * Distincte de la **cérémonie** elle-même (défi/signature/origine invalides →
+ * `AuthenticationError` 401, message uniforme anti-énumération) : ici la
+ * cérémonie a réussi cryptographiquement, c'est la politique du serveur qui
+ * refuse d'enregistrer un credential de plus.
+ */
+export declare class WebAuthnError extends nodefonyError {
+    constructor(message: string, code: 409);
+}
+export default WebAuthnError;

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

@@ -0,0 +1,8 @@
+export { AuthenticationError } from "./AuthenticationError.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 { WebAuthnError } from "./WebAuthnError.js";

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

@@ -0,0 +1,29 @@
+import { Service, Module } from "nodefony";
+import { RemoteJwtVerifier } from "../src/token/RemoteJwtVerifier.js";
+/**
+ * Pose (ou non) le vérificateur de jetons d'accès TIERS dans le conteneur.
+ *
+ * Ce service est une **décision de câblage**, pas de la cryptographie : toute la
+ * mécanique vit dans {@link RemoteJwtVerifier}, et la doctrine de refus dans le
+ * cœur (`nodefony/src/oauth/`). Ici, on lit la configuration et on tranche une
+ * seule question — cette application accepte-t-elle des jetons émis ailleurs ?
+ *
+ * **Aucun émetteur déclaré = rien n'est posé**, et c'est le comportement voulu :
+ * une porte protégée qui ne trouve pas de vérificateur refuse de servir en le
+ * disant (503 + CRITIC), là où un vérificateur présent mais vide refuserait
+ * chaque jeton un par un — même résultat pour l'appelant, diagnostic beaucoup
+ * plus difficile pour l'exploitant.
+ *
+ * Le coût est nul quand la capacité n'est pas utilisée : rien n'est instancié,
+ * aucune requête n'est faite au démarrage. La découverte des clés n'a lieu qu'au
+ * PREMIER jeton réellement présenté, et une seule fois par émetteur.
+ */
+declare class AccessTokenVerifierService extends Service {
+    #private;
+    module: Module;
+    constructor(module: Module);
+    /** Le vérificateur, ou `null` si aucun émetteur n'est déclaré. */
+    get verifier(): RemoteJwtVerifier | null;
+}
+export default AccessTokenVerifierService;
+export { AccessTokenVerifierService };

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

@@ -0,0 +1,103 @@
+import { Service, Module, type IPage } from "nodefony";
+import { type ITokenCounts } from "../src/token/tokenFilters.js";
+import type { ITokenListQuery } from "../contracts/ITokenStore.js";
+import type { IApiKeyView, IApiKeyCreated, IApiKeyCapabilities, ICreateApiKeyOptions } from "../contracts/IApiKey.js";
+/**
+ * Gestion des **clés API personnelles (PAT, P6.12)** — émission, listing et
+ * révocation, au-dessus du `ITokenStore` **partagé** (posé au container par le
+ * `TokenService`, qui en possède aussi le `gc`). Un PAT et un refresh token
+ * cohabitent dans la même table (`kind`) ; ce service ne traite que `kind:"pat"`.
+ *
+ * **Sécurité** : le secret (256 bits aléatoires) n'est rendu en clair qu'à la
+ * création (`IApiKeyCreated.token`, RFC « shown once ») ; seul son `sha256` est
+ * persisté. Création/révocation s'appliquent **toujours à un porteur donné**
+ * (jamais à autrui) — l'identité est résolue côté endpoint (session BFF). La
+ * vérification d'une clé présentée vit, elle, dans `ApiKeyAuthenticator`.
+ *
+ * Le store est résolu **paresseusement** du container (`tokenStore`) au premier
+ * usage : indépendant de l'ordre de boot des services.
+ */
+declare class ApiKeyService extends Service {
+    #private;
+    module: Module;
+    constructor(module: Module);
+    /** `true` si les clés API sont activées en config. */
+    isEnabled(): boolean;
+    /**
+     * Champs de tri que le backend **actuellement branché** sait honorer, en
+     * vocabulaire public. Le data plane admin les passe en allowlist au traducteur
+     * de requête de page : hors de cette liste, un `?order=` est refusé en 400.
+     *
+     * La liste vient du store, jamais d'une constante recopiée ici : c'est ce qui
+     * fait qu'un backend à capacité réduite (Redis, dont le `SCAN` n'a pas d'ordre
+     * global) refuse le tri **sans qu'aucune règle supplémentaire ne soit écrite**.
+     * Store absent ou indisponible → aucune capacité annoncée, donc aucun tri promis.
+     *
+     * @returns les champs triables, ou un tableau vide.
+     */
+    sortableFields(): readonly string[];
+    /**
+     * Émet une nouvelle clé API pour un porteur — renvoie sa vue publique **+ le
+     * token en clair** (affiché une seule fois).
+     *
+     * @throws ApiKeyError 400 — nom vide/trop long, scope hors catalogue, expiry invalide.
+     * @throws ApiKeyError 409 — plafond `maxPerSubject` atteint.
+     * @throws ApiKeyError 503 — store indisponible.
+     */
+    createForSubject(subjectId: string, subjectType: "user" | "service", opts: ICreateApiKeyOptions): Promise<IApiKeyCreated>;
+    /** Liste les clés (PAT) d'un porteur — vue publique, sans secret, récentes d'abord. */
+    listForSubject(subjectId: string): Promise<IApiKeyView[]>;
+    /**
+     * Liste **paginée** des clés (PAT) du système, tous porteurs confondus — vue
+     * d'ADMINISTRATION (gouvernance / réponse à incident), publique et sans secret.
+     * Réservé au data plane admin (RBAC `ROLE_NODEFONY_ADMIN`) : l'identité du porteur
+     * (`subjectId`) est exposée pour la supervision.
+     *
+     * Pagination **native au store** (jamais un `listAll()` matérialisé en RAM) : `kind`
+     * est forcé à `"pat"` ; les autres filtres (`subjectId`/`revoked`) + la fenêtre
+     * (`limit`/`offset`/`cursor`) viennent de `query`. Tri `createdAt` DESC par défaut.
+     *
+     * @param query - filtres + fenêtre de page ({@link ITokenListQuery}, `kind` ignoré).
+     * @returns une page de vues publiques ({@link IApiKeyView}, sans secret).
+     */
+    listPagePat(query: ITokenListQuery): Promise<IPage<IApiKeyView>>;
+    /**
+     * Les compteurs de tête de la console — posés sur la collection ENTIÈRE, pas
+     * sur la page affichée.
+     *
+     * Les trois états partitionnent, mais chacun est **compté** : une partition
+     * est une propriété du domaine d'aujourd'hui, pas une garantie du code, et un
+     * quatrième état la briserait en silence si l'un se déduisait des autres.
+     *
+     * `kind` reste forcé à `"pat"` comme pour la liste : ces cartes surplombent
+     * un tableau de clés d'API, pas de jetons de rafraîchissement.
+     *
+     * @param query - filtres à appliquer avant comptage (sans fenêtre).
+     */
+    countKeyFacets(query?: Partial<ITokenListQuery>): Promise<ITokenCounts>;
+    /**
+     * Révoque **n'importe quelle** clé (PAT) — action d'ADMINISTRATION (réponse à
+     * incident : clé compromise), SANS contrainte de porteur (≠ `revokeForSubject`).
+     * Audité avec l'acteur admin ET le porteur cible. Idempotent.
+     *
+     * @param id - identifiant public de la clé.
+     * @param actorId - identité de l'admin qui révoque (tracée pour l'audit).
+     * @returns la vue publique mise à jour, ou `null` si introuvable / pas un PAT.
+     */
+    revokeAnyPat(id: string, actorId: string): Promise<IApiKeyView | null>;
+    /**
+     * Capacités/contraintes d'émission (plafond, scopes, préfixe, durée par défaut)
+     * — pour un formulaire de création honnête côté console. Aucune valeur sensible.
+     */
+    describeCapabilities(): IApiKeyCapabilities;
+    /**
+     * Révoque une clé du porteur. **Anti-énumération** : une clé inexistante OU
+     * appartenant à autrui renvoie `false` (« introuvable pour ce porteur ») —
+     * jamais un 403 qui révélerait son existence. Idempotent (déjà révoquée → `true`).
+     *
+     * @returns `true` si la clé du porteur a été trouvée (et révoquée), sinon `false`.
+     */
+    revokeForSubject(subjectId: string, id: string): Promise<boolean>;
+}
+export default ApiKeyService;
+export { ApiKeyService };

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

@@ -0,0 +1,30 @@
+import { Service, Module, type IPage } from "nodefony";
+import type { IAuditEvent, IAuditEventDraft } from "../contracts/IAuditEvent.js";
+import type { IAuditListQuery, IAuditSink } from "../contracts/IAuditStore.js";
+/**
+ * Journal d'audit de sécurité (P6.14) — collecte les **événements** de sécurité
+ * (login, refus d'accès, jeton émis/révoqué, défense CSRF/CORS, verrou WS) émis
+ * EXPLICITEMENT par le firewall, les authenticators et les controllers. Distinct
+ * du log de trafic (`JsonAuditLogger`, P3.1, 1 PDU/requête) : ici on trace les
+ * **transitions d'état** de sécurité, jamais le hot-path par requête.
+ *
+ * Propriétaire du {@link IAuditStore} (référence mémoire append-only) : le pose au
+ * container (`auditStore`, consommé par le data plane P6.15) et arme le `gc` de
+ * rétention (timer `unref`). Implémente {@link IAuditSink} — `record` est
+ * **fire-and-forget** (jamais bloquant) et **no-op à coût nul** si désactivé.
+ *
+ * Slot : store **pluggable** (ORM/Loki, multi-pod) = lot futur, comme
+ * `tokenStoreRegistry`. Le socle n'embarque que la référence mémoire.
+ */
+declare class AuditService extends Service implements IAuditSink {
+    #private;
+    module: Module;
+    constructor(module: Module);
+    record(draft: IAuditEventDraft): void;
+    subscribe(listener: (event: IAuditEvent) => void): () => void;
+    /** Lit une page du journal (délègue au store) ; vide si l'audit est inactif. */
+    listPage(query: IAuditListQuery): Promise<IPage<IAuditEvent>>;
+    /** `true` si l'audit est actif (config `audit.enabled`). */
+    isEnabled(): boolean;
+}
+export default AuditService;

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

@@ -0,0 +1,123 @@
+import { Service, Module } from "nodefony";
+import type { ContextType, ISession } from "@nodefony/http";
+/**
+ * Projection PUBLIQUE de l'utilisateur — ce qui sort en JSON vers le client.
+ * Jamais l'entité brute : le hash (`IPasswordAuthenticatedUser.password`) ne
+ * doit traverser ni la sérialisation ni un log.
+ */
+export interface ISafeUser {
+    id: string;
+    username: string;
+    roles: string[];
+}
+/**
+ * Issue d'un `login` : soit l'identité est établie (session ouverte), soit un
+ * **second facteur** est requis (2FA) — le mot de passe seul n'a PAS authentifié.
+ */
+export type ILoginOutcome = {
+    status: "authenticated";
+    user: ISafeUser;
+} | {
+    status: "mfa_required";
+    methods: ["totp"];
+};
+/**
+ * Flux de session BFF — login/logout/me côté serveur (P6 J3).
+ *
+ * C'est le GUICHET : le credential est présenté UNE fois (`login`), vérifié par
+ * le {@link IPasswordVerifier} (hash, leurre anti-timing, re-hash migration),
+ * puis remplacé par un cookie de session opaque `HttpOnly` — le mot de passe ne
+ * recircule jamais, le navigateur ne stocke aucun token lisible par JS.
+ *
+ * Anti session-fixation (OWASP) : l'ID de session est TOUJOURS régénéré au
+ * login — un ID pré-posé par un attaquant (cookie forcé avant le guichet) ne
+ * survit pas à l'authentification ; l'ancienne entrée storage est détruite.
+ *
+ * Throttling NIST SP 800-63B : le MÊME `LoginThrottler` que la porte Basic
+ * (instance partagée via le container, posée par le firewall au boot) — un
+ * attaquant ne contourne pas le backoff en changeant de porte.
+ *
+ * Les handlers HTTP (`SessionAuthController`, `@nodefony/framework`) sont des
+ * adaptateurs minces au-dessus de ce service — la logique reste testable sans
+ * transport.
+ */
+declare class AuthFlow extends Service {
+    #private;
+    module: Module;
+    constructor(module: Module);
+    /**
+     * Authentifie le couple identifiant/mot de passe et OUVRE la session BFF.
+     *
+     * Ordre NIST : throttle AVANT le verifier (un identifiant bloqué ne coûte
+     * aucun hash argon2 — le backoff protège aussi le serveur du DoS), échec
+     * compté, succès remis à zéro.
+     *
+     * @param context - contexte HTTP courant (porte la session/le cookie).
+     * @param identifier - identifiant saisi (body JSON, non typé à la frontière).
+     * @param password - mot de passe saisi.
+     * @returns `authenticated` (identité établie) ou `mfa_required` (2ᵉ facteur requis).
+     * @throws ThrottledError (429 + `Retry-After`) — backoff actif.
+     * @throws AuthenticationError (401, message uniforme) — credential absent ou
+     *   invalide.
+     */
+    login(context: ContextType, identifier: unknown, password: unknown): Promise<ILoginOutcome>;
+    /**
+     * Ouvre la session BFF pour un utilisateur **déjà authentifié par un autre
+     * facteur** (passkey/WebAuthn, OAuth, magic link…) — aucun mot de passe à
+     * vérifier ici, la preuve a été apportée en amont par l'appelant.
+     *
+     * Même anti-fixation que {@link login} (ID régénéré, ancienne entrée
+     * détruite). L'identité est re-résolue + revalidée (compte actif/non
+     * verrouillé) via la source unique `resolveSessionIdentity` — un compte banni
+     * entre la preuve et l'ouverture de session est rejeté.
+     *
+     * @param identifier - identifiant de l'utilisateur prouvé (ex. `sub` du credential).
+     * @throws AuthenticationError (401, message uniforme) — identifiant absent, ou
+     *   compte disparu/inactif/verrouillé.
+     */
+    establishSessionFor(context: ContextType, identifier: unknown, reason?: string): Promise<ISafeUser>;
+    /**
+     * Valide le **second facteur** (code TOTP ou code de récupération) après un
+     * `login` ayant renvoyé `mfa_required`, puis OUVRE la session BFF. Le défi
+     * PENDING déposé en session par `login` est lu, vérifié, puis invalidé (usage
+     * unique) ; l'identité n'est établie qu'ICI. **Throttlé** sur l'identité en
+     * attente (anti brute-force du code à 6 chiffres).
+     *
+     * @param context - contexte HTTP (porte la session PENDING).
+     * @param code - code présenté (TOTP ou code de récupération).
+     * @returns la projection publique de l'utilisateur authentifié.
+     * @throws ThrottledError (429) — trop de tentatives.
+     * @throws AuthenticationError (401, uniforme) — aucun défi en cours, code absent
+     *   ou invalide (la session N'est PAS ouverte ; le défi reste pour un retry).
+     */
+    completeMfaLogin(context: ContextType, code: unknown): Promise<ISafeUser>;
+    /**
+     * Garantit une session pour la requête courante — la démarre (+ cookie) si
+     * elle n'existe pas encore. Sert aux cérémonies **pré-authentification**
+     * (login WebAuthn) : elles doivent porter un challenge côté serveur AVANT que
+     * l'utilisateur soit connecté. La session anonyme ainsi créée devient la
+     * session authentifiée au login — {@link establishSessionFor} régénère l'ID
+     * (anti-fixation préservée), donc un challenge déposé ici n'ouvre aucune brèche.
+     *
+     * @returns la session (existante ou neuve), ou `null` si le service de session
+     *   est indisponible.
+     */
+    ensureSession(context: ContextType): Promise<ISession | null>;
+    /**
+     * Détruit la session courante (storage + cookie). Idempotent : sans session
+     * active, ne fait rien.
+     *
+     * @returns `true` si une session a réellement été détruite.
+     */
+    logout(context: ContextType): Promise<boolean>;
+    /**
+     * Identité portée par la session courante, re-résolue auprès du provider
+     * (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 401.
+     */
+    me(context: ContextType): Promise<ISafeUser | null>;
+}
+export default AuthFlow;
+export { AuthFlow };

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

@@ -0,0 +1,33 @@
+import { Service, Module, Severity, Msgid, Message, Pdu } from "nodefony";
+import type { IAuthorizationService } from "../contracts/IAuthorizationService.js";
+import type { IToken } from "../contracts/IToken.js";
+/**
+ * Service d'autorisation Nodefony (niveau C, P6 J6) — décide d'un accès via un
+ * jury de {@link IAccessVoter}.
+ *
+ * Stratégie **affirmative + DENY veto** : un seul `DENY` bloque (veto) ; sinon un
+ * `GRANT` suffit ; **silence total** (tous `ABSTAIN`, ou aucun voter compétent)
+ * → `DENY` (**Zero Trust** : fermé par défaut). Tout refus est audité (WARNING) ;
+ * les accès accordés restent silencieux (pas de spam — l'audit d'octroi explicite
+ * viendra avec `@AuditLog`, P6.14).
+ *
+ * Les voters sont découverts au boot via le `voterRegistry` (built-in `role` +
+ * ceux des apps/plugins) — aucun nom en dur ici. Consommé par les décorateurs
+ * (`@IsGranted`, J7) et le verrou de frame WS (« 1 garde = N transports »).
+ *
+ * Perf : aucune allocation par appel (`decide` itère les voters et teste
+ * `supports()` en place) ; les voters sont instanciés UNE fois au boot.
+ */
+declare class Authorization extends Service implements IAuthorizationService {
+    #private;
+    module: Module;
+    constructor(module: Module);
+    /**
+     * Le token a-t-il le droit `attribute` sur `subject` ? Affirmative + DENY veto,
+     * défaut `DENY` (Zero Trust). Voir {@link IAuthorizationService.decide}.
+     */
+    decide(token: IToken, attribute: string, subject?: unknown): Promise<boolean>;
+    log(pci: unknown, severity?: Severity, msgid?: Msgid, msg?: Message): Pdu;
+}
+export default Authorization;
+export { Authorization };

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

@@ -0,0 +1,48 @@
+/**
+ * Sous-ensemble de la config `cors` consommé par la politique (cf defineSecurityConfig).
+ */
+export interface ICorsOptions {
+    enabled: boolean;
+    origins: readonly string[];
+    credentials: boolean;
+    methods: readonly string[];
+    allowedHeaders: readonly string[];
+    exposedHeaders: readonly string[];
+    maxAgeS: number;
+}
+/** En-têtes de réponse CORS à poser (nom canonique → valeur). */
+export type CorsHeaders = Record<string, string>;
+/**
+ * Politique CORS de Nodefony — Same-Origin Policy assouplie côté serveur
+ * (Fetch Standard / W3C CORS protocol). Logique PURE et synchrone : décide les
+ * en-têtes `Access-Control-*` à poser pour une origine donnée. Instanciée une
+ * fois au boot par le firewall, testable sans serveur.
+ *
+ * Invariants de sécurité (OWASP) :
+ * - **Jamais `*` + credentials** : interdit au boot (refine Zod). Ici, `*` n'est
+ *   émis QUE si `credentials=false` ; avec credentials, l'origine est reflétée.
+ * - **Reflet d'origine ⇒ `Vary: Origin`** : signalé via {@link reflectsOrigin}
+ *   pour que l'appelant pose l'en-tête `Vary` (correction de cache).
+ * - **Origine non whitelistée ⇒ aucun en-tête** : la réponse n'est pas partageable
+ *   (le navigateur bloque), zéro information divulguée.
+ *
+ * @see Fetch Standard (CORS protocol) · OWASP CORS.
+ */
+export declare class Cors {
+    #private;
+    constructor(options: ICorsOptions);
+    /** `true` si la valeur Allow-Origin reflète l'origine (⇒ l'appelant doit poser `Vary: Origin`). */
+    reflectsOrigin(allowOrigin: string): boolean;
+    /**
+     * En-têtes d'une réponse au **preflight** `OPTIONS` (méthodes/headers autorisés
+     * + cache + credentials), ou `null` si l'origine n'est pas autorisée (réponse
+     * 204 nue → le navigateur bloque).
+     */
+    preflightHeaders(origin: string): CorsHeaders | null;
+    /**
+     * En-têtes d'une réponse à une **requête réelle** cross-origin (Allow-Origin +
+     * credentials + headers exposés au JS), ou `null` si l'origine n'est pas autorisée.
+     */
+    actualHeaders(origin: string): CorsHeaders | null;
+}
+export default Cors;

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

@@ -0,0 +1,57 @@
+/** Sous-ensemble de la config `csrf` consommé par la défense (cf defineSecurityConfig). */
+export interface ICsrfOptions {
+    enabled: boolean;
+    fetchMetadata: boolean;
+    checkOrigin: boolean;
+    strictSameSite: boolean;
+}
+/** En-têtes bruts d'une requête, extraits par le firewall (clés HTTP en lowercase). */
+export interface ICsrfRequest {
+    /** Méthode HTTP (`context.method`). */
+    method: string | null | undefined;
+    /** `Sec-Fetch-Site` — provenance tamponnée par le navigateur (défense primaire). */
+    secFetchSite: string | undefined;
+    /** `Origin` — origine du document initiateur (fallback). */
+    origin: string | undefined;
+    /** `Referer` — utilisé seulement si `Origin` est absent (fallback). */
+    referer: string | undefined;
+    /** Hôte cible (`context.domain` / en-tête `Host`) — pour le test same-host du fallback. */
+    host: string | undefined;
+}
+/**
+ * Défense CSRF par défaut de Nodefony — **Fetch Metadata d'abord** (modèle Go 1.25
+ * `CrossOriginProtection` / OWASP 2025), repli `Origin`/`Referer` pour les vieux
+ * navigateurs. Logique PURE et synchrone (aucun I/O, aucune alloc sur le hot-path
+ * GET) → testable sans serveur, instanciée une seule fois au boot par le firewall.
+ *
+ * Chaîne de décision sur une requête state-changing :
+ *
+ * 1. **Origine de confiance** (alias multi-domaine `csrf.trustedOrigins` ∪ whitelist
+ *    CORS) → laisser passer même en cross-site : un alias légitime de l'app, ou ce
+ *    que CORS autorise déjà, n'est pas du CSRF (cohérence CSRF ↔ CORS).
+ * 2. **Fetch Metadata** (`Sec-Fetch-Site`, infalsifiable) : `same-origin`/`none`
+ *    → OK ; `same-site` → OK sauf `strictSameSite` ; `cross-site` → **403** ;
+ *    valeur inconnue → on délègue au repli (forward-compat, W3C « SHOULD ignore »).
+ * 3. **Repli `Origin`/`Referer`** : aucune des deux → client non-navigateur, hors
+ *    vecteur CSRF → OK ; sinon same-host requis, mismatch → **403**.
+ *
+ * @see RFC 9110 §9.2.1 (méthodes sûres) · W3C Fetch Metadata · RFC 6265bis §8.8.1.
+ */
+export declare class Csrf {
+    #private;
+    /**
+     * `true` si la méthode mute l'état (hors {@link SAFE_METHODS}). Permet à
+     * l'appelant (firewall) de court-circuiter le hot-path GET sans lire d'en-tête.
+     */
+    static isStateChanging(method: string | null | undefined): boolean;
+    constructor(options: ICsrfOptions, allowedOrigins?: readonly string[]);
+    /**
+     * Valide la provenance d'une requête. No-op (retour immédiat) sur une méthode
+     * sûre — coût nul sur le GET dominant. Lève {@link CsrfError} (403) sinon.
+     *
+     * @throws CsrfError - mutation `cross-site` (Fetch Metadata) ou `Origin`/`Referer`
+     *   étranger aux origines de l'app (repli).
+     */
+    enforce(req: ICsrfRequest): void;
+}
+export default Csrf;

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

@@ -0,0 +1,148 @@
+import { Service, Module, Severity, Msgid, Message, Pdu } from "nodefony";
+import type { IProtectedResourceInput } from "nodefony";
+import type { ContextType } from "@nodefony/http";
+import { SecuredArea } from "../src/SecuredArea.js";
+import { RoleHierarchyWalker } from "../src/RoleHierarchyWalker.js";
+import { type CspFragment } from "../src/csp.js";
+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";
+/**
+ * Orchestrateur de sécurité Nodefony — refonte 2026 (P6).
+ *
+ * `isSecure()` (hot-path, court-circuit si aucune zone) ne fait QUE matcher la
+ * zone et poser `context.security`. `handleSecurity()` (lazy, seulement sur une
+ * zone protégée) exécute la chaîne d'authentication selon le `mode` de la zone
+ * (`first` : le premier qui reconnaît la requête authentifie ; `all` : tous
+ * doivent passer, le dernier porte l'identité) → propage l'utilisateur dans
+ * l'ALS → applique le **Zero Trust** (zone protégée sans preuve acceptée → 401,
+ * sauf anonymat explicite via l'authenticator `anonymous`).
+ *
+ * **Fail-closed** : config invalide au boot (Zod, nom d'authenticator inconnu)
+ * → le firewall capture TOUT le trafic et répond 401 (jamais une app servie
+ * sans sa sécurité). Erreur interne pendant l'authentification (source
+ * d'identité down, câblage manquant) → log ERROR serveur + 401 générique
+ * (aucun détail ne fuite au client).
+ *
+ * Conformité : tout 401 porte un challenge `WWW-Authenticate` (RFC 7235) fourni
+ * par le premier authenticator de la zone qui en déclare un.
+ *
+ * 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).
+ */
+declare class Firewall extends Service implements IFirewall {
+    #private;
+    module: Module;
+    constructor(module: Module);
+    /** Hiérarchie de rôles résolue (niveau A de l'autorisation, P6.8). */
+    get roleHierarchy(): RoleHierarchyWalker;
+    /**
+     * `true` si l'un des rôles de l'utilisateur couvre `required` (hiérarchie
+     * comprise). Surface lue par le verrou de frame WS ({@link buildFrameAuthorizer})
+     * pour le RBAC par canal — délègue au {@link RoleHierarchyWalker}.
+     */
+    hasRole(userRoles: readonly string[], required: string): boolean;
+    registerAuthenticator(authenticator: IAuthenticator): void;
+    getArea(name: string): ISecuredArea | undefined;
+    describe(): IFirewallDescription;
+    /**
+     * Hiérarchie de rôles déclarée + résolution transitive (data plane Studio).
+     * Brut = ce que l'app a écrit ; `inherits` = aplati précalculé par le walker.
+     */
+    describeRoleHierarchy(): IRoleHierarchyDescription;
+    /**
+     * Ce que l'application PROTÈGE, à publier en RFC 9728 — une entrée par
+     * ressource déclarée par une zone.
+     *
+     * ⭐ **Même donnée que le défi, donc impossible qu'ils divergent.** Le `401`
+     * d'une zone porte `resource_metadata="…/.well-known/oauth-protected-resource
+     * /<chemin de `area.resource`>"` ; ce que rend cette méthode est la source de
+     * ce que `@nodefony/framework` monte à cette URL. Une seconde déclaration —
+     * une clé « ressources publiées » à côté des zones — se serait périmée au
+     * premier renommage, et le symptôme aurait été un `404` que rien n'explique.
+     *
+     * 🔴 **Les serveurs d'autorisation sont les émetteurs de confiance, pas une
+     * liste à part.** `authorization_servers` répond à « qui peut délivrer un
+     * jeton pour cette ressource ? » — c'est exactement l'allowlist
+     * `resourceServer.issuers`, la seule que le vérificateur consulte. Publier
+     * autre chose reviendrait à envoyer le client demander un jeton à un émetteur
+     * dont on refuse ensuite la signature.
+     *
+     * Aucun émetteur de confiance ⇒ **rien à publier** : un document sans serveur
+     * d'autorisation apprendrait au client qu'un jeton est nécessaire sans jamais
+     * lui dire où l'obtenir (et la RFC 9728 comme la spécification MCP l'excluent).
+     *
+     * Appelée UNE fois, au montage des routes (`onKernelReady`) — hors hot path,
+     * d'où l'allocation directe plutôt qu'un cache à invalider.
+     *
+     * @returns les ressources protégées déclarées, éventuellement vide
+     */
+    publishedProtectedResources(): readonly IProtectedResourceInput[];
+    /**
+     * Match de zone par pathname (+ host) SANS contexte — source UNIQUE consultée
+     * par `isSecure` (HTTP) ET le verrou WebSocket (la frame `api.request` n'a
+     * qu'un path). Hot-path : patterns pré-compilés + pathname fourni → 0 alloc.
+     */
+    matchPath(pathname: string, host?: string): SecuredArea | null;
+    /** Match rapide de zone — pose `context.security`. `true` si zone capturée. */
+    isSecure(context: ContextType): boolean;
+    /**
+     * Pipeline complet de la zone : chaîne d'authenticators (selon `mode`) → ALS
+     * → Zero Trust. Rejette (401, challenge RFC 7235 posé) ou résout.
+     */
+    handleSecurity(context: ContextType): Promise<ContextType>;
+    /**
+     * Défense CSRF (P6 J5/étape 2) — branchée dans le pipeline HTTP de `@nodefony/http`
+     * pour TOUTE requête (zone ou non), APRÈS le resolve (les marqueurs `@CsrfProtect`/
+     * `@CsrfExempt` de la route sont disponibles). Trois rôles :
+     *
+     *  - **Émission** : sur une requête SÛRE vers une route `@CsrfProtect`, minte le
+     *    synchronizer token (`context.csrfToken`) — HttpContext pose ensuite le cookie
+     *    lisible `csrf-token`. Sinon, hot-path GET = retour immédiat (aucun en-tête lu).
+     *  - **Étape 1 (globale)** : sur une mutation, défense Fetch Metadata / Origin
+     *    (rejet cross-site même sur route publique). Skippée si `@CsrfExempt` (webhook,
+     *    auth par signature/clé) ou `bypassFirewall` (callbacks OAuth).
+     *  - **Étape 2 (opt-in)** : sur une mutation `@CsrfProtect`, exige EN PLUS le
+     *    synchronizer token (en-tête `x-csrf-token` ≡ cookie + HMAC valide).
+     *
+     * @throws CsrfError (403) — provenance tierce, ou synchronizer token absent/invalide.
+     */
+    enforceCsrf(context: ContextType): void;
+    /**
+     * Politique CORS (P6 J5) — appelée par `HttpKernel.handleHttp()`
+     * (`http-kernel.ts:1169`), en TÊTE du pipeline : avant le routing, avant le parse
+     * du corps, donc bien avant `handleFrontController` et le firewall. Un preflight
+     * n'a pas de route déclarée — router d'abord lèverait un 405.
+     * Pose les en-têtes `Access-Control-*` et **court-circuite le
+     * preflight** `OPTIONS` en `204` (le preflight ne porte jamais de credentials,
+     * Fetch Standard → il ne doit ni router ni s'authentifier). No-op hors requête
+     * cross-origin (pas d'`Origin`), CORS désactivé, ou réponse non-HTTP (WS).
+     *
+     * @returns `204` si la requête est un preflight (l'appelant court-circuite la
+     *   réponse), sinon `undefined` (la requête réelle suit le pipeline normal).
+     */
+    handleCors(context: ContextType): number | undefined;
+    /**
+     * 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).
+     *
+     * 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é.
+     */
+    applySecurityHeaders(context: ContextType): 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;
+    /** 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;
+}
+export default Firewall;
+export { Firewall };