@nodefony/security 10.0.0-beta.1 → 10.0.0-beta.2

package/README.md

@@ -25,7 +25,7 @@ Consomme [`@nodefony/user`](https://www.npmjs.com/package/@nodefony/user).
   (cookie opaque BFF, révocable, `HttpOnly; Secure; SameSite`) ; les **API/agents** portent leur
   preuve à chaque requête (**JWT** signé / clé API). Jamais « full stateless » : la session reste
   la fondation web (révocation immédiate), le JWT est réservé au sans-état machine-à-machine.
-- **Config type-safe** : schéma **Zod** (18 sections, tout `enabled`), **introspectable** (Studio
+- **Config type-safe** : schéma **Zod** (19 sections, la plupart désactivables par `enabled`), **introspectable** (Studio
   génère son formulaire d'édition). L'app configure via `use("@nodefony/security", { … })`.
 - **En-têtes natifs** (sans la lib `helmet`) — 0 dépendance, nonce CSP par requête.
 
@@ -67,7 +67,8 @@ export default defineConfig((ctx) => ({
 
 > Une zone se déclare idéalement **par module** (override `module-security`, dans la config du
 > module) pour vivre au plus près de ses routes. Authenticators fournis : `anonymous`, `session`,
-> `userpassword`, `jwt`, `apikey`, `webauthn`, plus les providers OAuth2. La chaîne est validée
+> `userpassword`, `jwt`, `external-jwt`, `apikey`. WebAuthn, OAuth2 et TOTP n'en sont pas : ils
+> ouvrent une session BFF, que l'authenticator `session` identifie ensuite. La chaîne est validée
 > au boot (`mode: "first"` par défaut = le premier qui reconnaît authentifie ; `"all"` = tous
 > requis, ex. mTLS + JWT). Config invalide → firewall **fail-closed** (tout rejeté).
 
@@ -117,7 +118,7 @@ csrf: {
 > ouvrir la lecture CORS des réponses au JavaScript tiers. Une origine listée dans `cors.origins` est
 > toutefois aussi acceptée (ce que CORS autorise explicitement n'est pas du CSRF).
 
-Le token synchronizer renforcé (`@CsrfProtect` / `@CsrfExempt`) arrive à l'étape suivante.
+Le token synchronizer renforcé s'active par route avec `@CsrfProtect` ; `@CsrfExempt` en exclut une route.
 
 ### CORS — l'inverse du CSRF
 
@@ -141,8 +142,9 @@ const schema = securityConfigJsonSchema(); // JSON Schema → formulaire d'édit
 ## Journal d'audit (événements de sécurité)
 
 Le journal trace les **transitions d'état** de sécurité (login, refus, jeton émis/révoqué, verrou
-WS) — distinct du log de trafic (1 PDU/requête). Émission **explicite** par point sensible ; le
-**chemin de succès reste muet** (le volume n'est pas un signal), seul l'échec/refus émet (cold-path)
+WS) — distinct du log de trafic (1 PDU/requête). Émission **explicite** par point sensible, sur les
+chemins froids (login, logout, émission ou révocation de jeton, refus) ; jamais par requête nominale :
+le trafic courant ne passe pas par l'audit (cold-path)
 → aucun coût ajouté au hot-path nominal. Activé par défaut (`audit.enabled`, OWASP A09), coût nul si
 désactivé. Lecture : `GET /nodefony/security/api/audit/events` (RBAC `ROLE_NODEFONY_ADMIN`).
 

package/dist/_virtual/{_@oxc-project_runtime@0.151.0 → _@oxc-project_runtime@0.152.0}/helpers/esm/decorate.js

@@ -1,4 +1,4 @@
-//#region \0@oxc-project+runtime@0.151.0/helpers/esm/decorate.js
+//#region \0@oxc-project+runtime@0.152.0/helpers/esm/decorate.js
 function __decorate(decorators, target, key, desc) {
 	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
 	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);

package/dist/_virtual/{_@oxc-project_runtime@0.151.0 → _@oxc-project_runtime@0.152.0}/helpers/esm/decorateMetadata.js

@@ -1,4 +1,4 @@
-//#region \0@oxc-project+runtime@0.151.0/helpers/esm/decorateMetadata.js
+//#region \0@oxc-project+runtime@0.152.0/helpers/esm/decorateMetadata.js
 function __decorateMetadata(k, v) {
 	if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }

package/dist/index.js

@@ -77,8 +77,8 @@ import SecurityUserPassword from "./nodefony/command/security-user-password.js";
 import SecurityToken from "./nodefony/command/security-token.js";
 import { createSecurityAdminApi, parseAuditQuery, registerSecurityAdminApi } from "./nodefony/src/admin/SecurityAdminApi.js";
 import { registerUserRevocationCascade } from "./nodefony/src/admin/userRevocationCascade.js";
-import __decorateMetadata from "./_virtual/_@oxc-project_runtime@0.151.0/helpers/esm/decorateMetadata.js";
-import __decorate from "./_virtual/_@oxc-project_runtime@0.151.0/helpers/esm/decorate.js";
+import __decorateMetadata from "./_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorateMetadata.js";
+import __decorate from "./_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorate.js";
 import { tokenStatusCriteria } from "./nodefony/src/token/tokenCriteria.js";
 import { AccessDeniedError } from "./nodefony/errors/AccessDeniedError.js";
 import "./nodefony/errors/index.js";

package/dist/nodefony/service/securityHeaders.js

@@ -20,6 +20,8 @@ const NONCE_PLACEHOLDER = "{{nonce}}";
 var SecurityHeaders = class {
 	#headers;
 	#cspParts;
+	#cspPrefix;
+	#cspSuffix;
 	#cspRaw;
 	constructor(o) {
 		const h = {};
@@ -39,6 +41,13 @@ var SecurityHeaders = class {
 		if (o.permissionsPolicy) h["Permissions-Policy"] = o.permissionsPolicy;
 		this.#headers = Object.freeze(h);
 		this.#cspParts = cspParts ? Object.freeze(cspParts) : null;
+		if (cspParts?.length === 2) {
+			this.#cspPrefix = cspParts[0] ?? "";
+			this.#cspSuffix = cspParts[1] ?? "";
+		} else {
+			this.#cspPrefix = null;
+			this.#cspSuffix = "";
+		}
 		this.#cspRaw = o.csp;
 	}
 	/** Table d'en-têtes applicatifs CONSTANTS (figée), posée telle quelle par le firewall. */
@@ -51,13 +60,15 @@ var SecurityHeaders = class {
 	}
 	/**
 	* Recompose le CSP en injectant le `nonce` de la requête aux emplacements
-	* `{{nonce}}`. 1 `join` (segments pré-split au boot). Le nonce est base64 (jamais
+	* `{{nonce}}` : une concaténation s'il n'y en a qu'un, un `join` sinon (segments
+	* pré-split au boot). Le nonce est base64 (jamais
 	* `'`/`;`/espace) → aucune évasion possible du token CSP.
 	*
 	* @param nonce - nonce base64 de la requête (`Context.cspNonce`).
 	* @returns la valeur `Content-Security-Policy` à poser sur la réponse.
 	*/
 	cspFor(nonce) {
+		if (this.#cspPrefix !== null) return this.#cspPrefix + nonce + this.#cspSuffix;
 		return this.#cspParts.join(nonce);
 	}
 	/**

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

@@ -43,7 +43,8 @@ export declare class SecurityHeaders {
     get hasNonce(): boolean;
     /**
      * Recompose le CSP en injectant le `nonce` de la requête aux emplacements
-     * `{{nonce}}`. 1 `join` (segments pré-split au boot). Le nonce est base64 (jamais
+     * `{{nonce}}` : une concaténation s'il n'y en a qu'un, un `join` sinon (segments
+     * pré-split au boot). Le nonce est base64 (jamais
      * `'`/`;`/espace) → aucune évasion possible du token CSP.
      *
      * @param nonce - nonce base64 de la requête (`Context.cspNonce`).

package/docs/api-keys.md

@@ -137,7 +137,7 @@ protégerait que des secrets faibles, et coûterait sur le chemin chaud.
 
 ### 1. Déclarer la zone machine et les règles d'émission
 
-Dans une app générée par `nodefony create app`, tout se déclare dans `nodefony.config.ts`. Une zone
+Dans une app générée par `nodefony create app`, tout se déclare dans la config du module — `nodefony/config/security.ts`, importé par `nodefony.config.ts`. Une zone
 dont les authenticators contiennent `apikey` exige un `Authorization: Bearer nf_…` valide :
 
 ```typescript

package/docs/audit.md

@@ -135,7 +135,8 @@ lourds s'enregistrent depuis **leur** module. Un
 ## 🚀 Démarrage rapide
 
 Dans une app générée par `nodefony create app`, l'audit est **déjà actif** (`enabled: true` par
-défaut, `config.ts:729`) sur un store mémoire. Voici le parcours complet : configurer, émettre,
+défaut, `config.ts:729`) sur le store que résout `auto` : la base SQLite locale de l'application
+générée, la mémoire seulement si aucun ORM n'est chargé. Voici le parcours complet : configurer, émettre,
 relire.
 
 ### 1. Choisir où le journal est écrit
@@ -265,7 +266,7 @@ Les critères se **combinent en ET** et sont traduits par `parseAuditQuery()`
 | `requestId` | tous les événements d'**une seule requête**     | `requestId=req-7c1e`        |
 | `since`     | borne basse d'horodatage, epoch ms **inclus**   | `since=1763503200000`       |
 | `until`     | borne haute d'horodatage, epoch ms **inclus**   | `until=1763524800000`       |
-| `limit`     | taille de page (défaut 100, **plafonné à 500**) | `limit=200`                 |
+| `limit`     | taille de page (défaut 100, **plafonné à 200**) | `limit=200`                 |
 | `cursor`    | le `nextCursor` de la page précédente           | `cursor=1763548800123:9f-1` |
 
 ```bash
@@ -496,7 +497,7 @@ Table dérivée du schéma Zod `auditSchema` (`config.ts:883`), rattaché à la
 | Option          | Type      | Défaut   | Effet                                                                                |
 | --------------- | --------- | -------- | ------------------------------------------------------------------------------------ |
 | `enabled`       | `boolean` | `true`   | `false` → `record()` no-op à coût nul, `listPage()` page vide, endpoint admin en 503 |
-| `store`         | `string`  | `"auto"` | nom résolu par le registre : `auto`, `memory`, `drizzle`                             |
+| `store`         | `string`  | `"auto"` | nom résolu par le registre : `auto`, `memory`, `drizzle`, `mongoose`                 |
 | `retentionDays` | `number`  | `365`    | fenêtre de conservation ; au-delà, la purge horaire supprime                         |
 | `immutable`     | `boolean` | `true`   | déclaré au schéma — voir l'avertissement ci-dessous                                  |
 | `stream`        | `boolean` | `true`   | déclaré au schéma — voir l'avertissement ci-dessous                                  |
@@ -514,7 +515,8 @@ enregistrés (`auditService.ts:96`, logique `resolveAutoStore()` dans `infra.ts:
 
 1. `NF_STORE` posée et le backend est enregistré pour l'audit → il gagne (levier de banc de charge) ;
 2. sinon, une base est déclarée (`NF_DATABASE_URL`) → `drizzle`, ou `mongoose` selon la famille ;
-3. sinon, repli **annoncé** sur `memory` — la décision est loggée en INFO, jamais silencieuse.
+3. sinon, un backend local persistant réellement chargé (`drizzle` = SQLite, puis `mongoose`) ;
+4. sinon, repli **annoncé** sur `memory` (volatil) — la décision est loggée en INFO, jamais silencieuse.
 
 La résolution finale est publiée au kernel (`auditService.ts:145`), ce qui alimente l'écran des stores
 de Studio : configuré, résolu, disponible, motif, emplacement physique.
@@ -702,10 +704,10 @@ webhook. Détail des souscriptions, de la signature et des relivraisons → [web
 | Journal vide après un redémarrage                   | Store `memory` : volatile et per-pod (`MemoryAuditStore.ts:37`)   | `audit.store: "drizzle"` (ou déclarer `NF_DATABASE_URL`)   |
 | Un pod voit des événements, l'autre non             | Store `memory` non partagé                                        | Store durable partagé                                      |
 | Le boot échoue en production sur l'audit            | Store **explicite** inconnu, fail-closed (`auditService.ts:115`)  | Corriger le nom, ou charger l'adapter qui l'enregistre     |
-| `limit=5000` ne rend que 500 événements             | Plafond du store (`MemoryAuditStore.ts:12`)                       | Paginer avec `nextCursor`, jamais gonfler `limit`          |
+| `limit=5000` ne rend que 200 événements             | Plafond de l'endpoint (`parsePageQuery`, `pageQuery.ts:77`)       | Paginer avec `nextCursor`, jamais gonfler `limit`          |
 | La page 2 répète ou saute des événements            | Pagination réimplémentée en offset                                | Repasser le `nextCursor` reçu — le curseur est opaque      |
-| Filtre `?category=authen` sans effet                | Catégorie inconnue **ignorée** (`SecurityAdminApi.ts:191`)        | Utiliser une valeur de l'union (`auth`, `authz`, `token`…) |
-| Le paramètre `q` ne filtre rien                     | Non appliqué sur ce journal (`IAuditStore.ts:20`)                 | Filtrer par `category`/`actor`/`action`/`requestId`        |
+| `?category=authen` renvoie 400                      | Valeur hors union refusée (`PageQueryError`)                      | Utiliser une valeur de l'union (`auth`, `authz`, `token`…) |
+| Le paramètre `q` renvoie 400                        | Recherche plein texte non supportée sur ce journal                | Filtrer par `category`/`actor`/`action`/`requestId`        |
 | `stream: false` ne coupe pas le live                | Drapeau non lu ; le live suit `#listeners` (`auditService.ts:55`) | Retirer le rôle admin, ou ne pas exposer le canal          |
 | Trous dans le journal pendant une panne de base     | Écriture best-effort (`auditService.ts:199`)                      | Store à haute disponibilité si la conformité l'exige       |
 | Aucun `login.success` alors que les logins marchent | Le succès du **firewall** est muet ; `login.success` vient du BFF | Filtrer `action=login.success`, pas `category=auth` seul   |

package/docs/authenticators.md

@@ -185,7 +185,7 @@ curl -si http://localhost:5151/api/v1/whoami | grep -E "^(HTTP|WWW)"
 
 # 2) Web — login BFF (compte dev seedé admin/nodefony-dev-42) → cookie de session
 curl -si -c /tmp/jar -H 'Content-Type: application/json' \
-  -d '{"username":"admin","password":"admin"}' \
+  -d '{"username":"admin","password":"nodefony-dev-42"}' \
   http://localhost:5151/nodefony/security/api/auth/login | head -1
 # HTTP/1.1 200 OK
 
@@ -349,7 +349,7 @@ l'ALS. `FirewallRealtimeAuthenticator.supports()` ne fait que le constater
 
 > [!NOTE]
 > **Asymétrie de révocation HTTP↔WS (assumée)** : le jeton realtime est figé au handshake (les
-> frames lisent un cache O(1)) → une révocation prend effet **à la reconnexion**, pas à la frame
+> frames lisent un cache O(1)) → une révocation prend effet **en une fenêtre** (tick du hub, et devant chaque `api.request`), pas à la frame
 > suivante. C'est l'état de l'art (Socket.IO/Phoenix figent aussi au handshake) ; la révocation
 > immédiate forte passe par le JWT + un canal « token révoqué ».
 

package/docs/authorization.md

@@ -331,7 +331,7 @@ Dès le `DENY`, le jury **s'arrête** — court-circuit, inutile de finir (`auth
 
 **Contre-exemple piégeux** : le veto ne traverse **pas** une clause OR. Dans
 `@IsGranted(["ROLE_ADMIN", "doc.edit"])`, chaque attribut est un **jury séparé**
-(`Resolver.ts:700-715`) : si `ROLE_ADMIN` est accordé, `doc.edit` — et son veto — n'est même pas
+(`Resolver.ts:878-885`) : si `ROLE_ADMIN` est accordé, `doc.edit` — et son veto — n'est même pas
 consulté. Un interdit absolu se porte en clause **AND** : empiler `@IsGranted("ROLE_ADMIN")` puis
 `@IsGranted("doc.edit", { subject: "id" })`.
 
@@ -364,16 +364,16 @@ moteur `authorization` est résolu **par nom** au runtime (`Resolver.ts:673-674`
 | `@IsGranted(["A", "B"])`                    | **OR interne** — un attribut accordé suffit (`SecurityClause.anyOf`, `routerDecorators.ts:424-433`)                              |
 | empiler `@IsGranted` / `@RequireScope`      | **AND** — toutes les clauses doivent passer (`SecurityRequirement.clauses`, `routerDecorators.ts:1579`)                          |
 | décorateur de classe + de méthode           | fusion en **AND**, figée UNE fois par route (`computeSecurityRequirement()`, `routerDecorators.ts:1544`)                         |
-| `@IsGranted("doc.edit", { subject: "id" })` | le param de route `id` est passé au voter (`Resolver._resolveSubject()`, `Resolver.ts:789`)                                      |
+| `@IsGranted("doc.edit", { subject: "id" })` | le param de route `id` est passé au voter (`Resolver._resolveSubject()`, `Resolver.ts:923`)                                      |
 | `@RequireScope("orders:read")`              | axe scope — metadata dédiée, fusionnée dans le même `SecurityRequirement` (`RequireScope()`, `routerDecorators.ts:1002`)         |
 | `@Anonymous()`                              | action **publique** — override les gardes de classe (`security: null`) + skip l'authn (`Anonymous()`, `routerDecorators.ts:953`) |
 | `@CurrentUser()`                            | injecte l'utilisateur de l'ALS — jamais le credential (`CurrentUser`, `routerDecorators.ts:1283`)                                |
 
 La garde s'évalue dans `Resolver.executeAction()` **AVANT** l'instanciation DI du controller — un
-403 court-circuite tout, y compris `initialize()` (`_enforceSecurity`, `Resolver.ts:406-408`). Le
+403 court-circuite tout, y compris `initialize()` (`_enforceSecurity`, `Resolver.ts:489-491`). Le
 même `executeAction` sert le pipeline HTTP **et** l'invoke WS-RPC : une garde, tous les
 transports. L'enforcement déroule chaque clause : OR interne via un `decide()` par attribut, AND
-entre clauses (`Resolver._enforceSecurity()`, `Resolver.ts:719`).
+entre clauses (`Resolver._enforceSecurity()`, `Resolver.ts:853`).
 
 > [!IMPORTANT]
 > **Fail-closed intégral** : route gardée mais moteur `authorization` absent (module security non
@@ -511,7 +511,7 @@ compilation** — rien à scanner au runtime ; le registre **est** le marqueur e
 
 ## 🔌 HTTP et WebSocket — une garde, N transports
 
-- **La même garde** : `Resolver.executeAction()` (`Resolver.ts:372`) est le point unique
+- **La même garde** : `Resolver.executeAction()` (`Resolver.ts:446`) est le point unique
   d'enforcement — pipeline HTTP classique **et** invoke WS-RPC (pont `api.request`). Un
   `@IsGranted` protège donc l'action quel que soit le transport (prouvé bout en bout par le banc
   `ws-isgranted-jwt`).
@@ -541,7 +541,7 @@ compilation** — rien à scanner au runtime ; le registre **est** le marqueur e
 ## ⚡ Performance & mémoire
 
 - **Hot path à coût nul** : une route non gardée porte `security: null` → 0 lookup, 0 await, 0
-  alloc (`Resolver.ts:406`) ; l'exigence est **figée une fois** par route et partagée entre
+  alloc (`Resolver.ts:486`) ; l'exigence est **figée une fois** par route et partagée entre
   requêtes (`SecurityRequirement`, `routerDecorators.ts:444`).
 - **`decide()` sans allocation** : itération en place des voters (`authorization.ts:70-72`),
   instanciés **une seule fois** au boot (`authorization.ts:70`).

package/docs/cors.md

@@ -134,7 +134,7 @@ chaque appel du front.
 ### 1. La config — dans `nodefony.config.ts`
 
 ```typescript
-// nodefony.config.ts (extrait généré par `nodefony create app`, puis complété)
+// nodefony/config/security.ts (extrait généré par `nodefony create app`, puis complété)
 use("@nodefony/security", {
   cors: {
     // Allowlist EXACTE : scheme + host + port. Un sous-domaine n'est PAS inclus.
@@ -323,7 +323,7 @@ sequenceDiagram
 ```
 
 `Firewall.handleCors()` (`firewall.ts:1007`) est appelé **en tête de** `HttpKernel.handleHttp()`
-(`http-kernel.ts:1333`), à la ligne `http-kernel.ts:1333` — **avant le routing**. La raison est
+(`http-kernel.ts:1456`), à la ligne `http-kernel.ts:1456` — **avant le routing**. La raison est
 concrète : un preflight `OPTIONS /api/articles` n'a **pas de route déclarée** ; s'il traversait le
 router, il repartirait en 405. Et selon le Fetch Standard, un preflight ne transporte jamais de
 credentials — il ne doit donc ni s'authentifier, ni exécuter le moindre code applicatif.
@@ -354,7 +354,7 @@ Deux nuances utiles :
   `Access-Control-Request-Headers` du client (`cors.ts:78`). Ce que tu déclares est ce qui est annoncé,
   point. Un en-tête custom non déclaré fait échouer le preflight côté navigateur.
 - **Les fichiers statiques sont couverts.** `handleCors` s'exécute avant le fallback `serve-static`
-  (`http-kernel.ts:1382`) : une police ou une image servie cross-origin reçoit les mêmes en-têtes que
+  (`http-kernel.ts:1630`) : une police ou une image servie cross-origin reçoit les mêmes en-têtes que
   tes routes.
 
 Le contrat est publié dans l'interface du firewall (`IFirewall.ts:35`) : `number | undefined` — `204`

package/docs/csrf.md

@@ -93,7 +93,7 @@ contrôleur** : l'attaque meurt sans avoir touché ton code.
 - **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: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:1524`) arrive **après** le
+  branchée dans le pipeline HTTP — l'appel `enforceCsrf` (`http-kernel.ts:1747`) 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 —
@@ -315,7 +315,7 @@ de session (TSDoc `CsrfTokenManager`, `csrfToken.ts:12-15`).
 | `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`). |
+| `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:542`). |
 | `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`). |
 
@@ -339,7 +339,7 @@ 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:162`).
+  marqueurs sont lus depuis le memo de route — 0 `Reflect` par requête (`Resolver.ts:205`).
 
 ## 📡 Observabilité — Studio
 

package/docs/external-jwt.md

@@ -123,11 +123,12 @@ concernent d'après la liste d'émetteurs, puis délègue la vérification au se
 La liste sert donc à deux choses : router, et dire dans quel espace de noms lire le sujet.
 
 ```ts
-firewall: {
+areas: {
   api: {
     pattern: "^/api",
     stateless: true,
     authenticators: ["external-jwt"],
+    resource: "https://api.example.com",
   },
 }
 ```

package/docs/firewall.md

@@ -73,11 +73,11 @@ le plus long gagne, pas le premier déclaré (`firewall.ts:257`).
 
 ### 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
+Le scaffold déclare trois zones (`main`, `secure`, `machine`) dans `nodefony/config/security.ts`, importé par `nodefony.config.ts` ; en voici deux — c'est la forme canonique (un **objet par
 nom**, validé Zod au boot : `areas: z.record(...)`, `config.ts:1126-1127`) :
 
 ```typescript
-// nodefony.config.ts (extrait généré par `nodefony create app`)
+// nodefony/config/security.ts (extrait généré par `nodefony create app`)
 use("@nodefony/security", {
   areas: {
     // Zone de TES routes : `session` PUIS `anonymous` → identifié si cookie,
@@ -151,7 +151,7 @@ curl -si http://localhost:5151/api/secure/account/me | head -1
 
 # 2) Login BFF (compte dev seedé admin/nodefony-dev-42) → cookie de session
 curl -si -c /tmp/jar -H 'Content-Type: application/json' \
-  -d '{"username":"admin","password":"admin"}' \
+  -d '{"username":"admin","password":"nodefony-dev-42"}' \
   http://localhost:5151/nodefony/security/api/auth/login | head -1
 # HTTP/1.1 200 OK
 
@@ -463,12 +463,12 @@ inchangé : la zone n'exige qu'une identité.
 C'est un **défaut**, pas une exclusivité. Quatre cas gardent la main, et chacun est une déclaration
 explicite du code — jamais un contournement :
 
-| Ce qui décide à la place                               | Pourquoi                                                                                                              |
-| ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
-| Une **garde d'action** (`@IsGranted`, `@RequireScope`) | L'action a déjà dit ce qu'elle exige. Sans cela, une page réservée à l'exploitant deviendrait inatteignable pour lui. |
-| Une route **`selfGuarded`**                            | Elle tranche son autorisation dans son code — typiquement parce qu'elle ne sert QUE le porteur courant.               |
-| Un **`bypassFirewall`**                                | La route EST le mécanisme d'authentification : lui imposer un rôle serait un verrou dont la clé est à l'intérieur.    |
-| L'**ouverture d'une connexion WebSocket**              | Une connexion n'accède à rien ; ce sont les frames qui accèdent, et chacune est gardée pour son compte.               |
+| Ce qui décide à la place                  | Pourquoi                                                                                                                                                                            |
+| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Une **garde de rôle** (`@IsGranted`)      | L'action a déjà dit quel rôle elle exige (un `@RequireScope` seul ne dispense pas du rôle de zone). Sans cela, une page réservée à l'exploitant deviendrait inatteignable pour lui. |
+| Une route **`areaRoleExempt`**            | Elle tranche son autorisation dans son code — typiquement parce qu'elle ne sert QUE le porteur courant.                                                                             |
+| Un **`bypassFirewall`**                   | La route EST le mécanisme d'authentification : lui imposer un rôle serait un verrou dont la clé est à l'intérieur.                                                                  |
+| L'**ouverture d'une connexion WebSocket** | Une connexion n'accède à rien ; ce sont les frames qui accèdent, et chacune est gardée pour son compte.                                                                             |
 
 Le dernier cas mérite d'être compris, parce qu'il pourrait passer pour un trou. Il n'en est pas un :
 une frame `api.request {path}` **repasse par la même décision** que la requête HTTP équivalente.
@@ -477,7 +477,7 @@ que la porte HTTP refuse. Ce que la dispense évite, c'est qu'un compte sans rô
 puisse plus ouvrir **aucune** socket, et perde du même coup le self-service dont il est le seul
 destinataire.
 
-> ⚠️ **`selfGuarded` n'est pas un interrupteur pour faire taire un refus.** Le poser sur une route
+> ⚠️ **`areaRoleExempt` n'est pas un interrupteur pour faire taire un refus.** Le poser sur une route
 > qui ne décide de rien la rend accessible à tout compte connecté, en silence. Il se justifie par ce
 > que fait le CODE de l'action : scoper au porteur courant, ou résoudre un rôle par point d'entrée.
 > Dans le doute, une garde d'action explicite est toujours préférable.
@@ -505,7 +505,7 @@ registerVoterFactory(
 //   l'utilisateur est-il propriétaire/membre du `subject` ? GRANT / DENY / ABSTAIN.
 ```
 
-Le voter est **découvert automatiquement** par l'`AuthorizationService` — aucun changement dans le
+Le voter est **découvert automatiquement** par le service `authorization` — aucun changement dans le
 cœur (`registerVoterFactory()`, `voterRegistry.ts:40`). Pourquoi un registre et pas un scan DI des
 `@injectable` : les interfaces TS sont **effacées à la compilation** — rien à scanner ; le registre
 **est** le marqueur explicite (TSDoc du registre, `voterRegistry.ts:6-16`). Trois axes (rôles,
@@ -553,16 +553,16 @@ ne paie quasiment rien.
 
 ## ⚠️ Pièges (symptôme → cause → correction)
 
-| Symptôme                                 | Cause (dans le code)                                    | Correction                                                      |
-| ---------------------------------------- | ------------------------------------------------------- | --------------------------------------------------------------- |
-| Boot rejette la config (`areas`)         | `areas` déclaré en **tableau** — c'est un objet par nom | `areas: { monNom: { pattern, authenticators } }`                |
-| Boot « authenticator inconnu »           | Nom absent du registre (fail-closed)                    | Corriger le nom / enregistrer l'authenticator                   |
-| 401 alors qu'un credential est envoyé    | Mode `first` : credential invalide échoue sans fallback | Vérifier le format/authenticator attendu                        |
-| Route « publique » ne voit jamais l'user | Hors zone, l'identité n'est **jamais** résolue          | Couvrir la route par une zone `["session", "anonymous"]`        |
-| API : JWT et clé API se marchent dessus  | —                                                       | Rien à faire : discriminés par la forme (`a.b.c` vs `prefix_…`) |
-| JWT révoqué encore accepté               | Auto-portage : révocation = état serveur                | S'assurer que `tokenStore` porte la denylist/`invalidBefore`    |
-| WS : révocation pas immédiate            | Jeton figé au handshake (asymétrie assumée)             | Effet à la reconnexion ; pour l'immédiat, canal JWT (J4)        |
-| 429 au login                             | Throttle NIST (backoff par identifiant)                 | Respecter `Retry-After` ; attendu sous attaque                  |
+| Symptôme                                 | Cause (dans le code)                                    | Correction                                                                      |
+| ---------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| Boot rejette la config (`areas`)         | `areas` déclaré en **tableau** — c'est un objet par nom | `areas: { monNom: { pattern, authenticators } }`                                |
+| Boot « authenticator inconnu »           | Nom absent du registre (fail-closed)                    | Corriger le nom / enregistrer l'authenticator                                   |
+| 401 alors qu'un credential est envoyé    | Mode `first` : credential invalide échoue sans fallback | Vérifier le format/authenticator attendu                                        |
+| Route « publique » ne voit jamais l'user | Hors zone, l'identité n'est **jamais** résolue          | Couvrir la route par une zone `["session", "anonymous"]`                        |
+| API : JWT et clé API se marchent dessus  | —                                                       | Rien à faire : discriminés par la forme (`a.b.c` vs `prefix_…`)                 |
+| JWT révoqué encore accepté               | Auto-portage : révocation = état serveur                | S'assurer que `tokenStore` porte la denylist/`invalidBefore`                    |
+| WS : révocation pas immédiate            | Jeton figé au handshake (asymétrie assumée)             | Effet en une fenêtre (tick du hub + avant chaque `api.request`, fermeture 4001) |
+| 429 au login                             | Throttle NIST (backoff par identifiant)                 | Respecter `Retry-After` ; attendu sous attaque                                  |
 
 ## 📡 Observabilité — Studio
 

package/docs/headers.md

@@ -122,10 +122,10 @@ 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:348`) précalcule la chaîne HSTS (`max-age`, `includeSubDomains`, `preload`) au
-  boot ; `onHttpRequest` (`http-kernel.ts:972`) ne fait plus que trois `setHeader`.
+  (`http-kernel.ts:358`) précalcule la chaîne HSTS (`max-age`, `includeSubDomains`, `preload`) au
+  boot ; `onHttpRequest` (`http-kernel.ts:1009`) 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,
+  (`Context.ts:253`) ne tire ses 128 bits (16 octets CSPRNG, en base64) d'un pool amorti (`randomFillSync`, 4 Ko pour 256 nonces) qu'à la première lecture,
   puis mémoïse. Une réponse qui n'a aucun script inline à signer ne paie aucun appel crypto.
 
 Le second parti pris est la **séparation d'autorité** décrite plus haut : un seul émetteur par
@@ -275,7 +275,7 @@ 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:989`) — et configuré côté `@nodefony/http` avec `frameOptions`
+(`http-kernel.ts:1049`) — 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:986`). C'est **l'en-tête qui justifie le mieux la couche transport** : le danger
+(`http-kernel.ts:1046`). 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,10 +297,10 @@ 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:348`) : `max-age`, puis `includeSubDomains` et `preload` selon la config.
+(`http-kernel.ts:358`) : `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:992`). C'est conforme à la RFC 6797, qui veut qu'un HSTS reçu en clair
+de serveur (`http-kernel.ts:1052`). 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.
 
@@ -397,7 +397,7 @@ Dérivé du schéma Zod `headersSchema` (`config.ts:206`).
 ### Socle transport — `use("@nodefony/http", { securityHeaders })`
 
 Dérivé de `securityHeadersSchema` (`http/nodefony/config/config.ts:123`). Ces trois réglages sont
-**éditables à chaud** (`runtimeMutable`) : `HttpKernel.onConfigChanged()` (`http-kernel.ts:398`)
+**éditables à chaud** (`runtimeMutable`) : `HttpKernel.onConfigChanged()` (`http-kernel.ts:408`)
 recalcule les caches, donc la valeur suivante s'applique sans redémarrage.
 
 | Option                                      | Type              | Défaut     | Effet                                                              |
@@ -446,13 +446,13 @@ Le chemin complet, sans surprise :
    `<script nonce="…">` portent forcément la même valeur. C'est le motif employé par le contrôleur
    de Studio (`StudioController.ts:62`).
 
-`SecurityHeaders.hasNonce` (`securityHeaders.ts:88`) est le drapeau qui décide du régime : à `false`,
+`SecurityHeaders.hasNonce` (`securityHeaders.ts:100`) est le drapeau qui décide du régime : à `false`,
 pas une seule opération crypto. Il n'y a **aucun setter** pour `cspNonce` : un jeton serveur doit
 rester imprévisible, jamais pilotable par le client — contrairement au `requestId`, qui, lui, accepte
 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:1386`). Cet ordre n'est pas cosmétique : il
+le repli statique et le `writeHead` (`http-kernel.ts:1624`). 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.
 
@@ -478,7 +478,7 @@ les tests fiables.
 **Coût** : le merge d'un module est payé **une fois**, au (dés)enregistrement
 (`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`.
+`securityHeaders.ts:131`) ; le cas courant reste le simple `join`.
 
 ## 🧩 Extension — déclarer un fragment CSP depuis son module
 
@@ -523,8 +523,8 @@ en dev soit plus large qu'en production, où ce fragment n'existe pas.
 | 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:267`)                 |
 | Isolation cross-origin               | WHATWG HTML (COOP/COEP/CORP)     | `securityHeaders.ts:71`                                      |
-| Anti-MIME-sniffing                   | WHATWG Fetch (`nosniff`)         | `secContentTypeOptions` (`http-kernel.ts:986`)               |
-| Durcissement en-têtes                | OWASP Secure Headers             | `computeSecurityHeaderCaches()` (`http-kernel.ts:348`)       |
+| Anti-MIME-sniffing                   | WHATWG Fetch (`nosniff`)         | `secContentTypeOptions` (`http-kernel.ts:1046`)              |
+| Durcissement en-têtes                | OWASP Secure Headers             | `computeSecurityHeaderCaches()` (`http-kernel.ts:358`)       |
 
 ## ⚡ Performance & mémoire
 
@@ -533,13 +533,13 @@ Le coût est concentré au boot, par construction :
 - **En-têtes constants** : une seule table, gelée (`securityHeaders.ts:77`). Par requête, une boucle
   `for…in` sur un objet de 1 à 6 entrées et autant de `setHeader`. Aucune allocation.
 - **CSP statique** : rien de plus — la chaîne est dans la table.
-- **CSP à nonce** : `randomBytes(16)` plus un `join` par requête. C'est le seul coût variable, et il
-  n'existe **que** si le CSP porte un placeholder : `hasNonce` (`securityHeaders.ts:88`)
+- **CSP à nonce** : un tirage dans le pool plus une concaténation `préfixe + nonce + suffixe` par requête. C'est le seul coût variable, et il
+  n'existe **que** si le CSP porte un placeholder : `hasNonce` (`securityHeaders.ts:100`)
   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: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
+- **Socle transport** : trois `setHeader` sur des chaînes précalculées (`http-kernel.ts:1047-1053`), avec
   un test `!== null` qui annule le coût des en-têtes désactivés.
 
 Le module n'attache aucun écouteur d'événement et ne conserve aucun état par requête : il n'entre pas

package/docs/index.md

@@ -43,7 +43,7 @@ Quatre parcours selon ce que tu viens faire. L'ordre compte : chaque étape supp
 **Je découvre la sécurité Nodefony** — comprendre le modèle avant de configurer quoi que ce soit.
 
 1. [Firewall](firewall.md) — zones, Zero Trust, la chaîne de décision. **Tout part d'ici.**
-2. [Authenticators](authenticators.md) — les six façons de prouver **qui** appelle.
+2. [Authenticators](authenticators.md) — les sept façons de prouver **qui** appelle.
 3. [Autorisation](authorization.md) — rôles, scopes, voters : **ce qu'il a le droit** de faire.
 4. [Jetons](tokens.md) — ce qui matérialise une identité prouvée, et comment on la révoque.
 
@@ -98,7 +98,7 @@ Le tableau pour choisir en cinq secondes ; les cards en dessous pour le détail.
     "desc": "Le pare-feu applicatif : trois questions pour chaque requête — est-ce une zone protégée ? qui es-tu ? as-tu le droit ? Le chemin chaud (détecter) est séparé du chemin froid (décider), donc une route publique ne paie rien.",
     "meta": "à lire en premier — toutes les autres briques s'y branchent" },
   { "icon": "🪪", "title": "authenticators", "href": "authenticators.md",
-    "desc": "Prouver qui appelle : six stratégies au même contrat — session, userpassword, jwt, apikey, anonymous, firewall-realtime — qui se composent dans l'ordre au sein d'une zone.",
+    "desc": "Prouver qui appelle : sept stratégies au même contrat — session, userpassword, jwt, external-jwt, apikey, anonymous, firewall-realtime — qui se composent dans l'ordre au sein d'une zone.",
     "meta": "commence par « Ordre et modes » : les pièges de configuration sont là" },
   { "icon": "⚖️", "title": "authorization", "href": "authorization.md",
     "desc": "Décider des droits : rôles hiérarchisés, scopes, et voters métier qui portent le vrai pouvoir applicatif. Le jury vote, la stratégie tranche.",
@@ -167,7 +167,7 @@ un mot de passe parce qu'il est perdu ou compromis.
 ## ⚙️ Configuration
 
 Un seul point d'entrée : `use("@nodefony/security", { … })` dans `nodefony.config.ts`, validé par Zod
-au boot. Blocs : `areas` (zones + authenticators), `cors`, `csrf`, `headers`, `loginThrottle`
+au boot. Blocs : `areas` (zones + authenticators), `cors`, `csrf`, `headers`, `rateLimit`
 (backoff NIST), puis un bloc par brique (`jwt`, `apiKeys`, `totp`, `webhooks`, `audit`, `passkeys`,
 `oauth2`). **Chaque page de brique détaille son bloc**, avec une table dérivée du schéma.
 

package/docs/lexique.md

@@ -126,21 +126,21 @@ source: "src/packages/@nodefony/security/docs/lexique.md"
 > L'**autorisation** (authz) répond « as-tu le DROIT de faire ça ? » (les voters, `@IsGranted`).
 > On peut être authentifié ET refusé (un `user` connecté sur une route `ROLE_ADMIN` → **403**, pas 401).
 
-| Sigle / terme                       | Développé                      | En clair                                                                                                                                                                                                    |
-| ----------------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **RBAC**                            | Role-Based Access Control      | Droits par RÔLES (`ROLE_ADMIN` peut X). Simple, couvre 80 % des besoins. Niveau **A** chez Nodefony (`RoleVoter`).                                                                                          |
-| **ABAC**                            | Attribute-Based Access Control | Droits par ATTRIBUTS contextuels (le **propriétaire** du document peut le modifier) → les voters reçoivent le `subject`. Niveau **C**.                                                                      |
-| **Voter**                           | « votant / juré »              | Petit juge spécialisé : pour une décision donnée il rend **un** verdict parmi 3 (GRANT / DENY / ABSTAIN). On en empile autant qu'on veut (rôles, propriété, horaires…), chacun sur son domaine.             |
-| **GRANT / DENY / ABSTAIN**          | accorde / refuse / s'abstient  | Les 3 verdicts d'un voter. **ABSTAIN** = « pas mon rayon » (ne compte pas). C'est la combinaison des votes qui tranche, pas un seul.                                                                        |
-| **`AuthorizationService.decide()`** | —                              | Le **juge en chef** (`authorization.ts`, J6) : interroge tous les voters et applique la stratégie de vote → un seul booléen GRANT/DENY.                                                                     |
-| **Stratégie affirmative**           | —                              | « **un seul GRANT suffit** » (tant qu'aucun DENY) — la stratégie de `decide()`. Permissive sur l'accord, stricte sur le refus.                                                                              |
-| **Veto (DENY)**                     | —                              | « **un seul DENY refuse tout** », même si d'autres votent GRANT. Le refus l'emporte toujours (sécurité d'abord).                                                                                            |
-| **Default DENY**                    | refus par défaut               | Tous ABSTAIN, ou **zéro** voter, ou aucun GRANT → **refusé** (Zero Trust). Il faut un OUI explicite, le silence ne suffit pas.                                                                              |
-| **Fail-closed (voter)**             | « échoue fermé »               | Si un voter **plante** (throw) → compté comme DENY + log ERROR, jamais une 500 qui laisserait passer. L'erreur ne doit jamais ouvrir la porte (cf lexique général `fail-closed`).                           |
-| **`voterRegistry`**                 | registre de voters             | Fabrique pluggable (convention-frère de `authenticatorRegistry`) : on **ajoute** un voter sans toucher `decide()`. Le futur `PermissionVoter` (RBAC ORM, niveau B/J6b) s'y branchera.                       |
-| **`RoleVoter`**                     | —                              | Le voter niveau **A** : GRANT si le token porte le rôle demandé (via `RoleHierarchyWalker`), ABSTAIN sinon — **jamais de veto** (il ne bloque pas les attributs qu'il ne connaît pas).                      |
-| **Attribute**                       | attribut (de décision)         | La chose demandée passée à `decide()` : un rôle (`ROLE_ADMIN`), une permission (`post:edit`)… Ne PAS confondre avec l'ABAC « attribut contextuel » (le `subject`).                                          |
-| **Subject**                         | sujet / ressource ciblée       | L'objet **sur lequel** porte l'action (le document à éditer), passé au voter pour les règles ABAC (« est-il le propriétaire ? »). Optionnel — souvent un param de route via `@IsGranted(..., { subject })`. |
+| Sigle / terme                | Développé                      | En clair                                                                                                                                                                                                    |
+| ---------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **RBAC**                     | Role-Based Access Control      | Droits par RÔLES (`ROLE_ADMIN` peut X). Simple, couvre 80 % des besoins. Niveau **A** chez Nodefony (`RoleVoter`).                                                                                          |
+| **ABAC**                     | Attribute-Based Access Control | Droits par ATTRIBUTS contextuels (le **propriétaire** du document peut le modifier) → les voters reçoivent le `subject`. Niveau **C**.                                                                      |
+| **Voter**                    | « votant / juré »              | Petit juge spécialisé : pour une décision donnée il rend **un** verdict parmi 3 (GRANT / DENY / ABSTAIN). On en empile autant qu'on veut (rôles, propriété, horaires…), chacun sur son domaine.             |
+| **GRANT / DENY / ABSTAIN**   | accorde / refuse / s'abstient  | Les 3 verdicts d'un voter. **ABSTAIN** = « pas mon rayon » (ne compte pas). C'est la combinaison des votes qui tranche, pas un seul.                                                                        |
+| **`Authorization.decide()`** | —                              | Le **juge en chef** (`authorization.ts`, J6) : interroge tous les voters et applique la stratégie de vote → un seul booléen GRANT/DENY.                                                                     |
+| **Stratégie affirmative**    | —                              | « **un seul GRANT suffit** » (tant qu'aucun DENY) — la stratégie de `decide()`. Permissive sur l'accord, stricte sur le refus.                                                                              |
+| **Veto (DENY)**              | —                              | « **un seul DENY refuse tout** », même si d'autres votent GRANT. Le refus l'emporte toujours (sécurité d'abord).                                                                                            |
+| **Default DENY**             | refus par défaut               | Tous ABSTAIN, ou **zéro** voter, ou aucun GRANT → **refusé** (Zero Trust). Il faut un OUI explicite, le silence ne suffit pas.                                                                              |
+| **Fail-closed (voter)**      | « échoue fermé »               | Si un voter **plante** (throw) → compté comme DENY + log ERROR, jamais une 500 qui laisserait passer. L'erreur ne doit jamais ouvrir la porte (cf lexique général `fail-closed`).                           |
+| **`voterRegistry`**          | registre de voters             | Fabrique pluggable (convention-frère de `authenticatorRegistry`) : on **ajoute** un voter sans toucher `decide()`. Le futur `PermissionVoter` (RBAC ORM, niveau B/J6b) s'y branchera.                       |
+| **`RoleVoter`**              | —                              | Le voter niveau **A** : GRANT si le token porte le rôle demandé (via `RoleHierarchyWalker`), ABSTAIN sinon — **jamais de veto** (il ne bloque pas les attributs qu'il ne connaît pas).                      |
+| **Attribute**                | attribut (de décision)         | La chose demandée passée à `decide()` : un rôle (`ROLE_ADMIN`), une permission (`post:edit`)… Ne PAS confondre avec l'ABAC « attribut contextuel » (le `subject`).                                          |
+| **Subject**                  | sujet / ressource ciblée       | L'objet **sur lequel** porte l'action (le document à éditer), passé au voter pour les règles ABAC (« est-il le propriétaire ? »). Optionnel — souvent un param de route via `@IsGranted(..., { subject })`. |
 
 ### Décorateurs sécurité (panoplie J7)
 

package/docs/oauth2.md

@@ -144,12 +144,13 @@ d'audit. Il n'existe **aucun** authenticator `oauth2` dans la chaîne du firewal
 c'est l'authenticator `session` qui identifie chaque requête, comme après un mot de passe.
 
 **Coût nul quand on ne s'en sert pas.** Aucune dépendance tierce : le client OAuth 2.0 est écrit
-dans le module (`oauth2Client.ts:321`), et `jose` — seul recours externe, pour lire les claims de
+dans le module (`OAuth2Client`, `oauth2Client.ts:321`), et `jose` — seul recours externe, pour lire les claims de
 l'ID token — est importé **paresseusement**. Les fournisseurs sont construits au premier login puis
 mémoïsés (`OAuth2Service.#resolveProvider()`, `oauth2.ts:296`) : c'est là, une seule fois par
-processus, que les points d'entrée d'un émetteur OIDC sont découverts. Les routes ne sont montées
-que si le service existe (`framework/index.ts:460`) : sans social login configuré, la surface HTTP
-est **404**, pas « désactivée ».
+processus, que les points d'entrée d'un émetteur OIDC sont découverts. Les routes sont montées dès
+que `@nodefony/security` est chargé (`framework/index.ts:460`) : sans social login configuré,
+`…/providers` rend une liste vide, `authorize` rend `404 Unknown provider`, et `authorize`/`callback`
+rendent `503 OAuth unavailable` quand `oauth2.enabled` vaut `false`.
 
 Au boot, la config est validée et les fournisseurs configurés sont confrontés au registre : un nom
 inconnu produit un **WARNING, pas un échec fatal** — `OAuth2Service.#build()` confronte les noms
@@ -215,8 +216,8 @@ export default defineConfig<typeof env>((ctx) => ({
 ### Les routes sont FOURNIES — tu n'écris aucun controller
 
 `mountOAuth2Routes()` (`OAuth2Controller.ts:234`) monte trois routes sous
-`/nodefony/security/api/oauth2` (`OAuth2Controller.ts:236`), et **seulement si** le service `oauth2`
-est présent (`framework/index.ts:460`) :
+`/nodefony/security/api/oauth2` (`OAuth2Controller.ts:236`) dès que le service `oauth2` est
+enregistré, c'est-à-dire dès que `@nodefony/security` est chargé (`framework/index.ts:460`) :
 
 | Route                        | Rôle                                                                  |
 | ---------------------------- | --------------------------------------------------------------------- |
@@ -488,14 +489,14 @@ que le mapping du profil. Exemple sans réseau dans le dépôt :
 Section `oauth2` du schéma Zod (`config.ts:1155`), branchée sur la config du module
 (`config.ts:1155`). Table dérivée du schéma — les défauts sont ceux du code.
 
-| Option            | Type                 | Défaut          | Effet                                                      |
-| ----------------- | -------------------- | --------------- | ---------------------------------------------------------- |
-| `enabled`         | booléen              | `true`          | Coupe le social login ; les routes ne montent pas.         |
-| `defaultRoles`    | liste de rôles       | `["ROLE_USER"]` | Rôles du Shadow User **à la création** (`config.ts:1048`). |
-| `allowSignup`     | booléen              | `true`          | `false` = compte préexistant lié exigé (`config.ts:1054`). |
-| `successRedirect` | chemin               | `/`             | Où revient l'utilisateur après succès.                     |
-| `failureRedirect` | chemin               | `/login`        | Où il revient après échec (uniforme, sans détail).         |
-| `providers`       | dictionnaire par nom | `{}`            | Fournisseurs activés (`config.ts:1070`).                   |
+| Option            | Type                 | Défaut          | Effet                                                       |
+| ----------------- | -------------------- | --------------- | ----------------------------------------------------------- |
+| `enabled`         | booléen              | `true`          | Coupe le social login : `authorize`/`callback` rendent 503. |
+| `defaultRoles`    | liste de rôles       | `["ROLE_USER"]` | Rôles du Shadow User **à la création** (`config.ts:1048`).  |
+| `allowSignup`     | booléen              | `true`          | `false` = compte préexistant lié exigé (`config.ts:1054`).  |
+| `successRedirect` | chemin               | `/`             | Où revient l'utilisateur après succès.                      |
+| `failureRedirect` | chemin               | `/login`        | Où il revient après échec (uniforme, sans détail).          |
+| `providers`       | dictionnaire par nom | `{}`            | Fournisseurs activés (`config.ts:1070`).                    |
 
 Par fournisseur (`oauthProviderSchema`, `config.ts:954`) :
 
@@ -608,15 +609,17 @@ session ouverte apparaît dans l'écran **Sessions** (IP et agent capturés à l
 provisionné dans l'écran **Users**, avec ses rôles réels.
 
 > [!NOTE]
-> L'événement d'audit du login social porte la raison par défaut `federated`
-> (`authFlow.ts:218`) : le controller n'affine pas le facteur. Pour distinguer OAuth de WebAuthn dans
-> un filtre d'audit, s'appuyer sur le contexte de la requête plutôt que sur cette seule valeur.
+> L'événement d'audit du login social porte la raison `oauth` : le controller la passe à
+> `AuthFlow.establishSessionFor()` (`OAuth2Controller.ts:194`), comme WebAuthn passe `webauthn`.
+> `federated` n'est que la valeur par défaut d'un appelant qui n'a pas nommé son facteur
+> (`authFlow.ts:215`).
 
 ## ⚠️ Pièges (symptôme → cause → correction)
 
 | Symptôme                                          | Cause (dans le code)                                                          | Correction                                                          |
 | ------------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------- |
-| `404` sur `…/oauth2/…`                            | Service `oauth2` absent (module non chargé / `enabled: false`)                | Charger `@nodefony/security` et activer `oauth2`                    |
+| `404` sur `…/oauth2/…`                            | Module `@nodefony/security` non chargé, ou nom de fournisseur inconnu         | Charger `@nodefony/security` ; vérifier le nom du fournisseur       |
+| `503 OAuth unavailable`                           | `oauth2.enabled: false`, ou boot du service échoué                            | Activer `oauth2` ; lire le WARNING de boot                          |
 | WARNING « inconnu du registre » au boot           | Nom configuré sans fabrique (`oauth2.ts:149-155`)                             | `registerOAuthProvider()` au chargement du module, ou builtin       |
 | `404` « Unknown provider » sur `authorize`        | Le nom n'est pas dans `listProviders()` (`OAuth2Controller.ts:14`)            | Vérifier le nom exact **et** la présence des secrets                |
 | Bouton absent de l'écran de login                 | Secrets manquants → fournisseur non monté (spread conditionnel)               | Renseigner `clientId`/`clientSecret` dans l'env                     |

package/docs/tokens.md

@@ -25,7 +25,7 @@ tags:
   ]
 version: "doc"
 status: stable
-updated: 2026-07-19
+updated: 2026-10-02
 source: "src/packages/@nodefony/security/docs/tokens.md"
 ---
 
@@ -142,8 +142,9 @@ le framework monte deux routes (`mountTokenAuthRoutes()`, `TokenAuthController.t
 - `POST /nodefony/security/api/token/refresh` — body `{refresh_token}` → rotation.
 
 > [!IMPORTANT]
-> Ces routes n'existent **que si** le service `tokenService` est présent — sinon 404, zéro surface
-> (`TokenAuthController.ts:46-48`). Elles sont `bypassFirewall: true` (`TokenAuthController.ts:145`) :
+> Ces routes n'existent **que si** `@nodefony/security` est chargé — sinon 404, zéro surface
+> (`framework/index.ts:415`). Module chargé mais JWT désactivé : elles existent et répondent
+> `503 Token issuance unavailable` (`TokenAuthController.ts:69`). Elles sont `bypassFirewall: true` (`TokenAuthController.ts:145`) :
 > elles SONT le mécanisme d'émission — protégées, obtenir un token exigerait d'être déjà
 > authentifié (deadlock). Le JWT part en **réponse JSON** (Bearer), jamais en cookie ni en URL.
 
@@ -479,7 +480,7 @@ Tables dérivées du schéma Zod — `jwtSchema` (`config.ts:366-425`) et `token
 
 | Symptôme                                      | Cause (dans le code)                                           | Correction                                               |
 | --------------------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------- |
-| 404 sur `/nodefony/security/api/token`        | Routes montées seulement si `tokenService` existe              | Charger `@nodefony/security` + `jwt.enabled: true`       |
+| 404 sur `/nodefony/security/api/token`        | Module `@nodefony/security` non chargé                         | Charger `@nodefony/security` + `jwt.enabled: true`       |
 | 503 « Token issuance unavailable »            | Service non initialisé (JWT désactivé, store indisponible)     | Vérifier config `jwt`/`tokenStore` + logs de boot        |
 | Refresh tokens invalidés à chaque redémarrage | Keystore en mémoire (aucune source configurée)                 | `jwt.keystore.keySetJson` (prod) ou `dir` (dev)          |
 | JWT rejeté après un déploiement multi-pod     | Clés différentes par pod (pas de clé partagée)                 | Provisionner `keySetJson` hors-bande (même clé partout)  |

package/docs/totp.md

@@ -190,8 +190,9 @@ export default defineConfig<typeof env>((ctx) => ({
 
 ### 3. Les endpoints sont FOURNIS — tu n'écris aucun controller
 
-`mountTotpRoutes()` (`TotpController.ts:154`) monte quatre routes self-service, **et seulement si**
-le service `totp` existe (security chargé + 2FA activé) — sinon zéro surface, 404 :
+`mountTotpRoutes()` (`TotpController.ts:154`) monte quatre routes self-service dès que
+`@nodefony/security` est chargé (le service `totp` est alors toujours enregistré). 2FA désactivé, ou
+service non initialisé : elles répondent `503 2FA unavailable` :
 
 | Route                                      | Corps      | Réponse                                        |
 | ------------------------------------------ | ---------- | ---------------------------------------------- |
@@ -211,7 +212,7 @@ Et côté login, deux routes du flux de session BFF (`mountSessionAuthRoutes()`,
 > [!WARNING]
 > Les routes `totp/*` **n'ont pas** `bypassFirewall` (`TotpController.ts:52`) : elles vivent dans la
 > zone data plane et exigent une session BFF. Le sujet est **toujours** l'utilisateur courant, lu
-> depuis la session (`TotpController.#currentSubject()`, `TotpController.ts:138`) — jamais un
+> depuis la session (`TotpController.#currentSubject()`, `TotpController.ts:142`) — jamais un
 > paramètre : on n'active ni ne désactive le 2FA d'autrui (anti-IDOR).
 
 ### 4. Ce qu'on observe
@@ -455,17 +456,17 @@ La saisie est tolérante — casse et tirets ignorés à la normalisation (`totp
 La section `totp` du schéma Zod (`config.ts:1144`) — validée au boot, donc une valeur hors bornes
 échoue **au démarrage**, pas au premier login :
 
-| Option          | Type                         | Défaut | Effet                                                              |
-| --------------- | ---------------------------- | ------ | ------------------------------------------------------------------ |
-| `enabled`       | `boolean`                    | `true` | Coupe le 2FA : service inerte, routes non montées (`totp.ts:101`). |
-| `issuer`        | `string?`                    | —      | Nom affiché dans l'app d'authentification. Omis = nom de l'app.    |
-| `algorithm`     | `"SHA1"\|"SHA256"\|"SHA512"` | `SHA1` | Fonction HMAC. `SHA1` = compat maximale (`config.ts:551`).         |
-| `digits`        | `int` 6–8                    | `6`    | Longueur du code (RFC 4226 §5.3 : 6 minimum).                      |
-| `period`        | `int` > 0                    | `30`   | Durée de vie d'un code, en secondes.                               |
-| `window`        | `int` ≥ 0                    | `1`    | Tolérance de dérive, en pas (`config.ts:572`).                     |
-| `recoveryCodes` | `int` > 0                    | `10`   | Nombre de codes générés à l'activation (`config.ts:580`).          |
-| `encryptionKey` | `string?`                    | —      | Clé de chiffrement du secret au repos (`config.ts:588`).           |
-| `store`         | `string`                     | `auto` | Backend de persistance du secret (`config.ts:594`).                |
+| Option          | Type                         | Défaut | Effet                                                           |
+| --------------- | ---------------------------- | ------ | --------------------------------------------------------------- |
+| `enabled`       | `boolean`                    | `true` | Coupe le 2FA : service inerte, routes en `503` (`totp.ts:101`). |
+| `issuer`        | `string?`                    | —      | Nom affiché dans l'app d'authentification. Omis = nom de l'app. |
+| `algorithm`     | `"SHA1"\|"SHA256"\|"SHA512"` | `SHA1` | Fonction HMAC. `SHA1` = compat maximale (`config.ts:551`).      |
+| `digits`        | `int` 6–8                    | `6`    | Longueur du code (RFC 4226 §5.3 : 6 minimum).                   |
+| `period`        | `int` > 0                    | `30`   | Durée de vie d'un code, en secondes.                            |
+| `window`        | `int` ≥ 0                    | `1`    | Tolérance de dérive, en pas (`config.ts:572`).                  |
+| `recoveryCodes` | `int` > 0                    | `10`   | Nombre de codes générés à l'activation (`config.ts:580`).       |
+| `encryptionKey` | `string?`                    | —      | Clé de chiffrement du secret au repos (`config.ts:588`).        |
+| `store`         | `string`                     | `auto` | Backend de persistance du secret (`config.ts:594`).             |
 
 ### Situation 1 — un utilisateur active la 2FA sur son compte
 

package/docs/webauthn.md

@@ -217,7 +217,7 @@ export async function enrollPasskey(): Promise<string> {
   return out.credentialId;
 }
 
-/** Se connecter sans mot de passe. `username` omis = passkey découvrable. */
+/** Se connecter sans mot de passe : un anonyme reçoit toujours un défi découvrable. */
 export async function loginWithPasskey(
   username?: string,
 ): Promise<{ username: string }> {
@@ -404,15 +404,16 @@ sans champ à remplir.
 passkeys: { residentKey: "required" }, // la passkey DOIT être découvrable
 ```
 
-Et côté client, **n'envoie pas** `username` à `login/options` : `allowCredentials` est alors omis et
-le navigateur propose les comptes qu'il connaît. C'est aussi la variante la plus sobre côté vie
-privée — voir la section suivante.
+Côté client, rien à faire de plus : le serveur **ignore** tout `username` posté par un anonyme.
+`allowCredentials` est omis et le navigateur propose les comptes qu'il connaît. Le ciblage ne vient
+jamais du corps de la requête, seulement de la session (`WebAuthnController.loginOptions()`,
+`WebAuthnController.ts:171`).
 
-| Ce que le client envoie à `login/options` | Ce que renvoie le serveur                       | Conséquence                                      |
-| ----------------------------------------- | ----------------------------------------------- | ------------------------------------------------ |
-| `{}`                                      | défi seul, **sans** `allowCredentials`          | l'authenticator propose ses comptes              |
-| `{"username":"alice"}` (alice a 3 clés)   | défi + `allowCredentials` de **3** identifiants | ciblage — mais l'anonyme apprend qu'ils existent |
-| `{"username":"fantome"}`                  | défi + `allowCredentials: []` (200, jamais 404) | pas d'erreur révélatrice — mais liste vide       |
+| Qui appelle `login/options`             | Ce que renvoie le serveur                            | Conséquence                                 |
+| --------------------------------------- | ---------------------------------------------------- | ------------------------------------------- |
+| anonyme, `{}`                           | défi seul, **sans** `allowCredentials`               | l'authenticator propose ses comptes         |
+| anonyme, `{"username":"alice"}`         | identique : le `username` est ignoré                 | aucun ciblage, rien à apprendre sur `alice` |
+| session authentifiée (ré-auth, step-up) | défi + `allowCredentials` des clés **de ce porteur** | ciblage de ses propres passkeys             |
 
 ## 🛡️ `rpId` et origines — l'ancre anti-phishing
 
@@ -439,14 +440,16 @@ est ignoré, sans jamais ouvrir à un domaine tiers) ; en dernier recours `https
 
 ## 🔐 Le point à ne pas rater — plafond d'enrôlement et `login/options` ouvert
 
-`login/options` est **accessible à un anonyme** (`bypassFirewall`) et accepte un `username`
-(`WebAuthnController.ts:168`). C'est nécessaire — on ne peut pas exiger d'être connecté pour se
-connecter — mais cela ouvre deux surfaces qu'il faut regarder en face.
+`login/options` est **accessible à un anonyme** (`bypassFirewall`). C'est nécessaire — on ne peut
+pas exiger d'être connecté pour se connecter. Le ciblage, lui, ne vient jamais du corps : un anonyme
+reçoit toujours un défi découvrable, et seule une session authentifiée cible ses propres passkeys
+(`WebAuthnController.loginOptions()`, `WebAuthnController.ts:171`). Deux surfaces restent à
+regarder en face.
 
 ### Amplification : bornée par le plafond, pas par une pagination
 
-Avec un `username`, le serveur charge **toutes** les passkeys du porteur pour construire
-`allowCredentials` (`webAuthn.ts:399`). Cet appel `findByUser` est **volontairement non paginé** —
+Pour une session authentifiée, le serveur charge **toutes** les passkeys du porteur pour construire
+`allowCredentials` (`WebAuthnService.generateAuthenticationOptions()`, `webAuthn.ts:389`). Cet appel `findByUser` est **volontairement non paginé** —
 `allowCredentials` doit être complet ou il est faux : un authenticator absent de la liste ne peut pas
 répondre, et le protocole n'offre aucune « page suivante » (`IWebAuthnCredentialStore.ts:88`).
 
@@ -460,22 +463,17 @@ Ce qui borne donc cette lecture, c'est **`passkeys.maxPerUser`** (défaut 20, `c
   (3 comptages, 0 chargement) ;
 - retirer un appareil **libère une place** : le plafond est une borne, pas un compteur qui dérive.
 
-### Énumération : le statut est uniforme, la liste ne l'est pas
+### Énumération : rien ne distingue deux comptes
 
-Un compte inexistant reçoit **200 + un défi**, exactement comme un compte réel — le test d'attaque E3
-(`webauthn-attack.test.ts`) verrouille ce point. Aucun 404, aucun message différencié, aucune latence
-de recherche de mot de passe.
+Un anonyme reçoit **toujours le même défi découvrable**, sans `allowCredentials`, qu'il poste ou non
+un `username` : aucun statut, aucune liste, aucune latence ne dit si un compte existe ou porte une
+passkey, et l'appel ne touche même pas le store. C'est le remède que la spécification W3C WebAuthn
+propose contre la fuite des identifiants de credentials ; `webauthnLoginOptionsPrivacy.test.ts` le
+verrouille.
 
-Mais `allowCredentials` reflète la réalité : **vide** pour un identifiant sans passkey, **peuplé** (et
-portant les identifiants de credentials) pour un porteur enrôlé. Un anonyme peut donc distinguer
-« cet identifiant a au moins une passkey » de « il n'en a pas ».
-
-> [!WARNING]
-> C'est le comportement standard d'un `login/options` avec identifiant, et la parade est
-> architecturale : **ne transmets pas `username`**. Avec `residentKey: "required"` et un client qui
-> poste `{}`, `allowCredentials` est omis, aucun état de compte ne transparaît, et l'appel ne touche
-> même pas le store. Si ton UX exige la saisie d'un identifiant, place un rate-limit devant
-> `login/options` — le firewall ne le protège pas, c'est une route en `bypassFirewall`.
+> [!NOTE]
+> `login/options` reste une route en `bypassFirewall` : le firewall ne la protège pas. Un rate-limit
+> en amont reste de bonne hygiène, pour borner le coût des défis émis.
 
 Les autres gardes de cette surface, toutes couvertes par des tests d'attaque :
 
@@ -680,19 +678,18 @@ requête. Le code en tire trois conséquences.
 
 ## ⚠️ Pièges (symptôme → cause → correction)
 
-| Symptôme                                             | Cause (dans le code)                                                       | Correction                                                     |
-| ---------------------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------- |
-| `409` à l'enrôlement                                 | Plafond `passkeys.maxPerUser` atteint (`webAuthn.ts:355`)                  | Retirer un appareil, ou relever `maxPerUser`                   |
-| `400 No challenge` au `verify`                       | Défi absent : déjà consommé, ou pas de cookie renvoyé                      | Un défi = un `verify` ; envoyer le cookie (`credentials`)      |
-| `401` systématique en production                     | Origine hors liste blanche, ou `rpId` ≠ domaine servi                      | Renseigner `passkeys.origins` + `rpId` enregistrable           |
-| Passkey KO en dev sur `127.0.0.1`                    | Une IP n'est pas un `rpId` valide → repli `localhost`                      | Accéder par `https://localhost:<port>`                         |
-| Passkeys d'un sous-domaine inutilisables sur l'autre | `rpId` unique, résolu au boot, pas de résolution par `Host`                | Choisir un `rpId` parent commun (`example.com`)                |
-| Login refusé après restauration d'une sauvegarde     | `signCount` régressif → clone suspecté (§6.1.1)                            | Comportement voulu — ré-enrôler l'appareil                     |
-| Tout le monde verrouillé dehors après un déploiement | `store` resté en `memory` : credentials volatils (`webAuthn.ts:183`)       | Déclarer une infra durable ; le `WARNING` boot le disait       |
-| `503 WebAuthn unavailable`                           | `passkeys.enabled: false` ou boot du service échoué                        | Activer `passkeys` ; vérifier le store configuré               |
-| Un anonyme distingue les comptes à passkey           | `allowCredentials` peuplé vs vide sur `login/options`                      | Ne pas envoyer `username` (usernameless) ; rate-limit la route |
-| `total` absent du listing admin                      | Backend curseur (Redis) → `countCredentials()` rend `-1`                   | Paginer par `nextCursor`, ne pas afficher de total             |
-| Passkeys orphelines après renommage d'un compte      | `userId` = `me.username` figé à l'enrôlement (`WebAuthnController.ts:109`) | Ne pas renommer, ou ré-enrôler après renommage                 |
+| Symptôme                                             | Cause (dans le code)                                                       | Correction                                                |
+| ---------------------------------------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------- |
+| `409` à l'enrôlement                                 | Plafond `passkeys.maxPerUser` atteint (`webAuthn.ts:355`)                  | Retirer un appareil, ou relever `maxPerUser`              |
+| `400 No challenge` au `verify`                       | Défi absent : déjà consommé, ou pas de cookie renvoyé                      | Un défi = un `verify` ; envoyer le cookie (`credentials`) |
+| `401` systématique en production                     | Origine hors liste blanche, ou `rpId` ≠ domaine servi                      | Renseigner `passkeys.origins` + `rpId` enregistrable      |
+| Passkey KO en dev sur `127.0.0.1`                    | Une IP n'est pas un `rpId` valide → repli `localhost`                      | Accéder par `https://localhost:<port>`                    |
+| Passkeys d'un sous-domaine inutilisables sur l'autre | `rpId` unique, résolu au boot, pas de résolution par `Host`                | Choisir un `rpId` parent commun (`example.com`)           |
+| Login refusé après restauration d'une sauvegarde     | `signCount` régressif → clone suspecté (§6.1.1)                            | Comportement voulu — ré-enrôler l'appareil                |
+| Tout le monde verrouillé dehors après un déploiement | `store` resté en `memory` : credentials volatils (`webAuthn.ts:183`)       | Déclarer une infra durable ; le `WARNING` boot le disait  |
+| `503 WebAuthn unavailable`                           | `passkeys.enabled: false` ou boot du service échoué                        | Activer `passkeys` ; vérifier le store configuré          |
+| `total` absent du listing admin                      | Backend curseur (Redis) → `countCredentials()` rend `-1`                   | Paginer par `nextCursor`, ne pas afficher de total        |
+| Passkeys orphelines après renommage d'un compte      | `userId` = `me.username` figé à l'enrôlement (`WebAuthnController.ts:109`) | Ne pas renommer, ou ré-enrôler après renommage            |
 
 ## 🧪 Tests & couverture
 

package/docs/webhooks.md

@@ -251,7 +251,7 @@ import { Buffer } from "node:buffer";
 // prettier-ignore
 import { Controller, controller, Post, Body, Headers, BypassFirewall } from "@nodefony/framework";
 
-const SECRET = (process.env.NODEFONY_HOOK_SECRET ?? "").replace(/^whsec_/, "");
+const SECRET = (process.env.NF_HOOK_SECRET ?? "").replace(/^whsec_/, "");
 
 @controller("/hooks")
 class HookMiniController extends Controller {
@@ -308,7 +308,7 @@ import { Buffer } from "node:buffer";
 import { Controller, controller, Post, Body, Headers, BypassFirewall } from "@nodefony/framework";
 
 /** Secret `whsec_…` donné par l'émetteur — via l'environnement, jamais en dur. */
-const SECRET = process.env.NODEFONY_HOOK_SECRET ?? "";
+const SECRET = process.env.NF_HOOK_SECRET ?? "";
 /** Fenêtre anti-rejeu (s) : un message plus vieux est refusé. */
 const TOLERANCE_S = 300;
 
@@ -956,21 +956,21 @@ secret, et sait **simuler des pannes** pour observer retries et auto-désactivat
 
 ## ⚠️ Pièges (symptôme → cause → correction)
 
-| Symptôme                                                | Cause (dans le code)                                                                                            | Correction                                                                   |
-| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
-| Boot : « webhooks désactivés » en production            | Aucune `encryptionKey` — fail-safe (`webhooks.ts:299`)                                                          | `npx nodefony security:secrets` puis câbler `NF_WEBHOOK_KEY`                 |
-| Après redémarrage, les signatures ne valident plus      | Clé **éphémère** de dev : les secrets stockés sont illisibles                                                   | Poser une `encryptionKey` stable ; tourner les secrets des endpoints         |
-| `422` à la création d'un endpoint                       | `assertPublicUrl()` refuse la cible (IP interne, schéma, userinfo)                                              | Viser une URL publique en `https://` ; en dev, `denyPrivateIps: false`       |
-| Rien n'arrive alors que l'endpoint est actif            | Aucun `auditService` → dispatcher inactif (`webhooks.ts:191`)                                                   | Vérifier que l'audit est activé ; le CRUD seul ne livre rien                 |
-| Un événement « métier » n'arrive jamais                 | La source est le **journal d'audit**, pas un bus applicatif                                                     | S'abonner à une action d'audit existante                                     |
-| Signature invalide côté récepteur                       | Corps re-sérialisé avant le HMAC, ou en-tête `webhook-id`/`-timestamp` ignoré                                   | Lire le corps **brut** ; signer `{id}.{timestamp}.{body}`                    |
-| Le récepteur voit deux fois le même événement           | Un retry rejoue le **même** `webhook-id`                                                                        | Dédupliquer par `webhook-id` côté récepteur                                  |
-| Endpoint passé `enabled: false` tout seul               | 20 échecs consécutifs → auto-désactivation (`webhooks.ts:565`)                                                  | Réparer la destination, puis `PATCH … {"enabled":true}`                      |
-| Livraisons « abandonnées » dans les logs                | File pleine (`maxQueue`) — best-effort assumé                                                                   | Augmenter `maxQueue`/`maxConcurrent`, ou réduire le volume souscrit          |
-| Un `302` vers l'interne n'est pas suivi                 | **Voulu** : `node:http(s)` ne suit jamais les 3xx                                                               | Rien à corriger — configurer l'URL finale côté destinataire                  |
-| Le secret a été perdu                                   | Il n'est montré qu'à la création/rotation                                                                       | `POST …/reveal` (audité) ou rotation + redéploiement chez le tiers           |
-| Après un redémarrage, plus aucun endpoint               | `store: "memory"` — registre volatil et par pod                                                                 | Déclarer une infra durable (`store: "auto"` suffit alors)                    |
-| Multi-pod : un endpoint créé ne livre que depuis un pod | Le snapshot n'est chargé qu'au boot (`webhooks.ts:325`) ; les pods qui n'ont pas vu l'écriture gardent l'ancien | Redémarrage tournant après une mutation, ou router l'admin sur tous les pods |
+| Symptôme                                                                       | Cause (dans le code)                                                                                       | Correction                                                             |
+| ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| Boot : « webhooks désactivés » en production                                   | Aucune `encryptionKey` — fail-safe (`webhooks.ts:299`)                                                     | `npx nodefony security:secrets` puis câbler `NF_WEBHOOK_KEY`           |
+| Après redémarrage, les signatures ne valident plus                             | Clé **éphémère** de dev : les secrets stockés sont illisibles                                              | Poser une `encryptionKey` stable ; tourner les secrets des endpoints   |
+| `422` à la création d'un endpoint                                              | `assertPublicUrl()` refuse la cible (IP interne, schéma, userinfo)                                         | Viser une URL publique en `https://` ; en dev, `denyPrivateIps: false` |
+| Rien n'arrive alors que l'endpoint est actif                                   | Aucun `auditService` → dispatcher inactif (`webhooks.ts:191`)                                              | Vérifier que l'audit est activé ; le CRUD seul ne livre rien           |
+| Un événement « métier » n'arrive jamais                                        | La source est le **journal d'audit**, pas un bus applicatif                                                | S'abonner à une action d'audit existante                               |
+| Signature invalide côté récepteur                                              | Corps re-sérialisé avant le HMAC, ou en-tête `webhook-id`/`-timestamp` ignoré                              | Lire le corps **brut** ; signer `{id}.{timestamp}.{body}`              |
+| Le récepteur voit deux fois le même événement                                  | Un retry rejoue le **même** `webhook-id`                                                                   | Dédupliquer par `webhook-id` côté récepteur                            |
+| Endpoint passé `enabled: false` tout seul                                      | 20 échecs consécutifs → auto-désactivation (`webhooks.ts:565`)                                             | Réparer la destination, puis `PATCH … {"enabled":true}`                |
+| Livraisons « abandonnées » dans les logs                                       | File pleine (`maxQueue`) — best-effort assumé                                                              | Augmenter `maxQueue`/`maxConcurrent`, ou réduire le volume souscrit    |
+| Un `302` vers l'interne n'est pas suivi                                        | **Voulu** : `node:http(s)` ne suit jamais les 3xx                                                          | Rien à corriger — configurer l'URL finale côté destinataire            |
+| Le secret a été perdu                                                          | Il n'est montré qu'à la création/rotation                                                                  | `POST …/reveal` (audité) ou rotation + redéploiement chez le tiers     |
+| Après un redémarrage, plus aucun endpoint                                      | `store: "memory"` — registre volatil et par pod                                                            | Déclarer une infra durable (`store: "auto"` suffit alors)              |
+| Multi-pod : un endpoint créé ne livre pas tout de suite depuis les autres pods | Le snapshot est relu après `webhooks.snapshotTtlS` (30 s par défaut, `webhooks.ts:406`), pas immédiatement | Attendre au plus `snapshotTtlS`, ou le baisser                         |
 
 ## 🧪 Tests & couverture
 
@@ -983,7 +983,7 @@ depuis vitest, jamais figés ici :
   historique, bornes de perf, arrêt) ; `webhookSignature` (vecteur officiel Standard Webhooks,
   altération du corps/id/timestamp) ; `webhookDelivery` (pin d'IP, non-suivi des 3xx, timeout,
   politique de protocole, capture du corps de réponse) ; `webhookStore` (CRUD mémoire + copie
-  défensive) ; `webhookAdminApi` (les 8 endpoints, rôles, `400`/`404`/`422`/`503`, audit des
+  défensive) ; `webhookAdminApi` (les 9 endpoints, rôles, `400`/`404`/`422`/`503`, audit des
   mutations) ; `webhookPagination` (harnais du banc de contrat sur le store mémoire).
 - **attaque (red-team)** — `webhookSsrf.attack.test.ts` : matrice threat-first dérivée d'OWASP SSRF
   et de CAPEC-664 (IPv4-mapped IPv6 sous 7 notations, confusion `userinfo`, IP encodée

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodefony/security",
-  "version": "10.0.0-beta.1",
+  "version": "10.0.0-beta.2",
   "description": "Pare-feu applicatif par zones pour Nodefony : authentification, autorisation par rôles, protection CSRF, journal d'audit",
   "author": "Christophe CAMENSULI <ccamensuli@gmail.com>",
   "main": "./dist/index.js",
@@ -54,22 +54,22 @@
     "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@nodefony/framework": "^10.0.0-beta.1",
-    "@nodefony/http": "^10.0.0-beta.1",
-    "@nodefony/user": "^10.0.0-beta.1",
+    "@nodefony/framework": "^10.0.0-beta.2",
+    "@nodefony/http": "^10.0.0-beta.2",
+    "@nodefony/user": "^10.0.0-beta.2",
     "@types/node": "26.6.3",
-    "@vitest/coverage-v8": "5.0.2",
-    "nodefony": "^10.0.0-beta.1",
-    "vitest": "5.0.2"
+    "@vitest/coverage-v8": "5.0.3",
+    "nodefony": "^10.0.0-beta.2",
+    "vitest": "5.0.3"
   },
   "license": "Apache-2.0",
   "readmeFilename": "README.md",
   "contributors": [],
   "peerDependencies": {
-    "@nodefony/framework": "^10.0.0-beta.1",
-    "@nodefony/http": "^10.0.0-beta.1",
-    "@nodefony/user": "^10.0.0-beta.1",
-    "nodefony": "^10.0.0-beta.1"
+    "@nodefony/framework": "^10.0.0-beta.2",
+    "@nodefony/http": "^10.0.0-beta.2",
+    "@nodefony/user": "^10.0.0-beta.2",
+    "nodefony": "^10.0.0-beta.2"
   },
   "files": [
     "dist",