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

package/docs/cors.md

@@ -103,13 +103,13 @@ Trois conséquences que beaucoup de développeurs découvrent trop tard :
 `Cors` (`cors.ts:33`) est une classe **pure et synchrone** : elle ne touche ni au réseau, ni à la
 requête — elle prend une origine et renvoie la table des en-têtes à poser, ou `null`. Elle est
 instanciée **une seule fois au boot** par le firewall, si et seulement si la section est activée
-(`firewall.ts:239-240`). Conséquence directe : la politique est **testable sans serveur**, et son coût par
+(`firewall.ts:240-241`). Conséquence directe : la politique est **testable sans serveur**, et son coût par
 requête se réduit à une lecture de `Set` (voir Performance).
 
 Trois invariants de sécurité, tenus par construction :
 
 - **Jamais `*` avec credentials.** La combinaison est **rejetée au boot** par un `refine` Zod
-  (`config.ts:156-159`) — le navigateur la refuserait de toute façon. Défense en profondeur : même
+  (`config.ts:162-165`) — le navigateur la refuserait de toute façon. Défense en profondeur : même
   instanciée à la main avec cette combinaison, `Cors.#allowOrigin()` **reflète l'origine** au lieu
   d'émettre `*` (`cors.ts:58`).
 - **Reflet d'origine ⇒ `Vary: Origin`.** Dès que la valeur `Allow-Origin` n'est pas `*`, la politique
@@ -204,8 +204,8 @@ curl -si http://localhost:5151/api/articles -H 'Origin: https://evil.com'
 
 ## ⚙️ Configuration et mises en situation
 
-La section `cors` de la config du module (`corsSchema`, `config.ts:129` ; branchée à la racine en
-`config.ts:1137`). Toutes les clés ont un défaut sûr — une section omise donne une politique **fermée**.
+La section `cors` de la config du module (`corsSchema`, `config.ts:179` ; branchée à la racine en
+`config.ts:1143`). Toutes les clés ont un défaut sûr — une section omise donne une politique **fermée**.
 
 <!-- prettier-ignore -->
 | Option | Type | Défaut | Effet |
