@nodefony/security 10.0.0-alpha.8 → 10.0.0-beta.1

package/docs/csrf.md

@@ -91,9 +91,9 @@ contrôleur** : l'attaque meurt sans avoir touché ton code.
 ## La vision Nodefony
 
 - **Vérifier la provenance d'abord** (OWASP 2025, modèle Go 1.25 `CrossOriginProtection`) : la
-  couche 1 est la défense **par défaut**, `csrf.enabled: true` (`config.ts:151-156`).
+  couche 1 est la défense **par défaut**, `csrf.enabled: true` (`config.ts:163-168`).
 - **Globale, pas liée aux zones** : toute mutation cross-site est refusée, route publique ou non —
-  branchée dans le pipeline HTTP — l'appel `enforceCsrf` (`http-kernel.ts:1470`) arrive **après** le
+  branchée dans le pipeline HTTP — l'appel `enforceCsrf` (`http-kernel.ts:1524`) arrive **après** le
   resolve (les marqueurs de route sont lisibles) et **avant** la session (rejet précoce : un
   attaquant ne coûte ni lecture de session ni authentification).
 - **Logique pure** : la classe `Csrf` est synchrone, sans I/O ni allocation sur le hot-path —
@@ -111,7 +111,7 @@ cookies d'une victime, ils sont hors vecteur (`csrf.ts:113`).
 
 ### Opt-in couche 2 : `@CsrfProtect` sur une mutation à haute valeur
 
-Les décorateurs `CsrfProtect`/`CsrfExempt` sont exportés par `@nodefony/framework` (`framework/index.ts:86-87`) :
+Les décorateurs `CsrfProtect`/`CsrfExempt` sont exportés par `@nodefony/framework` (`framework/index.ts:101-102`) :
 
 ```typescript
 // nodefony/controllers/ProfileController.ts — complet, compile tel quel
@@ -148,13 +148,13 @@ export default ProfileController;
 
 (Wiring : `@controllers([ProfileController])` dans le module de l'app — `nodefony create controller`
 le fait pour toi. Posé sur la **classe**, `@CsrfProtect()` couvre toutes les actions : les marqueurs
-`csrfProtect`/`csrfExempt` acceptent méthode OU classe, `routerDecorators.ts:1605-1611`.)
+`csrfProtect`/`csrfExempt` acceptent méthode OU classe, `routerDecorators.ts:1650-1655`.)
 
 ### Comment le front obtient — puis rejoue — le token
 
 1. **Obtenir** : une requête **sûre** (GET) vers n'importe quelle route `@CsrfProtect` sème le token
    (`firewall.ts:958-964`) ; la réponse pose le cookie **lisible** `csrf-token` — non `HttpOnly`
-   exprès, `SameSite=Strict`, `Secure` en HTTPS (`HttpContext.writeHead()`, `HttpContext.ts:419-432`).
+   exprès, `SameSite=Strict`, `Secure` en HTTPS (`HttpContext.writeHead()`, `HttpContext.ts:482-497`).
 2. **Rejouer** : le SPA lit le cookie et renvoie sa valeur **à l'identique** dans l'en-tête
    `x-csrf-token` sur chaque mutation.
 
@@ -199,7 +199,7 @@ curl -si -b /tmp/jar -H "x-csrf-token: $TOKEN" \
 > [!IMPORTANT]
 > En **prod/cluster**, le secret du synchronizer doit être **fixé et partagé entre process** —
 > absent, un secret **éphémère** est généré (dev) : un redémarrage invalide les tokens en cours, et
-> chaque pod rejette les tokens des autres (`firewall.ts:199-209`). Générer et câbler :
+> chaque pod rejette les tokens des autres (`firewall.ts:225-234`). Générer et câbler :
 > `npx nodefony security:secrets` (`security-secrets.ts:39`) → `NF_CSRF_SECRET` →
 > `use("@nodefony/security", { csrf: { secret: ctx.env.NF_CSRF_SECRET } })`.
 
@@ -241,12 +241,12 @@ autorisation :
 ```
 
 > [!WARNING]
-> `@CsrfExempt` (`routerDecorators.ts:1099`) est un opt-out **ciblé CSRF**. Ne jamais « débloquer un
+> `@CsrfExempt` (`routerDecorators.ts:1142`) est un opt-out **ciblé CSRF**. Ne jamais « débloquer un
 > webhook » avec `@BypassFirewall`/`@Anonymous` : eux désactivent l'authentification de la zone.
 
 Cas voisin — **façade multi-domaine** (`www.example.com` poste vers l'API d'un autre domaine à toi) :
 déclarer l'alias dans `csrf.trustedOrigins` (match exact d'origine), pas dans `cors.origins` — CORS
-ouvrirait **aussi** la lecture des réponses au JS tiers (`config.ts:176-181`).
+ouvrirait **aussi** la lecture des réponses au JS tiers (`config.ts:188-193`).
 
 ## 🏗️ Architecture interne
 
@@ -257,7 +257,7 @@ sûres → coût nul sur le GET dominant (`csrf.ts:88`). Pour une mutation, dans
 
 1. **Origine de confiance** — `csrf.trustedOrigins` ∪ whitelist CORS → passe même en cross-site : ce
    que CORS autorise déjà explicitement **n'est pas** du CSRF (`csrf.ts:45`, union construite par le
-   firewall au boot, `firewall.ts:190-194`).
+   firewall au boot, `firewall.ts:217-220`).
 2. **Fetch Metadata** (`Sec-Fetch-Site`, infalsifiable par un script) : `same-origin`/`none` → OK ;
    `same-site` → OK sauf `strictSameSite` (`csrf.ts:102-104`) ; `cross-site` → **403** ; valeur
    inconnue → on **délègue au repli** (forward-compat, le W3C dit « SHOULD ignore », `csrf.ts:98-109`).
@@ -269,9 +269,9 @@ Lectures durcies côté firewall :
 
 - en-têtes lus en **première occurrence** — jamais un tableau d'en-têtes répétés (garde d'injection,
   `headerValue()`, `firewall.ts:103`) ; cookie extrait de l'en-tête **brut**, sans dépendre du
-  parse du contexte (`cookieValue()`, `firewall.ts:90-103`) ;
+  parse du contexte (`cookieValue()`, `firewall.ts:116-129`) ;
 - hôte cible **brut avec port** — `:authority` en HTTP/2, `context.domain` en dernier recours
