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

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:728`) rattache la requête à une **zone** via
-`Firewall.matchPath()` (`firewall.ts:719`) ; `Firewall.handleSecurity()` (`firewall.ts:761`) décide.
+`Firewall.isSecure()` (`firewall.ts:792`) rattache la requête à une **zone** via
+`Firewall.matchPath()` (`firewall.ts:783`) ; `Firewall.handleSecurity()` (`firewall.ts:825`) 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:257`).
+le plus long gagne, pas le premier déclaré (`firewall.ts:258`).
 
 ## 📖 Lexique
 
@@ -64,7 +64,7 @@ le plus long gagne, pas le premier déclaré (`firewall.ts:257`).
 | Zone          | Un motif d'URL (+ host) avec sa politique (`config.areas`, un objet par nom).   |
 | Authenticator | Une stratégie d'identification (session, userpassword, jwt, apikey, anonymous). |
 | Zero Trust    | Sans preuve valide sur une zone protégée → 401.                                 |
-| Challenge     | En-tête `WWW-Authenticate` (RFC 7235) qui dit comment s'authentifier.           |
+| Challenge     | En-tête `WWW-Authenticate` (RFC 9110 §11) qui dit comment s'authentifier.       |
 | BFF           | Backend-For-Frontend : le serveur gère session/jetons pour le front web.        |
 | PAT           | Personal Access Token : une clé d'API opaque, révocable côté serveur.           |
 | Bearer        | Schéma `Authorization: Bearer <token>` (RFC 6750).                              |
@@ -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
-nom**, validé Zod au boot : `areas: z.record(...)`, `config.ts:1126-1127`) :
+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:1443-1444`) :
 
 ```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
 
@@ -182,6 +182,39 @@ Authorization: Bearer eyJhbGciOiJFZERTQS␣…␣.␣…␣.␣…        # un J
 Authorization: Bearer nf_9a2c…                           # une clé API (préfixe nf_)
 ```
 
+### Protéger des pages : conduire le visiteur à la connexion (`entryPoint`)
+
+Sans réglage, un visiteur anonyme qui ouvre une page protégée reçoit un `401` brut.
+`entryPoint` lui donne la page de connexion à la place :
+
+```typescript
+use("@nodefony/security", {
+  areas: {
+    pages: {
+      pattern: "^/compte(/|$)",
+      authenticators: ["session"],
+      entryPoint: "/login", // la page de connexion du framework (loginPage.path)
+    },
+  },
+});
+```
+
+| La requête refusée                                                           | Réponse                              |
+| ---------------------------------------------------------------------------- | ------------------------------------ |
+| `GET`/`HEAD`, `Accept: text/html`, `Sec-Fetch-Mode: navigate` ou absent      | `302` → `/login?from=%2Fcompte`      |
+| appel d'API (`Accept: application/json`), `fetch()` (`Sec-Fetch-Mode: cors`) | `401` + `WWW-Authenticate`, inchangé |
+| `POST`, `PUT`, `DELETE`…, WebSocket                                          | refus inchangé                       |
+
+- La page de connexion ramène au chemin demandé (`from`, requête comprise) une fois connecté.
+  `from` passe par `safeRedirectPath`, la garde anti-redirection ouverte du cœur.
+- C'est toujours un **refus** : l'audit enregistre `auth.denied` / `no_credentials`, et le hook
+  `onAuthFailure` se déclenche, comme pour un `401`.
+- `entryPoint` doit être un chemin de l'origine : une adresse externe (`https://…`, `//…`) est
+  refusée au démarrage.
+- La page de connexion elle-même n'est jamais redirigée vers elle-même : si elle tombe dans la
+  zone, sa requête garde son `401`.
+- Absent (le défaut), tous les clients reçoivent le `401`.
+
 ## 🔐 Les authenticators intégrés
 
 Tous respectent le **même contrat** (`IAuthenticator`) : `supports(context)` (test bon marché : la
@@ -280,7 +313,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:279`).
+handshake des zones protégées `realtime` (`firewall.ts:302`).
 
 - **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 +353,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:1128`). Le `mode` dit comment la parcourir. Trois situations concrètes :
+(`firewall.ts:1236`). Le `mode` dit comment la parcourir. Trois situations concrètes :
 
 ### Situation 1 — humains ET machines sur la même API (`first`, le mode courant)
 
@@ -342,7 +375,7 @@ Ce qui se passe, requête par requête :
 | --- | --- | --- |
 | le cookie de session | `session` | identifié, `apikey` jamais consulté |
 | `Authorization: Bearer nf_…` | `apikey` | identifié (session ne matche pas, on passe) |
