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

package/docs/decorateurs.md

@@ -52,7 +52,7 @@ flowchart TD
 2. **Au montage**, `controller()` (`routerDecorators.ts:189`) relit ces métadonnées et fabrique les
    objets `Route` ; `controllers()` (`routerDecorators.ts:111`) accroche le contrôleur au module sur
    le hook `onBoot` du kernel.
-3. **À la première requête** de chaque route, `resolveActionMeta()` (`routerDecorators.ts:1669`)
+3. **À la première requête** de chaque route, `resolveActionMeta()` (`routerDecorators.ts:1772`)
    consolide toutes les étiquettes de l'action en **un objet figé** posé sur la route. Les requêtes
    suivantes ne lisent plus aucune métadonnée.
 
@@ -126,14 +126,14 @@ jamais surprendre.
 **1 — Un décorateur n'écrit QUE des métadonnées.** Aucun décorateur du framework ne contient de
 logique de sécurité, de session ou d'idempotence. `IsGranted()` (`routerDecorators.ts:903`) pose une
 clause ; c'est le `Resolver` qui appellera le moteur d'autorisation, **résolu par son nom** dans le
-conteneur (`Resolver._enforceSecurity()`, `Resolver.ts:853`). Pourquoi ce détour : `@nodefony/framework`
+conteneur (`Resolver._enforceSecurity()`, `Resolver.ts:871`). Pourquoi ce détour : `@nodefony/framework`
 ne dépend **pas** de `@nodefony/security` — sans ça, les deux modules formeraient un cycle. Le prix à
 payer est visible : une route gardée alors que le module `security` est absent renvoie **403**, pas
-une erreur de démarrage (fail-closed, `Resolver.ts:860`).
+une erreur de démarrage (fail-closed, `Resolver.ts:865`).
 
 **2 — Tout est figé une fois, puis relu en O(1).** Les métadonnées de l'action sont consolidées au
-premier passage dans `computeActionMeta()` (`routerDecorators.ts:1632`) puis gelées sur la route.
-L'objet `RouteActionMeta` (`routerDecorators.ts:1436`) est **partagé par toutes les requêtes** — le
+premier passage dans `computeActionMeta()` (`routerDecorators.ts:1729`) puis gelées sur la route.
+L'objet `RouteActionMeta` (`routerDecorators.ts:1537`) est **partagé par toutes les requêtes** — le
 framework ne le mute jamais, et ton code non plus. Une action non décorée obtient des champs à `null`,
 ce qui vaut **zéro branche** dans le chemin chaud.
 
@@ -274,7 +274,7 @@ Six familles, **36 décorateurs**, un seul fichier source. Le tableau de synthè
 | **Méthodes HTTP** | Quand l'action répond | `@Get` `@Post` `@Put` `@Patch` `@Delete` `@Options` `@Head` `@All` |
 | **Paramètres** | Ce que l'action reçoit en arguments | `@Param` `@Query` `@Body` `@Headers` `@Cookie` `@Session` `@CurrentUser` `@Req` `@Res` `@UploadedFile` `@UploadedFiles` |
 | **Réponse** | Statut, en-têtes, redirection | `@HttpCode` `@Header` `@Redirect` |
-| **Sécurité** | Qui passe, qui décide, quelles défenses | `@IsGranted` `@RequireScope` `@Anonymous` `@BypassFirewall` `@Csp` `@CsrfProtect` `@CsrfExempt` |
+| **Sécurité** | Qui passe, qui décide, quelles défenses | `@IsGranted` `@RequireScope` `@RequireAuthentication` `@Anonymous` `@BypassFirewall` `@Csp` `@CsrfProtect` `@CsrfExempt` |
 | **Cycle de la requête** | Session, anti-rejeu | `@UseSession` `@Idempotent` |
 
 > Tous s'importent depuis `"@nodefony/framework"` — jamais par un chemin relatif interne.
@@ -287,7 +287,7 @@ Six familles, **36 décorateurs**, un seul fichier source. Le tableau de synthè
 | `@controllers([…])` | **module** | Rattache des contrôleurs au module sur le hook `onBoot` ; sans lui, aucune route n'est servie (`controllers()`, `routerDecorators.ts:111`) | `@controllers([BookController])` |
 | `@controller("/prefix")` | **classe** | Pose le préfixe d'URL **et déclenche la création des routes** de la classe (`controller()`, `routerDecorators.ts:189`) | `@controller("/api/books")` |
 | `@route(nom, options)` | méthode | Forme complète : nom explicite, chemin, `requirements`, `defaults`, hôte (`route()`, `routerDecorators.ts:287`) | `@route("ws-echo", { path: "/echo", requirements: { methods: ["WEBSOCKET"] } })` |
-| `@Domain(motif \| motifs)` | **dual** | Restreint la route (ou la classe) à un ou plusieurs vhosts ; hors domaine → **403** (`Domain()`, `routerDecorators.ts:664`) | `@Domain("*.cdn.example.com")` |
+| `@Domain(motif \| motifs)` | **dual** | Restreint la route (ou la classe) à un ou plusieurs vhosts ; hors domaine → **403** (`Domain()`, `routerDecorators.ts:692`) | `@Domain("*.cdn.example.com")` |
 | `@Scope("request")` | **classe** | Une instance de contrôleur par requête — par connexion en WebSocket — au lieu de l'instance partagée par défaut (`Scope()`, `routerDecorators.ts:795`) | `@Scope("request")` |
 
 **`@controller` est le déclencheur.** Il relit les métadonnées posées par `@route`/`@Get`/… puis les
@@ -308,18 +308,18 @@ requête dans `initialize()`, ou garder un état sur `this`.
 
 ### Méthodes HTTP
 