-  (`firewall.ts:772-775`) ;
+  (`firewall.ts:977-982`) ;
 - le refus est un `CsrfError` **403 au message générique** : la politique (en-têtes inspectés,
   whitelist) ne fuite jamais au client (`CsrfError.ts:17-21`).
 
@@ -296,28 +296,28 @@ de session (TSDoc `CsrfTokenManager`, `csrfToken.ts:12-15`).
 1. `@CsrfProtect`/`@CsrfExempt` posent un **marqueur** de metadata — zéro import de
    `@nodefony/security` côté framework, zéro cycle (`routerDecorators.ts:886`).
 2. Au match de la route, `Resolver.match()` recopie les marqueurs sur le contexte
-   (`Resolver.ts:152-153`) — champs portés par le `Context` de base, HTTP comme WS
-   (`Context.ts:181-183`).
+   (`Resolver.ts:156-186`) — champs portés par le `Context` de base, HTTP comme WS
+   (`Context.ts:241-243`).
 3. `Firewall.enforceCsrf()` (`firewall.ts:948`) fait les trois rôles : **émission** du token sur
    requête sûre `@CsrfProtect`, **couche 1** sur toute mutation, **couche 2** en plus si
    `@CsrfProtect`. Les routes `bypassFirewall` (callbacks OAuth) sont exemptées
    (`firewall.ts:950-953`), les `@CsrfExempt` sortent après la barrière méthode sûre
-   (`firewall.ts:951`).
+   (`firewall.ts:967`).
 4. `HttpContext.writeHead()` matérialise `context.csrfToken` en cookie `csrf-token` — flush groupé
-   avec le cookie de session (`HttpContext.ts:419-432`).
+   avec le cookie de session (`HttpContext.ts:482-497`).
 
-## ⚙️ Configuration (schéma Zod `csrfSchema`, `config.ts:149-192`)
+## ⚙️ Configuration (schéma Zod `csrfSchema`, `config.ts:161-204`)
 
 <!-- prettier-ignore -->
 | Option | Type · défaut | Effet |
 | --- | --- | --- |
-| `enabled` | boolean · `true` | Active toute la défense — couches 1 **et** 2 (`config.ts:151-156`). |
-| `fetchMetadata` | boolean · `true` | Défense primaire `Sec-Fetch-Site` (`config.ts:157-162`). |
-| `checkOrigin` | boolean · `true` | Repli `Origin`/`Referer` same-host pour les navigateurs sans `Sec-Fetch-*` (`config.ts:164-169`). |
-| `strictSameSite` | boolean · `false` | `true` = refuser aussi `same-site` (sous-domaine non maîtrisé / multi-tenant) — distinct de l'attribut cookie (`config.ts:170-175`). |
-| `sameSite` | enum · `Lax` | **Déclaratif** : surfacé dans l'introspection (`firewall.ts:582`) ; l'attribut effectif du cookie `csrf-token` est `Strict` en dur (`HttpContext.ts:469`). |
-| `trustedOrigins` | string[] · `[]` | Alias **exacts** (`scheme://host[:port]`) autorisés même cross-site — sans ouvrir la lecture CORS (`config.ts:176-181`). |
-| `secret` | string ≥ 16 car. · — | Secret HMAC du synchronizer — PROD : via env, **partagé cluster** ; absent = éphémère dev (`config.ts:182-188`). |
+| `enabled` | boolean · `true` | Active toute la défense — couches 1 **et** 2 (`config.ts:163-168`). |
+| `fetchMetadata` | boolean · `true` | Défense primaire `Sec-Fetch-Site` (`config.ts:169-174`). |
+| `checkOrigin` | boolean · `true` | Repli `Origin`/`Referer` same-host pour les navigateurs sans `Sec-Fetch-*` (`config.ts:176-181`). |
+| `strictSameSite` | boolean · `false` | `true` = refuser aussi `same-site` (sous-domaine non maîtrisé / multi-tenant) — distinct de l'attribut cookie (`config.ts:182-187`). |
+| `sameSite` | enum · `Lax` | **Déclaratif** : surfacé dans l'introspection (`firewall.ts:604`) ; l'attribut effectif du cookie `csrf-token` est `Strict` en dur (`HttpContext.ts:486`). |
+| `trustedOrigins` | string[] · `[]` | Alias **exacts** (`scheme://host[:port]`) autorisés même cross-site — sans ouvrir la lecture CORS (`config.ts:188-193`). |
+| `secret` | string ≥ 16 car. · — | Secret HMAC du synchronizer — PROD : via env, **partagé cluster** ; absent = éphémère dev (`config.ts:194-200`). |
 
 ## 📜 Normes appliquées
 
@@ -325,7 +325,7 @@ de session (TSDoc `CsrfTokenManager`, `csrfToken.ts:12-15`).
 | ------------------------------ | --------------------------------- | -------------------------------------- |
 | Méthodes sûres                 | RFC 9110 §9.2.1                   | `SAFE_METHODS` (`csrf.ts:8-13`)        |
 | Provenance                     | W3C Fetch Metadata                | `Csrf.enforce()` (`csrf.ts:85`)        |
-| Valeur `site` inconnue → repli | Fetch Metadata « SHOULD ignore »  | `csrf.ts:107`                          |
+| Valeur `site` inconnue → repli | Fetch Metadata « SHOULD ignore »  | `csrf.ts:96`                           |
 | Token signé                    | OWASP Signed Double-Submit Cookie | `CsrfTokenManager` (`csrfToken.ts:23`) |
 | Refus 403                      | RFC 9110 §15.5.4                  | `CsrfError` (`CsrfError.ts:17-21`)     |
 | Modèle de référence            | Go 1.25 `CrossOriginProtection`   | TSDoc `Csrf` (`csrf.ts:38-41`)         |
@@ -339,14 +339,14 @@ de session (TSDoc `CsrfTokenManager`, `csrfToken.ts:12-15`).
 - **Lazy** : `#csrf`/`#csrfTokens` restent `null` si la défense est désactivée — aucune structure
   allouée « au cas où » (`firewall.ts:164`).
 - Le coût HMAC (1 à l'émission, 1 à la vérif) n'est payé **que** sur les routes `@CsrfProtect` ; les
-  marqueurs sont lus depuis le memo de route — 0 `Reflect` par requête (`Resolver.ts:142`).
+  marqueurs sont lus depuis le memo de route — 0 `Reflect` par requête (`Resolver.ts:162`).
 
 ## 📡 Observabilité — Studio
 
 L'écran **Firewall** de Studio expose la défense dans son onglet Défenses (`FirewallDefenses`,
 `Firewall.tsx:313-314`). La projection est **sans secret par construction** :
