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

package/docs/authorization.md

@@ -118,20 +118,20 @@ pour les cas où le rôle ne suffit pas.
 
 ## La vision Nodefony — un jury découplé et fail-closed
 
-`Authorization.decide(token, attribute, subject?)` (`authorization.ts:70`) itère les voters, teste
-`supports()` en place — zéro allocation par appel (`authorization.ts:78-80`) — et applique la
+`Authorization.decide(token, attribute, subject?)` (`authorization.ts#Authorization.decide`) itère les voters, teste
+`supports()` en place — zéro allocation par appel (`authorization.ts#Authorization.decide`) — et applique la
 stratégie ci-dessus. Points structurants :
 
 - **Fail-closed sur erreur** : un voter qui `throw` (lookup DB down, bug) ne fait ni accorder
   l'accès ni planter la requête en 500 — on **refuse** cette décision + log `ERROR`
-  (`authorization.ts:85-93`). Même posture que le firewall sur une erreur interne.
+  (`authorization.ts#Authorization.decide`). Même posture que le firewall sur une erreur interne.
 - **Découverte par registre** : les voters sont instanciés **une fois au boot** par
-  `Authorization.#build()` (`authorization.ts:55-64`) depuis le registre — aucun nom en dur dans
-  le service. Les builtins `role`/`scope` s'enregistrent à l'import (`voterRegistry.ts:55-59`).
+  `Authorization.#build()` (`authorization.ts#Authorization.#build`) depuis le registre — aucun nom en dur dans
+  le service. Les builtins `role`/`scope` s'enregistrent à l'import (`voterRegistry.ts`).
 - **Transport-agnostique** : l'audit lit `getUserIdentifier()` (et non `getUser()`), commun au
-  token HTTP **et** au token WS `IRealtimeToken` (`authorization.ts:119-122`).
+  token HTTP **et** au token WS `IRealtimeToken` (`authorization.ts#Authorization.#auditDeny`).
 - **Audit asymétrique** : tout **refus** est audité par `Authorization.#auditDeny()` — WARNING +
