@nodefony/framework 10.0.0-alpha.7 → 10.0.0-alpha.8

package/dist/nodefony/config/config.js

@@ -53,7 +53,8 @@ var config_default = {
 		},
 		"nodefony-admin": {
 			pattern: "^/nodefony/[^/]+/api(/|$)",
-			authenticators: ["session"]
+			authenticators: ["session"],
+			roles: ["ROLE_NODEFONY_ADMIN"]
 		}
 	} }
 };

package/dist/nodefony/controller/AdminApiController.js

@@ -150,13 +150,33 @@ var AdminApiController = class AdminApiController extends Controller {
 			idempotencyKey: resolveIdempotencyKey(als?.idempotencyKey, this.context?.request?.headers?.["idempotency-key"])
 		};
 	}
-	/** Extrait les rôles de l'utilisateur ALS sans coupler le core à `IUser`. */
+	/**
+	* Extrait les rôles de l'utilisateur ALS sans coupler le core à `IUser`, en
+	* y **ajoutant ceux que la hiérarchie leur fait couvrir**.
+	*
+	* Sans cet aplatissement, un point d'entrée qui exige `ROLE_DEV` refuserait
+	* un administrateur de plateforme qui le couvre pourtant par hiérarchie : la
+	* décision du plan d'administration est une comparaison de noms
+	* (`isAdminGranted`), là où le jury d'autorisation et le verrou de frame
+	* consultent tous deux la hiérarchie. Trois portes, un même rôle exigé, deux
+	* verdicts possibles — et c'est la porte qu'on relit le moins qui serait la
+	* plus stricte.
+	*
+	* Le parcours est résolu **par nom** (`roleHierarchy`), comme le moteur
+	* d'autorisation : `@nodefony/framework` n'importe jamais `@nodefony/security`.
+	* Absent (module de sécurité non chargé), on rend les rôles bruts — on ne
+	* perd donc jamais ce que l'appelant porte déjà.
+	*/
 	extractRoles(user) {
+		let roles = [];
 		if (user && typeof user === "object" && "roles" in user) {
-			const roles = user.roles;
-			if (Array.isArray(roles)) return roles.filter((r) => typeof r === "string");
+			const brut = user.roles;
+			if (Array.isArray(brut)) roles = brut.filter((r) => typeof r === "string");
 		}
-		return [];
+		if (roles.length === 0) return roles;
+		const walker = this.context?.container?.get("roleHierarchy");
+		if (!walker?.reachableRoles) return roles;
+		return [...walker.reachableRoles(roles)];
 	}
 };
 //#endregion

package/dist/nodefony/controller/ApiKeyController.js

@@ -142,7 +142,8 @@ function mountApiKeyRoutes(frameworkModule) {
 		path,
 		constructor: ApiKeyController,
 		classMethod,
-		requirements: { methods: [method] }
+		requirements: { methods: [method] },
+		areaRoleExempt: true
 	});
 	if (!Object.prototype.hasOwnProperty.call(ApiKeyController.prototype, "module")) router_default.setController(ApiKeyController, frameworkModule);
 	mounted = true;

package/dist/nodefony/controller/TotpController.js

@@ -120,7 +120,8 @@ function mountTotpRoutes(frameworkModule) {
 		path,
 		constructor: TotpController,
 		classMethod,
-		requirements: { methods: [method] }
+		requirements: { methods: [method] },
+		areaRoleExempt: true
 	});
 	if (!Object.prototype.hasOwnProperty.call(TotpController.prototype, "module")) router_default.setController(TotpController, frameworkModule);
 	mounted = true;

package/dist/nodefony/decorators/routerDecorators.js

@@ -904,7 +904,10 @@ function computeSecurityRequirement(ctor, method) {
 		...methodScopes
 	];
 	if (all.length === 0) return null;