-Toutes les fabriques sortent du même moule, `httpMethodDecorator()` (`routerDecorators.ts:489`) :
+Toutes les fabriques sortent du même moule, `httpMethodDecorator()` (`routerDecorators.ts:494`) :
 elles nomment la route automatiquement `ClasseName::methode` et posent `requirements.methods`.
 
 | Décorateur               | Méthode filtrée | Ancre                                 | Exemple             |
 | ------------------------ | --------------- | ------------------------------------- | ------------------- |
-| `@Get(path?, opts?)`     | `GET`           | `Get` (`routerDecorators.ts:535`)     | `@Get("/{id}")`     |
-| `@Post(path?, opts?)`    | `POST`          | `Post` (`routerDecorators.ts:536`)    | `@Post("")`         |
-| `@Put(path?, opts?)`     | `PUT`           | `Put` (`routerDecorators.ts:537`)     | `@Put("/{id}")`     |
-| `@Delete(path?, opts?)`  | `DELETE`        | `Delete` (`routerDecorators.ts:538`)  | `@Delete("/{id}")`  |
-| `@Patch(path?, opts?)`   | `PATCH`         | `Patch` (`routerDecorators.ts:539`)   | `@Patch("/{id}")`   |
-| `@Options(path?, opts?)` | `OPTIONS`       | `Options` (`routerDecorators.ts:540`) | `@Options("/{id}")` |
-| `@Head(path?, opts?)`    | `HEAD`          | `Head` (`routerDecorators.ts:541`)    | `@Head("/{id}")`    |
+| `@Get(path?, opts?)`     | `GET`           | `Get` (`routerDecorators.ts:540`)     | `@Get("/{id}")`     |
+| `@Post(path?, opts?)`    | `POST`          | `Post` (`routerDecorators.ts:541`)    | `@Post("")`         |
+| `@Put(path?, opts?)`     | `PUT`           | `Put` (`routerDecorators.ts:542`)     | `@Put("/{id}")`     |
+| `@Delete(path?, opts?)`  | `DELETE`        | `Delete` (`routerDecorators.ts:543`)  | `@Delete("/{id}")`  |
+| `@Patch(path?, opts?)`   | `PATCH`         | `Patch` (`routerDecorators.ts:544`)   | `@Patch("/{id}")`   |
+| `@Options(path?, opts?)` | `OPTIONS`       | `Options` (`routerDecorators.ts:545`) | `@Options("/{id}")` |
+| `@Head(path?, opts?)`    | `HEAD`          | `Head` (`routerDecorators.ts:546`)    | `@Head("/{id}")`    |
 | `@All(path?, opts?)`     | **aucune**      | `All()` (`routerDecorators.ts:548`)   | `@All("/proxy/*")`  |
 
 Deux points qu'un dev découvre sinon à ses dépens :
@@ -342,33 +342,34 @@ async index(@Param("page") page: string) { /* … */ }
 
 ### Paramètres — ce que l'action reçoit
 
-Onze décorateurs, tous produits par `paramDecoratorFactory()` (`routerDecorators.ts:1191`) sauf
+Onze décorateurs, tous produits par `paramDecoratorFactory()` (`routerDecorators.ts:1214`) sauf
 `@Body`, qui accepte une option supplémentaire. Chacun pose `{ source, key, index }` ; la valeur est
-calculée par `resolveParamArg()` (`routerDecorators.ts:1326`), une fonction **pure** — ce qui la rend
+calculée par `resolveParamArg()` (`routerDecorators.ts:1358`), une fonction **pure** — ce qui la rend
 testable sans démarrer de serveur.
 
 | Décorateur          | Sans clé renvoie…                    | Avec clé renvoie…                          | Ancre                                        |
 | ------------------- | ------------------------------------ | ------------------------------------------ | -------------------------------------------- |
-| `@Param("id")`      | toutes les variables d'URL (objet)   | la variable d'URL nommée                   | `Param` (`routerDecorators.ts:1212`)         |
-| `@Query("q")`       | toute la query string                | un paramètre de la query string            | `Query` (`routerDecorators.ts:1213`)         |
+| `@Param("id")`      | toutes les variables d'URL (objet)   | la variable d'URL nommée                   | `Param` (`routerDecorators.ts:1238`)         |
+| `@Query("q")`       | toute la query string                | un paramètre de la query string            | `Query` (`routerDecorators.ts:1239`)         |
 | `@Body("field")`    | le corps parsé entier                | un champ du corps parsé                    | `Body()` (`routerDecorators.ts:1253`)        |
-| `@Headers("x-foo")` | tous les en-têtes de requête         | un en-tête (**lookup en minuscules**)      | `Headers` (`routerDecorators.ts:1279`)       |
-| `@Cookie("sid")`    | la map des cookies                   | un cookie (objet `Cookie`, champ `.value`) | `Cookie` (`routerDecorators.ts:1280`)        |
-| `@Session("user")`  | l'objet `Session` vivant             | `session.get(clé)`                         | `Session` (`routerDecorators.ts:1281`)       |
-| `@CurrentUser()`    | l'utilisateur résolu par le firewall | —                                          | `CurrentUser` (`routerDecorators.ts:1283`)   |
-| `@Req()`            | la requête brute du contexte         | —                                          | `Req` (`routerDecorators.ts:1284`)           |
-| `@Res()`            | la réponse du contexte               | —                                          | `Res` (`routerDecorators.ts:1285`)           |
-| `@UploadedFile()`   | le **premier** fichier téléversé     | —                                          | `UploadedFile` (`routerDecorators.ts:1286`)  |
-| `@UploadedFiles()`  | tous les fichiers téléversés         | —                                          | `UploadedFiles` (`routerDecorators.ts:1287`) |
+| `@Headers("x-foo")` | tous les en-têtes de requête         | un en-tête (**lookup en minuscules**)      | `Headers` (`routerDecorators.ts:1304`)       |
+| `@Cookie("sid")`    | la map des cookies                   | un cookie (objet `Cookie`, champ `.value`) | `Cookie` (`routerDecorators.ts:1305`)        |
+| `@Session("user")`  | l'objet `Session` vivant             | `session.get(clé)`                         | `Session` (`routerDecorators.ts:1306`)       |
+| `@CurrentUser()`    | l'utilisateur résolu par le firewall | —                                          | `CurrentUser` (`routerDecorators.ts:1308`)   |
+| `@Req()`            | la requête brute du contexte         | —                                          | `Req` (`routerDecorators.ts:1309`)           |
+| `@Res()`            | la réponse du contexte               | —                                          | `Res` (`routerDecorators.ts:1310`)           |
+| `@UploadedFile()`   | le **premier** fichier téléversé     | —                                          | `UploadedFile` (`routerDecorators.ts:1311`)  |
+| `@UploadedFiles()`  | tous les fichiers téléversés         | —                                          | `UploadedFiles` (`routerDecorators.ts:1312`) |
 
