@nodefony/security 10.0.0-alpha.6 → 10.0.0-alpha.8

package/dist/_virtual/{_@oxc-project_runtime@0.149.0 → _@oxc-project_runtime@0.150.0}/helpers/esm/decorate.js

@@ -1,4 +1,4 @@
-//#region \0@oxc-project+runtime@0.149.0/helpers/esm/decorate.js
+//#region \0@oxc-project+runtime@0.150.0/helpers/esm/decorate.js
 function __decorate(decorators, target, key, desc) {
 	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
 	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);

package/dist/_virtual/{_@oxc-project_runtime@0.149.0 → _@oxc-project_runtime@0.150.0}/helpers/esm/decorateMetadata.js

@@ -1,4 +1,4 @@
-//#region \0@oxc-project+runtime@0.149.0/helpers/esm/decorateMetadata.js
+//#region \0@oxc-project+runtime@0.150.0/helpers/esm/decorateMetadata.js
 function __decorateMetadata(k, v) {
 	if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }

package/dist/index.js

@@ -77,8 +77,8 @@ import SecurityUserPassword from "./nodefony/command/security-user-password.js";
 import SecurityToken from "./nodefony/command/security-token.js";
 import { createSecurityAdminApi, parseAuditQuery, registerSecurityAdminApi } from "./nodefony/src/admin/SecurityAdminApi.js";
 import { registerUserRevocationCascade } from "./nodefony/src/admin/userRevocationCascade.js";
-import __decorateMetadata from "./_virtual/_@oxc-project_runtime@0.149.0/helpers/esm/decorateMetadata.js";
-import __decorate from "./_virtual/_@oxc-project_runtime@0.149.0/helpers/esm/decorate.js";
+import __decorateMetadata from "./_virtual/_@oxc-project_runtime@0.150.0/helpers/esm/decorateMetadata.js";
+import __decorate from "./_virtual/_@oxc-project_runtime@0.150.0/helpers/esm/decorate.js";
 import { tokenStatusCriteria } from "./nodefony/src/token/tokenCriteria.js";
 import { AccessDeniedError } from "./nodefony/errors/AccessDeniedError.js";
 import "./nodefony/errors/index.js";

package/dist/nodefony/config/config.js