-	return Object.freeze({ clauses: Object.freeze(all) });
+	return Object.freeze({
+		clauses: Object.freeze(all),
+		hasRoleClause: classClauses.length + methodClauses.length > 0
+	});
 }
 /**
 * P6 — Fusionne les directives `@Csp` (classe + méthode) en un jeu figé, ou

package/dist/nodefony/service/AdminBroker.js

@@ -81,7 +81,8 @@ let AdminBroker = class AdminBroker extends Service {
 				path,
 				constructor: AdminApiController,
 				classMethod: "dispatch",
-				requirements: { methods }
+				requirements: { methods },
+				areaRoleExempt: true
 			});
 			this.byRouteName.set(name, {
 				name,

package/dist/nodefony/service/router.js

@@ -125,6 +125,7 @@ let Router = class Router extends Service {
 	resolve(context, cleanPathOverride, methodOverride) {
 		const resolver = new Resolver(context);
 		resolver.methodOverride = methodOverride ?? null;
+		resolver.messageInvocation = cleanPathOverride !== void 0;
 		const cleanPath = cleanPathOverride ?? Route.cleanPathname(context);
 		let index = routeIndex;
 		if (index === null || index.length !== routes.length || index.first !== routes[0] || index.last !== routes[routes.length - 1]) index = buildRouteIndex();

package/dist/nodefony/src/Resolver.js

@@ -13,6 +13,14 @@ import { Http2Response, HttpResponse, WebsocketResponse } from "@nodefony/http";
 * `context.container` (le cache `"controller"` y survit au Resolver : un
 * forward ou un 2ᵉ Resolver WS sur la MÊME connexion retrouve l'instance).
 */