-`Firewall.#describeDefenses()` (`firewall.ts:575`) publie la config résolue, et `synchronizerToken`
-n'est que la **présence** du secret armé — jamais sa valeur (`firewall.ts:601`).
+`Firewall.#describeDefenses()` (`firewall.ts:591`) publie la config résolue, et `synchronizerToken`
+n'est que la **présence** du secret armé — jamais sa valeur (`firewall.ts:607`).
 
 ## ⚠️ Pièges (symptôme → cause → correction)
 
@@ -355,7 +355,7 @@ n'est que la **présence** du secret armé — jamais sa valeur (`firewall.ts:60
 | Mutation légitime cross-domaine bloquée en 403 | Domaine alias non déclaré                                                                      | Ajouter l'origine à `csrf.trustedOrigins` (ou CORS si lecture voulue)     |
 | Client non-navigateur (curl/CI) refusé         | N'arrive pas sur une route non décorée : ni Fetch Metadata ni `Origin` → passe (`csrf.ts:113`) | Attendu ; sur `@CsrfProtect`, semer le token (GET) avant la mutation      |
 | `@CsrfProtect` échoue en 403 côté SPA          | En-tête `x-csrf-token` non rejoué, ou ≠ cookie (`firewall.ts:778-783`)                         | Relire le cookie `csrf-token` et le rejouer à l'identique                 |
-| Tokens invalidés au redémarrage / entre pods   | `csrf.secret` absent → secret éphémère par process (`firewall.ts:199-209`)                     | Fixer `csrf.secret` (≥ 16 car., partagé cluster) — `security:secrets`     |
+| Tokens invalidés au redémarrage / entre pods   | `csrf.secret` absent → secret éphémère par process (`firewall.ts:227-237`)                     | Fixer `csrf.secret` (≥ 16 car., partagé cluster) — `security:secrets`     |
 | `same-site` refusé alors qu'attendu OK         | `strictSameSite` activé (`csrf.ts:102-104`)                                                    | Le désactiver si les sous-domaines sont de confiance                      |
 | `http://` accepté par le repli (même hôte)     | Le repli compare l'**hôte seul**, jamais le scheme (`Csrf.#sameHost()`, `csrf.ts:130-136`)     | Limite documentée (banc red-team) ; Fetch Metadata prime sur nav. moderne |
 | Webhook provider bloqué en 403                 | POST cross-site légitime, hors whitelist                                                       | `@CsrfExempt` sur la route — jamais `@BypassFirewall`                     |

package/docs/external-jwt.md

@@ -33,9 +33,9 @@ Accepter un émetteur ne veut pas dire lui remettre les clés. Deux décisions r
 sont elles qui font la différence entre « intégrer un annuaire » et « en faire l'unique autorité
 d'accès » :
 
-1. **La liste des émetteurs acceptés** est une allowlist (`config.ts:660`). Un jeton dont l'`iss` n'y figure pas est
+1. **La liste des émetteurs acceptés** est une allowlist (`config.ts:666-671`). Un jeton dont l'`iss` n'y figure pas est
    refusé **avant toute requête sortante** — l'application ne va pas interroger un émetteur inconnu.
-2. **Le sujet du jeton ne devient pas d'office un utilisateur** (`config.ts:666`). Par défaut, il
+2. **Le sujet du jeton ne devient pas d'office un utilisateur** (`config.ts:672-677`). Par défaut, il
    doit correspondre à un compte local. Un annuaire d'entreprise vaut pour des milliers de personnes : les accepter
    toutes parce que leur jeton est valide supprimerait la seconde décision, qui est la raison d'être
    du pare-feu.
@@ -44,16 +44,24 @@ d'accès » :
 
 ```ts
 // nodefony.config.ts
-security: {
-  resourceServer: {
-    issuers: [
-      {
-        issuer: "https://auth.example.com/realms/mon-royaume",
-        algorithms: ["RS256"],
+import { defineConfig, use } from "nodefony";
+
+export default defineConfig({
+  modules: [
+    "@nodefony/http",
+    "@nodefony/framework",
+    use("@nodefony/security", {
+      resourceServer: {
+        issuers: [
+          {
+            issuer: "https://auth.example.com/realms/mon-royaume",
+            algorithms: ["RS256"],
+          },
+        ],
       },
-    ],
-  },
-}
+    }),
+  ],
+});
 ```
 
 Cela suffit : les clés publiques de l'émetteur sont découvertes par ses points de métadonnées
@@ -81,7 +89,7 @@ normalisés (RFC 8414 / OpenID), et le pare-feu accepte désormais un `Authoriza
 Un `sub` n'est unique que **dans l'espace de son émetteur** (OIDC Core §2). L'identité est donc la
 paire `(émetteur, sujet)`, jamais le sujet seul.
 
-En mode `prefixed` (`config.ts:650`), l'identifiant cherché localement est `<issuer>#<sub>` : deux émetteurs ne peuvent
+En mode `prefixed` (`config.ts:656-660`), l'identifiant cherché localement est `<issuer>#<sub>` : deux émetteurs ne peuvent
 pas se disputer un compte, et surtout **aucun sujet étranger ne peut tomber par hasard sur un
 identifiant local existant**. En mode `subject`, le `sub` est cherché tel quel — dans un annuaire où
 l'utilisateur choisit son identifiant, quelqu'un peut alors se présenter avec `sub: "admin"` et être
@@ -96,7 +104,7 @@ parce qu'il **est** cette application, ou parce que ses sujets sont déjà des i
   Absent, désactivé ou verrouillé : l'accès est refusé. C'est le mode d'une application dont les
   utilisateurs existent chez elle, l'émetteur ne servant qu'à les authentifier.
 - **`ephemeral`** — aucun compte local n'est exigé ni créé ; l'appelant vit le temps de la requête
-  avec les rôles d'`ephemeralRoles` (`config.ts:672`). C'est le mode de l'appelant **purement machine** : un agent, un
+  avec les rôles d'`ephemeralRoles` (`config.ts:678`). C'est le mode de l'appelant **purement machine** : un agent, un
   service. Sans rôle déclaré, il ne passe aucun `@IsGranted` et n'est autorisé que par ses **scopes**
   — qui viennent du jeton, donc bornés par le serveur d'autorisation.
 