@@ -44,6 +44,7 @@ const areaSchema = z.strictObject({
 	stateless: z.boolean().default(false).describe("Stratégie d'identité AU-DESSUS du protocole (HTTP reste stateless par nature). false (défaut) : la zone PEUT tenir un registre serveur — la session n'est créée qu'AU LOGIN (jamais pour un anonyme, zéro alloc), cookie opaque révocable (BFF). true : aucun registre — chaque requête porte sa preuve complète (JWT/clé API), la session est ignorée même si un cookie est présent. ⚠️ Une zone destinée à un appelant NON-NAVIGATEUR (service partenaire, script, agent) doit être `true` : laissée à `false`, elle marche à l'essai — un navigateur ou un `curl -c` renvoie le cookie posé — puis échoue chez le vrai client, qui ne stocke rien et repart anonyme à chaque requête. Le symptôme est un 401 intermittent en production, que rien dans le code ne montre."),
 	mode: z.enum(["first", "all"]).default("first").describe("Chaîne d'authenticators : 'first' = le premier qui reconnaît la requête authentifie (ex. cookie OU bearer) ; 'all' = tous doivent passer (ex. mtls+jwt zone admin)."),
 	authenticators: z.array(z.string()).default([]).describe("Authenticators de la zone (sémantique selon `mode`). Validés au boot contre le registre."),
+	roles: z.array(z.string()).default([]).describe("Rôle(s) exigés PAR DÉFAUT dans la zone, en OU (l'un suffit ; hiérarchie comprise). Vide (défaut) = la zone n'exige qu'une identité, et toute route qu'elle couvre est ouverte à n'importe quel compte authentifié — c'est un défaut OUVERT, qu'une surface d'administration ne doit pas garder. Renseigné, le rôle s'applique à toute route de la zone qui ne décide PAS elle-même de son autorisation : une route gardée (`@IsGranted`, `@RequireScope`) et le pont du plan d'administration (qui résout un rôle par point d'entrée) gardent la main — sans quoi une zone fermée à l'administrateur écraserait un point d'entrée voulu accessible à son propriétaire (`me`, `sessions/mine`). Un refus ici est un 403 (authentifié, pas autorisé), jamais un 401."),
 	entryPoint: z.string().optional().describe("Route de login/redirect si non authentifié."),
 	host: z.string().optional().describe("Domaine/vhost de la zone (ex. admin.exemple.com). Omis = tous domaines."),
 	resource: z.string().optional().describe("URI canonique de la ressource protégée — l'AUDIENCE qu'un jeton doit porter pour être accepté ici (RFC 8707 §2). Obligatoire dès que la zone liste un authenticator de jetons TIERS (`external-jwt`), qui refuse de démarrer sans elle. C'est ce qui empêche un jeton valide, délivré au même porteur pour un AUTRE service, d'être rejoué sur celui-ci. Elle s'ÉCRIT et ne se dérive pas du `Host` : derrière un relais, ce que le processus croit être son adresse n'est pas ce que le client a demandé, et l'audience doit être exactement celle que le serveur d'autorisation a inscrite dans le jeton. Ex. « https://api.example.com/mcp »."),
@@ -336,7 +337,7 @@ const securityConfigSchema = z.strictObject({
 	encoders: z.record(z.string(), encoderSchema).default(() => ({ default: encoderSchema.parse({ type: "argon2id" }) })).describe("Chaîne d'encodeurs de mot de passe. 1re entrée = principal (hash à la création), suivantes = legacy en lecture seule (migration au login). Défaut : un argon2id sûr — le firewall en dérive le service `passwordEncoder`."),
 	roleHierarchy: z.record(z.string(), z.array(z.string())).default({}).describe("Hiérarchie de rôles (ROLE_ADMIN: ['ROLE_USER'])."),
 	areas: z.record(z.string(), areaSchema).default({}).describe("Zones sécurisées (firewall) par nom."),
-	realtimeChannels: z.array(realtimeChannelRuleSchema).default([]).describe("Politiques d'autorisation par préfixe sur le temps réel. Couvre les canaux WS (subscribe/inbound) **ET les actions RPC** : le nom de méthode d'une frame entrante est soumis aux mêmes règles de préfixe — une règle `admin:` garde donc aussi l'action `admin:purge`. Étend/surcharge les défauts système (syslog:/orm:/node:/dashboard:/debugbar:/realtime:/cluster: + :health/:stats = ROLE_ADMIN). Ce qui n'est couvert par aucune règle reste libre, sauf gating `@RealtimeChannel` côté controller."),
+	realtimeChannels: z.array(realtimeChannelRuleSchema).default([]).describe("Politiques d'autorisation par préfixe sur le temps réel. Couvre les canaux WS (subscribe/inbound) **ET les actions RPC** : le nom de méthode d'une frame entrante est soumis aux mêmes règles de préfixe — une règle `admin:` garde donc aussi l'action `admin:purge`. Étend/surcharge les défauts système (syslog:/orm:/node:/dashboard:/debugbar:/realtime:/cluster: + :health/:stats = ROLE_NODEFONY_ADMIN, l'échelle PLATEFORME : ces canaux exposent l'état du processus, pas celui d'une application). Ce qui n'est couvert par aucune règle reste libre, sauf gating `@RealtimeChannel` côté controller."),
 	cors: corsSchema.default(() => corsSchema.parse({})),
 	csrf: csrfSchema.default(() => csrfSchema.parse({})),
 	headers: headersSchema.default(() => headersSchema.parse({})),

package/dist/nodefony/src/SecuredArea.js

@@ -16,6 +16,12 @@ var SecuredArea = class {
 	host;
 	realtime;
 	resource;
+	/**
+	* Rôles exigés par défaut dans la zone, ou `null` quand elle n'en exige
+	* aucun. `null` plutôt qu'un tableau vide : le hot path teste une référence,
+	* et aucune zone ne porte de tableau qu'elle n'utilise pas.
+	*/
+	roles;
 	constructor(name, config) {
 		this.name = name;
 		this.pattern = new RegExp(config.pattern, "u");
@@ -26,6 +32,7 @@ var SecuredArea = class {
 		this.host = config.host;
 		this.realtime = config.realtime;
 		this.resource = config.resource;
+		this.roles = config.roles.length > 0 ? config.roles : null;
 	}
 	/**
 	* Cœur du match — pathname (+ host éventuel) déjà extraits, SANS `context`.

package/dist/nodefony/src/realtime/frameAuthorizer.js

@@ -2,13 +2,26 @@ import { NODEFONY_CHANNEL_NAMESPACE, PLATFORM_CHANNELS, PLATFORM_INBOUND, starts
 //#region nodefony/src/realtime/frameAuthorizer.ts
 /**
 * Politique système par défaut des canaux d'**introspection serveur** : réservés
-* aux administrateurs. DURCISSEMENT Zero Trust (P6) : avant, « authentifié
-* suffisait » (tout `ROLE_USER` lisait `nodefony:syslog`) ; désormais `ROLE_ADMIN`.
-* Surchargeable finement par `realtimeChannels` (ex. `ROLE_SECURITY_AUDITOR`).
+* à l'exploitant de l'INSTANCE, pas à l'administrateur d'une application.
+*
+* Ce que ces canaux exposent est l'état du **processus** — journaux, base,
+* métriques, supervision, et jusqu'au déclenchement d'un ramasse-miettes
+* bloquant. C'est l'échelle PLATEFORME, celle que le préfixe `ROLE_NODEFONY_*`
+* désigne : le seul rôle qui traverse l'isolation entre organisations
+* clientes. Un `ROLE_ADMIN` est, lui, destiné à être scopé à une organisation ;
+* le jour où plusieurs partagent une instance, il aurait lu la supervision du
+* processus qui les héberge toutes.
+*
+* Le canal d'audit ({@link SECURITY_CHANNEL_POLICY}) partage désormais cette
+* échelle — il ne se distingue plus par le rôle, mais par ce qu'il contient.
+*
+* Surchargeable finement par `realtimeChannels` : une application qui veut
+* ouvrir un de ces canaux à un rôle d'organisation le DÉCLARE, elle ne l'hérite
+* pas.
 */
 const SYSTEM_CHANNEL_POLICY = {
 	authenticated: true,
-	roles: ["ROLE_ADMIN"]
+	roles: ["ROLE_NODEFONY_ADMIN"]
 };
 /**
 * Namespace d'introspection serveur (observabilité) — s'y abonner expose l'état
@@ -24,11 +37,12 @@ const SYSTEM_CHANNEL_POLICY = {
 */
 const DEFAULT_SYSTEM_PREFIXES = [NODEFONY_CHANNEL_NAMESPACE];
 /**
-* Plancher des canaux de **sécurité** (`nodefony:audit`, P6.14 lot 4) : réservé au
-* super-admin Nodefony (`ROLE_NODEFONY_ADMIN`) — un cran AU-DESSUS du plancher
-* d'observabilité générique (`ROLE_ADMIN`). Le journal d'audit du pod ne se lit
-* pas avec un simple rôle admin applicatif. Cohérent avec le data plane HTTP de
-* l'audit (`SecurityAdminApi`, lot 3, même rôle).
+* Plancher des canaux de **sécurité** (`nodefony:audit`) : réservé à l'exploitant
+* de l'instance (`ROLE_NODEFONY_ADMIN`). Même échelle que
+* {@link SYSTEM_CHANNEL_POLICY} — le journal d'audit du pod n'est pas plus
+* exposé que sa supervision, et aucun des deux ne se lit avec un rôle
+* d'organisation. Cohérent avec le plan d'administration HTTP de l'audit
+* (`SecurityAdminApi`, même rôle).
 *
 * Multi-tenant (futur) : `nodefony:audit` reste un canal **plateforme** (pod),
 * jamais exposé à un user tenant ; l'événement portera le `tenantId` (via l'ALS)

package/dist/types/nodefony/config/config.d.ts

@@ -8,6 +8,7 @@ declare const areaSchema: z.ZodObject<{
         first: "first";
     }>>;
     authenticators: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    roles: z.ZodDefault<z.ZodArray<z.ZodString>>;
     entryPoint: z.ZodOptional<z.ZodString>;
     host: z.ZodOptional<z.ZodString>;
     resource: z.ZodOptional<z.ZodString>;
@@ -34,6 +35,7 @@ export declare const securityConfigSchema: z.ZodObject<{
             first: "first";
         }>>;
         authenticators: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        roles: z.ZodDefault<z.ZodArray<z.ZodString>>;
         entryPoint: z.ZodOptional<z.ZodString>;
         host: z.ZodOptional<z.ZodString>;
         resource: z.ZodOptional<z.ZodString>;

package/dist/types/nodefony/contracts/ISecuredArea.d.ts

@@ -52,6 +52,21 @@ export interface ISecuredArea {
      * verrou WS consulte la même zone que HTTP (invariant `api.request` ≤ `GET`).
      */
     readonly realtime: boolean;
+    /**
+     * Rôles exigés PAR DÉFAUT dans la zone — en OU, hiérarchie comprise —, ou
+     * `null` quand la zone n'exige qu'une identité.
+     *
+     * C'est le **filet** d'une surface d'administration : une route que personne
+     * n'a pensé à garder hérite du rôle de sa zone, au lieu d'être ouverte à
+     * n'importe quel compte authentifié. Une route qui décide elle-même de son
+     * autorisation — garde déclarée, ou pont du plan d'administration qui résout
+     * un rôle par point d'entrée — n'en dépend pas : c'est ce qui laisse exister
+     * un point d'entrée ouvert à son propriétaire (`me`, `sessions/mine`) dans
+     * une zone par ailleurs fermée.
+     *
+     * Un refus est un **403** (authentifié mais pas autorisé), jamais un 401.
+     */
+    readonly roles: readonly string[] | null;
     /** La requête tombe-t-elle dans cette zone ? (pattern + host éventuel). */
     match(context: ContextType): boolean;
 }

package/dist/types/nodefony/src/SecuredArea.d.ts

@@ -18,6 +18,12 @@ export declare class SecuredArea implements ISecuredArea {
     readonly host?: string;
     readonly realtime: boolean;
     readonly resource?: string;
+    /**
+     * Rôles exigés par défaut dans la zone, ou `null` quand elle n'en exige
+     * aucun. `null` plutôt qu'un tableau vide : le hot path teste une référence,
+     * et aucune zone ne porte de tableau qu'elle n'utilise pas.
+     */
+    readonly roles: readonly string[] | null;
     constructor(name: string, config: ISecurityAreaConfig);
     /**
      * Cœur du match — pathname (+ host éventuel) déjà extraits, SANS `context`.

package/dist/types/nodefony/src/realtime/frameAuthorizer.d.ts

@@ -48,9 +48,22 @@ export interface ISystemChannelRule {
 export type FrameDenyReporter = (surface: "api.request" | "channel", target: string, reason: string, token: IRealtimeToken) => void;
 /**
  * Politique système par défaut des canaux d'**introspection serveur** : réservés
- * aux administrateurs. DURCISSEMENT Zero Trust (P6) : avant, « authentifié
- * suffisait » (tout `ROLE_USER` lisait `nodefony:syslog`) ; désormais `ROLE_ADMIN`.
- * Surchargeable finement par `realtimeChannels` (ex. `ROLE_SECURITY_AUDITOR`).
+ * à l'exploitant de l'INSTANCE, pas à l'administrateur d'une application.
+ *
+ * Ce que ces canaux exposent est l'état du **processus** — journaux, base,
+ * métriques, supervision, et jusqu'au déclenchement d'un ramasse-miettes
+ * bloquant. C'est l'échelle PLATEFORME, celle que le préfixe `ROLE_NODEFONY_*`
+ * désigne : le seul rôle qui traverse l'isolation entre organisations
+ * clientes. Un `ROLE_ADMIN` est, lui, destiné à être scopé à une organisation ;
+ * le jour où plusieurs partagent une instance, il aurait lu la supervision du
+ * processus qui les héberge toutes.
+ *
+ * Le canal d'audit ({@link SECURITY_CHANNEL_POLICY}) partage désormais cette
+ * échelle — il ne se distingue plus par le rôle, mais par ce qu'il contient.
+ *
+ * Surchargeable finement par `realtimeChannels` : une application qui veut
+ * ouvrir un de ces canaux à un rôle d'organisation le DÉCLARE, elle ne l'hérite
+ * pas.
  */
 export declare const SYSTEM_CHANNEL_POLICY: IChannelPolicy;
 /**
@@ -67,11 +80,12 @@ export declare const SYSTEM_CHANNEL_POLICY: IChannelPolicy;
  */
 export declare const DEFAULT_SYSTEM_PREFIXES: readonly ["nodefony:"];
 /**
- * Plancher des canaux de **sécurité** (`nodefony:audit`, P6.14 lot 4) : réservé au
- * super-admin Nodefony (`ROLE_NODEFONY_ADMIN`) — un cran AU-DESSUS du plancher
- * d'observabilité générique (`ROLE_ADMIN`). Le journal d'audit du pod ne se lit
- * pas avec un simple rôle admin applicatif. Cohérent avec le data plane HTTP de
- * l'audit (`SecurityAdminApi`, lot 3, même rôle).
+ * Plancher des canaux de **sécurité** (`nodefony:audit`) : réservé à l'exploitant
+ * de l'instance (`ROLE_NODEFONY_ADMIN`). Même échelle que
+ * {@link SYSTEM_CHANNEL_POLICY} — le journal d'audit du pod n'est pas plus
+ * exposé que sa supervision, et aucun des deux ne se lit avec un rôle
+ * d'organisation. Cohérent avec le plan d'administration HTTP de l'audit
+ * (`SecurityAdminApi`, même rôle).
  *
  * Multi-tenant (futur) : `nodefony:audit` reste un canal **plateforme** (pod),
  * jamais exposé à un user tenant ; l'événement portera le `tenantId` (via l'ALS)

package/docs/audit.md

@@ -584,8 +584,7 @@ Ces deux absences n'ont pas le même statut. Redis n'en aura pas, et la raison n
 que le journal d'audit **croît sans borne**, se conserve des mois pour la conformité, et se
 **consulte** (recherche, filtres, pagination) : garder tout ça en mémoire vive coûte cher pour un
 motif d'accès qui n'est pas le sien. Mongo, lui, est un chemin **durable** :
-l'audit y **manque**, et c'est un manque à combler (objectif « full NoSQL », `MIGRATION_STATUS.md`
-P7.11) — un utilisateur choisit sa base de données, pas de perdre sa traçabilité.
+l'audit y **manque**, et c'est un manque à combler (objectif « full NoSQL ») — un utilisateur choisit sa base de données, pas de perdre sa traçabilité.
 
 En attendant, une application MongoDB qui veut un journal durable a trois voies : brancher un store
 maison (voir l'extension ci-dessous), charger `@nodefony/drizzle` à côté de Mongo — même en SQLite

package/docs/authorization.md

@@ -87,6 +87,35 @@ Nodefony **centralise** la décision dans un service unique, appelé par les dé
 (`@IsGranted`, `@RequireScope`) sur tous les transports, avec une posture **fail-closed** : au
 moindre doute (voter qui plante, silence du jury, moteur absent), c'est refusé — jamais accordé.
 
+## Où se situe Nodefony parmi les modèles de contrôle d'accès
+
+Le contrôle d'accès a plusieurs façons de répondre à « as-tu le droit ? », selon **ce sur quoi**
+la décision porte : un rôle porté par le compte (RBAC), des attributs du sujet, de la ressource et
+du contexte (ABAC), une relation dans un graphe (ReBAC), ou une politique écrite hors du code
+(XACML, et les moteurs qui s'en inspirent). Ce ne sont pas des concurrents : les systèmes réels en
+empilent plusieurs.
+
+Nodefony fait du **RBAC hiérarchique** — des rôles, et une hiérarchie qui dit lesquels en couvrent
+d'autres, au sens des composantes _Core_ et _Hierarchical_ du modèle NIST (ANSI INCITS 359-2004,
+révisée 2012). Le reste se **branche** au jury, décrit plus bas : un voter maison qui lit des
+attributs fait de l'ABAC, un voter qui interroge un moteur de graphe (OpenFGA, SpiceDB, Ory Keto —
+famille issue de l'article _Zanzibar_, Google, 2019) fait du ReBAC.
+
+**Ce qui n'est PAS couvert**, et qu'il vaut mieux savoir avant de concevoir :
+
+- **la séparation des devoirs** (deux rôles incompatibles sur un même compte) n'est pas outillée ;
+  elle se joue à l'affectation des rôles, pas à la décision ;
+- **le filtrage d'une liste** — « montre-moi seulement les lignes que j'ai le droit de voir » — ne
+  passe pas par le jury : chaque décision porte sur **une** ressource. Ce filtrage appartient à ta
+  requête de dépôt ;
+- **le contexte de la requête** (heure, adresse, en-têtes, corps) n'est pas au contrat d'un voter ;
+  ce qui lui parvient, c'est le jeton et le sujet ;
+- **aucune décision « accordé, à condition que »** (les _obligations_ de XACML) : le verdict est
+  binaire.
+
+En pratique, et c'est le cas dans 95 % des applications : des rôles, plus **un** voter d'ownership
+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
@@ -302,7 +331,7 @@ Dès le `DENY`, le jury **s'arrête** — court-circuit, inutile de finir (`auth
 
 **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:587-607`) : si `ROLE_ADMIN` est accordé, `doc.edit` — et son veto — n'est même pas
+(`Resolver.ts:689-702`) : 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" })`.
 
@@ -327,16 +356,16 @@ 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:577-578`) :
+moteur `authorization` est résolu **par nom** au runtime (`Resolver.ts:673-674`) :
 
 | Déclaration                                 | Sémantique                                                                                                                       |
 | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `@IsGranted("ROLE_ADMIN")`                  | un attribut — rôle, scope ou verbe métier (`IsGranted()`, `routerDecorators.ts:839`)                                             |
+| `@IsGranted("ROLE_ADMIN")`                  | un attribut — rôle, scope ou verbe métier (`IsGranted()`, `routerDecorators.ts:878`)                                             |
 | `@IsGranted(["A", "B"])`                    | **OR interne** — un attribut accordé suffit (`SecurityClause.anyOf`, `routerDecorators.ts:407-412`)                              |
 | empiler `@IsGranted` / `@RequireScope`      | **AND** — toutes les clauses doivent passer (`SecurityRequirement.clauses`, `routerDecorators.ts:426`)                           |
 | décorateur de classe + de méthode           | fusion en **AND**, figée UNE fois par route (`computeSecurityRequirement()`, `routerDecorators.ts:1500`)                         |
-| `@IsGranted("doc.edit", { subject: "id" })` | le param de route `id` est passé au voter (`Resolver._resolveSubject()`, `Resolver.ts:613-617`)                                  |
-| `@RequireScope("orders:read")`              | axe scope — metadata dédiée, fusionnée dans le même `SecurityRequirement` (`RequireScope()`, `routerDecorators.ts:760`)          |
+| `@IsGranted("doc.edit", { subject: "id" })` | le param de route `id` est passé au voter (`Resolver._resolveSubject()`, `Resolver.ts:743-747`)                                  |
+| `@RequireScope("orders:read")`              | axe scope — metadata dédiée, fusionnée dans le même `SecurityRequirement` (`RequireScope()`, `routerDecorators.ts:975`)          |
 | `@Anonymous()`                              | action **publique** — override les gardes de classe (`security: null`) + skip l'authn (`Anonymous()`, `routerDecorators.ts:887`) |
 | `@CurrentUser()`                            | injecte l'utilisateur de l'ALS — jamais le credential (`CurrentUser`, `routerDecorators.ts:1236`)                                |
 
@@ -344,7 +373,7 @@ La garde s'évalue dans `Resolver.executeAction()` **AVANT** l'instanciation DI
 403 court-circuite tout, y compris `initialize()` (`_enforceSecurity`, `Resolver.ts:331-336`). 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:576-606`).
+entre clauses (`Resolver._enforceSecurity()`, `Resolver.ts:672-702`).
 
 > [!IMPORTANT]
 > **Fail-closed intégral** : route gardée mais moteur `authorization` absent (module security non
@@ -373,6 +402,25 @@ Capte les attributs `ROLE_*` (`RoleVoter.supports()`, `RoleVoter.ts:25-27`) et v
   (`RoleVoter.ts:30-32`), posée par le firewall au boot (`firewall.ts:206`).
 - Sync par nature → `Promise.resolve`, pas de wrapper `async` inutile (`RoleVoter.ts:36-38`).
 
+#### Deux échelles de rôles — plateforme et organisation
+
+Une **convention de nom** sépare deux échelles, et c'est elle qui prépare le jour où plusieurs
+organisations partageront une instance :
+
+| Préfixe           | Échelle          | Qui le porte               | Scopable ? |
+| ----------------- | ---------------- | -------------------------- | ---------- |
+| `ROLE_NODEFONY_*` | **plateforme**   | l'exploitant de l'instance | **jamais** |
+| `ROLE_*`          | **organisation** | un compte de l'application | oui        |
+
+L'échelle plateforme est la seule qui traverse l'isolation entre organisations. Les ressources du
+**processus** — journaux, base, supervision, ramasse-miettes — sont donc gardées par elle, jamais
+par un rôle d'organisation : un administrateur applicatif n'a pas à lire l'état du serveur qui
+héberge aussi les autres.
+
+> ⚠️ **Ne donne jamais un `ROLE_NODEFONY_*` à un compte client.** Un « administrateur » chez le
+> client, c'est `ROLE_ADMIN`. C'est une convention : **rien dans le code ne l'impose** pour tes
+> propres rôles — seules les politiques de plateforme du framework sont vérifiées par un test.
+
 ### `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
@@ -400,6 +448,49 @@ voir [firewall](./firewall.md)) et fait deux choses au boot :
   le boot **jette avec le chemin complet** `A → B → A` (`RoleHierarchyWalker.ts:69-95`) : jamais
   de boucle infinie silencieuse en production.
 
+## 🛡️ Le rôle par défaut d'une zone — et ce qu'il n'écrase pas
+
+Une zone du pare-feu peut exiger un rôle **par défaut** chez elle (`roles`, voir
+[firewall](./firewall.md)). C'est le filet d'un espace d'administration : une route que personne
+n'a pensé à garder hérite du rôle de sa zone, au lieu d'être ouverte à tout compte connecté.
+
+La précédence est un **remplacement, jamais un cumul de rôles** : si l'action déclare sa propre
+garde de rôle, c'est elle qui décide — y compris pour ouvrir plus largement que la zone. C'est
+voulu : une page réservée à l'exploitant (`ROLE_SUPERVISOR`) doit rester atteignable dans une zone
+fermée à l'administrateur de plateforme.
+
+Quatre cas gardent la main, et chacun est une déclaration explicite :
+
+| Ce qui décide à la place                  | Pourquoi                                                                                          |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| une garde de **rôle** (`@IsGranted`)      | l'action a dit ce qu'elle exige                                                                   |
+| le **pont du plan d'administration**      | il résout un rôle par point d'entrée, sous une route unique — d'où l'existence de `me`, `mine`    |
+| une route qui **est** le mécanisme d'auth | lui imposer un rôle serait un verrou dont la clé est à l'intérieur                                |
+| l'**ouverture** d'une connexion WebSocket | une connexion n'accède à rien ; ce sont les frames qui accèdent, et chacune est gardée séparément |
+
+> 🔴 **`@RequireScope` seul n'est pas une décision d'identité.** Un scope dit ce qu'une clé
+> déléguée peut faire en ton nom ; sur une session humaine, le voter de scope accorde sans
+> condition. Une action gardée par un scope seul reste donc soumise au rôle de sa zone — les deux
+> axes se **cumulent**. Les traiter comme interchangeables ouvrait la route à tout compte connecté.
+
+Le dernier cas mérite d'être compris, parce qu'il ressemble à un trou sans en être un : une frame
+`api.request {path}` repasse par la **même** décision que la requête HTTP équivalente. L'invariant
+tenu est `api.request {path}` ≤ `GET {path}`.
+
+## 🚪 Trois portes décident — et deux ne passent pas par le jury
+
+C'est la chose la plus utile à savoir avant d'écrire un voter, et la plus facile à ignorer :
+
+| Porte                                      | Qui tranche                         | Le jury est-il consulté ? |
+| ------------------------------------------ | ----------------------------------- | ------------------------- |
+| une action gardée (`@IsGranted`), la zone  | `Authorization.decide()`            | **oui**                   |
+| un point d'entrée du plan d'administration | son rôle déclaré (`isAdminGranted`) | non                       |
+| une frame WebSocket (canal, `api.request`) | la politique de canal               | non                       |
+
+Les trois appliquent la **hiérarchie** de rôles, donc un même rôle y rend le même verdict. Mais un
+voter maison — ABAC, ReBAC, ownership — n'est consulté que par la première. Une règle métier qui
+doit valoir partout se place donc dans le code de l'action, pas seulement dans un voter.
+
 ## 🧩 Étendre le jury — le contrat et le registre
 
 Le contrat `IAccessVoter` (`IAccessVoter.ts:20-26`) tient en deux méthodes :
@@ -432,11 +523,20 @@ compilation** — rien à scanner au runtime ; le registre **est** le marqueur e
 
 ## 📜 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                     | **Zero Trust** (fermé par défaut)      | 403 fail-closed du Resolver (`Resolver.ts:582-584`)       |
-| 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: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:582-584`)       |
+| Journalisation de sécurité | audit des refus, jamais des octrois                                                                                     | `#auditDeny` → `recordAudit` (`authorization.ts:113-142`) |
+
+> 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
+> algorithme de combinaison, aucune obligation), et pas « compatible Zanzibar » (pas d'expansion,
+> pas de liste, pas de jeton de cohérence). Ce qu'il offre, c'est de quoi **brancher** ces moteurs
+> pour une décision ponctuelle.
 
 ## ⚡ Performance & mémoire
 
@@ -452,6 +552,11 @@ compilation** — rien à scanner au runtime ; le registre **est** le marqueur e
 
 ## ⚠️ Pièges (symptôme → cause → correction)
 
+| Symptôme                                                                | Cause                                                                                           | Correction                                                              |
+| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| 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_`                                   |

package/docs/firewall.md

@@ -431,6 +431,57 @@ muets (volume, pas un signal). Les voters sont instanciés **une fois au boot**
     ou futur (`mtls`, `agent`…) — est traité comme scopable, donc **bridé par défaut**.
   - En une ligne : rôles = qui tu es ; scopes = ce qu'une **clé** a le droit de faire.
 
+### `roles` — le rôle exigé PAR DÉFAUT dans une zone
+
+Une zone qui ne liste que des authenticators exige une **identité**, rien de plus : toute route
+qu'elle couvre est alors ouverte à **n'importe quel compte connecté**. C'est acceptable pour une
+application ; c'est un défaut ouvert pour une surface d'administration, où l'oubli d'une garde ne
+devrait jamais se solder par une fuite.
+
+`roles` renverse ce défaut. Il se déclare **une fois sur la zone**, au lieu d'être recopié sur
+chaque route :
+
+```typescript
+use("@nodefony/security", {
+  areas: {
+    admin: {
+      pattern: "^/back-office(/|$)",
+      authenticators: ["session"],
+      roles: ["ROLE_ADMIN"], // ← exigé par défaut dans toute la zone
+    },
+  },
+});
+```
+
+Les rôles listés sont en **OU** — un seul suffit — et la **hiérarchie s'applique** : un
+`ROLE_NODEFONY_ADMIN` satisfait `ROLE_ADMIN` si la hiérarchie le dit. Un refus est un **403**
+(authentifié, mais pas autorisé), jamais un 401. Omettre la clé laisse le comportement historique
+inchangé : la zone n'exige qu'une identité.
+
+#### Ce que le rôle de zone n'écrase PAS
+
+C'est un **défaut**, pas une exclusivité. Quatre cas gardent la main, et chacun est une déclaration
+explicite du code — jamais un contournement :
+
+| Ce qui décide à la place                               | Pourquoi                                                                                                              |
+| ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| Une **garde d'action** (`@IsGranted`, `@RequireScope`) | L'action a déjà dit ce qu'elle exige. Sans cela, une page réservée à l'exploitant deviendrait inatteignable pour lui. |
+| Une route **`selfGuarded`**                            | Elle tranche son autorisation dans son code — typiquement parce qu'elle ne sert QUE le porteur courant.               |
+| Un **`bypassFirewall`**                                | La route EST le mécanisme d'authentification : lui imposer un rôle serait un verrou dont la clé est à l'intérieur.    |
+| L'**ouverture d'une connexion WebSocket**              | Une connexion n'accède à rien ; ce sont les frames qui accèdent, et chacune est gardée pour son compte.               |
+
+Le dernier cas mérite d'être compris, parce qu'il pourrait passer pour un trou. Il n'en est pas un :
+une frame `api.request {path}` **repasse par la même décision** que la requête HTTP équivalente.
+L'invariant tenu est donc `api.request {path}` ≤ `GET {path}` — on n'obtient jamais par la socket ce
+que la porte HTTP refuse. Ce que la dispense évite, c'est qu'un compte sans rôle d'administration ne
+puisse plus ouvrir **aucune** socket, et perde du même coup le self-service dont il est le seul
+destinataire.
+
+> ⚠️ **`selfGuarded` n'est pas un interrupteur pour faire taire un refus.** Le poser sur une route
+> qui ne décide de rien la rend accessible à tout compte connecté, en silence. Il se justifie par ce
+> que fait le CODE de l'action : scoper au porteur courant, ou résoudre un rôle par point d'entrée.
+> Dans le doute, une garde d'action explicite est toujours préférable.
+
 ### La hiérarchie de rôles
 
 `RoleHierarchyWalker` (`src/RoleHierarchyWalker.ts`) : `ROLE_ADMIN` hérite `ROLE_USER`, etc.

package/docs/oauth2.md

@@ -163,6 +163,13 @@ reste de l'application démarre, le bouton correspondant n'apparaît simplement
 Un fournisseur n'est monté **que si ses deux secrets sont présents** : pas de bouton mort sur l'écran
 de login quand la variable manque.
 
+> **Pourquoi ces deux noms n'ont pas de préfixe `NF_`, contrairement à la règle.** Le préfixe dit à
+> qui appartient la valeur, pas qui la lit — et `GITHUB_CLIENT_ID` vous est **délivré par GitHub**.
+> Son nom est celui que la documentation du fournisseur, Auth.js et Passport emploient déjà : si
+> votre application en a une, Nodefony la lit telle quelle plutôt que de vous faire recopier la même
+> valeur sous un second nom, qui finirait par diverger. La base des callbacks, elle, n'est émise par
+> personne : c'est un réglage que votre application se donne, donc `NF_OAUTH_REDIRECT_BASE`.
+
 ```typescript
 // env.ts — SEUL lecteur de process.env (catalogue typé, validé au boot).
 // nodefony.config.ts — `ctx.env` EST ce catalogue (typé par le paramètre générique).
@@ -173,7 +180,7 @@ export const env = defineEnv({
   GITHUB_CLIENT_SECRET: envString({ optional: true }),
   // Base des callbacks : doit correspondre EXACTEMENT à l'URL enregistrée chez
   // le fournisseur (RFC 9700 — comparaison de chaînes, pas de préfixe).
-  OAUTH_REDIRECT_BASE: envString({ default: "https://localhost:5152" }),
+  NF_OAUTH_REDIRECT_BASE: envString({ default: "https://localhost:5152" }),
 });
 
 export default defineConfig<typeof env>((ctx) => ({
@@ -194,7 +201,7 @@ export default defineConfig<typeof env>((ctx) => ({
                 github: {
                   clientId: ctx.env.GITHUB_CLIENT_ID,
                   clientSecret: ctx.env.GITHUB_CLIENT_SECRET,
-                  redirectUri: `${ctx.env.OAUTH_REDIRECT_BASE}/nodefony/security/api/oauth2/github/callback`,
+                  redirectUri: `${ctx.env.NF_OAUTH_REDIRECT_BASE}/nodefony/security/api/oauth2/github/callback`,
                 },
               }
             : {}),

package/docs/totp.md

@@ -577,7 +577,7 @@ Deux pièges de lecture, signalés dans l'entité elle-même :
 | `mongoose` | —                                             | —                                   | ⏳ manquant, à venir |
 | `redis`    | —                                             | —                                   | ⏳ manquant, à venir |
 
-Ces deux absences sont des **manques**, pas des choix de périmètre (`MIGRATION_STATUS.md`, P7.11) —
+Ces deux absences sont des **manques**, pas des choix de périmètre —
 mais elles se comblent à deux régimes différents.
 
 `redis` le portera **en opt-in explicite, jamais choisi par `auto`** — exactement le régime des

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodefony/security",
-  "version": "10.0.0-alpha.6",
+  "version": "10.0.0-alpha.8",
   "description": "Pare-feu applicatif par zones pour Nodefony : authentification, autorisation par rôles, protection CSRF, journal d'audit",
   "author": "Christophe CAMENSULI <ccamensuli@gmail.com>",
   "main": "./dist/index.js",
@@ -47,26 +47,26 @@
     "@simplewebauthn/server": "14.0.2",
     "jose": "6.2.12",
     "tslib": "2.8.1",
-    "zod": "^4.6.1"
+    "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@nodefony/framework": "^10.0.0-alpha.6",
-    "@nodefony/http": "^10.0.0-alpha.6",
-    "@nodefony/user": "^10.0.0-alpha.6",
-    "@types/node": "26.5.1",
-    "@vitest/coverage-v8": "5.0.0",
-    "nodefony": "^10.0.0-alpha.6",
+    "@nodefony/framework": "^10.0.0-alpha.8",
+    "@nodefony/http": "^10.0.0-alpha.8",
+    "@nodefony/user": "^10.0.0-alpha.8",
+    "@types/node": "26.6.2",
+    "@vitest/coverage-v8": "5.0.1",
+    "nodefony": "^10.0.0-alpha.8",
     "rimraf": "6.1.3",
-    "vitest": "5.0.0"
+    "vitest": "5.0.1"
   },
   "license": "Apache-2.0",
   "readmeFilename": "README.md",
   "contributors": [],
   "peerDependencies": {
-    "@nodefony/framework": "^10.0.0-alpha.6",
-    "@nodefony/http": "^10.0.0-alpha.6",
-    "@nodefony/user": "^10.0.0-alpha.6",
-    "nodefony": "^10.0.0-alpha.6"
+    "@nodefony/framework": "^10.0.0-alpha.8",
+    "@nodefony/http": "^10.0.0-alpha.8",
+    "@nodefony/user": "^10.0.0-alpha.8",
+    "nodefony": "^10.0.0-alpha.8"
   },
   "files": [
     "dist",