nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/node/kernel/Module.js

@@ -0,0 +1,453 @@
+import { extend } from "../Tools.js";
+import Service from "../Service.js";
+import { toImportSpecifier } from "./resolveModuleEntry.js";
+import { tagListener } from "./lifecycleTags.js";
+import Injector from "./injector/injector.js";
+import { createRequire } from "node:module";
+import cluster from "node:cluster";
+import { basename, dirname, isAbsolute, resolve } from "node:path";
+import * as fs from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+//#region src/kernel/Module.ts
+const regModuleName = /^[Mm]odule-([\w-]+)/u;
+const controllers = {};
+/**
+* Unité fonctionnelle de Nodefony — successeur direct du concept "Bundle" (Symfony / Nodefony JS).
+*
+* Un Module encapsule un domaine : routes, controllers, services, entités ORM, config, commandes
+* CLI. Il est instancié par le {@link Kernel} au boot depuis le manifeste `config.modules`
+* (résolu/chargé à `onPreRegister`). Hérite de {@link Service} → bénéficie du DI Container,
+* EventEmitter, Syslog.
+*
+* Hooks lifecycle disponibles (méthodes prototype obligatoires, jamais arrow ni property init —
+* `super()` tourne AVANT les initializers) :
+* - `onKernelRegister()` — phase `onRegister` (modules s'auto-déclarent)
+* - `onKernelBoot()` — phase `onBoot` (services bootés, connexions ouvertes)
+* - `onKernelReady()` — phase `onReady` (cross-wiring inter-modules)
+* - `init(kernel?)` — appelé par {@link Kernel.addModule}, équivalent constructeur async
+*
+* @example
+* ```ts
+* import { Module, services } from "nodefony";
+*
+* // `@services([...])` déclare les services du module ; l'ordre de la liste
+* // n'importe pas (il est recalculé depuis les dépendances déclarées).
+* @services([MyService])
+* export class MyModule extends Module {
+*   static readonly path: string = import.meta.url;
+*
+*   async onKernelBoot(): Promise<this> {
+*     this.log("Module booted", "INFO");
+*     return this;
+*   }
+* }
+* ```
+*
+* @remarks Le constructor attache TOUJOURS **un** listener, indépendamment des hooks de la
+*   sous-classe : un `prependOnceListener("onPreBoot")` qui charge le `package.json` du module
+*   ({@link Module.setEvents}). Les hooks `onKernelRegister/Boot/Ready` ne sont attachés que si la
+*   sous-classe les définit.
+*/
+var Module = class Module extends Service {
+	commands = {};
+	static controllers = controllers;
+	/**
+	* Criticité du module pour la **résilience de boot** (Phase 3). `true` (défaut)
+	* = un échec/timeout d'un de ses hooks lifecycle interrompt le boot **en
+	* production** (le pod crashe → l'orchestrateur le redémarre, cloud-native) et
+	* émet un WARNING **en développement** (le serveur démarre quand même). `false`
+	* = fail-soft partout (le module est optionnel : un échec n'empêche jamais le
+	* boot — ex. studio, fronts de démo, mediasoup, realtime, redis).
+	*
+	* ⚠️ **Statique** (pas une propriété d'instance) : lue dans le constructeur via
+	* `Module.setEvents()`, donc AVANT que les initializers de la sous-classe ne
+	* tournent — une `critical = false` en propriété d'instance arriverait trop
+	* tard. Override déclaratif : `static override critical = false;`.
+	*/
+	static critical = true;
+	package;
+	path = "";
+	isApp = false;
+	/**
+	* Noms des services enregistrés PAR ce module (via {@link addService},
+	* y compris ceux du décorateur `@services`). Alloué au 1er ajout (lazy).
+	* Sert l'introspection admin (Studio) — qui n'est pas inférable du Container
+	* partagé seul. Cf {@link getServiceNames}.
+	*/
+	_serviceNames = null;
+	/**
+	* Initialise le module — appelé par {@link Kernel.addModule}.
+	*
+	* @param name - nom unique du module dans le kernel (key dans `kernel.modules`).
+	* @param kernel - kernel parent (fournit container, syslog, lifecycle events).
+	* @param path - chemin source du module (généralement `import.meta.url`).
+	* @param options - config du module (merge avec defaults via `setParameters("modules.<name>")`).
+	*/
+	constructor(name, kernel, path, options) {
+		super(name, kernel.container, void 0, options);
+		this.setParameters(`modules.${this.name}`, this.options);
+		this.path = this.setPath(path);
+		this.setEvents();
+	}
+	/**
+	* Schéma JSON (`z.toJSONSchema`) de la configuration du module, ou `null` si le
+	* module n'est pas (encore) migré vers une validation Zod.
+	*
+	* Lu par le data plane admin ({@link KernelAdminApi} endpoint `module/{name}`) :
+	* Studio affiche alors la config en mode « réglages documentés » (clé, type,
+	* défaut, valeurs possibles, état, et valeur effective issue de `options`) au
+	* lieu d'un dump brut clé→valeur. Les flags Nodefony (`reserved`,
+	* `runtimeMutable`, `kernelDerived`, `secret`) attachés via `.meta()` (natif zod) sont
+	* recopiés dans le JSON Schema par `z.toJSONSchema()` et exploités par l'UI.
+	*
+	* Défaut `null` (aucun schéma). Un module migré **override** pour renvoyer son
+	* `xConfigJsonSchema()`. Le core n'importe PAS zod : la sérialisation vit dans
+	* chaque module qui possède son schéma (0 dépendance ajoutée au cœur).
+	*
+	* @returns le JSON Schema de la config du module, ou `null`.
+	*/
+	configSchema() {
+		return null;
+	}
+	/**
+	* Config **validée + gelée** du module — point d'accès UNIFORME et typé.
+	*
+	* Renvoie `this.options` (l'objet de config du module, réassigné par sa
+	* validation Zod à `onKernelRegister`). Un module se type via
+	* `extends Module<IXConfig>` → `this.config` est alors `IXConfig` sans cast.
+	* Remplace le double idiome historique (`this.options` brut d'un côté,
+	* `this.get("<module>Config")` de l'autre) par un seul accès. Coût nul : le
+	* getter renvoie la référence, aucune allocation ni appel système.
+	*
+	* @returns la config du module, typée `TConfig` (défaut `Record<string, unknown>`).
+	*/
+	get config() {
+		return this.options;
+	}
+	/**
+	* Résout le chemin source du module (`module.path`) — normalise URL `file://`,
+	* remonte au-dessus de `dist/` si nécessaire.
+	*
+	* @remarks Opération purement LEXICALE, volontairement : l'entrée est déjà absolue
+	*   (`import.meta.url`). Remonter le dossier `dist` passait auparavant par
+	*   `resolve(myPath, "..")`, qui ancre le chemin sur le répertoire courant — donc sous
+	*   Windows y ajoute la lettre de lecteur et normalise les séparateurs. La racine d'un
+	*   module se mettait ainsi à dépendre de l'endroit d'où l'on avait lancé le process.
+	*   `dirname` donne le même résultat sur tout chemin absolu, sans cet ancrage.
+	*
+	* @param myPath - chemin brut (souvent `import.meta.url` de la classe Module).
+	* @returns chemin absolu du dossier source du module.
+	*/
+	setPath(myPath) {
+		if (myPath.startsWith("file://")) myPath = fileURLToPath(myPath);
+		const dir = basename(dirname(myPath)) === "dist" ? dirname(myPath) : myPath;
+		return dirname(dir);
+	}
+	gePath(name = this.name) {
+		return Module.getModulePath(name);
+	}
+	/**
+	* Résout le chemin d'installation d'un module npm via `require.resolve`.
+	*
+	* @param name - nom du package npm (`"@nodefony/http"`, etc.).
+	* @returns chemin absolu vers le dossier du module.
+	*/
+	static getModulePath(name) {
+		const pth = createRequire(import.meta.url).resolve(name);
+		if (basename(dirname(pth)) === "dist") return dirname(dirname(pth));
+		return dirname(pth);
+	}
+	/**
+	* Câble les hooks lifecycle (`onKernelRegister/Boot/Ready`) sur le kernel parent.
+	*
+	* Appelé une seule fois dans le constructor. Lit les méthodes prototype définies par
+	* la sous-classe et les attache via `kernel.once()`. Si la sous-classe ne définit pas
+	* un hook, il n'est pas attaché (pas de listener orphelin).
+	*
+	* Toujours attache un listener `onPreBoot` (prepend, donc index 0) pour charger le
+	* `package.json` du module. Les overrides de config `Module-<name>`, eux, ne passent
+	* PLUS par ici : ils sont appliqués par `Kernel.applyModuleConfigOverrides()` entre
+	* `onPreRegister` et `onRegister` (raison détaillée dans le corps de la méthode).
+	*/
+	setEvents() {
+		const owner = this.name;
+		const critical = this.constructor.critical;
+		if (this.onKernelRegister) this.kernel?.once("onRegister", tagListener(this.onKernelRegister.bind(this), owner, critical));
+		if (this.onKernelBoot) this.kernel?.once("onBoot", tagListener(this.onKernelBoot.bind(this), owner, critical));
+		if (this.onKernelReady) this.kernel?.once("onReady", tagListener(this.onKernelReady.bind(this), owner, critical));
+		this.kernel?.prependOnceListener("onPreBoot", tagListener(async () => {
+			this.package = await this.getPackageJson();
+		}, owner, critical));
+	}
+	/**
+	* Pose un hook de cycle de vie du kernel **au nom de ce module** — donc avec sa
+	* politique de boot (propriétaire + criticité), comme les hooks de classe.
+	*
+	* À utiliser partout où un hook est posé « à la main » depuis le module ou
+	* depuis un de ses services (`this.module.hookKernel("onBoot", …)`) plutôt que
+	* `kernel.once(...)` directement. Pourquoi : un listener non tagué n'a pas de
+	* criticité, et {@link Kernel.isBootErrorFatal} traite l'absence de tag comme
+	* **critique**. Un module qui déclare pourtant `static critical = false`
+	* voyait donc son échec interrompre le boot en production — la déclaration ne
+	* portait que sur ses hooks de classe, pas sur ceux de ses services. Le
+	* journal ne pouvait même pas nommer le coupable (`"(anonyme)"`).
+	*
+	* @param event - nom de l'événement de cycle (`onRegister`, `onBoot`, `onReady`…).
+	* @param listener - le hook ; il hérite du nom et de la criticité du module.
+	* @returns le module (chaînable).
+	*/
+	hookKernel(event, listener) {
+		const critical = this.constructor.critical;
+		this.kernel?.once(event, tagListener(listener, this.name, critical));
+		return this;
+	}
+	/**
+	* Détecte les overrides de config destinés à d'autres modules (clés `Module-<name>`),
+	* les applique, puis les RETIRE des options du module porteur.
+	*
+	* Permet à un module de surcharger la config d'un autre module sans toucher au code de
+	* ce dernier. Exemple : `Module-http: { port: 8080 }` dans la config de l'app → applique
+	* `{ port: 8080 }` à `@nodefony/http`. Warn si module cible inconnu.
+	*
+	* 🔴 **La clé est CONSOMMÉE.** C'est un ordre de configuration adressé à un
+	* autre module, pas une donnée du module porteur : une fois appliquée, elle
+	* n'a plus rien à faire dans ses options. La garder cassait la validation du
+	* porteur dès lors que son schéma refuse les clés inconnues — et déclarer
+	* `module-*` dans les onze schémas du dépôt aurait recopié onze fois une règle
+	* qui vit ici. Le retrait vaut AUSSI quand la cible est introuvable : la
+	* configuration est morte, elle vient d'être signalée, et rien ne gagne à ce
+	* qu'elle fasse en plus tomber le boot du porteur.
+	*
+	* Personne d'autre ne lit ces clés (`rg` sur `regModuleName` : ce fichier
+	* seul) ; sous l'ancien `z.object` elles disparaissaient de toute façon au
+	* parse, silencieusement — ce retrait rend explicite ce qui se produisait déjà.
+	*
+	* @param deep - merge profond (`true`, défaut) vs shallow (`false`).
+	* @returns options du module courant, débarrassées des clés d'override consommées.
+	*/
+	readOverrideModuleConfig(deep = true) {
+		const consumed = [];
+		for (const ele in this.options) {
+			let index = null;
+			const override = this.options[ele];
+			index = regModuleName.exec(ele);
+			if (index && index[1]) {
+				consumed.push(ele);
+				const mod = this.kernel?.getModule(index[1]);
+				if (!mod) {
+					this.log(`Override de config ignoré : module "${index[1]}" introuvable (absent de @modules) — retirer la clé "${ele}" ou charger le module`, this.isApp ? "WARNING" : "INFO");
+					continue;
+				}
+				this.log(`Override Configuration Module: ${mod.name}`, "INFO");
+				if (deep) mod.options = extend(true, {}, mod.options, override);
+				else mod.options = extend({}, mod.options, override);
+			}
+		}
+		for (const key of consumed) delete this.options[key];
+		return this.options;
+	}
+	registerService(service, name) {
+		return Injector.register(name || service.constructor.name, service);
+	}
+	/**
+	* Instancie un service via l'{@link Injector} et l'enregistre dans le container du module.
+	*
+	* Si le service expose une méthode `init(module)`, elle est appelée après
+	* instanciation (équivalent constructeur async). Warn si un service du même nom existe
+	* déjà (override).
+	*
+	* @param service - constructeur du service (typiquement décoré `@injectable`).
+	* @param args - arguments additionnels passés au constructeur (après les `@inject` resolved).
+	* @returns instance du service prête à l'usage.
+	*/
+	async addService(service, ...args) {
+		const inst = Injector.instantiate(service, this, ...args);
+		if (this.get(inst.name)) this.log(`SERVICE ALREADY EXIST  override old service  : ${inst.name}`, "WARNING");
+		this.log(`SERVICE ADD : ${inst.name}`, "DEBUG");
+		const serviceInit = inst;
+		const kernel = this.kernel;
+		if (kernel) await kernel.guardServiceInitialize(serviceInit, this, this.constructor.critical);
+		else if (serviceInit.init) {
+			this.log(`SERVICE INITIALIZE : ${inst.name}`, "DEBUG");
+			await serviceInit.init(this);
+		}
+		Injector.rememberContainerKey(service, inst.name);
+		this.set(inst.name, inst);
+		(this._serviceNames ??= []).push(inst.name);
+		return this.get(inst.name);
+	}
+	/**
+	* Politique d'échec d'un service déclaré via `@services([...])` : la MÊME que
+	* pour le reste du boot — fatal en production (ou sur une erreur de
+	* configuration), fail-soft **ANNONCÉ** ailleurs (agrégé au BootReport, qui
+	* fait dire « boot DÉGRADÉ » au superviseur). Jamais un skip silencieux.
+	*
+	* Appelée par le décorateur `@services`, dont le `catch` se contentait de
+	* logger : l'échec n'atteignait ni la politique de criticité ni le BootReport.
+	*
+	* @param error - l'échec remonté par `addService`/`loadService`.
+	* @param service - le constructeur (ou le chemin) du service fautif.
+	* @throws l'erreur d'origine si l'échec est fatal (production + module critique).
+	*/
+	handleServiceBootError(error, service) {
+		const serviceName = typeof service === "string" ? service : service?.name ?? "(anonyme)";
+		const kernel = this.kernel;
+		if (!kernel) {
+			this.log(error, "ERROR");
+			return;
+		}
+		const critical = this.constructor.critical;
+		if (kernel.serviceBootErrorFatal(error, `${this.name} → ${serviceName}`, critical)) throw error;
+	}
+	/**
+	* Noms des services enregistrés par ce module (ordre d'ajout).
+	* Vide tant qu'aucun service n'a été ajouté.
+	*/
+	getServiceNames() {
+		return this._serviceNames ? [...this._serviceNames] : [];
+	}
+	/**
+	* Charge dynamiquement un service depuis un chemin (`import()`) puis l'enregistre via
+	* {@link addService}.
+	*
+	* @param service - chemin/spécifier du module à importer (URL, npm package, path relatif).
+	* @param args - arguments additionnels passés au constructeur.
+	* @returns instance du service après instanciation + `init()`.
+	*/
+	async loadService(service, ...args) {
+		const res = await import(toImportSpecifier(service));
+		return this.addService(res.default, ...args);
+	}
+	async getPackageJson(cwd) {
+		return await this.loadJson(resolve(this.path, "package.json"), cwd);
+	}
+	/**
+	* Récupère un controller enregistré **dans ce module**.
+	*
+	* Le registre `Module.controllers` est process-global mais indexé par clé
+	* **module-scopée** `${module}:${ClassName}` (posée par `Router.setController`),
+	* exactement comme l'identité d'un `forward("module:controller:action")`. Deux
+	* modules peuvent donc porter un controller homonyme sans collision.
+	*
+	* @param name - nom de classe du controller (ex. `"DefaultController"`).
+	* @returns constructeur typé du controller.
+	* @throws Si `name` est falsy ou si le controller n'est pas enregistré pour ce module.
+	*/
+	getController(name) {
+		if (!name) throw new Error(`Module getController argument name is mandatory`);
+		const key = `${this.name}:${name}`;
+		if (Module.controllers[key]) return Module.controllers[key];
+		throw new Error(`Controller ${key} not exist`);
+	}
+	/**
+	* Retourne les controllers enregistrés **pour ce module** (clés = nom de classe
+	* nu, préfixe module retiré). Vue jetable filtrée depuis le registre global.
+	*/
+	getControllers() {
+		const prefix = `${this.name}:`;
+		const out = {};
+		for (const key in Module.controllers) if (key.startsWith(prefix)) out[key.slice(prefix.length)] = Module.controllers[key];
+		return out;
+	}
+	/**
+	* Liste les dépendances + peerDependencies du module (depuis son `package.json`).
+	*
+	* @returns array de noms de packages npm. **devDependencies exclus**. Doublons possibles
+	*   si un même package est listé dans `dependencies` ET `peerDependencies`.
+	*/
+	getDependencies() {
+		return Module.getPackageDependencies(this.package);
+	}
+	/**
+	* Variante static — extrait les deps depuis un `package.json` arbitraire.
+	*
+	* @param mypackage - objet `package.json` parsé.
+	* @returns array de noms de packages npm (deps + peerDeps, devDeps exclus).
+	*/
+	static getPackageDependencies(mypackage) {
+		if (mypackage) {
+			const dependencies = Object.keys(mypackage.dependencies || {});
+			const peerDependencies = Object.keys(mypackage.peerDependencies || {});
+			return [...dependencies, ...peerDependencies];
+		}
+		return [];
+	}
+	getModuleName() {
+		return this.package?.name;
+	}
+	getModuleVersion() {
+		return this.package?.version;
+	}
+	/**
+	* Enregistre une commande CLI custom rattachée à ce module.
+	*
+	* Pattern legacy `nodefony <name>:<action>` (ex: `nodefony users:add`). Le {@link CliKernel}
+	* doit être disponible (sinon throw `Kernel not ready`). En mode cluster worker, exceptions
+	* non-primary sont silencieusement avalées (retour `void`).
+	*
+	* @param cliCommand - constructeur de la commande (extends `Command`).
+	* @returns instance de la commande enregistrée OU `void` si worker secondaire.
+	* @throws `Error("Kernel not ready")` si `kernel.cli` n'est pas instancié.
+	*/
+	addCommand(cliCommand) {
+		if (this.kernel && this.kernel.cli) try {
+			const command = new cliCommand(this.kernel.cli);
+			this.commands[command.name] = command;
+			return command;
+		} catch (e) {
+			if (cluster.isPrimary) throw e;
+			else if (cluster.isWorker) return;
+		}
+		throw new Error(`Kernel not ready`);
+	}
+	/**
+	* Exécute `npm install` (ou yarn/pnpm) dans le dossier du module.
+	*
+	* @param force - ajoute `--force` à l'install. Défaut `false`.
+	* @returns code de retour du process (0 = succès) ou Error si crash.
+	* @throws Si `packageManager` n'est pas attaché au CliKernel.
+	*/
+	async install(force = false) {
+		if ((this.kernel?.cli)?.packageManager) {
+			if (force) return await (this.kernel?.cli)?.packageManager(["install", "--force"], this.path);
+			return await (this.kernel?.cli)?.packageManager(["install"], this.path);
+		}
+		throw new Error(`Package Manager not found`);
+	}
+	/**
+	* Exécute `npm outdated` dans le dossier du module.
+	*
+	* @returns code de retour du process ou Error si crash.
+	* @throws Si `packageManager` n'est pas attaché au CliKernel.
+	*/
+	async outdated() {
+		if ((this.kernel?.cli)?.packageManager) return await (this.kernel?.cli)?.packageManager(["outdated"], this.path);
+		throw new Error(`Package Manager not found`);
+	}
+	async loadJson(url, cwd = process.cwd()) {
+		try {
+			const detectpath = isAbsolute(url) ? url : resolve(cwd, url);
+			const fileContent = await fs.readFile(detectpath, "utf-8");
+			return JSON.parse(fileContent);
+		} catch (error) {
+			this.log(error, "ERROR");
+			throw error;
+		}
+	}
+	/**
+	* Surcharge {@link Service.log} — `msgid` défaut = `"MODULE <name>"` pour identifier
+	* les logs de ce module dans le pipeline Syslog.
+	*
+	* @param pci - payload (string, Error, objet — narrower côté lecteur).
+	* @param severity - sévérité RFC 5424 (`"INFO"`, `"ERROR"`, etc.).
+	* @param msgid - catégorie de message. Défaut `"MODULE <name>"`.
+	* @param msg - détail libre optionnel.
+	* @returns le `Pdu` produit (utile pour audit/tests).
+	*/
+	log(pci, severity, msgid, msg) {
+		if (!msgid) msgid = `MODULE ${this.name}`;
+		return super.log(pci, severity, msgid, msg);
+	}
+};
+//#endregion
+export { Module as default };