+/**
+* Exigences d'autorisation dérivées des **zones** du firewall, mémoïsées par
+* zone (`Resolver._areaSecurity`). Les zones sont figées au boot : une entrée
+* par zone, fabriquée une fois pour la vie du processus. `WeakMap` plutôt que
+* `Map` pour ne pas retenir une zone d'un kernel arrêté — plusieurs kernels
+* cohabitent dans une même suite de tests.
+*/
+const areaRequirements = /* @__PURE__ */ new WeakMap();
 var Resolver = class {
 	injector;
 	controller = null;
@@ -44,6 +52,18 @@ var Resolver = class {
 	* sur `context.method`.
 	*/
 	methodOverride = null;
+	/**
+	* Cette résolution est-elle une invocation **par message** (pont WS-RPC
+	* `api.request`) plutôt que l'établissement de la connexion ?
+	*
+	* Posé par `Router.resolve` dès qu'un `cleanPathOverride` est fourni : c'est
+	* exactement ce qui distingue « la socket s'ouvre » de « la socket demande
+	* telle ressource ». Le premier n'accède à rien, le second accède — et seul
+	* le second doit subir le rôle par défaut de la zone ({@link _areaSecurity}),
+	* sans quoi l'ouverture même du tuyau deviendrait réservée aux
+	* administrateurs.
+	*/
+	messageInvocation = false;
 	constructor(context) {
 		this.context = context;
 		this.injector = context.container?.get("injector") ?? null;
@@ -152,6 +172,10 @@ var Resolver = class {
 	async executeAction(data, reload = false, metaArg) {
 		const meta = metaArg ?? (this.route ? resolveActionMeta(this.route) : computeActionMeta(this.controller, this.actionName));
 		if (meta.security !== null) await this._enforceSecurity(meta.security);
+		if (meta.security === null || !meta.security.hasRoleClause) {
+			const area = this._areaSecurity();
+			if (area !== null) await this._enforceSecurity(area);
+		}
 		let controller = this.context.container?.get("controller");
 		if (!controller || reload || this.controller && !(controller instanceof this.controller)) controller = await this.newController();
 		if (this.controller?.scope !== "singleton") {
@@ -282,6 +306,43 @@ var Resolver = class {
 		}
 	}
 	/**
+	* Exigence d'autorisation **héritée de la zone** du firewall, pour une route
+	* qui n'en déclare aucune — ou `null` quand il n'y a rien à appliquer.
+	*
+	* Pourquoi ce filet existe : une zone qui n'exige qu'une **identité** laisse
+	* toute route qu'elle couvre accessible à n'importe quel compte authentifié.
+	* Sur une surface d'administration, le défaut doit être l'inverse — l'oubli
+	* se solde par un refus, jamais par une fuite. Le rôle se déclare donc UNE
+	* fois sur la zone, au lieu d'être recopié sur chaque route.
+	*
+	* Trois dispenses, et elles sont toutes des déclarations explicites :
+	* `bypassFirewall` (la route EST le mécanisme d'authentification),
+	* {@link Route.areaRoleExempt} (le pont du plan d'administration, qui résout un
+	* rôle par point d'entrée), et une garde d'action — traitée par l'appelant,
+	* qui n'entre ici que si `meta.security` est nul.
+	*
+	* L'exigence est **mémoïsée par zone** : les zones sont figées au boot et se
+	* comptent sur une main, donc la fabrication n'a lieu qu'une fois par zone
+	* sur la vie du processus — le hot path ne fait qu'un `get` de `WeakMap`.
+	*
+	* @returns l'exigence à évaluer, ou `null` s'il n'y en a aucune.
+	*/
+	_areaSecurity() {
+		if (this.bypassFirewall) return null;
+		if (this.route?.areaRoleExempt) return null;
+		if (this.context.method === "WEBSOCKET" && !this.messageInvocation) return null;
+		const area = this.context.security;
+		if (!area || !area.security) return null;
+		const roles = area.roles;
+		if (roles === null || roles.length === 0) return null;
+		let requirement = areaRequirements.get(area);
+		if (requirement === void 0) {
+			requirement = Object.freeze({ clauses: Object.freeze([Object.freeze({ anyOf: roles })]) });
+			areaRequirements.set(area, requirement);
+		}
+		return requirement;
+	}
+	/**
 	* Évalue l'exigence d'autorisation (`@IsGranted`) d'une action via le service
 	* `authorization` (par nom, 0 import security). Clauses en **AND**, attributs
 	* d'une clause en **OR**. Refus (ou moteur/identité absents) → 403 (Zero Trust,

package/dist/nodefony/src/Route.js

@@ -140,6 +140,11 @@ var Route = class Route {
 	varRegexp;
 	bypassFirewall = false;
 	/**
+	* La route décide seule de son autorisation → la zone du firewall n'applique
+	* pas son rôle par défaut. Cf {@link RouteOptions.areaRoleExempt}.
+	*/
+	areaRoleExempt = false;
+	/**
 	* P2.9 — Cache mémoïsé : l'action attend-elle le **flux brut** du body
 	* (`@Body({ stream:true })`) ? `undefined` = pas encore calculé (résolu au 1er
 	* `routeExpectsBodyStream(route)` via lecture `Reflect` des `ParamMeta`, O(1)
@@ -174,6 +179,7 @@ var Route = class Route {
 			this.setDefaults(obj.defaults);
 			this.requirements = obj.requirements || {};
 			this.bypassFirewall = obj.bypassFirewall ?? false;
+			this.areaRoleExempt = obj.areaRoleExempt ?? false;
 			this.compile();
 		}
 		this.generateId();
@@ -335,7 +341,7 @@ var Route = class Route {
 		const ctrl = this.controller?.name || "?";
 		const action = this.classMethod || this.name;
 		const mod = this.module?.name ? `@${this.module.name}/` : "";
-		const auth = this.bypassFirewall ? "  (no auth)" : "";
+		const auth = this.bypassFirewall ? "  (no auth)" : this.areaRoleExempt ? "  (hors rôle de zone)" : "";
 		return `${method} ${this.path} → ${mod}${ctrl}.${action}${auth}`;
 	}
 	toObject() {
@@ -348,7 +354,8 @@ var Route = class Route {
 			filePath: this.filePath,
 			schemes: this.schemes,
 			variables: this.variables,
-			bypassFirewall: this.bypassFirewall
+			bypassFirewall: this.bypassFirewall,
+			areaRoleExempt: this.areaRoleExempt
 		};
 	}
 	setDefaults(arg) {

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

@@ -34,6 +34,7 @@ declare const _default: {
             "nodefony-admin": {
                 pattern: string;
                 authenticators: string[];
+                roles: string[];
             };
         };
     };

package/dist/types/nodefony/controller/AdminApiController.d.ts

@@ -64,7 +64,23 @@ declare class AdminApiController extends Controller {
     private idempotencyGate;
     /** Projette le Context courant en requête admin normalisée. */
     private buildRequest;
-    /** Extrait les rôles de l'utilisateur ALS sans coupler le core à `IUser`. */
+    /**
+     * Extrait les rôles de l'utilisateur ALS sans coupler le core à `IUser`, en
+     * y **ajoutant ceux que la hiérarchie leur fait couvrir**.
+     *
+     * Sans cet aplatissement, un point d'entrée qui exige `ROLE_DEV` refuserait
+     * un administrateur de plateforme qui le couvre pourtant par hiérarchie : la
+     * décision du plan d'administration est une comparaison de noms
+     * (`isAdminGranted`), là où le jury d'autorisation et le verrou de frame
+     * consultent tous deux la hiérarchie. Trois portes, un même rôle exigé, deux
+     * verdicts possibles — et c'est la porte qu'on relit le moins qui serait la
+     * plus stricte.
+     *
+     * Le parcours est résolu **par nom** (`roleHierarchy`), comme le moteur
+     * d'autorisation : `@nodefony/framework` n'importe jamais `@nodefony/security`.
+     * Absent (module de sécurité non chargé), on rend les rôles bruts — on ne
+     * perd donc jamais ce que l'appelant porte déjà.
+     */
     private extractRoles;
 }
 export default AdminApiController;

package/dist/types/nodefony/decorators/routerDecorators.d.ts

@@ -121,6 +121,20 @@ export interface SecurityClause {
 export interface SecurityRequirement {
     /** Clauses en AND — toutes doivent être accordées (chacune est un OR interne). */
     readonly clauses: readonly SecurityClause[];
+    /**
+     * L'exigence porte-t-elle au moins une clause de **rôle** (`@IsGranted`), par
+     * opposition à des clauses de **scope** seules (`@RequireScope`) ?
+     *
+     * Les deux axes sont orthogonaux : un rôle dit QUI tu es, un scope dit ce
+     * qu'une clé déléguée peut faire EN TON NOM. Une action gardée par un scope
+     * seul n'a donc rien décidé de l'identité — et sur une session humaine le
+     * voter de scope accorde sans condition, puisqu'il ne contraint que les clés
+     * machine. C'est ce que lit le rôle par défaut d'une zone pour savoir s'il
+     * doit s'appliquer EN PLUS (`Resolver`) : sans cette distinction, un
+     * `@RequireScope` seul dispenserait du rôle de zone et ouvrirait la route à
+     * tout compte connecté.
+     */
+    readonly hasRoleClause: boolean;
 }
 /**
  * Directives CSP additionnelles déclarées par une action (`@Csp`) :

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

@@ -16,16 +16,6 @@ import { type RouteActionMeta, type RedirectMeta } from "../decorators/routerDec
 export interface ControllerWithInitialize {
     initialize(): Promise<this>;
 }
-/**
- * Résout une route vers son couple controller/action et exécute l'action —
- * UN Resolver est alloué par requête HTTP (et par connexion WS, réutilisé
- * par message). **POJO volontaire** (V3.1) : n'étend PAS `Service` — le
- * plumbing Service (Map de listeners trackés, spread d'options, lookups
- * kernel/syslog) coûtait par requête sans aucun consommateur (jamais écouté,
- * jamais loggé, jamais dans le container). Le DI per-request passe par
- * `context.container` (le cache `"controller"` y survit au Resolver : un
- * forward ou un 2ᵉ Resolver WS sur la MÊME connexion retrouve l'instance).
- */
 declare class Resolver implements IResolver {
     injector?: Injector | null;
     controller: ControllerConstructor | null;
@@ -57,6 +47,18 @@ declare class Resolver implements IResolver {
      * sur `context.method`.
      */
     methodOverride: string | null;
+    /**
+     * Cette résolution est-elle une invocation **par message** (pont WS-RPC
+     * `api.request`) plutôt que l'établissement de la connexion ?
+     *
+     * Posé par `Router.resolve` dès qu'un `cleanPathOverride` est fourni : c'est
+     * exactement ce qui distingue « la socket s'ouvre » de « la socket demande
+     * telle ressource ». Le premier n'accède à rien, le second accède — et seul
+     * le second doit subir le rôle par défaut de la zone ({@link _areaSecurity}),
+     * sans quoi l'ouverture même du tuyau deviendrait réservée aux
+     * administrateurs.
+     */
+    messageInvocation: boolean;
     constructor(context: ContextType);
     match(route: Route, context: ContextType, cleanPath?: string): ((string | null)[] & Record<string, unknown>) | null | undefined;
     /**
@@ -133,6 +135,29 @@ declare class Resolver implements IResolver {
      * le pont (`executeActionGuarded`) enveloppe la valeur nue.
      */
     private _callWithIdempotency;
+    /**
+     * Exigence d'autorisation **héritée de la zone** du firewall, pour une route
+     * qui n'en déclare aucune — ou `null` quand il n'y a rien à appliquer.
+     *
+     * Pourquoi ce filet existe : une zone qui n'exige qu'une **identité** laisse
+     * toute route qu'elle couvre accessible à n'importe quel compte authentifié.
+     * Sur une surface d'administration, le défaut doit être l'inverse — l'oubli
+     * se solde par un refus, jamais par une fuite. Le rôle se déclare donc UNE
+     * fois sur la zone, au lieu d'être recopié sur chaque route.
+     *
+     * Trois dispenses, et elles sont toutes des déclarations explicites :
+     * `bypassFirewall` (la route EST le mécanisme d'authentification),
+     * {@link Route.areaRoleExempt} (le pont du plan d'administration, qui résout un
+     * rôle par point d'entrée), et une garde d'action — traitée par l'appelant,
+     * qui n'entre ici que si `meta.security` est nul.
+     *
+     * L'exigence est **mémoïsée par zone** : les zones sont figées au boot et se
+     * comptent sur une main, donc la fabrication n'a lieu qu'une fois par zone
+     * sur la vie du processus — le hot path ne fait qu'un `get` de `WeakMap`.
+     *
+     * @returns l'exigence à évaluer, ou `null` s'il n'y en a aucune.
+     */
+    private _areaSecurity;
     /**
      * Évalue l'exigence d'autorisation (`@IsGranted`) d'une action via le service
      * `authorization` (par nom, 0 import security). Clauses en **AND**, attributs

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

@@ -37,6 +37,29 @@ export interface RouteOptions {
      * le mécanisme qu'elles servent. Défaut `false` (Zero Trust).
      */
     bypassFirewall?: boolean;
+    /**
+     * **INTERNE — n'est pas destiné aux applications.** Soustrait la route au
+     * rôle exigé par défaut dans sa zone du firewall (`ISecuredArea.roles`).
+     *
+     * Le nom dit ce que le drapeau FAIT, et non ce qu'il promettrait : il
+     * n'installe **aucune** garde, il en retire une. Posé sur une route qui ne
+     * décide de rien, il la rend accessible à tout compte connecté, en silence.
+     * C'est pourquoi un contrôle refuse toute route qui le porte hors des
+     * producteurs déclarés du framework — voir
+     * `tests/unit/areaRoleExemptInventory.test.ts`.
+     *
+     * Les deux seuls usages légitimes, tous deux internes : le pont du plan
+     * d'administration, qui résout un rôle **par point d'entrée**
+     * (`resolveAdminRole`) sous une route unique ; et les routes de gestion des
+     * clés personnelles, dont l'action est scopée au porteur courant. Sans eux,
+     * une zone fermée au rôle d'administrateur ferait disparaître le
+     * self-service (`me`, `sessions/mine`, `keys`) pour son propre destinataire.
+     *
+     * Une application qui veut protéger sa route déclare une garde
+     * (`@IsGranted`) : c'est une décision qui se relit, là où ceci est une
+     * exception qui se justifie. Défaut `false`.
+     */
+    areaRoleExempt?: boolean;
 }
 export interface RouteRequirements {
     domain?: string | string[];
@@ -85,6 +108,11 @@ declare class Route implements IRoute {
     methodsAllow?: string;
     varRegexp?: Record<string, RegExp>;
     bypassFirewall: boolean;
+    /**
+     * La route décide seule de son autorisation → la zone du firewall n'applique
+     * pas son rôle par défaut. Cf {@link RouteOptions.areaRoleExempt}.
+     */
+    areaRoleExempt: boolean;
     /**
      * P2.9 — Cache mémoïsé : l'action attend-elle le **flux brut** du body
      * (`@Body({ stream:true })`) ? `undefined` = pas encore calculé (résolu au 1er

package/docs/idempotence.md

@@ -368,7 +368,7 @@ MongoDB mérite une mention : `mongoose` n'implémente **pas encore** de store d
 `NF_DATABASE_URL=mongodb://…` fait donc tomber la résolution en étape **4** → repli `memory` avec la
 raison annoncée — et un repli `memory` en cluster ne déduplique plus rien entre pods : le rejeu que
 cette brique promet d'empêcher passe sur un autre pod. En attendant le store Mongo (objectif « full
-NoSQL », `MIGRATION_STATUS.md` P7.11), la dédup cross-pod passe par `redis`.
+NoSQL »), la dédup cross-pod passe par `redis`.
 
 ### Le contrat de dégradation : fail-loud, jamais silencieux
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodefony/framework",
-  "version": "10.0.0-alpha.7",
+  "version": "10.0.0-alpha.8",
   "description": "Le modèle de programmation Nodefony : routeur, contrôleurs, décorateurs et vues — HTTP et WebSocket dans le même contexte",
   "author": "Christophe CAMENSULI <ccamensuli@gmail.com>",
   "main": "./dist/index.js",
@@ -51,12 +51,12 @@
     "tslib": "2.8.1"
   },
   "devDependencies": {
-    "@nodefony/http": "^10.0.0-alpha.7",
+    "@nodefony/http": "^10.0.0-alpha.8",
     "@types/chai": "5.2.3",
-    "@types/node": "26.6.1",
+    "@types/node": "26.6.2",
     "@vitest/coverage-v8": "5.0.1",
     "chai": "6.2.2",
-    "nodefony": "^10.0.0-alpha.7",
+    "nodefony": "^10.0.0-alpha.8",
     "rimraf": "6.1.3",
     "tsx": "4.23.13",
     "vitest": "5.0.1"
@@ -65,8 +65,8 @@
   "readmeFilename": "README.md",
   "contributors": [],
   "peerDependencies": {
-    "@nodefony/http": "^10.0.0-alpha.7",
-    "nodefony": "^10.0.0-alpha.7",
+    "@nodefony/http": "^10.0.0-alpha.8",
+    "nodefony": "^10.0.0-alpha.8",
     "zod": "^4.6.5"
   },
   "files": [