-  `recordAudit` (`authorization.ts:113-142`) ; les octrois restent **muets** (volume, pas un
+  `recordAudit` (`authorization.ts#Authorization`) ; les octrois restent **muets** (volume, pas un
   signal). Le refus porte sa raison : `veto` / `abstain` / `no-voter` / `error`.
 
 ## 🚀 Démarrage rapide
@@ -327,18 +327,18 @@ class LegalHoldVoter implements IAccessVoter {
 | `DocumentVoter` GRANT (propriétaire) + `LegalHoldVoter` ABSTAIN | ✅ 200                                 |
 | `DocumentVoter` GRANT + `LegalHoldVoter` **DENY**               | ❌ 403 (`veto`) — le DENY bat le GRANT |
 
-Dès le `DENY`, le jury **s'arrête** — court-circuit, inutile de finir (`authorization.ts:94-97`).
+Dès le `DENY`, le jury **s'arrête** — court-circuit, inutile de finir (`authorization.ts#Authorization.decide`).
 
 **Contre-exemple piégeux** : le veto ne traverse **pas** une clause OR. Dans
 `@IsGranted(["ROLE_ADMIN", "doc.edit"])`, chaque attribut est un **jury séparé**
-(`Resolver.ts:896-903`) : si `ROLE_ADMIN` est accordé, `doc.edit` — et son veto — n'est même pas
+(`Resolver.ts#Resolver._enforceSecurity`) : si `ROLE_ADMIN` est accordé, `doc.edit` — et son veto — n'est même pas
 consulté. Un interdit absolu se porte en clause **AND** : empiler `@IsGranted("ROLE_ADMIN")` puis
 `@IsGranted("doc.edit", { subject: "id" })`.
 
 ### Situation 3 — le silence ferme la porte (la typo devient un 403, pas une faille)
 
 Tu déploies `@IsGranted("doc.edti")` (faute de frappe), ou tu as oublié d'enregistrer ton voter.
-**Aucun voter compétent** → refus par défaut (`!granted`, `authorization.ts:100-108`) : la route répond 403
+**Aucun voter compétent** → refus par défaut (`!granted`, `authorization.ts#Authorization`) : la route répond 403
 systématiquement, et le log nomme la cause :
 
 ```
@@ -356,29 +356,29 @@ se voit au premier test.
 ## 🧰 Déclarer l'exigence — `@IsGranted`, `@RequireScope`, `@Anonymous`
 
 Les décorateurs n'écrivent **que des métadonnées** (0 import `@nodefony/security`, 0 cycle) ; le
-moteur `authorization` est résolu **par nom** au runtime (`Resolver.ts:678-679`) :
-
-| Déclaration                                 | Sémantique                                                                                                                       |
-| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `@IsGranted("ROLE_ADMIN")`                  | un attribut — rôle, scope ou verbe métier (`IsGranted()`, `routerDecorators.ts:903`)                                             |
-| `@IsGranted(["A", "B"])`                    | **OR interne** — un attribut accordé suffit (`SecurityClause.anyOf`, `routerDecorators.ts:424-433`)                              |
-| empiler `@IsGranted` / `@RequireScope`      | **AND** — toutes les clauses doivent passer (`SecurityRequirement.clauses`, `routerDecorators.ts:1676`)                          |
-| décorateur de classe + de méthode           | fusion en **AND**, figée UNE fois par route (`computeSecurityRequirement()`, `routerDecorators.ts:1648`)                         |
-| `@IsGranted("doc.edit", { subject: "id" })` | le param de route `id` est passé au voter (`Resolver._resolveSubject()`, `Resolver.ts:941`)                                      |
-| `@RequireScope("orders:read")`              | axe scope — metadata dédiée, fusionnée dans le même `SecurityRequirement` (`RequireScope()`, `routerDecorators.ts:1002`)         |
-| `@Anonymous()`                              | action **publique** — override les gardes de classe (`security: null`) + skip l'authn (`Anonymous()`, `routerDecorators.ts:969`) |
-| `@CurrentUser()`                            | injecte l'utilisateur de l'ALS — jamais le credential (`CurrentUser`, `routerDecorators.ts:1308`)                                |
+moteur `authorization` est résolu **par nom** au runtime (`Resolver.ts#Resolver._callWithIdempotency`) :
+
+| Déclaration                                 | Sémantique                                                                                                                             |
+| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `@IsGranted("ROLE_ADMIN")`                  | un attribut — rôle, scope ou verbe métier (`IsGranted()`, `routerDecorators.ts#IsGranted`)                                             |
+| `@IsGranted(["A", "B"])`                    | **OR interne** — un attribut accordé suffit (`SecurityClause.anyOf`, `routerDecorators.ts#SecurityClause.anyOf`)                       |
+| empiler `@IsGranted` / `@RequireScope`      | **AND** — toutes les clauses doivent passer (`SecurityRequirement.clauses`, `routerDecorators.ts#SecurityRequirement.clauses`)         |
+| décorateur de classe + de méthode           | fusion en **AND**, figée UNE fois par route (`computeSecurityRequirement()`, `routerDecorators.ts#computeSecurityRequirement`)         |
+| `@IsGranted("doc.edit", { subject: "id" })` | le param de route `id` est passé au voter (`Resolver._resolveSubject()`, `Resolver.ts#Resolver._resolveSubject`)                       |
+| `@RequireScope("orders:read")`              | axe scope — metadata dédiée, fusionnée dans le même `SecurityRequirement` (`RequireScope()`, `routerDecorators.ts#RequireScope`)       |
+| `@Anonymous()`                              | action **publique** — override les gardes de classe (`security: null`) + skip l'authn (`Anonymous()`, `routerDecorators.ts#Anonymous`) |
+| `@CurrentUser()`                            | injecte l'utilisateur de l'ALS — jamais le credential (`CurrentUser`, `routerDecorators.ts#CurrentUser`)                               |
 
 La garde s'évalue dans `Resolver.executeAction()` **AVANT** l'instanciation DI du controller — un
-403 court-circuite tout, y compris `initialize()` (`_enforceSecurity`, `Resolver.ts:507-509`). Le
+403 court-circuite tout, y compris `initialize()` (`_enforceSecurity`, `Resolver.ts#Resolver._enforceSecurity`). Le
 même `executeAction` sert le pipeline HTTP **et** l'invoke WS-RPC : une garde, tous les
 transports. L'enforcement déroule chaque clause : OR interne via un `decide()` par attribut, AND
-entre clauses (`Resolver._enforceSecurity()`, `Resolver.ts:871`).
+entre clauses (`Resolver._enforceSecurity()`, `Resolver.ts#Resolver._enforceSecurity`).
 
 > [!IMPORTANT]
 > **Fail-closed intégral** : route gardée mais moteur `authorization` absent (module security non
 > chargé) OU aucune identité résolue (route **hors zone** firewall) → **403** direct
-> (`Resolver.ts:683-693`). Une route gardée doit être couverte par une zone — voir
+> (`Resolver.ts#Resolver._callWithIdempotency`). Une route gardée doit être couverte par une zone — voir
 > [firewall](./firewall.md).
 
 ## 🧑‍⚖️ Les voters intégrés — deux axes, un même jury
@@ -391,16 +391,16 @@ entre clauses (`Resolver._enforceSecurity()`, `Resolver.ts:871`).
 
 ### `role` — l'axe « qui tu es »
 
-Capte les attributs `ROLE_*` (`RoleVoter.supports()`, `RoleVoter.ts:25-27`) et vote :
+Capte les attributs `ROLE_*` (`RoleVoter.supports()`, `RoleVoter.ts#RoleVoter.supports`) et vote :
 
 - **`GRANT`** si l'utilisateur possède le rôle, hiérarchie résolue ; **`ABSTAIN` sinon — jamais
-  `DENY`** (`RoleVoter.vote()`, `RoleVoter.ts:33-35`). L'absence d'un rôle ne doit pas opposer un
+  `DENY`** (`RoleVoter.vote()`, `RoleVoter.ts#RoleVoter.vote`). L'absence d'un rôle ne doit pas opposer un
   **veto** aux autres axes (un accès peut être légitime via un scope ou l'ownership) : c'est le
   default-DENY du jury qui ferme, pas ce voter. C'est aussi ce qui rend l'OR
   (`@IsGranted(["A","B"])`) possible.
 - La hiérarchie est lue **en lazy** depuis le container — clé `roleHierarchy`
-  (`RoleVoter.ts:30-32`), posée par le firewall au boot (`firewall.ts:210`).
-- Sync par nature → `Promise.resolve`, pas de wrapper `async` inutile (`RoleVoter.ts:36-38`).
+  (`RoleVoter.ts#RoleVoter.vote`), posée par le firewall au boot (`firewall.ts#Firewall.#build`).
+- Sync par nature → `Promise.resolve`, pas de wrapper `async` inutile (`RoleVoter.ts#RoleVoter.vote`).
 
 #### Deux échelles de rôles — plateforme et organisation
 
@@ -424,28 +424,75 @@ héberge aussi les autres.
 ### `scope` — l'axe « ce qu'une clé déléguée peut faire »
 
 Frère du `role` sur l'autre axe. Capte la forme conventionnée `api:action` — un `:`, jamais
-`ROLE_*` (`ScopeVoter.supports()`, `ScopeVoter.ts:46-48`) → aucune collision avec les rôles ni un
+`ROLE_*` (`ScopeVoter.supports()`, `ScopeVoter.ts#ScopeVoter.supports`) → aucune collision avec les rôles ni un
 verbe métier. Le cœur est le **modèle de confiance** :
 
 - **Jeton humain** (`session`, `userpassword`, `anonymous`) → `GRANT` no-op : un scope ne bride
-  **jamais** un humain, son autorisation passe par ses rôles (`ScopeVoter.ts:52-54`).
+  **jamais** un humain, son autorisation passe par ses rôles (`ScopeVoter.ts#ScopeVoter.vote`).
 - **Jeton machine** (`apikey`, `jwt`, `oauth2`, ou tout type futur) → `GRANT` si le scope exact
-  est présent, sinon `ABSTAIN` (`ScopeVoter.ts:57-61`).
+  est présent, sinon `ABSTAIN` (`ScopeVoter.ts#ScopeVoter.vote`).
 - **Fail-closed côté machine** : `NON_SCOPABLE_TOKEN_TYPES` est une **allowlist d'humains**
-  (`ScopeVoter.ts:17-21`) — tout type absent (`mtls`, `agent`…) est considéré **scopable**, donc
+  (`ScopeVoter.ts#NON_SCOPABLE_TOKEN_TYPES`) — tout type absent (`mtls`, `agent`…) est considéré **scopable**, donc
   bridé par défaut. Un nouveau type de jeton délégué est **fermé par oubli**, jamais ouvert.
 - Pur : aucune dépendance, aucune I/O — instancié une fois au boot.
 
+### Qui OBTIENT un scope — `grantableScopes`
+
+Le voter `scope` contrôle un scope à l'**usage** : il regarde ce que le jeton porte, jamais comment
+il l'a obtenu. `@RequireScope("vitrine:write")` et les `scopes` d'un outil MCP sont des contrôles
+d'usage. Reste à décider qui a le droit de **recevoir** ce scope : sans réponse, l'émetteur de
+l'application l'accorde à tout compte connecté qui le demande, et le contrôle d'usage ne filtre
+plus rien.
+
+```typescript
+use("@nodefony/security", {
+  grantableScopes: {
+    "vitrine:write": ["ROLE_ADMIN"], // un scope exact
+    "shop:*": ["ROLE_SHOP"], // une famille
+    "shop:refund": ["ROLE_SHOP_MANAGER"], // l'exact l'emporte sur la famille
+  },
+});
+```
+
+- **Clé** : un scope exact, ou une famille `préfixe:*`. Une clé exacte l'emporte sur une famille,
+  la famille la plus longue sur une plus courte ; l'ordre des clés ne décide de rien
+  (`ScopeGrantPolicy.rolesFor()`, `scopeGrants.ts#ScopeGrantPolicy.rolesFor`).
+- **Valeur** : les rôles dont **un** suffit, hiérarchie de rôles comprise. Une liste vide est
+  refusée au démarrage : pour n'accorder un scope à personne, on ne l'expose pas.
+- **Non déclaré** : le scope reste accordé à tout compte connecté. Rien ne change pour une
+  application qui ne déclare rien.
+- **Refusées au démarrage** : `admin:read`, `admin:write` et `admin:*`, réservés au plan
+  d'administration du framework (`scopeGrantKeyProblem()`, `scopeGrants.ts#scopeGrantKeyProblem`). Le message nomme
+  la clé et la raison.
+
+Un seul juge pour les deux émetteurs de l'application, et pour les deux familles de scopes
+(`refusedScopes()`, `scopeGrants.ts#refusedScopes`) :
+
+| Émetteur                                       | Scope refusé                                                                                                              | Pourquoi cette forme                                                        |
+| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| Jeton d'accès (`/token`, `security:mcp:token`) | retiré ; le jeton est émis avec le reste, le refus est nommé au journal (`tokenService.ts#TokenService.#grantableScopes`) | RFC 6749 §3.3 : le serveur accorde moins que demandé et le dit dans `scope` |
+| Renouvellement d'un jeton                      | rejugé sur les rôles du compte relu (`tokenService.ts#TokenService.refresh`)                                              | un rôle retiré retire son scope au prochain renouvellement                  |
+| Clé API                                        | création refusée, **403** qui nomme le scope (`apiKeys.ts#ApiKeyService.createForSubject`)                                | une clé créée avec moins que demandé surprendrait sans rien dire            |
+
+`grantableScopes` ne borne **pas** un jeton signé par un émetteur tiers (Keycloak…) : celui-ci
+accorde selon sa propre politique. Et ce n'est pas une règle de zone : un jeton ne sait pas quelle
+zone le lira, et `security:mcp:token` signe sans aucune requête.
+
+**Depuis un module.** Un module complète la section par `module-security` dans sa configuration
+(voir [configuration](../../../../../docs/guides/configuration.md)). Un préfixe = un propriétaire :
+la fusion de configuration fusionne les listes **case par case**, si bien qu'une clé déclarée à deux
+endroits mêle les deux listes de rôles.
+
 ### La hiérarchie de rôles — aplatie et vérifiée au boot
 
 `RoleHierarchyWalker` se déclare dans la config (`use("@nodefony/security", { roleHierarchy })`,
 voir [firewall](./firewall.md)) et fait deux choses au boot :
 
 - **Aplatissement DFS précalculé** (`#detectCycles()` puis `#precompute()`,
-  `RoleHierarchyWalker.ts:13-14`) → `RoleHierarchyWalker.hasRole()` est **O(1)** sur le hot path
-  (`RoleHierarchyWalker.ts:23-30`).
+  `RoleHierarchyWalker.ts#RoleHierarchyWalker.#precompute`) → `RoleHierarchyWalker.hasRole()` est **O(1)** sur le hot path
+  (`RoleHierarchyWalker.ts#RoleHierarchyWalker.hasRole`).
 - **Détection de cycles** par DFS coloré — un arc vers un nœud « en cours de visite » = cycle, et
-  le boot **jette avec le chemin complet** `A → B → A` (`RoleHierarchyWalker.ts:69-95`) : jamais
+  le boot **jette avec le chemin complet** `A → B → A` (`RoleHierarchyWalker.ts#RoleHierarchyWalker.#detectCycles`) : jamais
   de boucle infinie silencieuse en production.
 
 ## 🛡️ Le rôle par défaut d'une zone — et ce qu'il n'écrase pas
@@ -493,44 +540,44 @@ doit valoir partout se place donc dans le code de l'action, pas seulement dans u
 
 ## 🧩 Étendre le jury — le contrat et le registre
 
-Le contrat `IAccessVoter` (`IAccessVoter.ts:20-26`) tient en deux méthodes :
+Le contrat `IAccessVoter` (`IAccessVoter.ts#IAccessVoter`) tient en deux méthodes :
 
 - `supports(attribute, subject?)` — test **bon marché** : ce voter sait-il décider de cet
   attribut ? Appelé sur chaque voter à chaque `decide()`.
 - `vote(token, attribute, subject?)` — **async** (les voters métier font des lookups DB) ; renvoie
-  un `VoterVote` : `GRANT` / `DENY` / `ABSTAIN` (`IAccessVoter.ts:7-11`).
+  un `VoterVote` : `GRANT` / `DENY` / `ABSTAIN` (`IAccessVoter.ts#VoterVote`).
 
 L'enregistrement passe par le registre — `registerVoterFactory(name, factory)`
-(`voterRegistry.ts:39-44`), consommé une fois au boot (`listVoterFactories()`,
-`voterRegistry.ts:47-49`). La fabrique reçoit `{ container }` et ne fait **que construire** : les
+(`voterRegistry.ts#registerVoterFactory`), consommé une fois au boot (`listVoterFactories()`,
+`voterRegistry.ts#listVoterFactories`). La fabrique reçoit `{ container }` et ne fait **que construire** : les
 résolutions coûteuses restent lazy dans l'instance (cf. le `DocumentVoter` du Démarrage rapide).
 
 Pourquoi un registre et pas un scan DI des `@injectable` : les interfaces TS sont **effacées à la
 compilation** — rien à scanner au runtime ; le registre **est** le marqueur explicite
-(`voterRegistry.ts:10-16`). Convention-frère : `authenticatorRegistry`, `tokenStoreRegistry`.
+(`voterRegistry.ts#IVoterFactoryContext`). Convention-frère : `authenticatorRegistry`, `tokenStoreRegistry`.
 
 ## 🔌 HTTP et WebSocket — une garde, N transports
 
-- **La même garde** : `Resolver.executeAction()` (`Resolver.ts:450`) est le point unique
+- **La même garde** : `Resolver.executeAction()` (`Resolver.ts#Resolver.executeAction`) est le point unique
   d'enforcement — pipeline HTTP classique **et** invoke WS-RPC (pont `api.request`). Un
   `@IsGranted` protège donc l'action quel que soit le transport (prouvé bout en bout par le banc
   `ws-isgranted-jwt`).
 - **Le service ignore le transport** : l'audit lit `getUserIdentifier()`, commun à `IToken` (HTTP)
-  et `IRealtimeToken` (WS) (`authorization.ts:119-122`).
+  et `IRealtimeToken` (WS) (`authorization.ts#Authorization.#auditDeny`).
 - **Le verrou de frame** (canaux realtime) applique son RBAC par canal avec la **même
-  hiérarchie** : `satisfies()` (`frameAuthorizer.ts:290`) délègue à `Firewall.hasRole()`
-  (`firewall.ts:521`) — les rôles exigés par un canal héritent comme partout ailleurs.
+  hiérarchie** : `satisfies()` (`frameAuthorizer.ts#satisfies`) délègue à `Firewall.hasRole()`
+  (`firewall.ts#Firewall.hasRole`) — les rôles exigés par un canal héritent comme partout ailleurs.
 
 ## 📜 Normes appliquées
 
-| Domaine                    | Norme / posture                                                                                                         | Ancrage                                                   |
-| -------------------------- | ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
-| Contrôle d'accès           | OWASP Top 10 **A01** (IDOR, élévation)                                                                                  | défaut `DENY` du jury (`authorization.ts:100-108`)        |
-| Modèle de rôles            | RBAC **hiérarchique**, au sens des composantes _Core_ et _Hierarchical_ d'ANSI INCITS 359 — sans séparation des devoirs | `RoleHierarchyWalker.reachableRoles()`                    |
-| Combinaison des votes      | _deny-overrides_ : un refus l'emporte, le silence ferme                                                                 | `Authorization.decide()`                                  |
-| Scopes délégués            | **RFC 6749 §3.3** — définis par le serveur d'autorisation ; sans effet sur une session humaine                          | `ScopeVoter.vote()`                                       |
-| Modèle                     | **Zero Trust** (fermé par défaut)                                                                                       | 403 fail-closed du Resolver (`Resolver.ts:683-693`)       |
-| Journalisation de sécurité | audit des refus, jamais des octrois                                                                                     | `#auditDeny` → `recordAudit` (`authorization.ts:113-142`) |
+| Domaine                    | Norme / posture                                                                                                         | Ancrage                                                                   |
+| -------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| Contrôle d'accès           | OWASP Top 10 **A01** (IDOR, élévation)                                                                                  | défaut `DENY` du jury (`authorization.ts#Authorization`)                  |
+| Modèle de rôles            | RBAC **hiérarchique**, au sens des composantes _Core_ et _Hierarchical_ d'ANSI INCITS 359 — sans séparation des devoirs | `RoleHierarchyWalker.reachableRoles()`                                    |
+| Combinaison des votes      | _deny-overrides_ : un refus l'emporte, le silence ferme                                                                 | `Authorization.decide()`                                                  |
+| Scopes délégués            | **RFC 6749 §3.3** — définis par le serveur d'autorisation ; sans effet sur une session humaine                          | `ScopeVoter.vote()`                                                       |
+| Modèle                     | **Zero Trust** (fermé par défaut)                                                                                       | 403 fail-closed du Resolver (`Resolver.ts#Resolver._callWithIdempotency`) |
+| Journalisation de sécurité | audit des refus, jamais des octrois                                                                                     | `#auditDeny` → `recordAudit` (`authorization.ts#Authorization`)           |
 
 > Ce tableau dit ce que le code **fait**, pas ce qu'il revendique : Nodefony n'est pas « conforme
 > ANSI 359 » (ni sessions de rôles, ni séparation des devoirs), pas « conforme XACML » (un seul
@@ -541,14 +588,14 @@ compilation** — rien à scanner au runtime ; le registre **est** le marqueur e
 ## ⚡ Performance & mémoire
 
 - **Hot path à coût nul** : une route non gardée porte `security: null` → 0 lookup, 0 await, 0
-  alloc (`Resolver.ts:490`) ; l'exigence est **figée une fois** par route et partagée entre
-  requêtes (`SecurityRequirement`, `routerDecorators.ts:444`).
-- **`decide()` sans allocation** : itération en place des voters (`authorization.ts:70-72`),
-  instanciés **une seule fois** au boot (`authorization.ts:70`).
+  alloc (`Resolver.ts#Resolver._enforceActionSecurity`) ; l'exigence est **figée une fois** par route et partagée entre
+  requêtes (`SecurityRequirement`, `routerDecorators.ts#SecurityRequirement`).
+- **`decide()` sans allocation** : itération en place des voters (`authorization.ts#Authorization.decide`),
+  instanciés **une seule fois** au boot (`authorization.ts#Authorization.decide`).
 - **`hasRole()` O(1)** : hiérarchie aplatie au boot, rien de récursif par requête
-  (`RoleHierarchyWalker.ts:23-30`).
+  (`RoleHierarchyWalker.ts#RoleHierarchyWalker.hasRole`).
 - **Audit = cold path** : uniquement sur refus, avec un descripteur léger du sujet — jamais de
-  `JSON.stringify` aveugle (`describeSubject()`, `authorization.ts:159-165`).
+  `JSON.stringify` aveugle (`describeSubject()`, `authorization.ts#describeSubject`).
 
 ## ⚠️ Pièges (symptôme → cause → correction)
 
@@ -557,16 +604,16 @@ compilation** — rien à scanner au runtime ; le registre **est** le marqueur e
 | Une action gardée par `@RequireScope` seul reste accessible à un humain | le voter de scope accorde sans condition à une session — il ne contraint que les clés déléguées | ajouter un `@IsGranted`, ou compter sur le rôle par défaut de la zone   |
 | `@RequireScope("openid")` refuse tout, sans message                     | un scope sans `:` n'est capté par aucun voter → le jury ferme par défaut                        | employer la forme `api:action`, ou déclarer un voter pour cette famille |
 
-| Symptôme                               | Cause (dans le code)                                                                | Correction                                                     |
-| -------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------- |
-| Accès refusé alors que le rôle existe  | Attribut mal formé (pas `ROLE_…`) → le `RoleVoter` n'entre pas                      | Respecter le préfixe `ROLE_`                                   |
-| 403 systématique sur une route gardée  | Moteur absent OU identité non résolue — route **hors zone** (`Resolver.ts:683-693`) | Couvrir la route par une zone firewall                         |
-| Un voter métier bloque tout            | Il renvoie `DENY` au lieu d'`ABSTAIN` quand il ne s'applique pas                    | Renvoyer `ABSTAIN` hors de son domaine                         |
-| Un `DENY` n'a pas bloqué               | Attributs d'une clause = jurys **séparés** (OR) — un autre attribut a accordé       | Porter l'interdit en clause AND (empiler les `@IsGranted`)     |
-| Clé API accède à une action non prévue | Type de jeton traité comme humain (allowlist)                                       | Vérifier que le type n'est pas dans `NON_SCOPABLE_TOKEN_TYPES` |
-| `ROLE_ADMIN` n'hérite pas `ROLE_USER`  | Hiérarchie non déclarée / non posée au container                                    | Déclarer `roleHierarchy` (config security) au boot             |
-| Boot qui plante « cycle détecté »      | Hiérarchie de rôles cyclique                                                        | Casser le cycle (le message nomme le chemin)                   |
-| Accès accordé à un voter qui a planté  | (n'arrive pas) fail-closed : une erreur de voter = refus                            | Corriger le voter ; l'erreur est loggée ERROR                  |
+| Symptôme                               | Cause (dans le code)                                                                                      | Correction                                                     |
+| -------------------------------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| Accès refusé alors que le rôle existe  | Attribut mal formé (pas `ROLE_…`) → le `RoleVoter` n'entre pas                                            | Respecter le préfixe `ROLE_`                                   |
+| 403 systématique sur une route gardée  | Moteur absent OU identité non résolue — route **hors zone** (`Resolver.ts#Resolver._callWithIdempotency`) | Couvrir la route par une zone firewall                         |
+| Un voter métier bloque tout            | Il renvoie `DENY` au lieu d'`ABSTAIN` quand il ne s'applique pas                                          | Renvoyer `ABSTAIN` hors de son domaine                         |
+| Un `DENY` n'a pas bloqué               | Attributs d'une clause = jurys **séparés** (OR) — un autre attribut a accordé                             | Porter l'interdit en clause AND (empiler les `@IsGranted`)     |
+| Clé API accède à une action non prévue | Type de jeton traité comme humain (allowlist)                                                             | Vérifier que le type n'est pas dans `NON_SCOPABLE_TOKEN_TYPES` |
+| `ROLE_ADMIN` n'hérite pas `ROLE_USER`  | Hiérarchie non déclarée / non posée au container                                                          | Déclarer `roleHierarchy` (config security) au boot             |
+| Boot qui plante « cycle détecté »      | Hiérarchie de rôles cyclique                                                                              | Casser le cycle (le message nomme le chemin)                   |
+| Accès accordé à un voter qui a planté  | (n'arrive pas) fail-closed : une erreur de voter = refus                                                  | Corriger le voter ; l'erreur est loggée ERROR                  |
 
 ## 📡 Observabilité — Studio
 

package/docs/cors.md

@@ -100,28 +100,28 @@ Trois conséquences que beaucoup de développeurs découvrent trop tard :
 
 ## La vision Nodefony — une politique pure, fail-safe, verrouillée au boot
 
-`Cors` (`cors.ts:33`) est une classe **pure et synchrone** : elle ne touche ni au réseau, ni à la
+`Cors` (`cors.ts#Cors`) 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:240-241`). Conséquence directe : la politique est **testable sans serveur**, et son coût par
+(`firewall.ts#Firewall.#build`). 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:162-165`) — le navigateur la refuserait de toute façon. Défense en profondeur : même
+  (`config.ts#areaSchema`) — 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`).
+  d'émettre `*` (`cors.ts#Cors.#allowOrigin`).
 - **Reflet d'origine ⇒ `Vary: Origin`.** Dès que la valeur `Allow-Origin` n'est pas `*`, la politique
-  ajoute `Vary` elle-même, sans que l'appelant ait à y penser (`Cors.reflectsOrigin()`, `cors.ts:63` ;
-  posé en `cors.ts:81` et `cors.ts:94`). Sans lui, un cache partagé servirait à une origine la réponse
+  ajoute `Vary` elle-même, sans que l'appelant ait à y penser (`Cors.reflectsOrigin()`, `cors.ts#Cors.reflectsOrigin` ;
+  posé en `cors.ts#Cors.preflightHeaders` et `cors.ts#Cors.actualHeaders`). Sans lui, un cache partagé servirait à une origine la réponse
   taillée pour une autre — un empoisonnement de cache.
 - **Origine inconnue ⇒ `null` ⇒ aucun en-tête.** Pas de message d'erreur, pas de 403 bavard
-  (`cors.ts:74`, `cors.ts:92`). La réponse part normalement mais n'est pas partageable : le navigateur
+  (`cors.ts#Cors.preflightHeaders`, `cors.ts#Cors.actualHeaders`). La réponse part normalement mais n'est pas partageable : le navigateur
   bloque, et un attaquant n'apprend **rien** sur le contenu de ton allowlist.
 
-Le contrat d'entrée est `ICorsOptions` (`cors.ts:4`) — exactement le sous-ensemble `cors` de la config
-du module, rien de plus. La sortie est une table nom → valeur (`CorsHeaders`, `cors.ts:15`) que
+Le contrat d'entrée est `ICorsOptions` (`cors.ts#ICorsOptions`) — exactement le sous-ensemble `cors` de la config
+du module, rien de plus. La sortie est une table nom → valeur (`CorsHeaders`, `cors.ts#CorsHeaders`) que
 l'appelant recopie sur la réponse.
 
 ## 🚀 Démarrage rapide
@@ -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: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**.
+La section `cors` de la config du module (`corsSchema`, `config.ts#corsSchema` ; branchée à la racine en
+`config.ts#loginPageSchema`). 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:1019`)                       |
+| aucun `Origin` (même origine, ou `curl`) | rien — la requête suit le pipeline normal (`firewall.ts#Firewall.#recordAuth`)       |
 
 ### Situation 2 — une API publique en lecture seule (le joker `*`)
 
@@ -256,7 +256,7 @@ cors: {
 }
 ```
 
-Ici, et seulement ici, la politique émet littéralement `*` (`cors.ts:58`) — et donc **pas de
+Ici, et seulement ici, la politique émet littéralement `*` (`cors.ts#Cors.#allowOrigin`) — et donc **pas de
 `Vary: Origin`** : la réponse est identique pour tout le monde, elle est cachable telle quelle.
 
 ### Situation 3 — le contre-exemple piégeux : `*` + credentials
@@ -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:194-197`), avec un message qui dit quoi faire. La raison n'est pas cosmétique : cette
+> (`config.ts#corsSchema`), 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.
@@ -291,7 +291,7 @@ cors: {
 }
 ```
 
-Cet en-tête n'est posé **que sur la requête réelle** (`cors.ts:96`), jamais sur le preflight — un
+Cet en-tête n'est posé **que sur la requête réelle** (`cors.ts#Cors.actualHeaders`), jamais sur le preflight — un
 preflight ne transporte pas de corps, il n'y a rien à exposer. Symétrie à ne pas confondre :
 `allowedHeaders` = ce que le front a le droit d'**envoyer** ; `exposedHeaders` = ce qu'il a le droit de
 **lire**.
@@ -322,42 +322,42 @@ sequenceDiagram
   R-->>B: 200 + Access-Control-*
 ```
 
-`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
+`Firewall.handleCors()` (`firewall.ts#Firewall.handleCors`) est appelé **en tête de** `HttpKernel.handleHttp()`
+(`http-kernel.ts#HttpKernel.handleHttp`), à la ligne `http-kernel.ts#HttpKernel.createHttpContext` — **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:1013`) :
+Quatre sorties en no-op, dans cet ordre (`firewall.ts#Firewall.#recordAuth`) :
 
 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:1019`) ;
+2. pas d'en-tête `Origin` ⇒ requête same-origin ou client non-navigateur (`firewall.ts#Firewall.#recordAuth`) ;
 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:94`) ;
+   (`firewall.ts#IHeaderCapableResponse.setHeader`) ;
 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:1038`).
+   court-circuité en 204 (`firewall.ts#Firewall.enforceCsrf`).
 
 **La détection du preflight est stricte** : méthode `OPTIONS` **et** présence de
-`Access-Control-Request-Method` (`firewall.ts:1054-1056`). Un `OPTIONS` nu — celui d'un client qui interroge
+`Access-Control-Request-Method` (`firewall.ts#Firewall.enforceCsrf`). 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
 
-| Moment             | Déclencheur                                 | En-têtes posés                                                                                | Ancrage      |
-| ------------------ | ------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------ |
-| **Preflight**      | `OPTIONS` + `Access-Control-Request-Method` | `Allow-Origin`, `Allow-Methods`, `Allow-Headers`, `Max-Age` (+ `Vary`, + `Allow-Credentials`) | `cors.ts:72` |
-| **Requête réelle** | tout le reste, avec un `Origin`             | `Allow-Origin` (+ `Vary`, + `Allow-Credentials`, + **`Expose-Headers`**)                      | `cors.ts:90` |
+| Moment             | Déclencheur                                 | En-têtes posés                                                                                | Ancrage                         |
+| ------------------ | ------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------- |
+| **Preflight**      | `OPTIONS` + `Access-Control-Request-Method` | `Allow-Origin`, `Allow-Methods`, `Allow-Headers`, `Max-Age` (+ `Vary`, + `Allow-Credentials`) | `cors.ts#Cors.preflightHeaders` |
+| **Requête réelle** | tout le reste, avec un `Origin`             | `Allow-Origin` (+ `Vary`, + `Allow-Credentials`, + **`Expose-Headers`**)                      | `cors.ts#Cors.actualHeaders`    |
 
 Deux nuances utiles :
 
 - **`Allow-Headers` est statique**, dérivé de la config — la politique ne réfléchit pas le
-  `Access-Control-Request-Headers` du client (`cors.ts:78`). Ce que tu déclares est ce qui est annoncé,
+  `Access-Control-Request-Headers` du client (`cors.ts#Cors.preflightHeaders`). 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:1661`) : une police ou une image servie cross-origin reçoit les mêmes en-têtes que
+  (`http-kernel.ts#HttpKernel.runHttpPipeline`) : 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`
+Le contrat est publié dans l'interface du firewall (`IFirewall.ts#IFirewall.handleCors`) : `number | undefined` — `204`
 signifie « je suis un preflight, réponds et arrête-toi ».
 
 ## 🛡️ CORS, CSRF et en-têtes de sécurité — qui protège quoi
@@ -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:640`) : ce que tu autorises explicitement en
+`csrf.trustedOrigins` et de `cors.origins` (`firewall.ts#Firewall.#describeDefenses`) : 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:194`). Ajouter une origine à `cors.origins` est **plus** permissif que l'ajouter à
+origine (`config.ts#corsSchema`). Ajouter une origine à `cors.origins` est **plus** permissif que l'ajouter à
 `csrf.trustedOrigins`.
 
 ## 🔌 Et le WebSocket ?
@@ -384,11 +384,11 @@ origine (`config.ts:194`). 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:1098`) — il n'y aurait rien à protéger avec des en-têtes que personne ne lit.
+(`firewall.ts#Firewall.handleCors`) — 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:724`) valide l'`Origin` **au handshake**, avant l'accept, et ferme en code WS `1008`
-si elle est refusée. Sa doctrine :
+(`http-kernel.ts#HttpKernel.checkWebsocketOrigin`) valide l'`Origin` **au handshake**, avant l'accept, et répond `403` sans
+ouvrir la socket si elle est refusée. Sa doctrine :
 
 - **same-origin par défaut** : l'`Origin` du handshake doit correspondre au `Host` servi ;
 - **loopback toléré en development** uniquement, pour le cross-port Vite ↔ serveur ;
@@ -402,41 +402,41 @@ Deux réglages distincts, parce que deux mécanismes navigateur distincts.
 
 ## 📜 Normes appliquées
 
-| 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: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:724`)                  |
+| Sujet                             | Norme                       | Comment le code s'y conforme                                                                                  |
+| --------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| Protocole CORS                    | Fetch Standard (WHATWG)     | `Cors` (`cors.ts#Cors`) — preflight vs requête réelle séparés                                                 |
+| Preflight sans credentials        | Fetch Standard              | court-circuit en 204 avant auth/routing (`firewall.ts#Firewall.enforceCsrf`)                                  |
+| `*` incompatible avec credentials | Fetch Standard · OWASP CORS | rejet au boot (`config.ts#areaSchema`) + reflet défensif (`cors.ts#Cors.#allowOrigin`)                        |
+| Correction de cache               | RFC 9110 (`Vary`)           | `Vary: Origin` dès que l'origine est reflétée (`cors.ts#Cors.preflightHeaders`, `cors.ts#Cors.actualHeaders`) |
+| Comparaison d'origines            | RFC 6454 (Web Origin)       | match **exact** `scheme://host:port` — `Cors.#allowOrigin()` (`cors.ts#Cors.#allowOrigin`)                    |
+| Anti-CSWSH                        | OWASP WSTG-CLNT-10          | `HttpKernel.checkWebsocketOrigin()` (`http-kernel.ts#HttpKernel.checkWebsocketOrigin`)                        |
 
 ## ⚡ Performance & mémoire
 
 La politique est **précalculée au boot** : les listes `methods`, `allowedHeaders`, `exposedHeaders` et
-`maxAgeS` sont jointes/converties une fois dans le constructeur (`cors.ts:42-49`), jamais par requête. Il
+`maxAgeS` sont jointes/converties une fois dans le constructeur (`cors.ts#ICorsOptions.maxAgeS`), jamais par requête. Il
 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: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`) ;
+- **0 pour une requête same-origin** — pas d'en-tête `Origin`, sortie immédiate (`firewall.ts#Firewall.#recordAuth`) ;
+- **0 pour un WebSocket** — sortie sur l'absence de `setHeader` (`firewall.ts#IHeaderCapableResponse.setHeader`) ;
+- **0 si la section est désactivée** — `#cors` reste `null`, aucun objet n'est alloué (`firewall.ts#Firewall.#cors`) ;
 - **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`).
+  origine refusée n'alloue rien du tout (retour `null` avant construction de la table, `cors.ts#Cors.preflightHeaders`).
 
 ## 📡 Observabilité — Studio
 
 La configuration CORS **résolue** (celle qui tourne réellement, pas le fichier source) est exposée 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
+`Firewall.describe()` (`firewall.ts#Firewall.describe`), qui délègue à `Firewall.#describeDefenses()`
+(`firewall.ts#Firewall.#describeDefenses`). La projection CORS y expose `origins`, `credentials`, `methods`,
+`allowedHeaders`, `exposedHeaders` et `maxAgeS` (`firewall.ts#Firewall.#describeDefenses`) — aucun secret ne transite par
 cette surface.
 
-- **Data plane** : `GET /nodefony/security/api/firewall` (`SecurityAdminApi.ts:328`), protégé
+- **Data plane** : `GET /nodefony/security/api/firewall` (`SecurityAdminApi.ts#createSecurityAdminApi`), protégé
   `ROLE_NODEFONY_ADMIN`.
 - **Écran** : console **Firewall** → section _Défenses_ (`FirewallDefenses`,
-  `FirewallDefenses.tsx:114`), carte CORS à côté des cartes CSRF, en-têtes et throttle.
+  `FirewallDefenses.tsx#FirewallDefenses`), carte CORS à côté des cartes CSRF, en-têtes et throttle.
 - **Schéma de config** : `securityConfigJsonSchema()` alimente le formulaire d'édition de Studio —
   la section `cors` y apparaît avec ses libellés et défauts, sans UI écrite à la main.
 
@@ -445,18 +445,18 @@ secondes les « pourtant j'ai bien mis l'origine ».
 
 ## ⚠️ Pièges (symptôme → cause → correction)
 
-| Symptôme                                                  | Cause                                                                                  | Correction                                                                                |
-| --------------------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
-| 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)               |
-| `response.headers.get("X-…")` renvoie `null`              | En-tête non déclaré dans `exposedHeaders` (`cors.ts:96`)                               | L'ajouter à `cors.exposedHeaders`                                                         |
-| 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: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                         |
+| Symptôme                                                  | Cause                                                                                                   | Correction                                                                                                            |
+| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| Le boot échoue sur la config CORS                         | `origins:["*"]` **et** `credentials:true` (`config.ts#corsSchema`)                                      | 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)                                           |
+| `response.headers.get("X-…")` renvoie `null`              | En-tête non déclaré dans `exposedHeaders` (`cors.ts#Cors.actualHeaders`)                                | L'ajouter à `cors.exposedHeaders`                                                                                     |
+| Le preflight échoue sur un en-tête custom                 | `allowedHeaders` est statique, il ne reflète pas la demande du client (`cors.ts#Cors.preflightHeaders`) | 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#Cors.preflightHeaders`)                   | 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#HttpKernel.checkWebsocketOrigin`) — 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