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

package/docs/csrf.md

@@ -91,13 +91,13 @@ 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#areaSchema`).
 - **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#HttpKernel.armAndGuard`) 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 —
-  testable sans serveur, instanciée une fois au boot (`csrf.ts:56`).
+  testable sans serveur, instanciée une fois au boot (`csrf.ts#Csrf`).
 - La couche 2 (`@CsrfProtect`) est la ceinture-et-bretelles des mutations à haute valeur ; la
   couche 3 côté cookies (attribut `SameSite`) reste portée par les émetteurs de cookies.
 
@@ -107,11 +107,11 @@ contrôleur** : l'attaque meurt sans avoir touché ton code.
 
 Rien à écrire ni à configurer : toute mutation dont la provenance est un site tiers reçoit **403**,
 sur toutes tes routes. Les clients non-navigateurs (curl, CI) passent — ils n'embarquent pas les
-cookies d'une victime, ils sont hors vecteur (`csrf.ts:113`).
+cookies d'une victime, ils sont hors vecteur (`csrf.ts#Csrf.enforce`).
 
 ### Opt-in couche 2 : `@CsrfProtect` sur une mutation à haute valeur
 
-Les décorateurs `CsrfProtect`/`CsrfExempt` sont exportés par `@nodefony/framework` (`framework/index.ts:101-102`) :
+Les décorateurs `CsrfProtect`/`CsrfExempt` sont exportés par `@nodefony/framework` (`framework/index.ts`) :
 
 ```typescript
 // nodefony/controllers/ProfileController.ts — complet, compile tel quel
@@ -148,13 +148,16 @@ 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#computeActionMeta`.)
 
 ### 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`).
+1. **Obtenir** : `GET /nodefony/security/api/auth/me` sème TOUJOURS le token — c'est la requête sûre
+   que tout client connaît, et elle évite de décorer une lecture pour le seul plaisir d'en obtenir
+   un (le token est sans état : celui-ci vaut pour toute route protégée). Plus généralement, une
+   requête **sûre** (GET) vers n'importe quelle route `@CsrfProtect` sème le token
+   (`firewall.ts#Firewall.#recordAuth`) ; la réponse pose le cookie **lisible** `csrf-token` — non `HttpOnly`
+   exprès, `SameSite=Strict`, `Secure` en HTTPS (`HttpContext.writeHead()`, `HttpContext.ts#HttpContext.writeHead`).
 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,8 +202,8 @@ 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 :
-> `npx nodefony security:secrets` (`security-secrets.ts:39`) → `NF_CSRF_SECRET` →
+> chaque pod rejette les tokens des autres (`firewall.ts#Firewall.#build`). Générer et câbler :
+> `npx nodefony security:secrets` (`security-secrets.ts#ROLES`) → `NF_CSRF_SECRET` →
 > `use("@nodefony/security", { csrf: { secret: ctx.env.NF_CSRF_SECRET } })`.
 
 ## ⚙️ Choisir sa défense — trois situations
@@ -241,129 +244,131 @@ autorisation :
 ```
 
 > [!WARNING]
-> `@CsrfExempt` (`routerDecorators.ts:1142`) est un opt-out **ciblé CSRF**. Ne jamais « débloquer un
+> `@CsrfExempt` (`routerDecorators.ts#CsrfExempt`) 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#corsSchema`).
 
 ## 🏗️ Architecture interne
 
 ### Couche 1 — la chaîne de décision (`Csrf.enforce()`)
 
-`Csrf.enforce()` (`csrf.ts:85`) est **pure, synchrone, zéro I/O**, no-op immédiat sur les méthodes
-sûres → coût nul sur le GET dominant (`csrf.ts:88`). Pour une mutation, dans l'ordre :
+`Csrf.enforce()` (`csrf.ts#Csrf.enforce`) est **pure, synchrone, zéro I/O**, no-op immédiat sur les méthodes
+sûres → coût nul sur le GET dominant (`csrf.ts#Csrf.enforce`). Pour une mutation, dans l'ordre :
 
 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`).
+   que CORS autorise déjà explicitement **n'est pas** du CSRF (`csrf.ts#Csrf`, union construite par le
+   firewall au boot, `firewall.ts#Firewall.#build`).
 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`).
+   `same-site` → OK sauf `strictSameSite` (`csrf.ts#Csrf.enforce`) ; `cross-site` → **403** ; valeur
+   inconnue → on **délègue au repli** (forward-compat, le W3C dit « SHOULD ignore », `csrf.ts#Csrf.enforce`).
 3. **Repli `Origin`/`Referer`** (vieux navigateur, ou `Sec-Fetch-Site` absent) : **aucune** des
    deux → client non-navigateur, hors vecteur → OK ; sinon **same-host** exigé, mismatch → **403**