package/docs/firewall.md

@@ -52,10 +52,10 @@ flowchart TD
   AU -->|succès| OK["user + token dans l'ALS → contrôleur"]
 ```
 
-`Firewall.isSecure()` (`firewall.ts:705`) rattache la requête à une **zone** via
-`Firewall.matchPath()` (`firewall.ts:696`) ; `Firewall.handleSecurity()` (`firewall.ts:738`) décide.
+`Firewall.isSecure()` (`firewall.ts:728`) rattache la requête à une **zone** via
+`Firewall.matchPath()` (`firewall.ts:719`) ; `Firewall.handleSecurity()` (`firewall.ts:761`) décide.
 Les zones sont triées par **spécificité** dans `#build()` — `list.sort` par longueur de motif :
-le plus long gagne, pas le premier déclaré (`firewall.ts:191`).
+le plus long gagne, pas le premier déclaré (`firewall.ts:257`).
 
 ## 📖 Lexique
 
@@ -74,7 +74,7 @@ le plus long gagne, pas le premier déclaré (`firewall.ts:191`).
 ### Dans une app `nodefony create app`, le firewall est DÉJÀ actif
 
 Le scaffold déclare deux zones dans `nodefony.config.ts` — c'est la forme canonique (un **objet par
-nom**, validé Zod au boot : `areas: z.record(...)`, `config.ts:902`) :
+nom**, validé Zod au boot : `areas: z.record(...)`, `config.ts:1126-1127`) :
 
 ```typescript
 // nodefony.config.ts (extrait généré par `nodefony create app`)
@@ -203,9 +203,9 @@ Point commun de sécurité : **message d'échec uniforme** (`"Invalid token"` /
 Credential = l'**identifiant** posé dans le blob de session (jamais un secret).
 
 - **N'ouvre jamais la session lui-même** : il exige une session reprise portant un user
-  (`supports()`, `SessionAuthenticator.ts:43`). C'est `AuthFlow.login()` (BFF) qui ouvre et
+  (`supports()`, `SessionAuthenticator.ts:75`). C'est `AuthFlow.login()` (BFF) qui ouvre et
   régénère l'ID (anti-fixation).
-- **L'identité est re-résolue à CHAQUE requête** (`SessionAuthenticator.ts:70`) → rôles frais,
+- **L'identité est re-résolue à CHAQUE requête** (`SessionAuthenticator.ts:96`) → rôles frais,
   révocation et verrouillage effectifs immédiatement.
 - **Pas de `challenge()`** : session absente = 401 nu → le front redirige vers son écran de login
   (pas de popup Basic).
@@ -226,7 +226,7 @@ Credential = `Authorization: Basic base64(identifiant:motdepasse)` — RFC 7617,
 
 ### `jwt` — Bearer JWT signé, durci RFC 8725
 
-Credential = `Authorization: Bearer <jws>` de structure compacte `a.b.c` (`JwtAuthenticator.ts:14`).
+Credential = `Authorization: Bearer <jws>` de structure compacte `a.b.c` (`JwtAuthenticator.ts:21`).
 Réservé API service↔service / agents (le web reste sur la session). Access token **EdDSA** signé par
 le keystore du serveur. Défenses **dures**, prouvées en test (RFC 8725 JWT BCP), toutes dans
 `JwtAuthenticator.authenticate()` :
@@ -234,15 +234,15 @@ le keystore du serveur. Défenses **dures**, prouvées en test (RFC 8725 JWT BCP
 - **allowlist d'algorithmes** `["EdDSA"]` — l'algo n'est **jamais** choisi d'après l'en-tête du
   token ; `alg=none` rejeté (`JwtAuthenticator.ts:120`).
 - **clé par `kid` depuis le JWKS LOCAL** (`createLocalJWKSet`) — jamais `jku`/`jwk` de l'en-tête
-  (anti-injection de clé / SSRF, `JwtAuthenticator.ts:155`).
+  (anti-injection de clé / SSRF, `JwtAuthenticator.ts:174`).
 - **`aud` + `iss` obligatoires** + `typ:"at+jwt"` (un refresh présenté comme access est rejeté) +
-  exp/nbf (`JwtAuthenticator.ts:105-108`).
+  exp/nbf (`JwtAuthenticator.ts:119-124`).
 - **révocation** malgré l'auto-portage : denylist `jti` + `invalidBefore` par sujet
-  (`JwtAuthenticator.ts:122-132`).
+  (`JwtAuthenticator.ts:138-148`).
 - **sujet revérifié** à réception (`loadUserByIdentifier(sub)`) : compte disparu/inactif/verrouillé
-  = rejet (`JwtAuthenticator.ts:174-187`).
+  = rejet (`JwtAuthenticator.ts:190-201`).
 
-Le token promu porte `scopes`, `jti`, `claims` (`JwtAuthenticator.ts:162-172`).
+Le token promu porte `scopes`, `jti`, `claims` (`JwtAuthenticator.ts:178-188`).
 
 > [!WARNING]
 > Un JWT est **auto-porté** : sans état serveur il n'est **pas** révocable. C'est la denylist
@@ -251,20 +251,20 @@ Le token promu porte `scopes`, `jti`, `claims` (`JwtAuthenticator.ts:162-172`).
 
 ### `apikey` — clé d'API opaque (PAT), révocable
 
-Credential = `Authorization: Bearer <prefix>_…` (`ApiKeyAuthenticator.ts:67`). Contrairement au JWT,
+Credential = `Authorization: Bearer <prefix>_…` (`ApiKeyAuthenticator.ts:75-79`). Contrairement au JWT,
 c'est un **bearer opaque** : sa vérité vit côté serveur (`ITokenStore`) → **révocable immédiatement**.
 
 Défenses de `ApiKeyAuthenticator.authenticate()` :
 
 - **forme + CRC validés AVANT tout accès au store** — anti-DoS (`parseApiKey()`,
-  `ApiKeyAuthenticator.ts:98`) ;
-- lookup par **hash sha256** : le secret n'existe nulle part au repos (`:105`) ;
+  `ApiKeyAuthenticator.ts:103`) ;
+- lookup par **hash sha256** : le secret n'existe nulle part au repos (`ApiKeyAuthenticator.ts:109`) ;
 - révocation (`revokedAt`), expiration (`expiresAt`), **ban en masse** du porteur
-  (`invalidBefore` vs `createdAt`, `:117-120`) ;
-- **sujet revérifié** à chaque requête — rôles frais (`:122`) ;
-- `lastUsedAt` écrit en **throttlé** — pas une écriture par requête (`:127-134`).
+  (`invalidBefore` vs `createdAt`, `ApiKeyAuthenticator.ts:111-124`) ;
+- **sujet revérifié** à chaque requête — rôles frais (`ApiKeyAuthenticator.ts:127`) ;
+- `lastUsedAt` écrit en **throttlé** — pas une écriture par requête (`ApiKeyAuthenticator.ts:136-143`).
 
-Le token porte `scopes`, `apiKeyId`, `tenantId` (`:138-140`). `jwt` et `apikey` **cohabitent** dans
+Le token porte `scopes`, `apiKeyId`, `tenantId` (`ApiKeyAuthenticator.ts:147-149`). `jwt` et `apikey` **cohabitent** dans
 une zone : ils se discriminent par la forme (JWT = `a.b.c`, PAT = `prefix_…`).
 
 ### `anonymous` — accepter l'anonymat, explicitement
@@ -280,7 +280,7 @@ Sans lui, zone protégée + aucune preuve = 401.
 
 Il promeut en jeton realtime **toute** identité que le firewall a résolue — session BFF comme jeton
 porteur (JWT, clé d'API). **Enregistré automatiquement** par `Firewall.#wireRealtime()` au