-La liste des sources possibles est fermée et typée : `ParamSource` (`routerDecorators.ts:385`).
+La liste des sources possibles est fermée et typée : `ParamSource` (`routerDecorators.ts:390`).
 
 #### Trois comportements à connaître
 
 **`@CurrentUser` lit l'ALS, jamais un argument caché.** La valeur vient de `RequestContext.getUser()`
-(`routerDecorators.ts:1279`) : l'utilisateur posé par le firewall. C'est **l'utilisateur**, jamais le
-justificatif (mot de passe, jeton). Hors zone authentifiée, la valeur est `undefined` — le décorateur
-n'authentifie rien, il expose ce qui a déjà été prouvé.
+(`routerDecorators.ts:1308`) : l'utilisateur posé par le firewall. C'est **l'utilisateur**, jamais le
+justificatif (mot de passe, jeton). Hors zone authentifiée, la valeur est `undefined` — y compris
+pour l'anonyme d'une zone qui l'accepte — : le décorateur n'authentifie rien, il expose ce qui a déjà
+été prouvé. Sans décorateur, la même valeur se lit par `this.user` dans le contrôleur.
 
 **`@Session` active la session à lui seul.** La simple présence d'un paramètre `@Session` vaut
 déclaration d'intention : `resolveSessionIntent()` (`routerDecorators.ts:858`) la détecte et pose
@@ -377,7 +378,7 @@ l'intent, exactement comme `@UseSession()`. Une route sans l'un ni l'autre ne pa
 **`@Body({ stream: true })` court-circuite le parsing.** Pour un gros téléversement (vidéo,
 sauvegarde), on injecte le **flux brut** de la requête au lieu du corps chargé en mémoire ; le
 pipeline saute alors le parsing pour cette route, décision prise en amont par
-`routeExpectsBodyStream()` (`routerDecorators.ts:1408`) :
+`routeExpectsBodyStream()` (`routerDecorators.ts:1509`) :
 
 ```typescript
 @Post("/upload")
@@ -389,7 +390,7 @@ async upload(@Body({ stream: true }) stream: NodeJS.ReadableStream) {
 
 > [!TIP]
 > L'ordre d'écriture des paramètres décorés n'a aucune importance : chaque valeur est placée à son
-> **index déclaré** par `buildParamArgs()` (`routerDecorators.ts:1390`), et les trous restent
+> **index déclaré** par `buildParamArgs()` (`routerDecorators.ts:1422`), et les trous restent
 > `undefined`. Tu peux mélanger décorés et non décorés — les non décorés reçoivent `undefined`.
 
 #### Le corps n'est pas validé — et c'est un choix
@@ -456,12 +457,12 @@ ne s'auto-promeut pas.
 | `@Header("X-Foo", "bar")` | méthode | Ajoute un en-tête ; **s'empile** (plusieurs `@Header` cumulent, `routerDecorators.ts:603`) | `@Header("Cache-Control","no-store")` |
 | `@Redirect("/url", 302)`  | méthode | Redirige **si** l'action ne renvoie rien (`Redirect()`, `routerDecorators.ts:649`)         | `@Redirect("/login", 302)`            |
 
-Les deux premiers sont appliqués par `Resolver._applyResponseMeta()` (`Resolver.ts:955`) **avant**
+Les deux premiers sont appliqués par `Resolver._applyResponseMeta()` (`Resolver.ts:977`) **avant**
 l'appel de l'action : ton code peut donc les écraser ensuite (`this.renderJson(data, 202)` gagne).
 
 `@Redirect` a une subtilité utile : si l'action **retourne un objet** portant `url` (et
 éventuellement `statusCode`), cet objet **prend le dessus** sur les valeurs du décorateur
-(`Resolver._handleRedirect()`, `Resolver.ts:980`) — la cible peut donc être calculée à l'exécution :
+(`Resolver._handleRedirect()`, `Resolver.ts:1002`) — la cible peut donc être calculée à l'exécution :
 
 ```typescript
 @Get("/go")