@@ -242,7 +242,7 @@ cors: {
 | `Origin: https://app.example.com:8443`   | rien — le **port** fait partie de l'origine, match exact                             |
 | `Origin: https://sub.app.example.com`    | rien — un sous-domaine n'est **pas** couvert par le parent                           |
 | `Origin: http://app.example.com`         | rien — le **scheme** fait partie de l'origine (downgrade refusé)                     |
-| aucun `Origin` (même origine, ou `curl`) | rien — la requête suit le pipeline normal (`firewall.ts:1013`)                       |
+| aucun `Origin` (même origine, ou `curl`) | rien — la requête suit le pipeline normal (`firewall.ts:1019`)                       |
 
 ### Situation 2 — une API publique en lecture seule (le joker `*`)
 
@@ -273,7 +273,7 @@ cors: { origins: ["https://app.example.com", "https://admin.example.com"], crede
 
 > [!WARNING]
 > `origins: ["*"]` **avec** `credentials: true` est rejeté par le schéma Zod au démarrage
-> (`config.ts:156-159`), avec un message qui dit quoi faire. La raison n'est pas cosmétique : cette
+> (`config.ts:194-197`), avec un message qui dit quoi faire. La raison n'est pas cosmétique : cette
 > combinaison, si un serveur la contournait en reflétant chaque origine, laisserait **tout site du
 > web** lire les réponses authentifiées de tes utilisateurs. Ne « corrige » jamais cette erreur en
 > reflétant l'origine reçue sans la valider.
@@ -322,23 +322,23 @@ sequenceDiagram
   R-->>B: 200 + Access-Control-*
 ```
 
-`Firewall.handleCors()` (`firewall.ts:1007`) est appelé **en tête de** `HttpKernel.handleHttp()`
-(`http-kernel.ts:1456`), à la ligne `http-kernel.ts:1456` — **avant le routing**. La raison est
+`Firewall.handleCors()` (`firewall.ts:1098`) est appelé **en tête de** `HttpKernel.handleHttp()`
+(`http-kernel.ts:1553`), à la ligne `http-kernel.ts:1553` — **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.
 
-Quatre sorties en no-op, dans cet ordre (`firewall.ts:1007`) :
+Quatre sorties en no-op, dans cet ordre (`firewall.ts:1013`) :
 
 1. CORS désactivé ⇒ `#cors` est `null`, retour immédiat ;
-2. pas d'en-tête `Origin` ⇒ requête same-origin ou client non-navigateur (`firewall.ts:1013`) ;
+2. pas d'en-tête `Origin` ⇒ requête same-origin ou client non-navigateur (`firewall.ts:1019`) ;
 3. la réponse n'expose pas `setHeader` ⇒ c'est un **WebSocket**, il n'y a pas d'en-tête HTTP à poser
-   (`firewall.ts:83`) ;
+   (`firewall.ts:94`) ;
 4. origine hors allowlist ⇒ la table est `null`, aucun en-tête n'est posé — mais un preflight reste
-   court-circuité en 204 (`firewall.ts:1032`).
+   court-circuité en 204 (`firewall.ts:1038`).
 
 **La détection du preflight est stricte** : méthode `OPTIONS` **et** présence de
-`Access-Control-Request-Method` (`firewall.ts:1018-1020`). Un `OPTIONS` nu — celui d'un client qui interroge
+`Access-Control-Request-Method` (`firewall.ts:1054-1056`). Un `OPTIONS` nu — celui d'un client qui interroge
 les méthodes supportées d'une route — est donc traité comme une requête réelle et continue le pipeline.
 
 ### Ce que chaque moment pose
@@ -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:1630`) : une police ou une image servie cross-origin reçoit les mêmes en-têtes que
+  (`http-kernel.ts:1661`) : 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`
@@ -371,12 +371,12 @@ Trois briques voisines, souvent confondues. Une seule ligne chacune :
 | **[En-têtes](./headers.md)** (CSP, COOP) | ce que la **page** a le droit de faire | dans le navigateur     | XSS, injection, fenêtres croisées    |
 
 Les deux premières se parlent. Au boot, la liste des origines de confiance CSRF est l'**union** de
-`csrf.trustedOrigins` et de `cors.origins` (`firewall.ts:605`) : ce que tu autorises explicitement en
+`csrf.trustedOrigins` et de `cors.origins` (`firewall.ts:640`) : ce que tu autorises explicitement en
 CORS ne peut pas être, au même instant, traité comme une tentative CSRF.
 
 L'inverse n'est pas vrai, et c'est délibéré : `csrf.trustedOrigins` déclare un **alias de domaine**
 légitime de ton app (une façade multi-domaine) sans pour autant exposer tes réponses au JS de cette
-origine (`config.ts:188`). Ajouter une origine à `cors.origins` est **plus** permissif que l'ajouter à
+origine (`config.ts:194`). Ajouter une origine à `cors.origins` est **plus** permissif que l'ajouter à
 `csrf.trustedOrigins`.
 
 ## 🔌 Et le WebSocket ?
@@ -384,10 +384,10 @@ origine (`config.ts:188`). Ajouter une origine à `cors.origins` est **plus** pe
 **Les navigateurs n'appliquent pas CORS aux WebSockets.** Une page tierce peut ouvrir un
 `new WebSocket("wss://api.example.com/…")` et le handshake partira **avec le cookie de session de la
 victime** : c'est le CSWSH. C'est pourquoi `handleCors` s'arrête net sur un contexte WS
-(`firewall.ts:1007`) — il n'y aurait rien à protéger avec des en-têtes que personne ne lit.
+(`firewall.ts:1098`) — il n'y aurait rien à protéger avec des en-têtes que personne ne lit.
 
 La garde équivalente vit dans le transport : `HttpKernel.checkWebsocketOrigin()`
-(`http-kernel.ts:621`) valide l'`Origin` **au handshake**, avant l'accept, et ferme en code WS `1008`
+(`http-kernel.ts:724`) valide l'`Origin` **au handshake**, avant l'accept, et ferme en code WS `1008`
 si elle est refusée. Sa doctrine :
 
 - **same-origin par défaut** : l'`Origin` du handshake doit correspondre au `Host` servi ;
@@ -405,11 +405,11 @@ Deux réglages distincts, parce que deux mécanismes navigateur distincts.
 | Sujet                             | Norme                       | Comment le code s'y conforme                                                |
 | --------------------------------- | --------------------------- | --------------------------------------------------------------------------- |
 | Protocole CORS                    | Fetch Standard (WHATWG)     | `Cors` (`cors.ts:33`) — preflight vs requête réelle séparés                 |
-| Preflight sans credentials        | Fetch Standard              | court-circuit en 204 avant auth/routing (`firewall.ts:1032`)                |
-| `*` incompatible avec credentials | Fetch Standard · OWASP CORS | rejet au boot (`config.ts:156-159`) + reflet défensif (`cors.ts:58`)        |
+| Preflight sans credentials        | Fetch Standard              | court-circuit en 204 avant auth/routing (`firewall.ts:1038`)                |
+| `*` incompatible avec credentials | Fetch Standard · OWASP CORS | rejet au boot (`config.ts:162-165`) + reflet défensif (`cors.ts:58`)        |
 | Correction de cache               | RFC 9110 (`Vary`)           | `Vary: Origin` dès que l'origine est reflétée (`cors.ts:81`, `cors.ts:94`)  |
 | Comparaison d'origines            | RFC 6454 (Web Origin)       | match **exact** `scheme://host:port` — `Cors.#allowOrigin()` (`cors.ts:57`) |
-| Anti-CSWSH                        | OWASP WSTG-CLNT-10          | `HttpKernel.checkWebsocketOrigin()` (`http-kernel.ts:621`)                  |
+| Anti-CSWSH                        | OWASP WSTG-CLNT-10          | `HttpKernel.checkWebsocketOrigin()` (`http-kernel.ts:724`)                  |
 
 ## ⚡ Performance & mémoire
 
@@ -419,18 +419,18 @@ ne reste à l'exécution qu'un `Set.has()` sur l'origine.
 
 Le coût par requête est donc :
 
-- **0 pour une requête same-origin** — pas d'en-tête `Origin`, sortie immédiate (`firewall.ts:1013`) ;
-- **0 pour un WebSocket** — sortie sur l'absence de `setHeader` (`firewall.ts:83`) ;
-- **0 si la section est désactivée** — `#cors` reste `null`, aucun objet n'est alloué (`firewall.ts:166`) ;
+- **0 pour une requête same-origin** — pas d'en-tête `Origin`, sortie immédiate (`firewall.ts:1019`) ;
+- **0 pour un WebSocket** — sortie sur l'absence de `setHeader` (`firewall.ts:94`) ;
+- **0 si la section est désactivée** — `#cors` reste `null`, aucun objet n'est alloué (`firewall.ts:184`) ;
 - **une petite table d'en-têtes** allouée uniquement pour une requête cross-origin autorisée. Une
   origine refusée n'alloue rien du tout (retour `null` avant construction de la table, `cors.ts:74`).
 
 ## 📡 Observabilité — Studio
 
 La configuration CORS **résolue** (celle qui tourne réellement, pas le fichier source) est exposée par
-`Firewall.describe()` (`firewall.ts:555`), qui délègue à `Firewall.#describeDefenses()`
-(`firewall.ts:591`). La projection CORS y expose `origins`, `credentials`, `methods`,
-`allowedHeaders`, `exposedHeaders` et `maxAgeS` (`firewall.ts:610`) — aucun secret ne transite par
+`Firewall.describe()` (`firewall.ts:588`), qui délègue à `Firewall.#describeDefenses()`
+(`firewall.ts:643`). La projection CORS y expose `origins`, `credentials`, `methods`,
+`allowedHeaders`, `exposedHeaders` et `maxAgeS` (`firewall.ts:645`) — aucun secret ne transite par
 cette surface.
 
 - **Data plane** : `GET /nodefony/security/api/firewall` (`SecurityAdminApi.ts:328`), protégé
@@ -447,7 +447,7 @@ secondes les « pourtant j'ai bien mis l'origine ».
 
 | Symptôme                                                  | Cause                                                                                  | Correction                                                                                |
 | --------------------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
-| Le boot échoue sur la config CORS                         | `origins:["*"]` **et** `credentials:true` (`config.ts:156-159`)                        | Lister les origines, ou passer `credentials:false`                                        |
+| Le boot échoue sur la config CORS                         | `origins:["*"]` **et** `credentials:true` (`config.ts:194-197`)                        | Lister les origines, ou passer `credentials:false`                                        |
 | Requête bloquée alors que l'origine « est » dans la liste | Match **exact** : port, scheme ou sous-domaine divergent                               | Écrire l'origine complète `scheme://host:port`, une entrée par variante                   |
 | `curl` fonctionne, le navigateur non                      | CORS s'applique dans le navigateur, pas au serveur                                     | Normal — reproduire avec un `Origin` explicite (`curl -H 'Origin: …'`)                    |
 | Cookie non envoyé malgré `credentials:true`               | Opt-in serveur seul : le client n'a pas `credentials: "include"`                       | Activer les deux côtés (et un cookie `SameSite=None; Secure` en cross-site)               |
@@ -455,7 +455,7 @@ secondes les « pourtant j'ai bien mis l'origine ».
 | Le preflight échoue sur un en-tête custom                 | `allowedHeaders` est statique, il ne reflète pas la demande du client (`cors.ts:78`)   | Déclarer l'en-tête dans `cors.allowedHeaders`                                             |
 | Un cache sert la réponse d'une origine à une autre        | `Vary: Origin` écrasé en aval (la politique le pose, `cors.ts:81`)                     | Ne pas `setHeader("Vary", …)` dans un controller — utiliser `appendHeader`                |
 | `OPTIONS` renvoie 405 au lieu de 204                      | Requête `OPTIONS` **sans** `Access-Control-Request-Method` : ce n'est pas un preflight | Envoyer l'en-tête, ou déclarer une route `OPTIONS`                                        |
-| Page tierce qui ouvre un WebSocket authentifié            | CORS ne couvre pas le WS                                                               | C'est `checkWebsocketOrigin` qui garde (`http-kernel.ts:621`) — vérifier `allowedOrigins` |
+| Page tierce qui ouvre un WebSocket authentifié            | CORS ne couvre pas le WS                                                               | C'est `checkWebsocketOrigin` qui garde (`http-kernel.ts:724`) — vérifier `allowedOrigins` |
 | Ouverture CORS « temporaire » restée en production        | `origins:["*"]` posé en dev                                                            | Vérifier la valeur **résolue** dans Studio, pas le fichier source                         |
 
 ## 🧪 Tests & couverture

package/docs/csrf.md

@@ -91,9 +91,9 @@ contrôleur** : l'attaque meurt sans avoir touché ton code.
 ## La vision Nodefony
 
 - **Vérifier la provenance d'abord** (OWASP 2025, modèle Go 1.25 `CrossOriginProtection`) : la
-  couche 1 est la défense **par défaut**, `csrf.enabled: true` (`config.ts:163-168`).
+  couche 1 est la défense **par défaut**, `csrf.enabled: true` (`config.ts:169-174`).
 - **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:1747`) arrive **après** le
+  branchée dans le pipeline HTTP — l'appel `enforceCsrf` (`http-kernel.ts:1854`) 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 —
@@ -148,13 +148,13 @@ export default ProfileController;
 
 (Wiring : `@controllers([ProfileController])` dans le module de l'app — `nodefony create controller`
 le fait pour toi. Posé sur la **classe**, `@CsrfProtect()` couvre toutes les actions : les marqueurs
-`csrfProtect`/`csrfExempt` acceptent méthode OU classe, `routerDecorators.ts:1650-1655`.)
+`csrfProtect`/`csrfExempt` acceptent méthode OU classe, `routerDecorators.ts:1750-1755`.)
 
 ### Comment le front obtient — puis rejoue — le token
 
 1. **Obtenir** : une requête **sûre** (GET) vers n'importe quelle route `@CsrfProtect` sème le token
-   (`firewall.ts:958-964`) ; la réponse pose le cookie **lisible** `csrf-token` — non `HttpOnly`
-   exprès, `SameSite=Strict`, `Secure` en HTTPS (`HttpContext.writeHead()`, `HttpContext.ts:482-497`).
+   (`firewall.ts:994-1000`) ; la réponse pose le cookie **lisible** `csrf-token` — non `HttpOnly`
+   exprès, `SameSite=Strict`, `Secure` en HTTPS (`HttpContext.writeHead()`, `HttpContext.ts:570-590`).
 2. **Rejouer** : le SPA lit le cookie et renvoie sa valeur **à l'identique** dans l'en-tête
    `x-csrf-token` sur chaque mutation.
 
@@ -199,7 +199,7 @@ curl -si -b /tmp/jar -H "x-csrf-token: $TOKEN" \
 > [!IMPORTANT]
 > En **prod/cluster**, le secret du synchronizer doit être **fixé et partagé entre process** —
 > absent, un secret **éphémère** est généré (dev) : un redémarrage invalide les tokens en cours, et
-> chaque pod rejette les tokens des autres (`firewall.ts:225-234`). Générer et câbler :
+> chaque pod rejette les tokens des autres (`firewall.ts:226-235`). Générer et câbler :
 > `npx nodefony security:secrets` (`security-secrets.ts:39`) → `NF_CSRF_SECRET` →
 > `use("@nodefony/security", { csrf: { secret: ctx.env.NF_CSRF_SECRET } })`.
 
@@ -241,12 +241,12 @@ autorisation :
 ```
 
 > [!WARNING]
-> `@CsrfExempt` (`routerDecorators.ts:1142`) est un opt-out **ciblé CSRF**. Ne jamais « débloquer un
+> `@CsrfExempt` (`routerDecorators.ts:1165`) est un opt-out **ciblé CSRF**. Ne jamais « débloquer un
 > webhook » avec `@BypassFirewall`/`@Anonymous` : eux désactivent l'authentification de la zone.
 
 Cas voisin — **façade multi-domaine** (`www.example.com` poste vers l'API d'un autre domaine à toi) :
 déclarer l'alias dans `csrf.trustedOrigins` (match exact d'origine), pas dans `cors.origins` — CORS
-ouvrirait **aussi** la lecture des réponses au JS tiers (`config.ts:188-193`).
+ouvrirait **aussi** la lecture des réponses au JS tiers (`config.ts:194-199`).
 
 ## 🏗️ Architecture interne
 
@@ -257,7 +257,7 @@ sûres → coût nul sur le GET dominant (`csrf.ts:88`). Pour une mutation, dans
 
 1. **Origine de confiance** — `csrf.trustedOrigins` ∪ whitelist CORS → passe même en cross-site : ce
    que CORS autorise déjà explicitement **n'est pas** du CSRF (`csrf.ts:45`, union construite par le
-   firewall au boot, `firewall.ts:217-220`).
+   firewall au boot, `firewall.ts:218-221`).
 2. **Fetch Metadata** (`Sec-Fetch-Site`, infalsifiable par un script) : `same-origin`/`none` → OK ;
    `same-site` → OK sauf `strictSameSite` (`csrf.ts:102-104`) ; `cross-site` → **403** ; valeur
    inconnue → on **délègue au repli** (forward-compat, le W3C dit « SHOULD ignore », `csrf.ts:98-109`).