-   (`csrf.ts:112-116`).
+   (`csrf.ts#Csrf.enforce`).
 
 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#headerValue`) ; cookie extrait de l'en-tête **brut**, sans dépendre du
+  parse du contexte (`cookieValue()`, `firewall.ts#cookieValue`) ;
 - hôte cible **brut avec port** — `:authority` en HTTP/2, `context.domain` en dernier recours
-  (`firewall.ts:977-982`) ;
+  (`firewall.ts#Firewall`) ;
 - 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`).
+  whitelist) ne fuite jamais au client (`CsrfError.ts#CsrfError`).
 
 ### Couche 2 — le token signé (`CsrfTokenManager`)
 
-`CsrfTokenManager` (`csrfToken.ts:23`) implémente le **signed double-submit** (OWASP Cheat Sheet) :
+`CsrfTokenManager` (`csrfToken.ts#CsrfTokenManager`) implémente le **signed double-submit** (OWASP Cheat Sheet) :
 
-- token = `nonce.HMAC-SHA256(secret, nonce)` en base64url — nonce de 144 bits (`csrfToken.ts:27`),
-  émis par `issue()` (`csrfToken.ts:34`) ;
+- token = `nonce.HMAC-SHA256(secret, nonce)` en base64url — nonce de 144 bits (`csrfToken.ts#CsrfTokenManager.#NONCE_BYTES`),
+  émis par `issue()` (`csrfToken.ts#CsrfTokenManager.issue`) ;
 - `verify()` exige en-tête **et** cookie **présents**, **égaux** (double-submit) et la **signature