package/dist/node/kernel/adminPlane/adminCaller.js

@@ -0,0 +1,98 @@
+import { ADMIN_DEFAULT_ROLE } from "./adminRbac.js";
+//#region src/kernel/adminPlane/adminCaller.ts
+/**
+* L'opérateur qui lance une commande sur sa propre application.
+*
+* Il possède déjà le processus : il lit les sources, il édite la configuration,
+* il peut arrêter le serveur. Lui refuser la lecture d'administration
+* n'ajouterait aucune barrière — il lui suffirait d'ouvrir un fichier — mais
+* rendrait la commande inutile. Le rôle est donc accordé ; ce qui compte, c'est
+* que ce soit ÉNONCÉ ici plutôt que fabriqué en silence au fond d'une lecture.
+*
+* @returns l'appelant à présenter depuis une commande locale.
+*/
+function localOperatorCaller() {
+	return {
+		user: null,
+		roles: [ADMIN_DEFAULT_ROLE],
+		label: "opérateur local (CLI)"
+	};
+}
+/**
+* Scope d'un jeton ouvrant la LECTURE du plan d'administration.
+*
+* Trois valeurs suffisent pour tout le plan (celle-ci, {@link ADMIN_SCOPE_WRITE},
+* et l'absence de scope pour la topologie) : un scope par endpoint se périmerait
+* à chaque ajout, et la granularité fine existe déjà pour les API d'une
+* application, portée par `@RequireScope` sur ses routes.
+*/
+const ADMIN_SCOPE_READ = "admin:read";
+/** Scope d'un jeton ouvrant les MUTATIONS du plan d'administration. */
+const ADMIN_SCOPE_WRITE = "admin:write";
+/**
+* Traduit les scopes d'un jeton en rôles Nodefony.
+*
+* ⚠️ Les deux scopes mènent aujourd'hui au MÊME rôle, et ce n'est pas un
+* raccourci : le contrôle d'accès du plan d'administration est uniforme — tous
+* les endpoints exigent `ROLE_NODEFONY_ADMIN`, lectures comme mutations.
+* Distinguer ici produirait un théâtre d'autorisation : deux scopes séparés qui
+* ouvrent exactement la même chose, et une promesse que le code ne tient pas.
+* La séparation deviendra réelle quand `IAdminEndpoint.role` se différenciera.
+*
+* Un jeton qui ne porte aucun de ces scopes n'obtient **aucun rôle** : la
+* vérification d'audience (RFC 8707) prouve que le jeton vise cette ressource,
+* elle ne dit rien de ce que son porteur a le droit d'y faire.
+*
+* ## Rôle et scope — la doctrine, et l'asymétrie qui reste
+*
+* Autorisation effective = **droits de l'utilisateur ∧ portée déléguée au
+* porteur**. Un scope borne ce qu'un TIERS peut faire au nom de quelqu'un ; en
+* session directe (cookie, Studio) il n'y a pas de tiers, donc rien à borner et
+* le rôle suffit. Dès qu'un JETON entre en jeu, il y a délégation, et les deux
+* doivent mordre — c'est ce que fait cette fonction, avec
+* {@link refusedAdminScopes} qui borne l'autre bout : porter le rôle ne suffit
+* pas à obtenir le scope, porter le scope ne suffit pas à avoir le rôle.
+*
+* ⚠️ **Dette nommée, non fermée** : un jeton présenté sur la porte HTTP
+* (`ExternalJwtAuthenticator`, `subjectPolicy: "require"`) est rattaché à un
+* compte local et hérite des rôles de ce compte **sans** intersection avec ses
+* scopes — les routes du plan d'administration sont montées par le broker, donc
+* ne portent aucun `@RequireScope`. Le même porteur obtient donc plus par HTTP
+* que par MCP. Fermer cela suppose que la provenance de l'identité (session ou
+* jeton) voyage jusqu'au contrôle de rôle, ce qu'elle ne fait pas aujourd'hui.
+*
+* ⚠️ Et ce n'est pas du moindre privilège : le plan d'administration n'a qu'UN
+* rôle, qui ouvre tous ses endpoints. « Fail-closed » — pas de laissez-passer
+* par défaut — n'est pas « Zero Trust ». La granularité réelle suppose que
+* `IAdminEndpoint.role` se différencie ; tant qu'il ne l'est pas, découper les
+* scopes plus finement ne serait qu'un décor.
+*
+* @param scopes - scopes accordés par le serveur d'autorisation.
+* @returns les rôles à présenter, éventuellement aucun.
+*/
+function rolesFromScopes(scopes) {
+	return scopes.includes("admin:read") || scopes.includes("admin:write") ? [ADMIN_DEFAULT_ROLE] : [];
+}
+/**
+* Les scopes d'administration demandés que ce porteur **ne peut pas** obtenir.
+*
+* Réciproque de {@link rolesFromScopes}, et indispensable avec elle : si un
+* scope ouvre le plan d'administration, alors l'émetteur ne peut pas le signer
+* sur simple demande. Sans cette borne, « tout jeton vaut administrateur »
+* devient « tout jeton QUI DEMANDE vaut administrateur » — le trou change de
+* forme, pas de taille.
+*
+* Ne juge QUE les scopes d'administration du framework. Les scopes d'une
+* application (`shop:read`, `billing:export`) ne regardent pas Nodefony : c'est
+* à elle de dire qui peut les obtenir.
+*
+* @param requested - scopes demandés au grant (RFC 6749 §3.3).
+* @param roles - rôles du porteur, tels que son compte les porte.
+* @returns les scopes à REFUSER — vide si la demande est légitime.
+*/
+function refusedAdminScopes(requested, roles) {
+	if (roles.includes("ROLE_NODEFONY_ADMIN")) return [];
+	return requested.filter((scope) => scope === "admin:read" || scope === "admin:write");
+}
+//#endregion
+export { ADMIN_SCOPE_READ, ADMIN_SCOPE_WRITE, localOperatorCaller, refusedAdminScopes, rolesFromScopes };