-| une clé **révoquée** `nf_…` | `apikey` | **401 direct** — l'échec d'`authenticate()` remonte, pas de fallback (`firewall.ts:1128`) |
+| une clé **révoquée** `nf_…` | `apikey` | **401 direct** — l'échec d'`authenticate()` remonte, pas de fallback (`firewall.ts:1236`) |
 | rien | aucun | **401** (Zero Trust) |
 
 ### Situation 2 — le piège de l'ordre (`anonymous` toujours EN DERNIER)
@@ -373,11 +406,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:1199`) — ici la preuve mot de passe, la plus fraîche.
+(`firewall.ts:1311`) — 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:435`) : jamais de zone
+> `Firewall.#instantiateAuthenticators()` est fail-closed (`firewall.ts:468`) : jamais de zone
 > « protégée » silencieusement ouverte à cause d'une faute de frappe.
 
 ## 🧑‍⚖️ Autorisation — rôles, scopes, voters (« as-tu le droit ? »)
@@ -463,12 +496,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 +510,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 +538,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,
@@ -513,34 +546,34 @@ scopes, métier), un même jury, combinables.
 
 ## 🔌 HTTP et WebSocket — le même firewall
 
-`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.
+`Firewall.#wireRealtime()` (`firewall.ts:301`) câble, pour toute zone protégée `realtime !== false`
+(opt-out, `firewall.ts:278`), le `FirewallRealtimeAuthenticator` au handshake (`firewall.ts:313`)
+**et** un `frameAuthorizer` (RBAC par canal, `firewall.ts:361`). 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:1216`) : le **code de fermeture** suffit.
+`firewall.ts:1345`) : le **code de fermeture** suffit.
 
 ## 🛡️ En-têtes de sécurité, CSRF, CORS
 
-- **`Firewall.applySecurityHeaders()`** (`firewall.ts:1045`) : CSP, Referrer-Policy, COOP/COEP/CORP
-  au-dessus du socle transport de `@nodefony/http`. **Nonce CSP paresseux** (`hasNonce`, `firewall.ts:1045`) :
+- **`Firewall.applySecurityHeaders()`** (`firewall.ts:1152`) : CSP, Referrer-Policy, COOP/COEP/CORP
+  au-dessus du socle transport de `@nodefony/http`. **Nonce CSP paresseux** (`hasNonce`, `firewall.ts:1081`) :
   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:971`), puis double-submit `x-csrf-token` ≡
-  cookie + HMAC (`firewall.ts:778`).
-- **`Firewall.handleCors()`** : preflight `OPTIONS` → 204 (`firewall.ts:1014`).
+- **`Firewall.enforceCsrf()`** (défense en profondeur, `firewall.ts:1042`) : Fetch Metadata
+  (`Sec-Fetch-Site`) + garde `Origin` (`firewall.ts:977`), puis double-submit `x-csrf-token` ≡
+  cookie + HMAC (`firewall.ts:628`).
+- **`Firewall.handleCors()`** : preflight `OPTIONS` → 204 (`firewall.ts:1098`).
 
 ## 📜 Normes appliquées
 
 | Domaine                | Norme           | Ancrage                                                |
 | ---------------------- | --------------- | ------------------------------------------------------ |
-| Challenge d'auth (401) | RFC 7235        | `Firewall.#setChallenge()` (`firewall.ts:1216`)        |
+| Challenge d'auth (401) | RFC 9110 §11    | `Firewall.#setChallenge()` (`firewall.ts:1345`)        |
 | 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:777-780`)            |
+| Rate limit (429)       | RFC 6585        | 429 + `Retry-After` (`firewall.ts:838-841`)            |
 | 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:818-833` (aucune preuve → 401)            |
+| CSRF                   | Fetch Metadata  | `Firewall.enforceCsrf()` (`firewall.ts:1042`)          |
+| Modèle                 | Zero Trust      | `firewall.ts:819-834` (aucune preuve → 401)            |
 
 ## ⚡ Performance & mémoire
 
@@ -553,16 +586,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