-  valide** (`csrfToken.ts:49-63`) — comparaisons à **temps constant**, jamais d'exception
-  (`csrfToken.ts:71-76`).
+  valide** (`csrfToken.ts#CsrfTokenManager.verify`) — comparaisons à **temps constant**, jamais d'exception
+  (`csrfToken.ts#CsrfTokenManager.#timingSafeEqual`).
 
 Pourquoi ça tient : le secret HMAC empêche un script tiers de **forger** un token (il ne peut pas
 calculer la signature) ; le double-submit l'empêche d'en **injecter** un (il ne peut ni écrire
 l'en-tête custom — préflight CORS — ni lire le cookie de la victime — SameSite + SOP). Et c'est
 **stateless** : aucune session requise → couvre le BFF web **et** l'API JWT sans coupler au stockage
-de session (TSDoc `CsrfTokenManager`, `csrfToken.ts:12-15`).
+de session (TSDoc `CsrfTokenManager`, `csrfToken.ts#CsrfTokenManager`).
 
 ### Le câblage dans le pipeline (du décorateur au 403)
 
 1. `@CsrfProtect`/`@CsrfExempt` posent un **marqueur** de metadata — zéro import de
-   `@nodefony/security` côté framework, zéro cycle (`routerDecorators.ts:886`).
+   `@nodefony/security` côté framework, zéro cycle (`routerDecorators.ts#resolveSessionIntent`).
 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
-   (`Context.ts:241-243`).
-3. `Firewall.enforceCsrf()` (`firewall.ts:948`) fait les trois rôles : **émission** du token sur
+   (`Resolver.ts#Resolver.match`) — champs portés par le `Context` de base, HTTP comme WS
+   (`Context.ts#Context`).
+3. `Firewall.enforceCsrf()` (`firewall.ts#Firewall.enforceCsrf`) 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#Firewall.enforceCsrf`). 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#Firewall.enforceCsrf`).
 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#HttpContext`).
 
-## ⚙️ Configuration (schéma Zod `csrfSchema`, `config.ts:161-204`)
+## ⚙️ Configuration (schéma Zod `csrfSchema`, `config.ts#csrfSchema`)
 
 <!-- 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#areaSchema`). |
+| `fetchMetadata` | boolean · `true` | Défense primaire `Sec-Fetch-Site` (`config.ts`). |
+| `checkOrigin` | boolean · `true` | Repli `Origin`/`Referer` same-host pour les navigateurs sans `Sec-Fetch-*` (`config.ts#corsSchema`). |
+| `strictSameSite` | boolean · `false` | `true` = refuser aussi `same-site` (sous-domaine non maîtrisé / multi-tenant) — distinct de l'attribut cookie (`config.ts#csrfSchema`). |
+| `sameSite` | enum · `Lax` | **Déclaratif** : surfacé dans l'introspection (`firewall.ts#Firewall.#describeDefenses`) ; l'attribut effectif du cookie `csrf-token` est `Strict` en dur (`HttpContext.ts#HttpContext.writeHead`). |
+| `trustedOrigins` | string[] · `[]` | Alias **exacts** (`scheme://host[:port]`) autorisés même cross-site — sans ouvrir la lecture CORS (`config.ts#csrfSchema`). |
+| `secret` | string ≥ 16 car. · — | Secret HMAC du synchronizer — PROD : via env, **partagé cluster** ; absent = éphémère dev (`config.ts#csrfSchema`). |
 
 ## 📜 Normes appliquées
 
-| Domaine                        | Norme                             | Ancrage                                |
-| ------------------------------ | --------------------------------- | -------------------------------------- |
-| Méthodes sûres                 | RFC 9110 §9.2.1                   | `SAFE_METHODS` (`csrf.ts:8-13`)        |
-| Provenance                     | W3C Fetch Metadata                | `Csrf.enforce()` (`csrf.ts:85`)        |
-| Valeur `site` inconnue → repli | Fetch Metadata « SHOULD ignore »  | `csrf.ts:96`                           |
-| Token signé                    | OWASP Signed Double-Submit Cookie | `CsrfTokenManager` (`csrfToken.ts:23`) |
-| Refus 403                      | RFC 9110 §15.5.4                  | `CsrfError` (`CsrfError.ts:17-21`)     |
-| Modèle de référence            | Go 1.25 `CrossOriginProtection`   | TSDoc `Csrf` (`csrf.ts:38-41`)         |
-| Cookies (SameSite)             | RFC 6265bis §8.8.1                | TSDoc `Csrf` (`csrf.ts:54`)            |
+| Domaine                        | Norme                             | Ancrage                                              |
+| ------------------------------ | --------------------------------- | ---------------------------------------------------- |
+| Méthodes sûres                 | RFC 9110 §9.2.1                   | `SAFE_METHODS` (`csrf.ts#SAFE_METHODS`)              |
+| Provenance                     | W3C Fetch Metadata                | `Csrf.enforce()` (`csrf.ts#Csrf.enforce`)            |
+| Valeur `site` inconnue → repli | Fetch Metadata « SHOULD ignore »  | `csrf.ts#Csrf.enforce`                               |
+| Token signé                    | OWASP Signed Double-Submit Cookie | `CsrfTokenManager` (`csrfToken.ts#CsrfTokenManager`) |
+| Refus 403                      | RFC 9110 §15.5.4                  | `CsrfError` (`CsrfError.ts#CsrfError`)               |
+| Modèle de référence            | Go 1.25 `CrossOriginProtection`   | TSDoc `Csrf` (`csrf.ts#Csrf`)                        |
+| Cookies (SameSite)             | RFC 6265bis §8.8.1                | TSDoc `Csrf` (`csrf.ts#Csrf`)                        |
 
 ## ⚡ 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`).
+- **GET = 0** : retour immédiat avant toute lecture d'en-tête (`csrf.ts#Csrf.enforce`) ; seule exception, une
+  route `@CsrfProtect` mint le token **une fois** (skip si déjà posé, `firewall.ts#Firewall.enforceCsrf`).
 - **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#Firewall`).
 - 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#Resolver.match`).
 
 ## 📡 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.tsx#Firewall`). La projection est **sans secret par construction** :
+`Firewall.#describeDefenses()` (`firewall.ts#Firewall.#describeDefenses`) publie la config résolue, et `synchronizerToken`
+n'est que la **présence** du secret armé — jamais sa valeur (`firewall.ts#Firewall.#describeDefenses`).
 
 ## ⚠️ Pièges (symptôme → cause → correction)
 
-| Symptôme                                       | Cause (dans le code)                                                                           | Correction                                                                |
-| ---------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
-| 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`     |
-| `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`                     |
+| Symptôme                                       | Cause (dans le code)                                                                                           | Correction                                                                |
+| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| 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#ICsrfRequest.origin`) | 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#Firewall.handleSecurity`)                         | 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#Firewall.#build`)                             | Fixer `csrf.secret` (≥ 16 car., partagé cluster) — `security:secrets`     |
+| `same-site` refusé alors qu'attendu OK         | `strictSameSite` activé (`csrf.ts#Csrf.enforce`)                                                               | 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#Csrf.#sameHost`)              | 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`                     |
 
 > [!TIP]
 > Un banc d'intégration **live** du repo exerce exactement ce flow (émission GET, double-submit,
 > exemption) sur les routes `/csrf/token`, `/csrf/submit` et `/csrf/webhook` du module de test