package/dist/node/kernel/adminPlane/adminRbac.js

@@ -0,0 +1,51 @@
+//#region src/kernel/adminPlane/adminRbac.ts
+/**
+* Décision d'autorisation du data plane admin (Studio) — fonction **PURE**,
+* cœur de la garantie RBAC, testée isolément (zéro dépendance runtime/DI).
+*
+* **Fail-closed.** Un endpoint qui exige un rôle (`requiredRole` non vide) n'est
+* accordé QUE si l'appelant le porte. Un appelant **sans rôle** (`roles=[]` — ex.
+* compte authentifié non doté, créé via `POST users` sans `roles`) est donc
+* **rejeté** (403). C'était le **fail-open historique** : le 403 était court-circuité
+* par une garde `roles.length > 0 &&` — vestige du « mode mock » d'avant P6, quand
+* aucun rôle n'était injecté. Zero Trust : l'absence de rôle ne vaut pas
+* laissez-passer. Le firewall (zone `nodefony-admin`) garantit l'AUTHENTIFICATION
+* en amont ; cette fonction tranche le RÔLE.
+*
+* `requiredRole` vide (`""`) ou absent = endpoint **public déclaré**
+* (`IAdminEndpoint.public`, ex. liveness `livez`) → toujours accordé : le RBAC du
+* broker est volontairement court-circuité, la protection vit alors dans le firewall.
+*
+* @param roles - rôles **bruts** de l'appelant (projection ALS `IAdminRequest.roles`).
+* @param requiredRole - rôle exigé par la route (`""`/`undefined` = public).
+* @returns `true` si l'accès est accordé.
+*/
+function isAdminGranted(roles, requiredRole) {
+	if (!requiredRole) return true;
+	return roles.includes(requiredRole);
+}
+/**
+* Rôle exigé par défaut d'un endpoint d'administration qui n'en déclare aucun.
+*
+* Le défaut est **restrictif** : un producteur qui oublie de qualifier son
+* endpoint le publie au rôle d'administrateur, jamais à l'anonyme. Ouvrir plus
+* large se DÉCLARE (`IAdminEndpoint.public`) et se relit en revue.
+*/
+const ADMIN_DEFAULT_ROLE = "ROLE_NODEFONY_ADMIN";
+/**
+* Rôle **effectif** d'un endpoint — la règle, à un seul endroit.
+*
+* Toutes les portes du plan d'administration (route HTTP montée par le broker,
+* pont WS-RPC, commande `inspect`, serveur MCP) doivent trancher le même rôle
+* pour le même endpoint. Deux résolutions séparées finiraient par diverger, et
+* c'est la porte secondaire — celle qu'on relit le moins — qui deviendrait la
+* plus permissive.
+*
+* @param endpoint - la définition telle que le producteur la déclare.
+* @returns le rôle exigé, ou `""` pour un endpoint **public déclaré**.
+*/
+function resolveAdminRole(endpoint) {
+	return endpoint.public ? "" : endpoint.role ?? "ROLE_NODEFONY_ADMIN";
+}
+//#endregion
+export { ADMIN_DEFAULT_ROLE, isAdminGranted, resolveAdminRole };