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

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

@@ -1,9 +1,8 @@
-//#region \0@oxc-project+runtime@0.153.0/helpers/esm/decorate.js
+// \0@oxc-project+runtime@0.155.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);
 	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
 	return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
-//#endregion
 export { __decorate as default };

package/dist/index.js

@@ -81,22 +81,21 @@ import SecurityUserList from "./nodefony/command/security-user-list.js";
 import SecurityUserDelete from "./nodefony/command/security-user-delete.js";
 import SecurityUserPassword from "./nodefony/command/security-user-password.js";
 import { publicRoutesNotice } from "./nodefony/src/boot/publicRoutesNotice.js";
-import SecurityToken from "./nodefony/command/security-token.js";
+import SecurityMcpToken from "./nodefony/command/security-mcp-token.js";
 import SecurityKeycloakRealm from "./nodefony/keycloak/security-keycloak-realm.js";
 import SecurityOAuthDoctor from "./nodefony/command/security-oauth-doctor.js";
 import { createSecurityAdminApi, parseAuditQuery, registerSecurityAdminApi } from "./nodefony/src/admin/SecurityAdminApi.js";
 import { registerUserRevocationCascade, usersEventBusNotice } from "./nodefony/src/admin/userRevocationCascade.js";
-import __decorateMetadata from "./_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorateMetadata.js";
-import __decorate from "./_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorate.js";
+import __decorate from "./_virtual/_@oxc-project_runtime@0.155.0/helpers/esm/decorate.js";
 import { tokenStatusCriteria } from "./nodefony/src/token/tokenCriteria.js";
 import { requestClientCredentialsToken } from "./nodefony/src/oauth/clientCredentials.js";
 import { AccessDeniedError } from "./nodefony/errors/AccessDeniedError.js";
 import "./nodefony/errors/index.js";
 import "./nodefony/contracts/index.js";
-import { Kernel, Module, services } from "nodefony";
+import { Module, services } from "nodefony";
 import { fileURLToPath } from "node:url";
 import { registerUserAdminApi } from "@nodefony/user";
-//#region index.ts
+// index.ts
 /**
 * `@nodefony/security` — couche de sécurité de Nodefony (refonte 2026, P6).
 *
@@ -120,7 +119,7 @@ let Security = class Security extends Module {
 		this.addCommand(SecurityUserList);
 		this.addCommand(SecurityUserDelete);
 		this.addCommand(SecurityUserPassword);
-		this.addCommand(SecurityToken);
+		this.addCommand(SecurityMcpToken);
 		this.addCommand(SecurityKeycloakRealm);
 		this.addCommand(SecurityOAuthDoctor);
 	}
@@ -185,7 +184,6 @@ Security = __decorate([services([
 	TotpService,
 	WebhookService,
 	KeycloakService
-]), __decorateMetadata("design:paramtypes", [typeof Kernel === "undefined" ? Object : Kernel])], Security);
+])], Security);
 var security_default = Security;
-//#endregion
 export { AccessDeniedError, AccessTokenVerifierService, AnonymousAuthenticator, AnonymousToken, ApiKeyAuthenticator, ApiKeyError, ApiKeyService, AuditService, AuthFlow, AuthenticationError, Authorization, Cors, CredentialTransportPolicy, Csrf, CsrfError, CsrfTokenManager, ExternalJwtAuthenticator, Firewall, InsecureTransportError, InvalidTargetError, JwtAuthenticator, JwtKeystore, KeycloakAdminClient, KeycloakAdminError, KeycloakService, LoginThrottler, MemoryAuditStore, MemoryTokenStore, MemoryTotpSecretStore, MemoryWebAuthnCredentialStore, MemoryWebhookStore, OAuth2Client, OAuth2RequestError, OAuth2Service, OAuth2Tokens, RemoteJwtVerifier, RoleHierarchyWalker, RoleVoter, ScopeVoter, SecuredArea, SecurityHeaders, SessionAuthenticator, SsrfError, TOKEN_DEFAULT_ORDER, TOKEN_FACETS, TOKEN_SORTABLE_FIELDS, ThrottledError, TokenService, TotpService, UnverifiableTokenError, UserPasswordAuthenticator, UserToken, VoterVote, WEBHOOK_DEFAULT_ORDER, WEBHOOK_SORTABLE_FIELDS, WebAuthnService, WebhookService, amrForFactor, assertPublicUrl, base32Decode, beginTotpEnrollment, confirmTotpEnrollment, createCodeChallenge, createDiscoveredOidcProvider, createGithubProvider, createOidcProvider, createSecurityAdminApi, decryptSecret, security_default as default, defineSecurityConfig, deriveKey, deriveTotpKey, diagnoseOAuthProvider, disableTotp, discoverAuthorizationServer, encryptSecret, generateApiKey, generateCodeVerifier, generateEphemeralKey, generateState, getAuditStoreFactory, getAuthenticatorFactory, getOAuthProviderFactory, getTokenStoreFactory, getTotpStoreFactory, getWebAuthnStoreFactory, getWebhookStoreFactory, hashApiKey, isBlockedAddress, keycloakAdminTarget, keycloakLoginThemeCheck, listAuditStores, listAuthenticatorFactories, listOAuthProviders, listTokenStores, listTotpStores, listVoterFactories, listWebAuthnStores, listWebhookStores, looksLikeApiKey, matchesTokenStatus, oauthProviderRequiresIssuer, parseApiKey, parseAuditQuery, peekIssuer, readAuditContext, readKeycloakLoginTheme, readLogoutTokenClaims, recordAudit, registerAuditStore, registerAuthenticatorFactory, registerOAuthProvider, registerSecurityAdminApi, registerTokenStore, registerTotpStore, registerVoterFactory, registerWebAuthnStore, registerWebhookStore, requestClientCredentialsToken, resolveJwtRuntime, securityConfigJsonSchema, shouldEnforceCredentialTransport, tokenStatusCriteria, tokenStatusOf, totpCode, totpStatus, verifyTotpLogin };

package/dist/nodefony/command/{security-token.js → security-mcp-token.js}

@@ -3,7 +3,7 @@ import { ADMIN_SCOPE_READ, ADMIN_SCOPE_WRITE, AGENT_TARGETS, CONSOLE_DATA_RUN_PR
 import path from "node:path";
 import { existsSync } from "node:fs";
 import { spawnSync } from "node:child_process";
-//#region nodefony/command/security-token.ts
+// nodefony/command/security-mcp-token.ts
 const options = {
 	runProfile: CONSOLE_DATA_RUN_PROFILE,
 	helpGroup: "COMPTES ET SECRETS",
@@ -74,7 +74,7 @@ const DIM = "\x1B[2m";
 const BOLD = "\x1B[1m";
 const RESET = "\x1B[0m";
 /**
-* `nodefony security:token` — émet un jeton d'accès pour une porte de cette
+* `nodefony security:mcp:token` — émet un jeton d'accès pour une porte de cette
 * application (la porte MCP par défaut).
 *
 * **Pourquoi une commande, et pas un `curl`.** Le jeton s'obtenait par un appel
@@ -88,18 +88,26 @@ const RESET = "\x1B[0m";
 * raison d'être de la liaison d'audience. La commande la vise d'elle-même,
 * `--resource` ne sert qu'à en viser une autre.
 *
-* Suit `security:secrets` : `--write` pose la valeur là où l'AGENT la lit
-* (gitignoré), jamais dans le `.env` commité, et ne remplace jamais une valeur
-* existante — une rotation est un geste explicite.
+* `--write` pose la valeur là où l'AGENT la lit (gitignoré), jamais dans le
+* `.env` de l'application. Relancée, elle REMPLACE le jeton chez les agents qui
+* le portent déjà — la rotation est le geste le plus fréquent — et n'en câble
+* aucun nouveau sans le proposer.
 */