-> (`FrameworkController.ts:139-160`) — la référence exécutable si un comportement te surprend.
+> (`FrameworkController.ts#FrameworkController.csrfWebhook`) — la référence exécutable si un comportement te surprend.
 
 ## 🧪 Tests & couverture
 

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#trustedIssuerSchema`). 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#remoteJwtAlgSchema`). 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#trustedIssuerSchema`), 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,21 +104,57 @@ 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#trustedIssuerSchema`). 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
-a pas de drapeau `enabled` qui permettrait « activé sans émetteur ». Une porte protégée par des
-jetons tiers, dans une application qui n'en déclare aucun, **refuse de servir** plutôt que d'accepter
-des porteurs qu'elle ne sait pas lire.
+Le service `accessTokenVerifier` est posé au conteneur dès qu'il a **quelque chose à vérifier** :
+les jetons de l'application elle-même (capacité `jwt` active, le défaut), et ceux des émetteurs de
+`issuers`. Il aiguille sur l'émetteur revendiqué : celui de l'application est jugé par les règles de
+l'authentificateur `jwt` (révocation et compte compris), tout autre par cette liste fermée — règle
+complète et contrôles, dans l'ordre : [Ce que la porte vérifie](obtenir-un-jeton.md#-ce-que-la-porte-vérifie--un-jeton-de-cette-application-face-à-une-ressource).
+Capacité `jwt` coupée ET `issuers` vide : rien n'est posé, et une porte protégée **refuse de servir**
+(`503`) plutôt que d'accepter des porteurs qu'elle ne sait pas lire. `issuers` mal configurée :
+rien n'est posé non plus, jetons de l'application compris.
 
-L'authentificateur `external-jwt` (`authenticatorRegistry.ts:118`) reconnaît les jetons qui le
+L'authentificateur `external-jwt` (`authenticatorRegistry.ts`) reconnaît les jetons qui le
 concernent d'après la liste d'émetteurs, puis délègue la vérification au service — qui refait le contrôle sur sa propre liste.
 La liste sert donc à deux choses : router, et dire dans quel espace de noms lire le sujet.
 
@@ -133,6 +169,38 @@ 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";
+// `env.ts` est le seul lecteur de l'environnement : le secret y est déclaré (NF_KEYCLOAK_MACHINE_SECRET).
+import { env } from "../../env";
+
+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: 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
@@ -153,8 +221,12 @@ l'audience à demander.
   l'aiguillage se fait sur l'`iss` du jeton. Inutile de les ranger « dans le bon ordre ».
 - **`HS256` est impossible en configuration**, et ce n'est pas un oubli : un secret partagé ferait de
   l'application un émetteur autant qu'un vérificateur. Seules des clés publiques sont acceptées.
-- **`issuers` vide n'est pas « désactivé par erreur »** : c'est le défaut, et il fait qu'une zone
-  protégée par jetons tiers refuse de servir plutôt que d'accepter des porteurs illisibles.
+- **`issuers` vide n'est pas « désactivé par erreur »** : c'est le défaut. La zone `external-jwt`
+  ne prend alors AUCUN jeton — elle n'aiguille que les émetteurs qu'elle déclare —, et les jetons de
+  l'application restent lisibles par le vérificateur pour les ressources qui le consultent.
+- **Déclarer l'émetteur de l'application dans `issuers` ne le soustrait pas à la révocation** : ses
+  jetons sont aiguillés vers la vérification locale avant toute liste, donc un jeton révoqué ou
+  celui d'un compte désactivé est refusé, déclaré ou non.
 
 ## 📖 Lexique