-handshake des zones protégées `realtime` (`firewall.ts:289`).
+handshake des zones protégées `realtime` (`firewall.ts:279`).
 
 - **Perf : il ne relit pas la base.** Handshake et frames tournent dans la même bulle ALS —
   l'identité déjà posée est réutilisée, 2 lectures base économisées par connexion
@@ -320,7 +320,7 @@ laisser chercher pourquoi `context.session` est nul.
 ## ⚙️ Ordre et modes (`mode: "first"` vs `"all"`)
 
 La liste `area.authenticators` se lit **dans l'ordre**, déroulée par `Firewall.#authenticate()`
-(`firewall.ts:1112`). Le `mode` dit comment la parcourir. Trois situations concrètes :
+(`firewall.ts:1128`). Le `mode` dit comment la parcourir. Trois situations concrètes :
 
 ### Situation 1 — humains ET machines sur la même API (`first`, le mode courant)
 
@@ -373,11 +373,11 @@ danger: {
 
 Le client doit présenter **les deux preuves** dans la même requête (cookie + `Authorization:
 Basic …`). Une seule manque → 401. Le **dernier** token de la chaîne porte l'identité
-(`firewall.ts:936-939`) — ici la preuve mot de passe, la plus fraîche.
+(`firewall.ts:1199`) — ici la preuve mot de passe, la plus fraîche.
 
 > [!TIP]
 > Un nom d'authenticator inconnu en config **fait échouer le boot** —
-> `Firewall.#instantiateAuthenticators()` est fail-closed (`firewall.ts:429`) : jamais de zone
+> `Firewall.#instantiateAuthenticators()` est fail-closed (`firewall.ts:435`) : jamais de zone
 > « protégée » silencieusement ouverte à cause d'une faute de frappe.
 
 ## 🧑‍⚖️ Autorisation — rôles, scopes, voters (« as-tu le droit ? »)
@@ -513,11 +513,11 @@ scopes, métier), un même jury, combinables.
 
 ## 🔌 HTTP et WebSocket — le même firewall
 
-`Firewall.#wireRealtime()` (`firewall.ts:268`) câble, pour toute zone protégée `realtime !== false`
-(opt-out, `firewall.ts:277`), le `FirewallRealtimeAuthenticator` au handshake (`firewall.ts:289`)
-**et** un `frameAuthorizer` (RBAC par canal, `firewall.ts:337`). Même résolution de zone que HTTP.
+`Firewall.#wireRealtime()` (`firewall.ts:279`) câble, pour toute zone protégée `realtime !== false`
+(opt-out, `firewall.ts:277`), le `FirewallRealtimeAuthenticator` au handshake (`firewall.ts:300`)
+**et** un `frameAuthorizer` (RBAC par canal, `firewall.ts:348`). Même résolution de zone que HTTP.
 Sur une socket, un refus n'a pas d'en-tête `WWW-Authenticate` (`Firewall.#setChallenge()`,
-`firewall.ts:1191`) : le **code de fermeture** suffit.
+`firewall.ts:1216`) : le **code de fermeture** suffit.
 
 ## 🛡️ En-têtes de sécurité, CSRF, CORS
 
@@ -525,22 +525,22 @@ Sur une socket, un refus n'a pas d'en-tête `WWW-Authenticate` (`Firewall.#setCh
   au-dessus du socle transport de `@nodefony/http`. **Nonce CSP paresseux** (`hasNonce`, `firewall.ts:1045`) :
   alloué seulement si une directive en a besoin.
 - **`Firewall.enforceCsrf()`** (défense en profondeur, `firewall.ts:948`) : Fetch Metadata
-  (`Sec-Fetch-Site`) + garde `Origin` (`firewall.ts:764`), puis double-submit `x-csrf-token` ≡
+  (`Sec-Fetch-Site`) + garde `Origin` (`firewall.ts:971`), puis double-submit `x-csrf-token` ≡
   cookie + HMAC (`firewall.ts:778`).
-- **`Firewall.handleCors()`** : preflight `OPTIONS` → 204 (`firewall.ts:991`).
+- **`Firewall.handleCors()`** : preflight `OPTIONS` → 204 (`firewall.ts:1014`).
 
 ## 📜 Normes appliquées
 
 | Domaine                | Norme           | Ancrage                                                |
 | ---------------------- | --------------- | ------------------------------------------------------ |
-| Challenge d'auth (401) | RFC 7235        | `Firewall.#setChallenge()` (`firewall.ts:1207`)        |
+| Challenge d'auth (401) | RFC 7235        | `Firewall.#setChallenge()` (`firewall.ts:1216`)        |
 | Bearer                 | RFC 6750        | `JwtAuthenticator.ts:13` · `ApiKeyAuthenticator.ts:11` |
 | JWT (BCP)              | RFC 7519, 8725  | `JwtAuthenticator.ts:33-44,104-108`                    |
 | HTTP Basic             | RFC 7617        | `UserPasswordAuthenticator.ts:10-28`                   |
-| Rate limit (429)       | RFC 6585        | 429 + `Retry-After` (`firewall.ts:764`)                |
+| Rate limit (429)       | RFC 6585        | 429 + `Retry-After` (`firewall.ts:777-780`)            |
 | Backoff de login       | NIST SP 800-63B | `UserPasswordAuthenticator.ts:43-46,101-104`           |
 | CSRF                   | Fetch Metadata  | `Firewall.enforceCsrf()` (`firewall.ts:948`)           |
-| Modèle                 | Zero Trust      | `firewall.ts:611` (aucune preuve → 401)                |
+| Modèle                 | Zero Trust      | `firewall.ts:818-833` (aucune preuve → 401)            |
 
 ## ⚡ Performance & mémoire
 

package/docs/headers.md

@@ -122,8 +122,8 @@ fait l'inverse : **tout ce qui est constant est calculé une fois au démarrage*
   statique) et la **gèle** avec `Object.freeze` (`securityHeaders.ts:77`). Par requête, le firewall
   se contente de la parcourir et de la poser : zéro concaténation, zéro objet créé.
 - Côté transport, même principe : `HttpKernel.computeSecurityHeaderCaches()`