@@ -39,7 +39,7 @@ source: "src/packages/@nodefony/security/docs/headers.md"
 > (`@nodefony/http`, dès l'entrée brute — couvre aussi les fichiers statiques et les erreurs) et la
 > couche **applicative** (`@nodefony/security`, dans le pipeline — CSP, Referrer-Policy, isolation
 > cross-origin). Ancré sur `SecurityHeaders` (`securityHeaders.ts:42`) et
-> `Firewall.applySecurityHeaders()` (`firewall.ts:1045`).
+> `Firewall.applySecurityHeaders()` (`firewall.ts:1152`).
 
 📍 [Documentation](../../../../../docs/index.md) › [Sécurité](index.md) › **En-têtes de sécurité**
 
@@ -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:411`) précalcule la chaîne HSTS (`max-age`, `includeSubDomains`, `preload`) au
+  boot ; `onHttpRequest` (`http-kernel.ts:1093`) 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
@@ -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:33`), donc `use("@nodefony/security", …)` propose les clés **et** les valeurs
+du core (`index.ts:37`), 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:238`) : seul `script-src`
+**Le défaut Nodefony** est délibérément « secure-but-usable » (`config.ts:276`) : 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,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:1144`) — 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:1141`). 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:411`) : `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:1147`). 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.
 
@@ -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:278`), la valeur la plus stricte. La valeur est un
+Défaut Nodefony : `no-referrer` (`security/nodefony/config/config.ts:316`), 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).
 
@@ -359,7 +359,7 @@ propres sous-domaines ; `cross-origin` ouvre — c'est ce qu'il faut sur une CDN
 **La menace** : plusieurs origines partageant heap et processus, donc des canaux auxiliaires
 mesurables.
 
-Nodefony l'émet comme un **booléen de champ structuré** RFC 8941 : la valeur est littéralement `?1`
+Nodefony l'émet comme un **booléen de champ structuré** RFC 9651 : la valeur est littéralement `?1`
 (`securityHeaders.ts:75`). C'est une **demande**, pas une garantie — le navigateur décide.
 
 ### `Permissions-Policy` — coupe le micro par défaut
@@ -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:206`).
+Dérivé du schéma Zod `headersSchema` (`config.ts:256`).
 
 <!-- prettier-ignore -->
 | Option | Type | Défaut | Effet |
@@ -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:461`)
 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:257`, `config.ts:257`, `config.ts:257`, `config.ts:257`) mais **ne pilotent rien** : la couche
+> (`config.ts:263`, `config.ts:263`, `config.ts:263`, `config.ts:263`) 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:282`) : Nodefony n'émet aucun
+> **du module http**. Même remarque pour `hidePoweredBy` (`config.ts:288`) : 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,20 +439,20 @@ 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:1045`) lit `context.cspNonce` —
+2. **Par requête**, `Firewall.applySecurityHeaders()` (`firewall.ts:1152`) 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
    `<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:1666`). 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,9 +476,9 @@ 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:1101`), jamais par requête. Le merge d'une route
+(`Firewall.#rebuildSecurityHeaders()`, `firewall.ts:1209`), 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
 
@@ -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:1099`) retire le fragment et
+- **Réversible** : `Firewall.unregisterCspOrigins()` (`firewall.ts:1202`) 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:1113`), jamais d'un CSP déjà fusionné — pas d'accumulation entre deux
+  (`firewall.ts:1212`), 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:1034`) — ce qui explique qu'un CSP observé
+`FrontendService.#viteCspFragment()` (`FrontendService.ts:804`) — 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: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:267`)                 |
+| HSTS                                 | RFC 6797                         | posé sur TLS uniquement (`http-kernel.ts:981`)               |
+| Champ structuré booléen              | RFC 9651                         | `Origin-Agent-Cluster: ?1` (`securityHeaders.ts:75`)         |
+| Referrer-Policy                      | W3C Referrer Policy (enum fermé) | 8 valeurs validées au boot (`config.ts:273`)                 |
 | 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:1141`)              |
+| Durcissement en-têtes                | OWASP Secure Headers             | `computeSecurityHeaderCaches()` (`http-kernel.ts:411`)       |
 
 ## ⚡ 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
+  l'enregistrement (`firewall.ts:1142`) ; 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:1131-1137`), 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
@@ -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:555`), qui projette la config **sans aucun secret**,
+viennent de `Firewall.describe()` (`firewall.ts:588`), 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:969`)                              | Comportement conforme RFC 6797 — vérifier sur le port HTTPS                     |
+| HSTS absent en développement                             | Posé sur TLS uniquement (`http-kernel.ts:981`)                              | 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

@@ -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.
 
@@ -59,9 +59,11 @@ Quatre parcours selon ce que tu viens faire. L'ordre compte : chaque étape supp
 **J'ouvre un login à des humains** — navigateur, comptes, second facteur.
 
 1. [Authenticators](authenticators.md) — la session BFF, et pourquoi le login est **déjà fourni**.