@@ -482,20 +483,21 @@ async go(@Query("to") to?: string) {
 Sept décorateurs, **tous duals** (classe ou méthode) et **tous sans logique** : ils posent une
 étiquette que le `Resolver` ou le firewall consommera.
 
-| Décorateur                               | Effet                                                                                                    | Ancre                                         |
-| ---------------------------------------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
-| `@IsGranted(attr \| attrs, { subject })` | Exige un attribut (rôle `ROLE_*` ou règle métier). Tableau = **OU** ; empilés = **ET** ; refus → **403** | `IsGranted()` (`routerDecorators.ts:903`)     |
-| `@RequireScope(scope \| scopes)`         | Exige un scope `api:action` d'un **jeton machine** ; no-op pour une session humaine                      | `RequireScope()` (`routerDecorators.ts:1002`) |
-| `@Anonymous()`                           | Rend l'action publique : annule l'autorisation **et** l'authentification (le « permitAll »)              | `Anonymous()` (`routerDecorators.ts:953`)     |
-| `@BypassFirewall`                        | Court-circuite le firewall (sonde de liveness, webhook signé, endpoint de login). **Sans parenthèses**   | `BypassFirewall` (`routerDecorators.ts:725`)  |
-| `@Csp({ "frame-src": [...] })`           | Ajoute des directives CSP **à cette réponse** ; classe + méthode fusionnent additivement                 | `Csp()` (`routerDecorators.ts:1071`)          |
-| `@CsrfProtect()`                         | Opt-**in** au jeton anti-CSRF (double-submit signé) en plus de la défense globale                        | `CsrfProtect` (`routerDecorators.ts:1133`)    |
-| `@CsrfExempt()`                          | Opt-**out** de la défense CSRF **en gardant** l'authentification (webhook, POST cross-origin légitime)   | `CsrfExempt` (`routerDecorators.ts:1142`)     |
+| Décorateur                                | Effet                                                                                                                                                             | Ancre                                                  |
+| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| `@IsGranted(attr \| attrs, { subject })`  | Exige un attribut (rôle `ROLE_*` ou règle métier). Tableau = **OU** ; empilés = **ET** ; refus → **403**                                                          | `IsGranted()` (`routerDecorators.ts:903`)              |
+| `@RequireScope(scope \| scopes)`          | Exige un scope `api:action` d'un **jeton machine** ; no-op pour une session humaine                                                                               | `RequireScope()` (`routerDecorators.ts:1002`)          |
+| `@RequireAuthentication({ maxAge, amr })` | Exige une connexion **récente** (`maxAge`, s) et/ou faite avec certains moyens (`amr` RFC 8176, ex. `otp`) ; évalué après `@IsGranted` ; refus → **401** RFC 9470 | `RequireAuthentication()` (`routerDecorators.ts:1883`) |
+| `@Anonymous()`                            | Rend l'action publique : annule l'autorisation **et** l'authentification (le « permitAll »)                                                                       | `Anonymous()` (`routerDecorators.ts:969`)              |
+| `@BypassFirewall`                         | Court-circuite le firewall (sonde de liveness, webhook signé, endpoint de login). **Sans parenthèses**                                                            | `BypassFirewall` (`routerDecorators.ts:725`)           |
+| `@Csp({ "frame-src": [...] })`            | Ajoute des directives CSP **à cette réponse** ; classe + méthode fusionnent additivement                                                                          | `Csp()` (`routerDecorators.ts:1092`)                   |
+| `@CsrfProtect()`                          | Opt-**in** au jeton anti-CSRF (double-submit signé) en plus de la défense globale                                                                                 | `CsrfProtect` (`routerDecorators.ts:1156`)             |
+| `@CsrfExempt()`                           | Opt-**out** de la défense CSRF **en gardant** l'authentification (webhook, POST cross-origin légitime)                                                            | `CsrfExempt` (`routerDecorators.ts:1165`)              |
 
 #### Rôles et scopes — deux axes, un seul verdict
 
 `@IsGranted` et `@RequireScope` écrivent dans **deux jeux de métadonnées distincts**, puis
-`computeSecurityRequirement()` (`routerDecorators.ts:1544`) les fusionne en une exigence unique dont
+`computeSecurityRequirement()` (`routerDecorators.ts:1648`) les fusionne en une exigence unique dont
 toutes les clauses sont en **ET**. Une seule chaîne d'application côté `Resolver`, deux jurés
 différents côté `security` (le voteur de rôles, le voteur de scopes).
 
@@ -544,7 +546,7 @@ héritées de la classe.
 
 | Décorateur                   | Cible | Effet                                                                                                      | Ancre                             |
 | ---------------------------- | ----- | ---------------------------------------------------------------------------------------------------------- | --------------------------------- |
-| `@UseSession({ readOnly? })` | dual  | Déclare le besoin d'une session serveur ; **méthode > classe** (`UseSession()`, `routerDecorators.ts:800`) | `@UseSession({ readOnly: true })` |
+| `@UseSession({ readOnly? })` | dual  | Déclare le besoin d'une session serveur ; **méthode > classe** (`UseSession()`, `routerDecorators.ts:830`) | `@UseSession({ readOnly: true })` |
 | `@Idempotent({ required? })` | dual  | Protège une mutation du double effet via `Idempotency-Key` (`Idempotent()`, `routerDecorators.ts:1171`)    | `@Idempotent()`                   |
 
 **`@UseSession` est la seule façon d'ouvrir une session** (avec un paramètre `@Session`, ou la reprise
@@ -571,9 +573,9 @@ recherches inutiles.
 | `@injectable()`                     | `nodefony`           | Rend une classe résoluble par le conteneur (`injectable()`, `kernelDecorator.ts:135`)          |
 | `@inject("nom")`                    | `nodefony`           | Injecte un service à une position de constructeur (`inject()`, `kernelDecorator.ts:186`)       |
 | `@Inject("nom")`                    | `nodefony`           | Idem, sur une propriété (`Inject()`, `kernelDecorator.ts:215`)                                 |
-| `@RealtimeAction("méthode")`        | `@nodefony/realtime` | Expose une action JSON-RPC sur socket (`RealtimeAction()`, `realtimeDecorators.ts:101`)        |
-| `@RealtimeChannel("canal", policy)` | `@nodefony/realtime` | Déclare un canal temps réel et sa politique (`RealtimeChannel()`, `realtimeDecorators.ts:192`) |
-| `@RealtimeInbound("méthode")`       | `@nodefony/realtime` | Traite un message entrant typé (`RealtimeInbound()`, `realtimeDecorators.ts:231`)              |
+| `@RealtimeAction("méthode")`        | `@nodefony/realtime` | Expose une action JSON-RPC sur socket (`RealtimeAction()`, `realtimeDecorators.ts:191`)        |
+| `@RealtimeChannel("canal", policy)` | `@nodefony/realtime` | Déclare un canal temps réel et sa politique (`RealtimeChannel()`, `realtimeDecorators.ts:240`) |
+| `@RealtimeInbound("méthode")`       | `@nodefony/realtime` | Traite un message entrant typé (`RealtimeInbound()`, `realtimeDecorators.ts:278`)              |
 
 Injection et portées → [injection-portees](../../../../../docs/architecture/injection-portees.md) ·
 socket → [realtime](../../realtime/docs/index.md).
@@ -620,11 +622,11 @@ Trois faits à retenir :
   `@route`, ou via `@All("/x", { requirements: { methods: ["WEBSOCKET"] } })` si tu préfères la forme
   courte. Les fabriques `@Get`/`@Post`… **fusionnent** les méthodes déclarées avec la leur :
   `@Get("/x", { requirements: { methods: ["WEBSOCKET"] } })` sert GET **et** WebSocket
-  (`routerDecorators.ts:535`).
+  (`routerDecorators.ts:540`).
 - **Les décorateurs de paramètre fonctionnent pareil.** Pour une invocation par socket, le corps de
   la mutation voyage dans l'ALS et **prime** sur le corps HTTP (vide dans ce cas) — c'est traité dans
-  `resolveParamArg()` (`routerDecorators.ts:1326`), et `@Query` lit la query du chemin **invoqué**,
-  pas celle du handshake (`Resolver._buildParamArgs()`, `Resolver.ts:929`).
+  `resolveParamArg()` (`routerDecorators.ts:1358`), et `@Query` lit la query du chemin **invoqué**,
+  pas celle du handshake (`Resolver._buildParamArgs()`, `Resolver.ts:947`).
 - **Les gardes s'appliquent identiquement.** `@IsGranted` protège une action joignable par socket
   exactement comme une action HTTP : la décision est prise avant l'instanciation, quel que soit le
   transport.
@@ -643,11 +645,11 @@ pas toutes identiques — c'est la source d'erreur n°1.
 | `@Domain` | option `host` de la route > méthode > classe | `controller()` (`routerDecorators.ts:189`) |
 | `@BypassFirewall` | **cumulatif** : `true` de la route, de la méthode ou de la classe suffit | `routerDecorators.ts:750` |
 | `@UseSession` | méthode > classe (fusion des champs) | `resolveSessionIntent()` (`routerDecorators.ts:858`) |
-| `@Idempotent` | méthode > classe | `computeIdempotent()` (`routerDecorators.ts:1606`) |
-| `@IsGranted` / `@RequireScope` | **cumul en ET** : classe **plus** méthode | `computeSecurityRequirement()` (`routerDecorators.ts:1544`) |
-| `@Anonymous` | méthode → annule tout ce que la classe a posé | `routerDecorators.ts:953` |
-| `@Csp` | fusion **additive** classe + méthode (sources concaténées) | `mergeCspDirectives()` (`routerDecorators.ts:1043`) |
-| `@CsrfProtect` / `@CsrfExempt` | OU logique : classe **ou** méthode suffit | `computeActionMeta()` (`routerDecorators.ts:1632`) |
+| `@Idempotent` | méthode > classe | `computeIdempotent()` (`routerDecorators.ts:1710`) |
+| `@IsGranted` / `@RequireScope` | **cumul en ET** : classe **plus** méthode | `computeSecurityRequirement()` (`routerDecorators.ts:1648`) |
+| `@Anonymous` | méthode → annule tout ce que la classe a posé | `routerDecorators.ts:969` |
+| `@Csp` | fusion **additive** classe + méthode (sources concaténées) | `mergeCspDirectives()` (`routerDecorators.ts:1066`) |
+| `@CsrfProtect` / `@CsrfExempt` | OU logique : classe **ou** méthode suffit | `computeActionMeta()` (`routerDecorators.ts:1729`) |
 | `@Header` | s'empile (plusieurs en-têtes) ; même clé → dernier écrit gagne | `Header()` (`routerDecorators.ts:603`) |
 | `@HttpCode` | un seul par action (le dernier posé écrase) | `HttpCode()` (`routerDecorators.ts:582`) |
 
@@ -692,7 +694,7 @@ sequenceDiagram
   RS->>RS: requêtes suivantes : lecture O(1), 0 Reflect
 ```
 
-Le snapshot `RouteActionMeta` (`routerDecorators.ts:1436`) regroupe **tout** ce que les décorateurs
+Le snapshot `RouteActionMeta` (`routerDecorators.ts:1537`) regroupe **tout** ce que les décorateurs
 ont dit de l'action :
 
 <!-- prettier-ignore -->
@@ -710,12 +712,12 @@ ont dit de l'action :
 
 Le `Resolver` consomme ce snapshot dans un ordre qui a du sens sécurité :
 **garde d'abord, instanciation ensuite**. `security !== null` déclenche
-`_enforceSecurity()` (`Resolver.ts:853`) **avant** `newController()` — un `403` n'instancie pas le
+`_enforceSecurity()` (`Resolver.ts:871`) **avant** `newController()` — un `403` n'instancie pas le
 contrôleur et n'exécute pas son `initialize()`. Puis viennent les arguments
-(`_buildParamArgs()`, `Resolver.ts:929`), les métadonnées de réponse
-(`_applyResponseMeta()`, `Resolver.ts:955`), l'action, et enfin la redirection éventuelle.
+(`_buildParamArgs()`, `Resolver.ts:947`), les métadonnées de réponse
+(`_applyResponseMeta()`, `Resolver.ts:977`), l'action, et enfin la redirection éventuelle.
 
-Un usage cold path mérite d'être connu : `extractActionScopes()` (`routerDecorators.ts:1520`) parcourt
+Un usage cold path mérite d'être connu : `extractActionScopes()` (`routerDecorators.ts:1624`) parcourt
 les routes au démarrage pour bâtir le **catalogue des scopes déclarés** — le formulaire de création
 de clés API dans Studio propose les scopes réellement utilisés par le code, jamais une liste
 maintenue à part.
@@ -724,15 +726,15 @@ maintenue à part.
 
 Un décorateur non employé doit coûter **zéro**. C'est tenu par trois mécanismes vérifiables :
 
-- **Lecture unique.** `resolveActionMeta()` (`routerDecorators.ts:1669`) mémorise le snapshot sur la
+- **Lecture unique.** `resolveActionMeta()` (`routerDecorators.ts:1772`) mémorise le snapshot sur la
   route au premier passage — ensuite, plus aucun appel `Reflect.getMetadata` ni `Object.entries` par
   requête. Le même schéma vaut pour la détection du flux brut
-  (`routeExpectsBodyStream()`, `routerDecorators.ts:1408`).
+  (`routeExpectsBodyStream()`, `routerDecorators.ts:1509`).
 - **`null` plutôt que structure vide.** Une action sans garde a `security: null` : le `Resolver` teste
-  un `null` et passe — ni résolution de service, ni `await`, ni allocation (`Resolver.ts:486`). Idem
+  un `null` et passe — ni résolution de service, ni `await`, ni allocation (`Resolver.ts:490`). Idem
   pour `idempotent`, `cspDirectives`, `paramsMeta`.
 - **Objets gelés et partagés.** Les exigences de sécurité et d'idempotence sont créées **une fois** et
-  `Object.freeze`-ées (`routerDecorators.ts:1496`, `:1340`) : une seule instance pour la durée de vie
+  `Object.freeze`-ées (`routerDecorators.ts:1650`, `:1696`) : une seule instance pour la durée de vie
   du processus, quelle que soit la charge. Corollaire : ne les mute jamais.
 
 Coût résiduel côté montage seulement : la reconstruction de la pile d'appels dans `route()`
@@ -743,7 +745,7 @@ route, jamais pendant une requête.
 
 Le module montre le patron à suivre : un décorateur maison **ne fait qu'écrire une métadonnée**, et
 un point du pipeline la relit. Pour un simple drapeau dual (classe + méthode), le framework fournit
-déjà la fabrique `booleanMarkerDecorator()` (`routerDecorators.ts:1108`), dont `@CsrfProtect` et
+déjà la fabrique `booleanMarkerDecorator()` (`routerDecorators.ts:1131`), dont `@CsrfProtect` et
 `@CsrfExempt` sont les deux usages.
 
 Le squelette d'un drapeau maison, en dehors du framework :

package/docs/idempotence.md

@@ -53,7 +53,7 @@ stateDiagram-v2
 ```
 
 Les quatre verdicts du store et leur traduction, décidés par `evaluateIdempotency()`
-(`idempotency.ts:142`) :
+(`idempotency.ts:131`) :
 
 - **fresh** → tu détiens la réservation : exécute l'action, puis **obligatoirement** `complete(clé,
 réponse)` (succès) ou `abort(clé)` (échec). Verdict rendu : `guarded`.
@@ -98,7 +98,7 @@ Sans ce ticket, trois choses cassent :
    donc il **doit** retenter ; c'est au serveur de rendre le retry inoffensif.
 2. **IDOR sur le cache** — si la clé stockée était la clé brute du client, il suffirait de deviner
    `order-42` pour lire la **réponse mémorisée d'un autre utilisateur**. Nodefony stocke
-   `JSON.stringify([identité, cléClient])` (`idempotency.ts:182`) : l'anti-IDOR n'est pas un contrôle
+   `JSON.stringify([identité, cléClient])` (`idempotency.ts:171`) : l'anti-IDOR n'est pas un contrôle
    ajouté, il est **structurel**, encodé dans la clé de cache. Le JSON sert de frontière non ambiguë
    (aucun séparateur magique qui pourrait entrer en collision).
 3. **DoS du cache** — une clé arbitrairement longue, ou un flot de clés uniques, remplirait la
@@ -114,14 +114,14 @@ Sans ce ticket, trois choses cassent :
 ## La vision Nodefony
 
 Le constat de conception qui compte : la sémantique IETF (quels statuts, quel scope, quelle
-empreinte) est décidée dans **un helper pur**, `evaluateIdempotency()` (`idempotency.ts:142`), qui ne
+empreinte) est décidée dans **un helper pur**, `evaluateIdempotency()` (`idempotency.ts:131`), qui ne
 connaît **aucun transport**. Il rend un verdict neutre (`IdempotencyVerdict`, `idempotency.ts:50`)
 que **deux** appelants traduisent dans leur monde :
 
 - le **data plane admin** — `AdminApiController.idempotencyGate()`
-  (`AdminApiController.ts:131`) → réponse `{status, headers, body}` ;
+  (`AdminApiController.ts:155`) → réponse `{status, headers, body}` ;
 - les **controllers userland** décorés `@Idempotent` — seam `Resolver._callWithIdempotency()`
-  (`Resolver.ts:682`) → `nodefonyError` typée, ou réponse rejouée.
+  (`Resolver.ts:687`) → `nodefonyError` typée, ou réponse rejouée.
 
 Conséquence pratique : il est **impossible** que l'idempotence HTTP et l'idempotence WebSocket
 divergent — elles partagent la même fonction. C'est le différenciateur du framework (HTTP + WS
@@ -223,7 +223,7 @@ curl -si -X POST http://localhost:5151/api/payments/charge \
 > [!WARNING]
 > **Le piège n°1** : en verdict `fresh`, la réservation est _in-flight_ tant que `complete` **ou**
 > `abort` n'a pas été appelé. Le seam `@Idempotent` gère ce couple pour toi (`try/catch`,
-> `Resolver.ts:759` et `Resolver.ts:783`). Si tu appelles le store **à la main** (cas avancé), c'est
+> `Resolver.ts:764` et `Resolver.ts:788`). Si tu appelles le store **à la main** (cas avancé), c'est
 > **ta** responsabilité : sans `abort` sur erreur, la clé reste bloquée jusqu'à l'expiration du bail
 > (60 s), et tout rejeu identique reçoit `409` pendant ce temps.
 
@@ -238,7 +238,7 @@ une route que d'anciens clients appellent déjà sans clé, le temps de la migra
 async subscribe(@Body() body: SubscribeInput) { /* … */ }
 ```
 