-var SecurityToken = class extends Command {
+var SecurityMcpToken = class extends Command {
 	constructor(cli) {
-		super("security:token", `émet un jeton d'accès pour la porte MCP`, cli, options);
+		super("security:mcp:token", `émet un jeton d'accès pour la porte MCP`, cli, {
+			...options,
+			examples: [
+				"nodefony security:mcp:token",
+				"nodefony security:mcp:token --write",
+				"nodefony security:mcp:token alice --scope admin:read --ttl 60"
+			]
+		});
 		this.addArgument("[identifier]", "compte porteur du jeton (défaut : admin)");
 		this.addOption("-s, --scope <scopes>", `scopes demandés, séparés par des espaces (défaut : « ${ADMIN_SCOPE_READ} » ; ajouter « ${ADMIN_SCOPE_WRITE} » pour les mutations)`);
 		this.addOption("-r, --resource <uri>", "audience visée (défaut : la porte MCP de cette application)");
 		this.addOption("-a, --agent <noms>", "agents à servir, séparés par des virgules (défaut : ceux détectés ; « none » pour aucun)");
-		this.addOption("-t, --ttl <duree>", "durée de validité, en minutes (défaut : 8 h avec --write, sinon celle de la config, 15 min)");
+		this.addOption("-t, --ttl <minutes>", "durée de validité, en minutes (défaut : 8 h avec --write, sinon celle de la config, 15 min)");
 		this.addOption("-w, --write", `pose ${MCP_TOKEN_ENV} dans la configuration des agents présents`);
 		this.addOption("-j, --json", "sortie JSON (scripts/CI)");
 	}
@@ -300,7 +308,7 @@ var SecurityToken = class extends Command {
   porteur obtiendrait un jeton pour la ressource de son choix :
 
       use("@nodefony/security", {
-        jwt: { audiences: ["${resource}"] },\n      })\n\n  → puis npm run build (le runtime lit le dist)\n` : `  La porte est servie par un module de DÉVELOPPEMENT, absent en\n  « ${env} » : un jeton pour une porte absente n'aurait personne\n  pour l'accepter.\n\n  → NODE_ENV=development nodefony security:token${opts.write ? " --write" : ""}\n`) + `  → ou vise une autre porte : --resource <uri>`, "ERROR");
+        jwt: { audiences: ["${resource}"] },\n      })\n\n  → puis npm run build (le runtime lit le dist)\n` : `  La porte est servie par un module de DÉVELOPPEMENT, absent en\n  « ${env} » : un jeton pour une porte absente n'aurait personne\n  pour l'accepter.\n\n  → NODE_ENV=development nodefony security:mcp:token${opts.write ? " --write" : ""}\n`) + `  → ou vise une autre porte : --resource <uri>`, "ERROR");
 				process.exitCode = 1;
 				return this;
 			}
@@ -363,5 +371,4 @@ var SecurityToken = class extends Command {
 		return this;
 	}
 };
-//#endregion
-export { SecurityToken as default, tokenTtlSeconds, ttlSeconds };
+export { SecurityMcpToken as default, tokenTtlSeconds, ttlSeconds };