@@ -268,10 +268,10 @@ sûres → coût nul sur le GET dominant (`csrf.ts:88`). Pour une mutation, dans
 Lectures durcies côté firewall :
 
 - en-têtes lus en **première occurrence** — jamais un tableau d'en-têtes répétés (garde d'injection,
-  `headerValue()`, `firewall.ts:103`) ; cookie extrait de l'en-tête **brut**, sans dépendre du
-  parse du contexte (`cookieValue()`, `firewall.ts:116-129`) ;
+  `headerValue()`, `firewall.ts:114`) ; cookie extrait de l'en-tête **brut**, sans dépendre du
+  parse du contexte (`cookieValue()`, `firewall.ts:117-130`) ;
 - hôte cible **brut avec port** — `:authority` en HTTP/2, `context.domain` en dernier recours
-  (`firewall.ts:977-982`) ;
+  (`firewall.ts:983-988`) ;
 - le refus est un `CsrfError` **403 au message générique** : la politique (en-têtes inspectés,
   whitelist) ne fuite jamais au client (`CsrfError.ts:17-21`).
 
@@ -296,28 +296,30 @@ de session (TSDoc `CsrfTokenManager`, `csrfToken.ts:12-15`).
 1. `@CsrfProtect`/`@CsrfExempt` posent un **marqueur** de metadata — zéro import de
    `@nodefony/security` côté framework, zéro cycle (`routerDecorators.ts:886`).
 2. Au match de la route, `Resolver.match()` recopie les marqueurs sur le contexte