-Précédence **méthode > classe** (`computeIdempotent()`, `routerDecorators.ts:1606`), comme
+Précédence **méthode > classe** (`computeIdempotent()`, `routerDecorators.ts:1710`), comme
 `@UseSession`. Poser `@Idempotent()` sur la **classe** couvre toutes les mutations du controller ;
 une méthode peut resserrer ou relâcher le mode. Les méthodes sûres (GET…) restent des no-op même
 sous une classe décorée.
@@ -264,9 +264,9 @@ Deux mécanismes rendent ça possible côté socket :
 - **La méthode logique voyage par `methodOverride`** — sur une socket, `context.method` vaut
   `WEBSOCKET`, qui n'est **pas** une mutation. Sans override, la porte serait sautée et un rejeu de
   frame `socket.mutate` créerait un doublon. Le Resolver teste donc
-  `isMutationMethod(this.methodOverride ?? context.method)` (`Resolver.ts:126`).
+  `isMutationMethod(this.methodOverride ?? context.method)` (`Resolver.ts:130`).
 
-Le pont utilise `executeActionGuarded()` (`Resolver.ts:647`) : porte d'idempotence **sans** rendu HTTP
+Le pont utilise `executeActionGuarded()` (`Resolver.ts:665`) : porte d'idempotence **sans** rendu HTTP
 — la valeur nue est enveloppée par le peer WS, jamais écrite sur un transport HTTP.
 
 ## 🏗️ Architecture interne