-2. [OAuth2](oauth2.md) — « se connecter avec GitHub/Google » et le Shadow User.
-3. [WebAuthn / passkeys](webauthn.md) — se connecter sans mot de passe, résistant au phishing.
-4. [TOTP](totp.md) — le second facteur classique, et l'élévation de privilège (step-up).
+2. [Page de connexion](login-page.md) — la page servie à `/login`, et comment l'habiller à ton nom.
+3. [OAuth2](oauth2.md) — « se connecter avec GitHub/Google » et le Shadow User.
+4. [Keycloak](keycloak.md) — brancher l'annuaire de l'entreprise, du realm au premier login.
+5. [WebAuthn / passkeys](webauthn.md) — se connecter sans mot de passe, résistant au phishing.
+6. [TOTP](totp.md) — le second facteur classique, et l'élévation de privilège (step-up).
 
 **J'audite avant une mise en production** — la passe qu'on regrette de ne pas avoir faite.
 
@@ -86,7 +88,9 @@ Le tableau pour choisir en cinq secondes ; les cards en dessous pour le détail.
 | [CSRF](csrf.md)                         | requête authentifiée forgée par un site tiers | tu sers un front avec cookie de session          |
 | [CORS](cors.md)                         | lecture cross-origine de tes réponses         | ton front est sur un autre domaine               |
 | [En-têtes](headers.md)                  | CSP, HSTS, COOP/COEP, Referrer-Policy         | tu sers du HTML à un navigateur                  |
+| [Page de connexion](login-page.md)      | la page `/login` servie, habillable           | des humains se connectent à ton application      |
 | [OAuth2](oauth2.md)                     | login social + provisionnement d'identité     | « se connecter avec … »                          |
+| [Keycloak](keycloak.md)                 | connexion par l'annuaire auto-hébergé         | tes comptes vivent dans un realm Keycloak        |
 | [WebAuthn](webauthn.md)                 | passkeys, connexion résistante au phishing    | tu veux supprimer les mots de passe              |
 | [TOTP](totp.md)                         | second facteur temporel + step-up             | 2FA, ou re-preuve avant une action sensible      |
 | [Webhooks](webhooks.md)                 | notifier un tiers, signé et sans SSRF         | un système externe doit réagir à tes événements  |
@@ -98,11 +102,14 @@ 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.",
     "meta": "juste après les authenticators — authentifier sans autoriser ne protège rien" },
+  { "icon": "🚪", "title": "page de connexion", "href": "login-page.md",
+    "desc": "La page servie à /login : identifiant, mot de passe, second facteur, boutons des fournisseurs, thèmes clair et sombre. Textes, panneau et couleurs se règlent par la configuration et une feuille de style — sans copier son balisage.",
+    "meta": "le piège : une couleur qui dépend du thème se redéfinit pour les DEUX thèmes" },
   { "icon": "🎫", "title": "tokens", "href": "tokens.md",
     "desc": "L'identité matérialisée : émission, keystore, rotation, révocation — et le choix structurant du framework, session opaque côté serveur pour le web, JWT pour les API.",
     "meta": "et pourquoi ce n'est pas « full stateless »" },
@@ -155,6 +162,7 @@ sans ouvrir de port (profil console) :
 | `nodefony security:user:delete <id>` | supprime, après confirmation ; refuse le dernier administrateur |
 | `nodefony security:secrets [--write]` | engendre les clés attendues et guide leur câblage |
 | `nodefony security:token` | émet un jeton d'accès pour la porte MCP |
+| `nodefony security:keycloak:realm [--write\|--check]` | écrit le realm Keycloak déduit de la configuration ([Keycloak](keycloak.md)) |
 
 En terminal, le mot de passe est **demandé masqué** et confirmé ; pour un script, `--password <pwd>`
 l'accepte en argument — au prix de l'historique du shell, que la commande rappelle.
@@ -167,7 +175,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.
 
@@ -176,7 +184,7 @@ au boot. Blocs : `areas` (zones + authenticators), `cors`, `csrf`, `headers`, `l
 <!-- prettier-ignore -->
 | Domaine | Normes |
 | --- | --- |
-| Auth / challenge (401) | RFC 7235 |
+| Auth / challenge (401) | RFC 9110 §11 |
 | JWT | RFC 7519, 8725 (BCP) |
 | OAuth 2 | RFC 9700 (BCP), 8707, 8693, 9449 (DPoP) |
 | Passkeys | W3C WebAuthn L3, CTAP2 |