-   (`Resolver.ts:156-186`) — champs portés par le `Context` de base, HTTP comme WS
+   (`Resolver.ts:160-190`) — champs portés par le `Context` de base, HTTP comme WS
    (`Context.ts:241-243`).
-3. `Firewall.enforceCsrf()` (`firewall.ts:948`) fait les trois rôles : **émission** du token sur
+3. `Firewall.enforceCsrf()` (`firewall.ts:1042`) fait les trois rôles : **émission** du token sur
    requête sûre `@CsrfProtect`, **couche 1** sur toute mutation, **couche 2** en plus si
-   `@CsrfProtect`. Les routes `bypassFirewall` (callbacks OAuth) sont exemptées
-   (`firewall.ts:950-953`), les `@CsrfExempt` sortent après la barrière méthode sûre
-   (`firewall.ts:967`).
+   `@CsrfProtect`. Seules les `@CsrfExempt` sortent, après la barrière méthode sûre
+   (`firewall.ts:1062`). Une route `bypassFirewall` n'est **pas** exemptée : le bypass retire
+   l'authentification, pas la provenance — les routes de connexion sont en bypass, et c'est là
+   qu'un formulaire tiers ouvrirait une session sur le compte de l'attaquant (login CSRF,
+   CWE-352, `firewall.ts:1035`).
 4. `HttpContext.writeHead()` matérialise `context.csrfToken` en cookie `csrf-token` — flush groupé