@@ -299,20 +299,22 @@ sequenceDiagram
 
 ### Le parcours d'une mutation, étape par étape
 
-1. **Court-circuit hot path.** `callController()` (`Resolver.ts:613`) lit `meta.idempotent` sur les
+1. **Court-circuit hot path.** `callController()` (`Resolver.ts:618`) lit `meta.idempotent` sur les
    métadonnées d'action **figées par route**. `null` sur la quasi-totalité des routes → une
    comparaison, flux normal, **zéro** lookup de store et zéro allocation.
 2. **No-op sur méthode sûre.** Une action `GET` sous une classe `@Idempotent` repart directement en
-   exécution (`Resolver.ts:688`).
-3. **Empreinte du payload.** `computeFingerprint()` (`idempotency.ts:123`) hache
-   `[nom de route, params de route, corps]` (`Resolver.ts:497`). Le corps vient de l'ALS (pont WS) ou
+   exécution (`Resolver.ts:693`).
+3. **Empreinte du payload.** `computeFingerprint()` (`idempotency.ts:112`) hache
+   `[nom de route, params de route, corps]` (`Resolver.ts:501`). Le corps vient de l'ALS (pont WS) ou
    du body HTTP parsé.
-4. **Identité.** `resolveIdentity()` (`idempotency.ts:100`) dérive l'identité de `request.user`
-   (`username` → `identifier` → `id`), avec repli sur l'`userId` de l'ALS. **`null` = pas de cache** :
-   le verdict devient `execute` (`idempotency.ts:176`) — jamais de partage cross-identité.
+4. **Identité.** `resolveIdentity()` (`idempotency.ts:102`) rend l'`identifier` de l'utilisateur
+   AUTHENTIFIÉ de la requête (`RequestContext.getAuthenticatedUser()`, la règle unique du cœur).
+   L'anonyme d'une zone `anonymous` n'a pas d'identité : tous les visiteurs anonymes partagent le
+   même `identifier`, ils partageraient donc le même cache. **`null` = pas de cache** : le verdict
+   devient `execute` — jamais de partage cross-identité.
 5. **Réservation.** `store.begin()` compose la clé scopée et tranche.
 6. **Mémorisation.** En succès, `complete(clé, {status, body})` où `status` est le code de réponse