-  (`http-kernel.ts:330`) précalcule la chaîne HSTS (`max-age`, `includeSubDomains`, `preload`) au
-  boot ; `onHttpRequest` (`http-kernel.ts:819`) ne fait plus que trois `setHeader`.
+  (`http-kernel.ts:348`) précalcule la chaîne HSTS (`max-age`, `includeSubDomains`, `preload`) au
+  boot ; `onHttpRequest` (`http-kernel.ts:972`) ne fait plus que trois `setHeader`.
 - Le seul coût variable est le **nonce CSP**, et il est **paresseux** : `Context.cspNonce`
   (`Context.ts:253`) ne génère ses 128 bits (`randomBytes(16)` en base64) qu'à la première lecture,
   puis mémoïse. Une réponse qui n'a aucun script inline à signer ne paie aucun appel crypto.
@@ -173,7 +173,7 @@ export default defineConfig(() => ({
 ```
 
 Les clés sont **typées et auto-complétées** : le module augmente le registre `NodefonyModuleConfig`
-du core (`index.ts:28`), donc `use("@nodefony/security", …)` propose les clés **et** les valeurs
+du core (`index.ts:33`), donc `use("@nodefony/security", …)` propose les clés **et** les valeurs
 d'enum (`referrerPolicy`, `coop`, `corp`…). Une valeur hors enum casse le boot, pas la production.
 
 ### 2. Ce qu'on observe
@@ -255,7 +255,7 @@ Choisir en cinq secondes — puis le détail dans les cartes.
 **La menace** : n'importe quelle entrée non échappée (commentaire, nom d'utilisateur, paramètre
 réfléchi) devient un vecteur d'exécution de code. Le CSP est le filet quand l'échappement a raté.
 
-**Le défaut Nodefony** est délibérément « secure-but-usable » (`config.ts:218`) : seul `script-src`
+**Le défaut Nodefony** est délibérément « secure-but-usable » (`config.ts:238`) : seul `script-src`
 est **strict** — `'self'` plus le nonce de la requête, ce qui est la vraie défense XSS. Le reste
 couvre les besoins réels d'une app moderne (CSS-in-JS via `style-src 'unsafe-inline'`, images
 `data:`/`blob:`, workers, fetch/WS same-origin) et ajoute les durcissements gratuits :
@@ -275,8 +275,8 @@ privilégient `frame-ancestors`, `X-Frame-Options` reste le filet pour les ancie
 victime est capté par ton interface.
 
 Posé par le **transport** depuis un cache calculé au boot — `secFrameOptions`
-(`http-kernel.ts:270`) — et configuré côté `@nodefony/http` avec `frameOptions`
-(`http/nodefony/config/config.ts:121`), qui vaut `DENY` par défaut. `SAMEORIGIN` si ton propre site
+(`http-kernel.ts:989`) — et configuré côté `@nodefony/http` avec `frameOptions`
+(`http/nodefony/config/config.ts:136`), qui vaut `DENY` par défaut. `SAMEORIGIN` si ton propre site
 s'auto-encadre. C'est un des trois en-têtes que security **ne ré-émet pas** : il doit valoir aussi
 pour un HTML statique servi directement depuis `public/`.
 
@@ -287,7 +287,7 @@ pour un HTML statique servi directement depuis `public/`.
 avec tes cookies.
 
 Valeur unique reconnue : `nosniff`, posée depuis le cache `secContentTypeOptions`
-(`http-kernel.ts:963`). C'est **l'en-tête qui justifie le mieux la couche transport** : le danger
+(`http-kernel.ts:986`). C'est **l'en-tête qui justifie le mieux la couche transport** : le danger
 vient précisément des fichiers servis hors pipeline applicatif — un banc live le prouve sur une 404
 (`security-headers.test.ts:38`).
 
@@ -297,15 +297,15 @@ vient précisément des fichiers servis hors pipeline applicatif — un banc liv
 installer un intercepteur.
 
 La chaîne est assemblée au boot par `HttpKernel.computeSecurityHeaderCaches()`
-(`http-kernel.ts:330`) : `max-age`, puis `includeSubDomains` et `preload` selon la config.
+(`http-kernel.ts:348`) : `max-age`, puis `includeSubDomains` et `preload` selon la config.
 
 Elle n'est posée que **sur une réponse HTTPS ou HTTP/2** — le cache `secHsts` est conditionné au type
-de serveur (`http-kernel.ts:965`). C'est conforme à la RFC 6797, qui veut qu'un HSTS reçu en clair
+de serveur (`http-kernel.ts:992`). C'est conforme à la RFC 6797, qui veut qu'un HSTS reçu en clair
 soit ignoré : l'émettre sur du HTTP simple ne ferait que polluer. Défaut : un an, sous-domaines
 inclus.
 
 > [!CAUTION]
-> `preload: true` (`http/nodefony/config/config.ts:92`) inscrit ton domaine dans la liste
+> `preload: true` (`http/nodefony/config/config.ts:107`) inscrit ton domaine dans la liste
 > pré-chargée des navigateurs. C'est un **engagement quasi irréversible** : tout sous-domaine
 > incapable de servir en HTTPS devient inaccessible, et la sortie de liste prend des mois. À ne
 > jamais activer « pour voir ».
@@ -315,7 +315,7 @@ inclus.
 **La menace** : la fuite d'URL. Chemins parlants, identifiants de session dans une query, jetons de
 réinitialisation — tout part chez le site suivant via le `Referer`.
 
-Défaut Nodefony : `no-referrer` (`security/nodefony/config/config.ts:263`), la valeur la plus stricte. La valeur est un
+Défaut Nodefony : `no-referrer` (`security/nodefony/config/config.ts:278`), la valeur la plus stricte. La valeur est un
 **enum W3C fermé** — huit valeurs validées au boot, donc pas de faute de frappe qui passerait en
 silence (l'écriture libre `no-refferer` casserait la protection sans prévenir).
 
@@ -379,7 +379,7 @@ config security est la première source de confusion sur ce sujet.
 
 ### Couche applicative — `use("@nodefony/security", { headers })`
 
-Dérivé du schéma Zod `headersSchema` (`config.ts:194`).
+Dérivé du schéma Zod `headersSchema` (`config.ts:206`).
 
 <!-- prettier-ignore -->
 | Option | Type | Défaut | Effet |
@@ -396,8 +396,8 @@ Dérivé du schéma Zod `headersSchema` (`config.ts:194`).
 
 ### Socle transport — `use("@nodefony/http", { securityHeaders })`
 
-Dérivé de `securityHeadersSchema` (`http/nodefony/config/config.ts:108`). Ces trois réglages sont
-**éditables à chaud** (`runtimeMutable`) : `HttpKernel.onConfigChanged()` (`http-kernel.ts:290`)
+Dérivé de `securityHeadersSchema` (`http/nodefony/config/config.ts:123`). Ces trois réglages sont
+**éditables à chaud** (`runtimeMutable`) : `HttpKernel.onConfigChanged()` (`http-kernel.ts:398`)
 recalcule les caches, donc la valeur suivante s'applique sans redémarrage.
 
 | Option                                      | Type              | Défaut     | Effet                                                              |
@@ -411,10 +411,10 @@ recalcule les caches, donc la valeur suivante s'applique sans redémarrage.
 
 > [!WARNING]
 > Les clés `hsts`, `hstsMaxAgeS`, `frameguard` et `noSniff` **existent** dans la config security
-> (`config.ts:200`, `config.ts:227`, `config.ts:233`) mais **ne pilotent rien** : la couche
+> (`config.ts:257`, `config.ts:257`, `config.ts:257`, `config.ts:257`) mais **ne pilotent rien** : la couche
 > applicative ne les lit pas (`securityHeaders.ts:6`), elles ne servent qu'à l'introspection
 > affichée dans Studio. Pour changer réellement `X-Frame-Options`, c'est `securityHeaders.frameOptions`
-> **du module http**. Même remarque pour `hidePoweredBy` (`config.ts:254`) : Nodefony n'émet aucun
+> **du module http**. Même remarque pour `hidePoweredBy` (`config.ts:282`) : Nodefony n'émet aucun
 > `X-Powered-By`, l'option est un no-op documenté.
 
 ## 🏗️ Le CSP en détail — deux régimes, trois façons de l'étendre
@@ -439,7 +439,7 @@ Le chemin complet, sans surprise :
 
 1. **Au boot**, la chaîne CSP est **pré-découpée** autour de `{{nonce}}` (`securityHeaders.ts:58`).
    Aucun parsing ni regex n'aura lieu pendant une requête.
-2. **Par requête**, `Firewall.applySecurityHeaders()` (`firewall.ts:835`) lit `context.cspNonce` —
+2. **Par requête**, `Firewall.applySecurityHeaders()` (`firewall.ts:1045`) lit `context.cspNonce` —
    ce qui **génère** le jeton à cet instant (`Context.ts:253`) — puis appelle
    `SecurityHeaders.cspFor()` (`securityHeaders.ts:100`) : un seul `join`.
 3. **Dans la vue**, le contrôleur relit `context.cspNonce`, qui est **mémoïsé** : l'en-tête et le
@@ -452,7 +452,7 @@ rester imprévisible, jamais pilotable par le client — contrairement au `reque
 une corrélation entrante.
 
 **Placement dans le pipeline** : `applySecurityHeaders` est appelé **après le resolve** et **avant**
-le repli statique et le `writeHead` (`http-kernel.ts:1372`). Cet ordre n'est pas cosmétique : il
+le repli statique et le `writeHead` (`http-kernel.ts:1386`). Cet ordre n'est pas cosmétique : il
 faut que le routeur ait posé les directives `@Csp` de la route pour pouvoir les fusionner, et il faut
 être avant l'écriture des en-têtes pour pouvoir en poser.
 
@@ -476,7 +476,7 @@ directive absente est ajoutée en fin. La fonction est **pure et déterministe**
 les tests fiables.
 
 **Coût** : le merge d'un module est payé **une fois**, au (dés)enregistrement
-(`Firewall.#rebuildSecurityHeaders()`, `firewall.ts:1085`), jamais par requête. Le merge d'une route
+(`Firewall.#rebuildSecurityHeaders()`, `firewall.ts:1101`), jamais par requête. Le merge d'une route
 `@Csp` est payé **uniquement sur les routes décorées** (`SecurityHeaders.cspForExtra()`,
 `securityHeaders.ts:115`) ; le cas courant reste le simple `join`.
 
@@ -502,15 +502,15 @@ Trois propriétés à retenir :
 
 - **Aucun couplage** : la résolution par nom de service évite un cycle de dépendances, et
   `registerCspOrigins` est optionnel — un module fonctionne dans une app **sans** security.
-- **Réversible** : `Firewall.unregisterCspOrigins()` (`firewall.ts:1074`) retire le fragment et
+- **Réversible** : `Firewall.unregisterCspOrigins()` (`firewall.ts:1099`) retire le fragment et
   reconstruit le CSP de base. C'est ce que fait `@nodefony/frontend` à l'arrêt du serveur Vite.
 - **Idempotent** : la reconstruction repart **toujours** du `headers.csp` d'origine
-  (`firewall.ts:1088`), jamais d'un CSP déjà fusionné — pas d'accumulation entre deux
+  (`firewall.ts:1113`), jamais d'un CSP déjà fusionné — pas d'accumulation entre deux
   enregistrements.
 
 L'exemple de référence vit dans le framework : en développement, `@nodefony/frontend` déclare les
 origines du serveur Vite et `'unsafe-eval'` (exigé par le Fast Refresh de React) via
-`FrontendService.#viteCspFragment()` (`FrontendService.ts:1012`) — ce qui explique qu'un CSP observé
+`FrontendService.#viteCspFragment()` (`FrontendService.ts:1034`) — ce qui explique qu'un CSP observé
 en dev soit plus large qu'en production, où ce fragment n'existe pas.
 
 ## 📜 Normes appliquées
@@ -519,12 +519,12 @@ en dev soit plus large qu'en production, où ce fragment n'existe pas.
 | ------------------------------------ | -------------------------------- | ------------------------------------------------------------ |
 | Politique de sécurité du contenu     | W3C CSP Level 3                  | `mergeCspFragments()` (`csp.ts:56`), directive non dupliquée |
 | Nonce CSP (unicité, imprévisibilité) | W3C CSP Level 3 §6.7.4           | `Context.cspNonce` — 128 bits CSPRNG (`Context.ts:253`)      |
-| HSTS                                 | RFC 6797                         | posé sur TLS uniquement (`http-kernel.ts:839`)               |
+| HSTS                                 | RFC 6797                         | posé sur TLS uniquement (`http-kernel.ts:969`)               |
 | Champ structuré booléen              | RFC 8941                         | `Origin-Agent-Cluster: ?1` (`securityHeaders.ts:75`)         |
-| Referrer-Policy                      | W3C Referrer Policy (enum fermé) | 8 valeurs validées au boot (`config.ts:239`)                 |
+| Referrer-Policy                      | W3C Referrer Policy (enum fermé) | 8 valeurs validées au boot (`config.ts:267`)                 |
 | Isolation cross-origin               | WHATWG HTML (COOP/COEP/CORP)     | `securityHeaders.ts:71`                                      |
-| Anti-MIME-sniffing                   | WHATWG Fetch (`nosniff`)         | `secContentTypeOptions` (`http-kernel.ts:963`)               |
-| Durcissement en-têtes                | OWASP Secure Headers             | `computeSecurityHeaderCaches()` (`http-kernel.ts:330`)       |
+| Anti-MIME-sniffing                   | WHATWG Fetch (`nosniff`)         | `secContentTypeOptions` (`http-kernel.ts:986`)               |
+| Durcissement en-têtes                | OWASP Secure Headers             | `computeSecurityHeaderCaches()` (`http-kernel.ts:348`)       |
 
 ## ⚡ Performance & mémoire
 
@@ -538,7 +538,7 @@ Le coût est concentré au boot, par construction :
   court-circuite entièrement ce chemin sinon. La paresse de `Context.cspNonce` (`Context.ts:253`)
   protège en plus les chemins internes qui n'atteignent jamais le firewall.
 - **Merge CSP** : jamais dans le chemin chaud. Le fragment d'un module est fusionné à
-  l'enregistrement (`firewall.ts:1067`) ; celui d'une route ne coûte que sur les routes `@Csp`.
+  l'enregistrement (`firewall.ts:1086`) ; celui d'une route ne coûte que sur les routes `@Csp`.
 - **Socle transport** : trois `setHeader` sur des chaînes précalculées (`http-kernel.ts:958-966`), avec
   un test `!== null` qui annule le coût des en-têtes désactivés.
 
@@ -550,7 +550,7 @@ dans le périmètre du gate mémoire, qu'il ne peut structurellement pas dégrad
 L'écran **Firewall** de Studio affiche la section « En-têtes de sécurité » — pilotée par
 `headers.enabled` (`FirewallDefenses.tsx:219`) — avec le CSP effectif, l'état du nonce par requête, la
 Referrer-Policy et les valeurs d'isolation. Les données
-viennent de `Firewall.describe()` (`firewall.ts:549`), qui projette la config **sans aucun secret**,
+viennent de `Firewall.describe()` (`firewall.ts:555`), qui projette la config **sans aucun secret**,
 exposée par `GET /nodefony/security/api/firewall`.
 
 L'onglet **Configuration** de Studio rend les mêmes options depuis le schéma Zod — chaque champ y
@@ -570,7 +570,7 @@ porte sa description, ce qui en fait la référence toujours à jour des défaut
 | CSP contenant `'nonce-{{nonce}}'` littéral               | `cspNonces` désactivé, placeholder laissé                                   | Nodefony purge le résiduel (`securityHeaders.ts:63`) ; retirer le placeholder   |
 | Une extension `script-src` de module sans effet          | Second en-tête / directive dupliquée (ignorée, W3C CSP3 §3)                 | Déclarer un fragment via `registerCspOrigins()`, jamais un `setHeader`          |
 | Assets tiers cassés après activation de l'isolation      | `coep: "require-corp"` exige CORP/CORS sur **chaque** ressource             | Retirer `coep` ou faire annoncer les ressources                                 |
-| HSTS absent en développement                             | Posé sur TLS uniquement (`http-kernel.ts:839`)                              | Comportement conforme RFC 6797 — vérifier sur le port HTTPS                     |
+| HSTS absent en développement                             | Posé sur TLS uniquement (`http-kernel.ts:969`)                              | Comportement conforme RFC 6797 — vérifier sur le port HTTPS                     |
 | Le CSP est plus large en dev qu'en prod                  | `@nodefony/frontend` déclare les origines Vite (`FrontendService.ts:695`)   | Attendu : le fragment n'existe pas en production                                |
 | Aucun en-tête applicatif                                 | Module security absent ou `headers.enabled: false`                          | Le socle transport reste actif ; réactiver security pour CSP/Referrer/isolation |
 | Domaine injoignable après activation de `preload`        | Inscription à la liste pré-chargée, sortie très lente                       | Ne jamais activer sans plan HTTPS sur **tous** les sous-domaines                |

package/docs/index.md

@@ -126,7 +126,9 @@ flowchart LR
 ```
 
 Le module consomme `@nodefony/user` (jamais l'inverse) et n'importe `@nodefony/http` / `framework`
-qu'en **type-only** — le couplage runtime resterait une dette.
+qu'en **type-only**, à une exception près : `schemaMismatchOf` (`webhooks.ts:49`), importé de
+`@nodefony/http` pour reconnaître une base au schéma en retard avec la même règle que le cœur HTTP,
+plutôt qu'avec une copie.
 
 ## 🧰 Surface publique