-   avec le cookie de session (`HttpContext.ts:482-497`).
+   avec le cookie de session (`HttpContext.ts:636-655`).
 
-## ⚙️ Configuration (schéma Zod `csrfSchema`, `config.ts:161-204`)
+## ⚙️ Configuration (schéma Zod `csrfSchema`, `config.ts:167-210`)
 
 <!-- prettier-ignore -->
 | Option | Type · défaut | Effet |
 | --- | --- | --- |
-| `enabled` | boolean · `true` | Active toute la défense — couches 1 **et** 2 (`config.ts:163-168`). |
-| `fetchMetadata` | boolean · `true` | Défense primaire `Sec-Fetch-Site` (`config.ts:169-174`). |
-| `checkOrigin` | boolean · `true` | Repli `Origin`/`Referer` same-host pour les navigateurs sans `Sec-Fetch-*` (`config.ts:176-181`). |
-| `strictSameSite` | boolean · `false` | `true` = refuser aussi `same-site` (sous-domaine non maîtrisé / multi-tenant) — distinct de l'attribut cookie (`config.ts:182-187`). |
-| `sameSite` | enum · `Lax` | **Déclaratif** : surfacé dans l'introspection (`firewall.ts:604`) ; l'attribut effectif du cookie `csrf-token` est `Strict` en dur (`HttpContext.ts: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`). |
+| `enabled` | boolean · `true` | Active toute la défense — couches 1 **et** 2 (`config.ts:169-174`). |
+| `fetchMetadata` | boolean · `true` | Défense primaire `Sec-Fetch-Site` (`config.ts:207-212`). |
+| `checkOrigin` | boolean · `true` | Repli `Origin`/`Referer` same-host pour les navigateurs sans `Sec-Fetch-*` (`config.ts:182-187`). |
+| `strictSameSite` | boolean · `false` | `true` = refuser aussi `same-site` (sous-domaine non maîtrisé / multi-tenant) — distinct de l'attribut cookie (`config.ts:220-225`). |
+| `sameSite` | enum · `Lax` | **Déclaratif** : surfacé dans l'introspection (`firewall.ts:650`) ; l'attribut effectif du cookie `csrf-token` est `Strict` en dur (`HttpContext.ts:634`). |
+| `trustedOrigins` | string[] · `[]` | Alias **exacts** (`scheme://host[:port]`) autorisés même cross-site — sans ouvrir la lecture CORS (`config.ts:226-231`). |
+| `secret` | string ≥ 16 car. · — | Secret HMAC du synchronizer — PROD : via env, **partagé cluster** ; absent = éphémère dev (`config.ts:232-238`). |
 
 ## 📜 Normes appliquées
 