-   courant et `body` la **valeur retournée** par l'action (`Resolver.ts:704`). En erreur,
+   courant et `body` la **valeur retournée** par l'action (`Resolver.ts:722`). En erreur,
    `abort(clé)` libère la clé : **un échec ne se mémorise pas**, il doit rester réessayable.
 
 > [!CAUTION]
@@ -321,15 +323,15 @@ sequenceDiagram
 > double-effet reste évité, mais le corps rejoué est vide. Pire, si le corps retourné n'est pas
 > sérialisable (retour d'un objet Response circulaire), un store SQL/Redis lève au `stringify`. Le
 > Resolver attrape ce cas : il **journalise un WARNING explicite** puis mémorise le statut avec un
-> corps `null` (`Resolver.ts:549`) — la dédup est préservée plutôt que perdue en silence.
+> corps `null` (`Resolver.ts:554`) — la dédup est préservée plutôt que perdue en silence.
 
 ### Où la porte est câblée
 
 | Appelant                     | Point d'entrée                                                       | Traduction du verdict              |
 | ---------------------------- | -------------------------------------------------------------------- | ---------------------------------- |
-| Controller userland HTTP     | `callController()` (`Resolver.ts:613`)                               | `nodefonyError` + rendu normal     |
-| Controller userland via WS   | `executeActionGuarded()` (`Resolver.ts:647`)                         | valeur nue, enveloppée par le peer |
-| Data plane admin `/nodefony` | `AdminApiController.idempotencyGate()` (`AdminApiController.ts:131`) | `{status, headers, body}`          |
+| Controller userland HTTP     | `callController()` (`Resolver.ts:618`)                               | `nodefonyError` + rendu normal     |
+| Controller userland via WS   | `executeActionGuarded()` (`Resolver.ts:665`)                         | valeur nue, enveloppée par le peer |
+| Data plane admin `/nodefony` | `AdminApiController.idempotencyGate()` (`AdminApiController.ts:155`) | `{status, headers, body}`          |
 
 ## ⚙️ Configuration
 
@@ -554,8 +556,8 @@ cycle. La porte est appliquée par le Resolver.
 | `size`                    |     ✅      | Nombre d'entrées vivantes, **sync best-effort** (`src/nodefony/src/types/IIdempotencyStore.ts:159`).            |
 
 Les helpers du seam sont exportés et réutilisables : `isMutationMethod()` (`idempotency.ts:28`),
-`resolveIdempotencyKey()` (`idempotency.ts:68`), `resolveIdentity()` (`idempotency.ts:100`),
-`computeFingerprint()` (`idempotency.ts:123`), `evaluateIdempotency()` (`idempotency.ts:142`).
+`resolveIdempotencyKey()` (`idempotency.ts:68`), `resolveIdentity()` (`idempotency.ts:102`),
+`computeFingerprint()` (`idempotency.ts:112`), `evaluateIdempotency()` (`idempotency.ts:131`).
 
 ### `listPage` — capacités RÉELLES par store
 
@@ -636,9 +638,9 @@ pour l'affichage Studio, `idempotencyStoreRegistry.ts:81`).
 <!-- prettier-ignore -->
 | Sujet | Norme | Ancrage |
 | --- | --- | --- |
-| En-tête `Idempotency-Key`, statuts, rejeu | `draft-ietf-httpapi-idempotency-key-header-06` | `evaluateIdempotency()` (`idempotency.ts:142`) |
+| En-tête `Idempotency-Key`, statuts, rejeu | `draft-ietf-httpapi-idempotency-key-header-06` | `evaluateIdempotency()` (`idempotency.ts:131`) |
 | Clé réutilisée avec un autre payload → 422 | draft §2.2 / §2.7 | `idempotency.ts:189` |
-| Exécution concurrente identique → 409 | draft §2.6 | `idempotency.ts:197` |
+| Exécution concurrente identique → 409 | draft §2.6 | `idempotency.ts:186` |
 | Clé requise absente → 400 | draft §2.7 | `idempotency.ts:165` |
 | Méthodes non sûres = mutations | RFC 9110 §9.2.1 | `MUTATION_METHODS` (`idempotency.ts:25`) |
 | Sémantique du 422 | RFC 9110 §15.5.21 | `IdempotencyVerdict` (`idempotency.ts:50`) |
@@ -647,8 +649,8 @@ pour l'affichage Studio, `idempotencyStoreRegistry.ts:81`).
 ## ⚡ Performance et mémoire
 
 Le coût est **nul hors mutations décorées**. Sans `@Idempotent`, `RouteActionMeta.idempotent` vaut
-`null` (`routerDecorators.ts:1151`) : `callController()` fait **une comparaison** et repart en flux
-normal — zéro lookup de container, zéro `await` supplémentaire, zéro allocation (`Resolver.ts:613`).
+`null` (`routerDecorators.ts:1194`) : `callController()` fait **une comparaison** et repart en flux
+normal — zéro lookup de container, zéro `await` supplémentaire, zéro allocation (`Resolver.ts:618`).
 La métadonnée est **figée par route** et mémoïsée : aucune lecture `Reflect` par requête.
 
 Sur le chemin décoré :
@@ -691,7 +693,7 @@ Trois surfaces existent aujourd'hui :
 
 | Symptôme                                               | Cause (dans le code)                                                                 | Correction                                                                   |
 | ------------------------------------------------------ | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
-| Rejeu qui renvoie un corps **vide**                    | L'action a retourné `this.renderJson(...)` au lieu du payload (`Resolver.ts:773`)    | Retourner la **valeur brute** ; un WARNING le signale déjà dans les logs     |
+| Rejeu qui renvoie un corps **vide**                    | L'action a retourné `this.renderJson(...)` au lieu du payload (`Resolver.ts:778`)    | Retourner la **valeur brute** ; un WARNING le signale déjà dans les logs     |
 | `409` en boucle sur un endpoint                        | Action qui lève avant `complete`/`abort` → in-flight bloqué jusqu'au bail (60 s)     | Le seam le gère ; en usage manuel du store, `try/finally` obligatoire        |
 | `422 Idempotency-Key is already used`                  | Même clé, **payload différent** (empreinte ≠, `idempotency.ts:189`)                  | Une clé = une intention ; nouvelle clé par requête distincte                 |
 | Rien n'est dédupliqué **malgré** la clé                | Pas d'identité fiable → verdict `execute` (`idempotency.ts:176`)                     | S'assurer que le firewall a résolu l'utilisateur **avant** la mutation       |