package/dist/nodefony/command/security-oauth-doctor.js

@@ -1,5 +1,5 @@
 import { Command } from "nodefony";
-//#region nodefony/command/security-oauth-doctor.ts
+// nodefony/command/security-oauth-doctor.ts
 const options = {
 	helpGroup: "COMPTES ET SECRETS",
 	showBanner: false,
@@ -44,7 +44,10 @@ function mark(check) {
 */
 var SecurityOAuthDoctor = class extends Command {
 	constructor(cli) {
-		super("security:oauth:doctor", "diagnostique le branchement des fournisseurs OAuth", cli, options);
+		super("security:oauth:doctor", "diagnostique le branchement des fournisseurs OAuth", cli, {
+			...options,
+			examples: ["nodefony security:oauth:doctor", "nodefony security:oauth:doctor --provider github --json"]
+		});
 		this.addOption("-p, --provider <nom>", "un seul fournisseur de oauth2.providers");
 		this.addOption("-j, --json", "sortie JSON (scripts/CI)");
 	}
@@ -62,5 +65,4 @@ var SecurityOAuthDoctor = class extends Command {
 		return this;
 	}
 };
-//#endregion
 export { SecurityOAuthDoctor as default };

package/dist/nodefony/command/security-secrets.js

@@ -5,7 +5,7 @@ import path from "node:path";
 import { appendFileSync } from "node:fs";
 import { randomBytes } from "node:crypto";
 import { spawnSync } from "node:child_process";
-//#region nodefony/command/security-secrets.ts
+// nodefony/command/security-secrets.ts
 const options = {
 	helpGroup: "COMPTES ET SECRETS",
 	showBanner: false,
@@ -69,7 +69,14 @@ const ROLES = {
 */
 var SecuritySecrets = class extends Command {
 	constructor(cli) {
-		super("security:secrets", "engendre les clés de chiffrement du module security", cli, options);
+		super("security:secrets", "engendre les clés de chiffrement du module security", cli, {
+			...options,
+			examples: [
+				"nodefony security:secrets",
+				"nodefony security:secrets --write",
+				"nodefony security:secrets --jwt-keyset"
+			]
+		});
 		this.addOption("-j, --json", "sortie JSON (scripts/CI)");
 		this.addOption("-w, --write", "écrit les clés manquantes dans le .env du projet (jamais de remplacement)");
 		this.addOption("-e, --env", "les 4 secrets en lignes CLÉ=valeur (docker run --env-file, gestionnaire de secrets)");
@@ -144,7 +151,7 @@ var SecuritySecrets = class extends Command {
 		w(`\n${BOLD}🔐 Secrets du module security${RESET} ${DIM}— 4 secrets, 3 fichiers${RESET}\n\n`);
 		for (const [name, role] of Object.entries(ROLES)) w(`  ${(name === "NF_JWT_KEYSET" ? cfgTs.includes(name) : new RegExp(`^\\s*${name}\\s*=`, "m").test(dotenv)) ? "\x1B[32m✓" : "\x1B[33m○"}${RESET} ${BOLD}${name.padEnd(16)}${RESET}${DIM}${role.protected}${RESET}\n    ${DIM}sans → ${role.without}${RESET}\n`);
 		const tokenStillThere = /^\s*NF_MCP_TOKEN\s*=/m.test(dotenv);
-		w(`\n${DIM}  · NF_MCP_TOKEN n'est PAS un secret de cette application, et n'a rien à\n    faire dans cette liste : c'est un jeton qu'elle ÉMET, présenté par un\n    agent pour entrer. Aucun code d'ici ne le lit. Il se pose chez l'agent\n    qui le porte — nodefony security:token --write.${RESET}\n`);
+		w(`\n${DIM}  · NF_MCP_TOKEN n'est PAS un secret de cette application, et n'a rien à\n    faire dans cette liste : c'est un jeton qu'elle ÉMET, présenté par un\n    agent pour entrer. Aucun code d'ici ne le lit. Il se pose chez l'agent\n    qui le porte — nodefony security:mcp:token --write.${RESET}\n`);
 		if (tokenStillThere) w(`${YELLOW}  ⚠ une ligne NF_MCP_TOKEN traîne encore dans .env — rien ne la lit,\n    tu peux la retirer.${RESET}\n`);
 		w(`\n${YELLOW}⚠ rien ne se tape dans le terminal : chaque bloc se colle dans le fichier indiqué.${RESET}\n\n`);
 		w(`${BOLD}1. Fichier ${CYAN}.env${RESET}${BOLD} — les valeurs${RESET} ${DIM}(valeurs du poste, gitignoré ; la notice est .env.example)${RESET}\n`);
@@ -175,5 +182,4 @@ var SecuritySecrets = class extends Command {
 		return this;
 	}
 };
-//#endregion
 export { SecuritySecrets as default };

package/dist/nodefony/command/security-user-add.js

@@ -1,6 +1,6 @@
 import { AUTH_LOGIN_PATH, CONSOLE_DATA_RUN_PROFILE, Command, askPasswordMasked } from "nodefony";
 import { WeakPasswordError } from "@nodefony/user";
-//#region nodefony/command/security-user-add.ts
+// nodefony/command/security-user-add.ts
 const options = {
 	runProfile: CONSOLE_DATA_RUN_PROFILE,
 	helpGroup: "COMPTES ET SECRETS",
@@ -42,7 +42,14 @@ const ROLE_BASE = "ROLE_USER";
 */
 var SecurityUserAdd = class extends Command {
 	constructor(cli) {
-		super("security:user:add", "crée un compte (mot de passe demandé masqué)", cli, options);
+		super("security:user:add", "crée un compte (mot de passe demandé masqué)", cli, {
+			...options,
+			examples: [
+				"nodefony security:user:add alice",
+				"nodefony security:user:add admin --admin",
+				"nodefony security:user:add bob --roles ROLE_USER,ROLE_DEV"
+			]
+		});
 		this.addArgument("[identifier]", "identifiant (login) du compte");
 		this.addOption("-p, --password <password>", "mot de passe (sinon : prompt masqué en TTY)");
 		this.addOption("-r, --roles <roles>", "rôles CSV (ex: ROLE_USER,ROLE_DEV) — défaut ROLE_USER");
@@ -146,5 +153,4 @@ var SecurityUserAdd = class extends Command {
 		return this;
 	}
 };
-//#endregion
 export { SecurityUserAdd as default };

package/dist/nodefony/command/security-user-delete.js

@@ -1,5 +1,5 @@
 import { CONSOLE_DATA_RUN_PROFILE, Command } from "nodefony";
-//#region nodefony/command/security-user-delete.ts
+// nodefony/command/security-user-delete.ts
 const options = {
 	runProfile: CONSOLE_DATA_RUN_PROFILE,
 	helpGroup: "COMPTES ET SECRETS",
@@ -37,7 +37,10 @@ const ADMIN_ROLE = "ROLE_NODEFONY_ADMIN";
 */
 var SecurityUserDelete = class extends Command {
 	constructor(cli) {
-		super("security:user:delete", "supprime un compte, après confirmation", cli, options);
+		super("security:user:delete", "supprime un compte, après confirmation", cli, {
+			...options,
+			examples: ["nodefony security:user:delete alice", "nodefony security:user:delete alice --yes"]
+		});
 		this.addArgument("[identifier]", "identifiant (login) du compte à retirer");
 		this.addOption("-y, --yes", "ne pas demander confirmation (obligatoire hors terminal)");
 	}
@@ -100,5 +103,4 @@ var SecurityUserDelete = class extends Command {
 		return this;
 	}
 };
-//#endregion
 export { SecurityUserDelete as default };

package/dist/nodefony/command/security-user-list.js

@@ -1,5 +1,5 @@
 import { CONSOLE_DATA_RUN_PROFILE, Command } from "nodefony";
-//#region nodefony/command/security-user-list.ts
+// nodefony/command/security-user-list.ts
 const options = {
 	runProfile: CONSOLE_DATA_RUN_PROFILE,
 	helpGroup: "COMPTES ET SECRETS",
@@ -31,7 +31,10 @@ const DEFAULT_LIMIT = 50;
 */
 var SecurityUserList = class extends Command {
 	constructor(cli) {
-		super("security:user:list", "liste les comptes : identifiant, rôles, état", cli, options);
+		super("security:user:list", "liste les comptes : identifiant, rôles, état", cli, {
+			...options,
+			examples: ["nodefony security:user:list", "nodefony security:user:list --role ROLE_ADMIN --json"]
+		});
 		this.addOption("-q, --query <texte>", "filtre sur l'identifiant (sous-chaîne, insensible à la casse)");
 		this.addOption("-r, --role <role>", "n'affiche que les porteurs d'un rôle");
 		this.addOption("-l, --limit <n>", `nombre maximum de comptes (défaut ${DEFAULT_LIMIT})`);
@@ -74,5 +77,4 @@ var SecurityUserList = class extends Command {
 		return this;
 	}
 };
-//#endregion
 export { SecurityUserList as default };

package/dist/nodefony/command/security-user-password.js

@@ -1,5 +1,5 @@
 import { AUTH_LOGIN_PATH, CONSOLE_DATA_RUN_PROFILE, Command, askPasswordMasked } from "nodefony";
-//#region nodefony/command/security-user-password.ts
+// nodefony/command/security-user-password.ts
 const options = {
 	runProfile: CONSOLE_DATA_RUN_PROFILE,
 	helpGroup: "COMPTES ET SECRETS",
@@ -40,7 +40,10 @@ const RESET = "\x1B[0m";
 */
 var SecurityUserPassword = class extends Command {
 	constructor(cli) {
-		super("security:user:password", "change le mot de passe d'un compte", cli, options);
+		super("security:user:password", "change le mot de passe d'un compte", cli, {
+			...options,
+			examples: ["nodefony security:user:password alice"]
+		});
 		this.addArgument("[identifier]", "identifiant (login) du compte");
 		this.addOption("-p, --password <password>", "nouveau mot de passe (sinon : prompt masqué en TTY)");
 	}
@@ -103,5 +106,4 @@ var SecurityUserPassword = class extends Command {
 		return this;
 	}
 };
-//#endregion
 export { SecurityUserPassword as default };

package/dist/nodefony/config/config.js

@@ -1,8 +1,9 @@
 import { parseKeySet } from "../src/token/JwtKeystore.js";
+import { scopeGrantKeyProblem } from "../src/token/scopeGrants.js";
 import { PLATFORM_ROLE_PREFIX, isPlatformRole } from "../src/oauth/providerRoles.js";
 import { DEFAULT_LOGIN_PAGE_SKIN, LOGIN_PAGE_LAYOUTS, LOGIN_PAGE_PATH, LOGIN_PAGE_SKINS, parseDiscoveryUrl, safeRedirectPath } from "nodefony";
 import { z } from "zod";
-//#region nodefony/config/config.ts
+// nodefony/config/config.ts
 /**
 * ════════════════════════════════════════════════════════════════════════════
 *  @nodefony/security — CONFIGURATION DU MODULE (schéma Zod = source unique)
@@ -263,7 +264,7 @@ const trustedIssuerSchema = z.strictObject({
 	subjectMapping: z.enum(["prefixed", "subject"]).default("prefixed").describe("Comment le sujet (`sub`) de CET émetteur devient un identifiant dans l'espace de noms local. « prefixed » (défaut) : l'identifiant cherché est « <issuer>#<sub> » — deux émetteurs ne peuvent pas se disputer un compte, et surtout aucun sujet étranger ne peut tomber par hasard sur un identifiant local existant. « subject » : le `sub` est cherché TEL QUEL, l'ancien comportement — à ne déclarer que si l'on maîtrise l'espace de noms de cet émetteur, typiquement parce qu'il EST cette application (jetons maison) ou parce que ses sujets sont déjà des identifiants locaux. 🔴 Le défaut n'est pas un réglage de confort : un annuaire où l'utilisateur choisit son identifiant permet de présenter `sub: \"admin\"`, et « subject » rattache alors le porteur au compte local du même nom. `sub` n'est unique que dans l'espace de son émetteur (OIDC Core §2) — l'identité est la paire, jamais le sujet seul.")
 });
 const resourceServerSchema = z.strictObject({
-	issuers: z.array(trustedIssuerSchema).default([]).describe("Émetteurs dont l'application accepte les jetons. VIDE (défaut) = aucun jeton tiers n'est vérifiable, et le service `accessTokenVerifier` n'est pas posé — une porte protégée refusera alors de servir plutôt que d'accepter des porteurs qu'elle ne sait pas lire. Un seul réglage commande le rôle : pas de drapeau `enabled` qui permettrait « activé sans émetteur »."),
+	issuers: z.array(trustedIssuerSchema).default([]).describe("Émetteurs TIERS dont l'application accepte les jetons. Les jetons signés par l'application elle-même n'ont pas à y figurer : dès que `jwt.enabled`, le service `accessTokenVerifier` les reconnaît, et les juge par les règles de l'authentificateur `jwt` (révocation, compte actif). VIDE (défaut) = aucun jeton tiers n'est vérifiable ; avec `jwt.enabled: false`, le service n'est pas posé et une porte protégée refusera de servir plutôt que d'accepter des porteurs qu'elle ne sait pas lire. Une liste INVALIDE n'en pose aucun, jetons locaux compris."),
 	subjectPolicy: z.enum(["require", "ephemeral"]).default("require").describe("Comment le sujet d'un jeton tiers (`sub`) devient un utilisateur de CETTE application. « require » (défaut) : le sujet doit correspondre à un compte local (`loadUserByIdentifier`) — absent, désactivé ou verrouillé, l'accès est refusé. « ephemeral » : aucun compte local n'est exigé ni créé, l'appelant vit le temps de la requête avec les rôles de `ephemeralRoles` — c'est le mode de l'appelant PUREMENT machine (agent, service). Le défaut est « require » parce qu'un jeton d'un annuaire d'entreprise vaut pour des milliers de comptes : l'accepter d'office ferait de cet annuaire l'unique autorité d'accès à l'application, et supprimerait la seconde décision — locale — qui est la raison d'être du pare-feu."),
 	ephemeralRoles: z.array(z.string().min(1)).default([]).describe("Rôles accordés à un appelant accepté en mode « ephemeral ». VIDE par défaut, et ce n'est pas une omission : sans rôle, l'appelant ne passe aucun `@IsGranted` et n'est autorisé que par ses SCOPES (`@RequireScope`), qui viennent du jeton et sont bornés par le serveur d'autorisation. Y écrire un rôle revient à accorder un pouvoir local à quiconque détient un jeton valide pour cette ressource — à faire sciemment, jamais par confort."),
 	timeoutMs: z.number().int().min(100).default(5e3).describe("Délai maximal d'une requête vers l'émetteur (découverte + clés)."),
@@ -363,7 +364,7 @@ const oauthProviderSchema = z.strictObject({
 	defaultRoles: z.array(z.string()).optional().describe("Rôles du Shadow User à la création — surcharge le global pour CE fournisseur."),
 	roleMapping: z.record(z.string().min(1), z.string().min(1)).optional().describe("Rôles du FOURNISSEUR traduits en rôles de l'application, recalculés à chaque connexion ET à chaque jeton présenté à l'API : `{ \"app-admin\": \"ROLE_ADMIN\" }`. Un rôle du fournisseur absent de la table est ignoré, jamais recopié. Les rôles donnés à la main sont conservés. OMIS = les rôles restent entièrement locaux (posés à la création, puis la base fait foi). Un rôle `ROLE_NODEFONY_*` refuse le démarrage, sauf `allowPlatformRoles`."),
 	audiences: z.array(z.string().min(1)).optional().describe("Ressources pour lesquelles CE fournisseur émet des jetons à l'application — la mention « valable pour » (`aud`) qu'il doit imprimer. Chaque entrée est la `resource` d'une zone `external-jwt`. Lue par `security:keycloak:realm`, qui en écrit les mappers d'audience ; sans effet sur la vérification, que la `resource` de la zone porte seule. OMIS = la `resource` de TOUTES les zones `external-jwt`. À écrire dès qu'une zone existe pour REFUSER les jetons de ce fournisseur : la déduire ferait imprimer son adresse."),
-	allowPlatformRoles: z.boolean().default(false).describe("Autorise `roleMapping` à accorder des rôles de PLATEFORME (`ROLE_NODEFONY_*` : console d'administration, génération de code, secrets). OMIS = refusé au démarrage. L'ouvrir fait de l'administrateur de l'annuaire un administrateur de l'instance, et d'un annuaire compromis une prise de contrôle complète — un avertissement le rappelle à chaque démarrage."),
+	allowPlatformRoles: z.boolean().default(false).describe("Autorise `roleMapping` à accorder des rôles de PLATEFORME (`ROLE_NODEFONY_*` : console d'administration, génération de code, secrets). OMIS = refusé au démarrage. L'ouvrir fait de l'administrateur de l'annuaire un administrateur de l'instance, et d'un annuaire compromis une prise de contrôle complète — rappelé à chaque démarrage, en avertissement en production, en information ailleurs."),
 	rolesSource: z.array(z.enum([
 		"client",
 		"realm",
@@ -396,6 +397,21 @@ const oauth2Schema = z.strictObject({
 	providers: z.record(z.string(), oauthProviderSchema).default({}).describe("Fournisseurs activés par nom (doit correspondre au registre : builtins google/keycloak/oidc/github ; tout autre serveur OpenID Connect en enregistrant une fabrique, décrit par son seul émetteur).")
 }).describe("Social login OAuth 2.0 — Authorization Code + PKCE, session BFF.");
 /**
+* Qui peut OBTENIR un scope d'application — appliqué par CHAQUE émetteur de
+* l'application (jeton d'accès, clé API), jamais par une zone : un jeton ne
+* sait pas quelle zone le lira, et `security:mcp:token` signe sans requête.
+*/
+const grantableScopesSchema = z.record(z.string(), z.array(z.string().min(1)).min(1, "au moins un rôle — pour n'accorder ce scope à personne, ne pas l'exposer")).superRefine((grants, ctx) => {
+	for (const key of Object.keys(grants)) {
+		const problem = scopeGrantKeyProblem(key);
+		if (problem !== null) ctx.addIssue({
+			code: "custom",
+			path: [key],
+			message: `« ${key} » ${problem}`
+		});
+	}
+}).default({}).describe("Qui peut OBTENIR un scope d'application. Clé : un scope exact (`vitrine:write`) ou une famille (`shop:*`) ; valeur : les rôles dont UN suffit, hiérarchie de rôles comprise. Une clé exacte l'emporte sur une famille, la famille la plus longue sur une plus courte. Un scope qu'aucune clé ne couvre reste accordé à tout compte connecté. Appliqué par chaque émetteur de CETTE application : un jeton d'accès est émis sans les scopes refusés (RFC 6749 §3.3, nommés au journal), une clé API demandée avec l'un d'eux est refusée (403). Ne borne PAS les jetons d'un émetteur tiers (Keycloak…), qui signe selon sa propre politique. `admin:read`, `admin:write` et `admin:*` sont refusés au démarrage : réservés au framework. Un module peut compléter cette section par `module-security` ; un préfixe = un propriétaire, car la fusion de configuration fusionne les listes case par case (`[\"A\",\"B\"]` surchargé par `[\"C\"]` donne `[\"C\",\"B\"]`).");
+/**
 * Règle d'autorisation d'un **namespace de canaux WebSocket** (subscribe/inbound)
 * par préfixe. Contraintes cumulatives ; un champ absent = pas de contrainte sur
 * cet axe. Étend OU surcharge les défauts système (placée AVANT eux à l'évaluation).
@@ -409,6 +425,7 @@ const realtimeChannelRuleSchema = z.strictObject({
 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'])."),
+	grantableScopes: grantableScopesSchema,
 	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_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({})),
@@ -441,5 +458,4 @@ const securityConfigSchema = z.strictObject({
 * construction ; passés au `super(..., config)` du Module class.
 */
 const config = securityConfigSchema.parse({});
-//#endregion
 export { config as default, securityConfigSchema };

package/dist/nodefony/config/defineModuleConfig.js

@@ -1,7 +1,7 @@
 import { securityConfigSchema } from "./config.js";
 import { BootConfigurationError, parseModuleConfig } from "nodefony";
 import { z } from "zod";
-//#region nodefony/config/defineModuleConfig.ts
+// nodefony/config/defineModuleConfig.ts
 /**
 * Valide + normalise + gèle la configuration de sécurité.
 *
@@ -31,5 +31,4 @@ function detectConflicts(areas) {
 		seen.set(area.pattern, name);
 	}
 }
-//#endregion
 export { defineSecurityConfig, securityConfigJsonSchema };

package/dist/nodefony/contracts/IAccessVoter.js

@@ -1,4 +1,4 @@
-//#region nodefony/contracts/IAccessVoter.ts
+// nodefony/contracts/IAccessVoter.ts
 /**
 * Vote d'un {@link IAccessVoter}. Stratégie firewall = affirmative + DENY veto :
 * un seul DENY bloque ; sinon un GRANT suffit ; tous ABSTAIN → DENY (Zero Trust).
@@ -9,5 +9,4 @@ let VoterVote = /* @__PURE__ */ function(VoterVote) {
 	VoterVote["ABSTAIN"] = "ABSTAIN";
 	return VoterVote;
 }({});
-//#endregion
 export { VoterVote };

package/dist/nodefony/errors/AccessDeniedError.js

@@ -1,5 +1,5 @@
 import { nodefonyError } from "nodefony";
-//#region nodefony/errors/AccessDeniedError.ts
+// nodefony/errors/AccessDeniedError.ts
 /**
 * Accès refusé — `code = 403`. Levée par l'autorisation (un `@IsGranted` non
 * satisfait, un voter DENY) : l'utilisateur EST authentifié mais n'a pas le droit.
@@ -10,5 +10,4 @@ var AccessDeniedError = class extends nodefonyError {
 		super(message, 403);
 	}
 };
-//#endregion
 export { AccessDeniedError, AccessDeniedError as default };

package/dist/nodefony/errors/ApiKeyError.js

@@ -1,11 +1,13 @@
 import { nodefonyError } from "nodefony";
-//#region nodefony/errors/ApiKeyError.ts
+// nodefony/errors/ApiKeyError.ts
 /**
 * Erreur de **gestion** d'une clé API (création/révocation) — porte un `code`
 * HTTP que l'adaptateur framework mappe par duck-typing (il n'importe jamais les
 * classes de `@nodefony/security`).
 *
 *  - `400` — entrée invalide (nom vide, scope hors catalogue) ;
+*  - `403` — scope demandé que le porteur ne peut pas obtenir (`grantableScopes`,
+*    ou `admin:*` sans le rôle d'administration) ;
 *  - `409` — plafond `apiKeys.maxPerSubject` atteint ;
 *  - `503` — store de jetons indisponible (clés activées mais non provisionnées).
 *
@@ -17,5 +19,4 @@ var ApiKeyError = class extends nodefonyError {
 		super(message, code);
 	}
 };
-//#endregion
 export { ApiKeyError, ApiKeyError as default };

package/dist/nodefony/errors/AuthenticationError.js

@@ -1,5 +1,5 @@
 import { nodefonyError } from "nodefony";
-//#region nodefony/errors/AuthenticationError.ts
+// nodefony/errors/AuthenticationError.ts
 /**
 * Échec d'authentification — `code = 401`. Levée par un {@link IAuthenticator}
 * quand le credential est absent/invalide, ou par le firewall en Zero Trust
@@ -10,5 +10,4 @@ var AuthenticationError = class extends nodefonyError {
 		super(message, 401);
 	}
 };
-//#endregion
 export { AuthenticationError, AuthenticationError as default };

package/dist/nodefony/errors/CsrfError.js

@@ -1,5 +1,5 @@
 import { nodefonyError } from "nodefony";
-//#region nodefony/errors/CsrfError.ts
+// nodefony/errors/CsrfError.ts
 /**
 * Mutation cross-site bloquée — `code = 403` (RFC 9110 §15.5.4 : le serveur a
 * compris la requête mais refuse de l'honorer).
@@ -19,5 +19,4 @@ var CsrfError = class extends nodefonyError {
 		super(message, 403);
 	}
 };
-//#endregion
 export { CsrfError, CsrfError as default };

package/dist/nodefony/errors/InsecureTransportError.js

@@ -1,5 +1,5 @@
 import { INSECURE_TRANSPORT_MESSAGE, nodefonyError } from "nodefony";
-//#region nodefony/errors/InsecureTransportError.ts
+// nodefony/errors/InsecureTransportError.ts
 /**
 * Secret refusé parce qu'il arrive en clair — `code = 403` (RFC 9110 §15.5.4 :
 * le serveur a compris la requête mais refuse de l'honorer).
@@ -20,5 +20,4 @@ var InsecureTransportError = class extends nodefonyError {
 		super(INSECURE_TRANSPORT_MESSAGE, 403);
 	}
 };
-//#endregion
 export { InsecureTransportError, InsecureTransportError as default };

package/dist/nodefony/errors/InvalidTargetError.js

@@ -1,5 +1,5 @@
 import { nodefonyError } from "nodefony";
-//#region nodefony/errors/InvalidTargetError.ts
+// nodefony/errors/InvalidTargetError.ts
 /**
 * La ressource demandée à l'émission ne peut pas être servie — `code = 400`,
 * code d'erreur OAuth `invalid_target` (RFC 8707 §2).
@@ -35,5 +35,4 @@ var InvalidTargetError = class extends nodefonyError {
 		this.requested = requested;
 	}
 };
-//#endregion
 export { InvalidTargetError, InvalidTargetError as default };

package/dist/nodefony/errors/SsrfError.js

@@ -1,5 +1,5 @@
 import { nodefonyError } from "nodefony";
-//#region nodefony/errors/SsrfError.ts
+// nodefony/errors/SsrfError.ts
 /**
 * URL rejetée par la protection SSRF — `code = 422`. Levée quand une URL sortante
 * (endpoint webhook, fetch applicatif…) est syntaxiquement valide mais cible une
@@ -13,5 +13,4 @@ var SsrfError = class extends nodefonyError {
 		super(message, 422);
 	}
 };
-//#endregion
 export { SsrfError, SsrfError as default };

package/dist/nodefony/errors/ThrottledError.js

@@ -1,5 +1,5 @@
 import { nodefonyError } from "nodefony";
-//#region nodefony/errors/ThrottledError.ts
+// nodefony/errors/ThrottledError.ts
 /**
 * Tentatives de login trop rapprochées — `code = 429` (RFC 6585 §4).
 *
@@ -17,5 +17,4 @@ var ThrottledError = class extends nodefonyError {
 		this.retryAfterS = retryAfterS;
 	}
 };
-//#endregion
 export { ThrottledError, ThrottledError as default };

package/dist/nodefony/errors/UnverifiableTokenError.js

@@ -1,5 +1,5 @@
 import { nodefonyError } from "nodefony";
-//#region nodefony/errors/UnverifiableTokenError.ts
+// nodefony/errors/UnverifiableTokenError.ts
 /**
 * Le jeton n'a pas pu être VÉRIFIÉ — `code = 503`, et surtout **pas 401**.
 *
@@ -38,5 +38,4 @@ var UnverifiableTokenError = class extends nodefonyError {
 		this.detail = detail;
 	}
 };
-//#endregion
 export { UnverifiableTokenError, UnverifiableTokenError as default };

package/dist/nodefony/errors/WebAuthnError.js

@@ -1,5 +1,5 @@
 import { nodefonyError } from "nodefony";
-//#region nodefony/errors/WebAuthnError.ts
+// nodefony/errors/WebAuthnError.ts
 /**
 * Erreur de **gestion** d'un credential WebAuthn (enrôlement) — porte un `code`
 * HTTP que l'adaptateur framework mappe par duck-typing (il n'importe jamais les
@@ -17,5 +17,4 @@ var WebAuthnError = class extends nodefonyError {
 		super(message, code);
 	}
 };
-//#endregion
 export { WebAuthnError, WebAuthnError as default };

package/dist/nodefony/keycloak/keycloakAdmin.js

@@ -1,5 +1,5 @@
 import { isNodefonyKeycloakTheme, keycloakLoginTheme, realmNameFromIssuer } from "./keycloakRealmInput.js";
-//#region nodefony/keycloak/keycloakAdmin.ts
+// nodefony/keycloak/keycloakAdmin.ts
 /** Refus ou échec d'un appel ; le message nomme la cause et le geste suivant. */
 var KeycloakAdminError = class extends Error {
 	status;
@@ -251,5 +251,4 @@ function keycloakLoginThemeCheck(skin) {
 		};
 	};
 }
-//#endregion
 export { KeycloakAdminClient, KeycloakAdminError, keycloakAdminTarget, keycloakLoginThemeCheck, readKeycloakLoginTheme };

package/dist/nodefony/keycloak/keycloakRealm.js

@@ -1,4 +1,4 @@
-//#region nodefony/keycloak/keycloakRealm.ts
+// nodefony/keycloak/keycloakRealm.ts
 /** Le type du mapper qui ajoute une audience au jeton d'accès. */
 const AUDIENCE_MAPPER = "oidc-audience-mapper";
 /**
@@ -256,5 +256,4 @@ function renderValue(value, indent, lead) {
 function renderKeycloakRealm(realm) {
 	return `${renderValue(realm, "", 0)}\n`;
 }
-//#endregion
 export { buildKeycloakRealm, keycloakDefaultRole, mergeKeycloakRealm, renderKeycloakRealm };

package/dist/nodefony/keycloak/keycloakRealmInput.js

@@ -1,6 +1,6 @@
 import { KEYCLOAK_THEME_NAME } from "./scaffold.js";
 import { DEFAULT_LOGIN_PAGE_SKIN } from "nodefony";
-//#region nodefony/keycloak/keycloakRealmInput.ts
+// nodefony/keycloak/keycloakRealmInput.ts
 /** Erreur de dérivation : la config ne permet pas d'écrire un realm. */
 var KeycloakRealmError = class extends Error {
 	name = "KeycloakRealmError";
@@ -120,5 +120,4 @@ function deriveKeycloakRealmInput(ctx) {
 		warnings
 	};
 }
-//#endregion
 export { KeycloakRealmError, deriveKeycloakRealmInput, isNodefonyKeycloakTheme, keycloakLoginTheme, realmNameFromIssuer };

package/dist/nodefony/keycloak/scaffold.js

@@ -3,7 +3,7 @@ import { fileURLToPath } from "node:url";
 import path from "node:path";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { randomUUID } from "node:crypto";
-//#region nodefony/keycloak/scaffold.ts
+// nodefony/keycloak/scaffold.ts
 /**
 * Le décor Keycloak de développement que `@nodefony/security` livre à une
 * application : realm d'import et thème aux couleurs du framework.
@@ -54,7 +54,8 @@ function packageRoot() {
 	for (;;) {
 		const manifest = path.join(dir, "package.json");
 		if (existsSync(manifest)) {
-			if (JSON.parse(readFileSync(manifest, "utf8")).name === PACKAGE_NAME) return dir;
+			const parsed = JSON.parse(readFileSync(manifest, "utf8"));
+			if (typeof parsed === "object" && parsed !== null && "name" in parsed && parsed.name === PACKAGE_NAME) return dir;
 		}
 		const parent = path.dirname(dir);
 		if (parent === dir) throw new Error(`racine du paquet ${PACKAGE_NAME} introuvable`);
@@ -227,5 +228,4 @@ function contributeKeycloak(context) {
 	context.write(APP_KEYCLOAK_REALM_FILE, renderKeycloakRealm(realm));
 	copyKeycloakTheme(context);
 }
-//#endregion
 export { APP_KEYCLOAK_REALM_FILE, APP_KEYCLOAK_THEMES_DIR, APP_KEYCLOAK_THEME_DIR, APP_PARTNER_DEV_RESOURCE, KEYCLOAK_THEME_NAME, appDevRealmInput, contributeKeycloak, copyKeycloakTheme, deliveredThemeTypes, devClientSecret, devMachineSecret, keycloakThemeSource, keycloakThemesSource };