@@ -334,19 +336,19 @@ de session (TSDoc `CsrfTokenManager`, `csrfToken.ts:12-15`).
 ## ⚡ Performance & mémoire
 
 - **GET = 0** : retour immédiat avant toute lecture d'en-tête (`csrf.ts:88`) ; seule exception, une
-  route `@CsrfProtect` mint le token **une fois** (skip si déjà posé, `firewall.ts:946`).
+  route `@CsrfProtect` mint le token **une fois** (skip si déjà posé, `firewall.ts:1025`).
 - **Zéro microtask** : la chaîne est synchrone de bout en bout (pas d'`async` pour du pur calcul).
 - **Lazy** : `#csrf`/`#csrfTokens` restent `null` si la défense est désactivée — aucune structure
-  allouée « au cas où » (`firewall.ts:164`).
+  allouée « au cas où » (`firewall.ts:165`).
 - 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:205`).
+  marqueurs sont lus depuis le memo de route — 0 `Reflect` par requête (`Resolver.ts:209`).
 
 ## 📡 Observabilité — Studio
 
 L'écran **Firewall** de Studio expose la défense dans son onglet Défenses (`FirewallDefenses`,
 `Firewall.tsx:313-314`). La projection est **sans secret par construction** :
-`Firewall.#describeDefenses()` (`firewall.ts:591`) publie la config résolue, et `synchronizerToken`
-n'est que la **présence** du secret armé — jamais sa valeur (`firewall.ts:607`).
+`Firewall.#describeDefenses()` (`firewall.ts:643`) publie la config résolue, et `synchronizerToken`
+n'est que la **présence** du secret armé — jamais sa valeur (`firewall.ts:653`).
 
 ## ⚠️ Pièges (symptôme → cause → correction)
 
@@ -354,8 +356,8 @@ n'est que la **présence** du secret armé — jamais sa valeur (`firewall.ts:60
 | ---------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
 | Mutation légitime cross-domaine bloquée en 403 | Domaine alias non déclaré                                                                      | Ajouter l'origine à `csrf.trustedOrigins` (ou CORS si lecture voulue)     |
 | Client non-navigateur (curl/CI) refusé         | N'arrive pas sur une route non décorée : ni Fetch Metadata ni `Origin` → passe (`csrf.ts:113`) | Attendu ; sur `@CsrfProtect`, semer le token (GET) avant la mutation      |
-| `@CsrfProtect` échoue en 403 côté SPA          | En-tête `x-csrf-token` non rejoué, ou ≠ cookie (`firewall.ts:778-783`)                         | Relire le cookie `csrf-token` et le rejouer à l'identique                 |
-| Tokens invalidés au redémarrage / entre pods   | `csrf.secret` absent → secret éphémère par process (`firewall.ts:227-237`)                     | Fixer `csrf.secret` (≥ 16 car., partagé cluster) — `security:secrets`     |
+| `@CsrfProtect` échoue en 403 côté SPA          | En-tête `x-csrf-token` non rejoué, ou ≠ cookie (`firewall.ts:839-844`)                         | Relire le cookie `csrf-token` et le rejouer à l'identique                 |
+| Tokens invalidés au redémarrage / entre pods   | `csrf.secret` absent → secret éphémère par process (`firewall.ts:233-243`)                     | Fixer `csrf.secret` (≥ 16 car., partagé cluster) — `security:secrets`     |
 | `same-site` refusé alors qu'attendu OK         | `strictSameSite` activé (`csrf.ts:102-104`)                                                    | Le désactiver si les sous-domaines sont de confiance                      |
 | `http://` accepté par le repli (même hôte)     | Le repli compare l'**hôte seul**, jamais le scheme (`Csrf.#sameHost()`, `csrf.ts:130-136`)     | Limite documentée (banc red-team) ; Fetch Metadata prime sur nav. moderne |
 | Webhook provider bloqué en 403                 | POST cross-site légitime, hors whitelist                                                       | `@CsrfExempt` sur la route — jamais `@BypassFirewall`                     |

package/docs/external-jwt.md

@@ -33,9 +33,9 @@ Accepter un émetteur ne veut pas dire lui remettre les clés. Deux décisions r
 sont elles qui font la différence entre « intégrer un annuaire » et « en faire l'unique autorité
 d'accès » :
 
-1. **La liste des émetteurs acceptés** est une allowlist (`config.ts:666-671`). Un jeton dont l'`iss` n'y figure pas est
+1. **La liste des émetteurs acceptés** est une allowlist (`trustedIssuerSchema`, `config.ts:710`). Un jeton dont l'`iss` n'y figure pas est
    refusé **avant toute requête sortante** — l'application ne va pas interroger un émetteur inconnu.
-2. **Le sujet du jeton ne devient pas d'office un utilisateur** (`config.ts:672-677`). Par défaut, il
+2. **Le sujet du jeton ne devient pas d'office un utilisateur** (`config.ts:678-683`). Par défaut, il
    doit correspondre à un compte local. Un annuaire d'entreprise vaut pour des milliers de personnes : les accepter
    toutes parce que leur jeton est valide supprimerait la seconde décision, qui est la raison d'être
    du pare-feu.
@@ -89,7 +89,7 @@ normalisés (RFC 8414 / OpenID), et le pare-feu accepte désormais un `Authoriza
 Un `sub` n'est unique que **dans l'espace de son émetteur** (OIDC Core §2). L'identité est donc la
 paire `(émetteur, sujet)`, jamais le sujet seul.
 
-En mode `prefixed` (`config.ts:656-660`), l'identifiant cherché localement est `<issuer>#<sub>` : deux émetteurs ne peuvent
+En mode `prefixed` (`config.ts:723-727`), l'identifiant cherché localement est `<issuer>#<sub>` : deux émetteurs ne peuvent
 pas se disputer un compte, et surtout **aucun sujet étranger ne peut tomber par hasard sur un
 identifiant local existant**. En mode `subject`, le `sub` est cherché tel quel — dans un annuaire où
 l'utilisateur choisit son identifiant, quelqu'un peut alors se présenter avec `sub: "admin"` et être
@@ -104,13 +104,45 @@ parce qu'il **est** cette application, ou parce que ses sujets sont déjà des i
   Absent, désactivé ou verrouillé : l'accès est refusé. C'est le mode d'une application dont les
   utilisateurs existent chez elle, l'émetteur ne servant qu'à les authentifier.
 - **`ephemeral`** — aucun compte local n'est exigé ni créé ; l'appelant vit le temps de la requête
-  avec les rôles d'`ephemeralRoles` (`config.ts:678`). C'est le mode de l'appelant **purement machine** : un agent, un
+  avec les rôles d'`ephemeralRoles` (`config.ts:745`). C'est le mode de l'appelant **purement machine** : un agent, un
   service. Sans rôle déclaré, il ne passe aucun `@IsGranted` et n'est autorisé que par ses **scopes**
   — qui viennent du jeton, donc bornés par le serveur d'autorisation.
 
 > Écrire un rôle dans `ephemeralRoles` accorde un pouvoir local à quiconque détient un jeton valide
 > pour cette ressource. À faire sciemment, jamais par confort.
 
+### Une politique PAR ZONE
+
+`resourceServer.subjectPolicy` vaut pour toute l'application. Une zone qui liste `external-jwt` peut
+la **surcharger** — c'est ce qui fait cohabiter une API d'appelants machine et une zone de personnes :
+
+```ts
+areas: {
+  partner: {
+    pattern: "^/api/partner",
+    stateless: true,
+    authenticators: ["jwt", "external-jwt"],
+    resource: "https://app.example/api/partner",
+    subjectPolicy: "ephemeral",        // l'appelant machine n'a pas de compte local
+    ephemeralRoles: ["ROLE_PARTNER"],  // facultatif — sinon : scopes seulement
+  },
+  staff: {
+    pattern: "^/staff",
+    authenticators: ["external-jwt"],
+    resource: "https://app.example/staff", // suit la globale (« require »)
+  },
+}
+```
+
+Trois règles, toutes vérifiées au boot ou au rattachement :
+
+- la zone qui ne dit rien suit la politique globale ;
+- `subjectPolicy` sur une zone **sans** `external-jwt` est refusé au boot : le réglage n'aurait
+  aucun effet, et l'auteur croirait sa zone ouverte aux machines ;
+- `ephemeralRoles` exige `subjectPolicy: "ephemeral"` écrit **dans la même zone**, et une zone
+  `ephemeral` muette n'accorde **aucun** rôle — jamais ceux de `resourceServer.ephemeralRoles`. Un
+  pouvoir local ne s'hérite pas d'un réglage écrit ailleurs.
+
 ## Comment ça s'articule
 
 Le service `accessTokenVerifier` n'est posé au conteneur **que si `issuers` n'est pas vide** — il n'y
@@ -133,6 +165,36 @@ areas: {
 }
 ```
 
+## Côté appelant — le jeton d'un programme
+
+Un script, un service partenaire ou un agent obtient son jeton **en son propre nom** par le flux
+`client_credentials` (RFC 6749 §4.4) : pas d'utilisateur, pas de navigateur, un client confidentiel
+et son secret. Le framework le porte, pour qu'aucun appelant ne recopie la plomberie OAuth :
+
+```ts
+import { requestClientCredentialsToken } from "@nodefony/security";
+
+const tokens = await requestClientCredentialsToken({
+  issuer: "https://sso.example.com/realms/acme", // le point de jeton en est DÉCOUVERT (RFC 8414)
+  clientId: "acme-machine",
+  clientSecret: process.env.NF_KEYCLOAK_MACHINE_SECRET ?? "",
+  resource: "https://app.example/api/partner", // audience visée (RFC 8707), facultative
+});
+await fetch("https://app.example/api/partner/whoami", {
+  headers: { Authorization: `Bearer ${tokens.accessToken()}` },
+});
+```
+
+- Le secret vide est refusé **avant** tout appel, en nommant le client : la cause réelle est une
+  variable absente, pas un `invalid_client`.
+- Un refus garde son code normalisé et son statut (`OAuth2RequestError`) : Keycloak rend
+  `unauthorized_client` en 401 sur un secret faux.
+- L'authentification du client est la MÊME que celle de l'échange de code (`postTokenRequest`,
+  `oauth2Client.ts`) : `client_secret_basic` par défaut, `client_secret_post` sur déclaration.
+- Le `sub` d'un compte de service Keycloak est un UUID tiré à la création du realm : il ne se sème
+  pas dans un compte local. La zone qui reçoit cet appelant déclare donc
+  `subjectPolicy: "ephemeral"` (§ « Une politique PAR ZONE »).
+
 ## Ce que l'application publie d'elle-même
 
 Une ressource protégée doit dire **où obtenir un jeton valable pour elle**. C'est l'objet des

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).                              |
@@ -74,7 +74,7 @@ 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 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`) :
+nom**, validé Zod au boot : `areas: z.record(...)`, `config.ts:1443-1444`) :
 
 ```typescript
 // nodefony/config/security.ts (extrait généré par `nodefony create app`)
@@ -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 ? »)
@@ -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