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

package/dist/nodefony/src/oauth/providers/oidc.js

@@ -1,7 +1,8 @@
 import { RemoteJwtVerifier } from "../../token/RemoteJwtVerifier.js";
 import { OAuth2Client } from "../oauth2Client.js";
 import { discoverAuthorizationServer } from "../metadata.js";
-//#region nodefony/src/oauth/providers/oidc.ts
+import { isPlainObject } from "nodefony";
+// nodefony/src/oauth/providers/oidc.ts
 const DEFAULT_OIDC_SCOPES = [
 	"openid",
 	"profile",
@@ -35,7 +36,7 @@ function readLogoutTokenClaims(issuer, payload) {
 	const sid = typeof payload.sid === "string" ? payload.sid : null;
 	if ((sub === null || sub === "") && (sid === null || sid === "")) return null;
 	const events = payload.events;
-	if (typeof events !== "object" || events === null || Array.isArray(events)) return null;
+	if (!isPlainObject(events)) return null;
 	const event = events[BACKCHANNEL_LOGOUT_EVENT];
 	if (typeof event !== "object" || event === null || Array.isArray(event)) return null;
 	if ("nonce" in payload) return null;
@@ -70,14 +71,17 @@ async function decodeIdTokenClaims(idToken) {
 * écarts : un jeton d'un autre émetteur (point 2), délivré à une autre
 * application (point 3), ou périmé (point 9), n'a rien à faire ici.
 *
+* @returns le `sub` du jeton, éprouvé non vide.
 * @throws Error - un claim obligatoire est absent, discordant ou périmé.
 */
 function assertIdTokenClaims(claims, opts) {
-	if (typeof claims.sub !== "string" || claims.sub.length === 0) throw new Error(`${opts.name}: ID token sans claim 'sub'.`);
+	const sub = claims.sub;
+	if (typeof sub !== "string" || sub.length === 0) throw new Error(`${opts.name}: ID token sans claim 'sub'.`);
 	if (claims.iss !== opts.issuer) throw new Error(`${opts.name}: ID token émis par « ${String(claims.iss)} », attendu « ${opts.issuer} ».`);
 	const aud = claims.aud;
 	if (!(aud === opts.clientId || Array.isArray(aud) && aud.includes(opts.clientId))) throw new Error(`${opts.name}: ID token délivré à une autre application.`);
 	if (typeof claims.exp !== "number" || claims.exp * 1e3 <= Date.now()) throw new Error(`${opts.name}: ID token périmé ou sans 'exp'.`);
+	return sub;
 }
 /**
 * Fabrique un {@link IOAuthProvider} **générique OIDC** — couvre TOUT fournisseur
@@ -113,8 +117,8 @@ function createOidcProvider(opts) {
 		},
 		async fetchProfile(tokens) {
 			const claims = await opts.decodeIdToken(tokens.idToken());
-			assertIdTokenClaims(claims, opts);
-			const sub = claims.sub;
+			if (!isPlainObject(claims)) throw new Error(`${opts.name}: ID token sans charge utile objet.`);
+			const sub = assertIdTokenClaims(claims, opts);
 			return {
 				provider: opts.name,
 				providerId: sub,
@@ -197,5 +201,4 @@ async function createDiscoveredOidcProvider(name, ctx, options = {}) {
 		})
 	});
 }
-//#endregion
 export { createDiscoveredOidcProvider, createOidcProvider, readLogoutTokenClaims };

package/dist/nodefony/src/openToSignup.js

@@ -1,4 +1,4 @@
-//#region nodefony/src/openToSignup.ts
+// nodefony/src/openToSignup.ts
 /**
 * Les zones protégées qui n'exigent aucun rôle alors que la connexion OAuth
 * crée les comptes à la volée — c'est-à-dire ouvertes à tout compte que le
@@ -43,5 +43,4 @@ function findZonesOpenToSignup(config) {
 	}
 	return found;
 }
-//#endregion
 export { findZonesOpenToSignup };

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

@@ -1,4 +1,4 @@
-//#region nodefony/src/realtime/UserRealtimeToken.ts
+// nodefony/src/realtime/UserRealtimeToken.ts
 /** Aucun scope — figé et partagé (0 allocation pour le cas humain, le plus courant). */
 const EMPTY_SCOPES = Object.freeze([]);
 /**
@@ -41,12 +41,20 @@ var UserRealtimeToken = class {
 	*/
 	#scopes;
 	/**
+	* Confirmation du COMPTE (annuaire relu), fournie par le
+	* {@link FirewallRealtimeAuthenticator} pour les modes dont l'application
+	* émet elle-même l'artefact. `null` = rien à confirmer.
+	*/
+	#confirmAccount;
+	/**
 	* @param user - identité authentifiée résolue par le firewall.
 	* @param revalidate - preuve de vie de l'identité, adaptée à son mode.
 	* @param type - mode d'authentification réel (défaut `"session"`).
 	* @param scopes - scopes délégués du jeton d'origine (défaut aucun).
+	* @param confirmAccount - relecture du compte, payée sur `api.request` seul.
 	*/
-	constructor(user, revalidate = null, type = "session", scopes = EMPTY_SCOPES) {
+	constructor(user, revalidate = null, type = "session", scopes = EMPTY_SCOPES, confirmAccount = null) {
+		this.#confirmAccount = confirmAccount;
 		this.#user = user;
 		this.#revalidate = revalidate;
 		this.type = type;
@@ -67,6 +75,13 @@ var UserRealtimeToken = class {
 	isValid(nowMs) {
 		return this.#revalidate ? this.#revalidate(nowMs) : Promise.resolve(true);
 	}
+	/**
+	* Le compte qui a ouvert la socket existe-t-il toujours, actif, et sous le
+	* même `id` immuable ? `true` si aucune confirmation n'est câblée.
+	*/
+	confirmAccount() {
+		return this.#confirmAccount ? this.#confirmAccount() : Promise.resolve(true);
+	}
 	getUserIdentifier() {
 		return this.#user.identifier;
 	}
@@ -90,5 +105,4 @@ var UserRealtimeToken = class {
 		return key === "user" ? this.#user : void 0;
 	}
 };
-//#endregion
 export { UserRealtimeToken, UserRealtimeToken as default };

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

@@ -1,5 +1,5 @@
 import { NODEFONY_CHANNEL_NAMESPACE, PLATFORM_CHANNELS, PLATFORM_INBOUND, startsWithCI } from "nodefony";
-//#region nodefony/src/realtime/frameAuthorizer.ts
+// nodefony/src/realtime/frameAuthorizer.ts
 /**
 * Politique système par défaut des canaux d'**introspection serveur** : réservés
 * à l'exploitant de l'INSTANCE, pas à l'administrateur d'une application.
@@ -254,7 +254,7 @@ function authorizeChannel(channel, token, firewall, resolver, systemRules, onDen
 * (api.request) ou la politique du canal (subscribe/inbound).
 *
 * Trois surfaces gardées :
-*  - `api.request {path}` (pont API souverain) : re-match de zone HTTP → zone
+*  - `api.request {path}` (pont socket) : re-match de zone HTTP → zone
 *    protégée + anonyme = refus (autorisation de ZONE, identique à `GET {path}` ;
 *    la méthode/action est gardée en aval par le router + `@IsGranted`).
 *  - `subscribe {channel}` : politique de canal (système plancher + déclaration
@@ -289,5 +289,4 @@ function buildFrameAuthorizer(firewall, options) {
 		return true;
 	};
 }
-//#endregion
 export { DEFAULT_SYSTEM_PREFIXES, DEFAULT_SYSTEM_RULES, RESERVED_FLOOR_PREFIXES, SECURITY_CHANNEL_POLICY, SYSTEM_CHANNEL_POLICY, UPLINK_CHANNEL_POLICY, buildFrameAuthorizer, buildFrameAuthorizer as default, buildSystemRules };

package/dist/nodefony/src/rolesWithin.js

@@ -0,0 +1,57 @@
+// nodefony/src/rolesWithin.ts
+/**
+* Lit un compte de l'annuaire, sans faire confiance au fournisseur : une
+* lecture qui lève et une lecture qui rend `null` disent toutes deux
+* « introuvable ».
+*/
+async function loadAccount(users, identifier) {
+	try {
+		return await users.loadUserByIdentifier(identifier) ?? null;
+	} catch {
+		return null;
+	}
+}
+/** Rôles chaîne d'un compte lu, sans lui faire confiance. */
+function rolesOf(user) {
+	return Array.isArray(user.roles) ? user.roles.filter((r) => typeof r === "string") : [];
+}
+/**
+* La règle « jouer un autre compte » : les rôles de `target`, hiérarchie
+* comprise, sont-ils TOUS atteints par ceux de `owner` ? Jouer un compte ne
+* monte jamais en droits.
+*
+* Fermée en cas de doute : un annuaire absent, un compte introuvable — y
+* compris un sujet externe éphémère, qui n'a pas de compte local — rendent un
+* refus, jamais un accord. L'annuaire est résolu à l'appel : le service `users`
+* peut être posé après le pare-feu.
+*
+* @param resolveUsers - rend l'annuaire des comptes (`users`), ou `null`
+* @param hierarchy - la hiérarchie de rôles du pare-feu
+* @returns la règle, à poser au conteneur sous `ROLES_WITHIN`
+*/
+function rolesWithin(resolveUsers, hierarchy) {
+	return async (owner, target) => {
+		const users = resolveUsers();
+		if (users === null) return {
+			ok: false,
+			reason: "annuaire des comptes indisponible (@nodefony/user)"
+		};
+		const ownerUser = await loadAccount(users, owner);
+		if (ownerUser === null) return {
+			ok: false,
+			reason: `\`${owner}\` n'a pas de compte dans l'annuaire de l'application (un sujet externe éphémère ne peut jouer aucun compte)`
+		};
+		const targetUser = await loadAccount(users, target);
+		if (targetUser === null) return {
+			ok: false,
+			reason: `compte \`${target}\` introuvable`
+		};
+		const granted = hierarchy.reachableRoles(rolesOf(ownerUser));
+		const extra = [...hierarchy.reachableRoles(rolesOf(targetUser))].filter((role) => !granted.has(role));
+		return extra.length === 0 ? { ok: true } : {
+			ok: false,
+			reason: `\`${target}\` a des rôles que \`${owner}\` n'a pas : ${extra.sort().join(", ")}`
+		};
+	};
+}
+export { rolesWithin };

package/dist/nodefony/src/sessionAuthentication.js

@@ -1,4 +1,4 @@
-//#region nodefony/src/sessionAuthentication.ts
+// nodefony/src/sessionAuthentication.ts
 /**
 * Facteurs d'authentification de Nodefony → méthodes RFC 8176, posées dans la
 * session à son ouverture. Les clés et leur lecteur sont au cœur
@@ -22,5 +22,4 @@ const NO_LOCAL_FACTOR = Object.freeze([]);
 function amrForFactor(factor) {
 	return Object.hasOwn(FACTOR_AMR, factor) ? FACTOR_AMR[factor] ?? NO_LOCAL_FACTOR : NO_LOCAL_FACTOR;
 }
-//#endregion
 export { amrForFactor };

package/dist/nodefony/src/sessionIdentity.js

@@ -1,6 +1,7 @@
 import { AuthenticationError } from "../errors/AuthenticationError.js";
+import { isBoundToAccount } from "./accountBinding.js";
 import { UserNotFoundError } from "@nodefony/user";
-//#region nodefony/src/sessionIdentity.ts
+// nodefony/src/sessionIdentity.ts
 const INVALID_SESSION = "Invalid session";
 /**
 * Résout l'identité portée par une session (l'identifiant stocké dans le blob)
@@ -31,5 +32,30 @@ async function resolveSessionIdentity(provider, identifier) {
 	if (user.isLocked() || !user.isActive()) throw new AuthenticationError(INVALID_SESSION);
 	return user;
 }
-//#endregion
-export { resolveSessionIdentity };
+/**
+* Résout l'identité d'une session DÉJÀ ouverte, en exigeant qu'elle ait été
+* ouverte pour CE compte — {@link resolveSessionIdentity} plus la liaison à
+* l'identifiant immuable (`isBoundToAccount`).
+*
+* La session range son principal sous l'`identifier`, qu'un compte recréé
+* (suppression hors framework, restauration, import) peut reprendre : sans la
+* liaison, la session de l'ancien titulaire ouvrirait le compte du nouveau.
+* Une session sans liaison est refusée au même titre.
+*
+* @param provider - source d'identité (`UserService` via le container).
+* @param identifier - identifiant fonctionnel stocké en session.
+* @param boundAccountId - identifiant immuable inscrit à l'ouverture
+*   (`metaBag`, clé `ACCOUNT_ID_KEY`).
+* @param boundCredentialsVersion - version des identifiants inscrite à
+*   l'ouverture (`metaBag`, clé `CREDENTIALS_VERSION_KEY`).
+* @returns l'utilisateur actif, titulaire de la session.
+* @throws AuthenticationError (401, message uniforme) — identifiant inconnu,
+*   compte verrouillé ou désactivé, session ouverte pour un autre compte ou
+*   avant le dernier changement de mot de passe.
+*/
+async function resolveBoundSessionIdentity(provider, identifier, boundAccountId, boundCredentialsVersion) {
+	const user = await resolveSessionIdentity(provider, identifier);
+	if (!isBoundToAccount(user, boundAccountId, boundCredentialsVersion)) throw new AuthenticationError(INVALID_SESSION);
+	return user;
+}
+export { resolveBoundSessionIdentity, resolveSessionIdentity };

package/dist/nodefony/src/throttle/LoginThrottler.js

@@ -1,4 +1,4 @@
-//#region nodefony/src/throttle/LoginThrottler.ts
+// nodefony/src/throttle/LoginThrottler.ts
 const DEFAULT_FREE_ATTEMPTS = 3;
 const DEFAULT_BASE_DELAY_S = 1;
 const DEFAULT_CAP_DELAY_S = 900;
@@ -93,5 +93,4 @@ var LoginThrottler = class {
 		}
 	}
 };
-//#endregion
 export { LoginThrottler, LoginThrottler as default };

package/dist/nodefony/src/token/AnonymousToken.js

@@ -1,5 +1,5 @@
 import { anonymousUser } from "@nodefony/user";
-//#region nodefony/src/token/AnonymousToken.ts
+// nodefony/src/token/AnonymousToken.ts
 /**
 * Token du visiteur non authentifié — Zero Trust : un visiteur EST un utilisateur
 * anonyme (jamais `null`).
@@ -36,5 +36,4 @@ var AnonymousToken = class {
 		(this.#attributes ??= /* @__PURE__ */ new Map()).set(key, value);
 	}
 };
-//#endregion
 export { AnonymousToken, AnonymousToken as default };

package/dist/nodefony/src/token/JwtKeystore.js

@@ -1,6 +1,7 @@
 import { createSecretExclusive, messageNonRestreint, modeNonRestreintAsync, readIfPresent } from "./secretFile.js";
+import { isPlainObject } from "nodefony";
 import { join } from "node:path";
-//#region nodefony/src/token/JwtKeystore.ts
+// nodefony/src/token/JwtKeystore.ts
 /**
 * Dossiers que le `Dockerfile` généré EFFACE à l'étage de construction.
 *
@@ -54,9 +55,18 @@ function parseKeySet(json) {
 	} catch {
 		throw new Error("JwtKeystore: keyset JSON invalide");
 	}
-	const keyset = parsed;
-	if (!keyset || !Array.isArray(keyset.keys) || keyset.keys.length === 0 || keyset.keys.some((k) => typeof k.kid !== "string")) throw new Error("JwtKeystore: keyset malformé (champ `keys` non vide avec `kid` requis)");
-	return keyset;
+	if (!isStoredKeySet(parsed)) throw new Error("JwtKeystore: keyset malformé (champ `keys` non vide avec `kid` requis)");
+	return parsed;
+}
+/**
+* Forme minimale d'un jeu de clés relu : un objet dont `keys` est un tableau non
+* vide d'objets portant chacun un `kid` textuel. Le reste de chaque JWK est
+* éprouvé par `jose` à l'import de la clé.
+*/
+function isStoredKeySet(value) {
+	if (!isPlainObject(value)) return false;
+	const keys = value.keys;
+	return Array.isArray(keys) && keys.length > 0 && keys.every((k) => isPlainObject(k) && typeof k.kid === "string");
 }
 /** Génère une nouvelle paire Ed25519 (extractable pour persistance JWK). */
 async function buildKeySet(jose) {
@@ -225,5 +235,4 @@ var JwtKeystore = class {
 		this.#log(`JWT keystore: ${messageNonRestreint(file, mode)} La clé PRIVÉE y réside : provisionnez-la plutôt hors-bande via jwt.keystore.keySetJson (recommandé en production).`, "WARNING");
 	}
 };
-//#endregion
 export { JwtKeystore, JwtKeystore as default, generateKeySet, keystoreLeaksIntoImage, parseKeySet };

package/dist/nodefony/src/token/MemoryTokenStore.js

@@ -1,7 +1,7 @@
 import { TOKEN_DEFAULT_ORDER, TOKEN_SORTABLE_FIELDS } from "./tokenSort.js";
 import { matchesTokenStatus } from "./tokenStatus.js";
 import { assertPageQuery, compareByOrder, pickOrder } from "nodefony";
-//#region nodefony/src/token/MemoryTokenStore.ts
+// nodefony/src/token/MemoryTokenStore.ts
 /**
 * Filtre un record contre une requête de listing — prédicat de RÉFÉRENCE du
 * contrat, réutilisé par les implémentations qui évaluent en mémoire.
@@ -245,5 +245,4 @@ var MemoryTokenStore = class {
 		for (const [jti, expiresAt] of this.#deniedJti) if (expiresAt <= now) this.#deniedJti.delete(jti);
 	}
 };
-//#endregion
 export { MemoryTokenStore, matchesTokenQuery };

package/dist/nodefony/src/token/RemoteJwtVerifier.js

@@ -1,5 +1,6 @@
+import { describeTransportFailure, untrustedAuthorityHint } from "../net/transportFailure.js";
 import { canonicalIssuer, extractScopes, metadataCandidateUrls, parseDiscoveryUrl, validateIssuerMetadata } from "nodefony";
-//#region nodefony/src/token/RemoteJwtVerifier.ts
+// nodefony/src/token/RemoteJwtVerifier.ts
 /**
 * Codes d'erreur `jose` qui désignent un **jeton fautif** — la liste est
 * BLANCHE, et c'est le point important.
@@ -163,7 +164,10 @@ var RemoteJwtVerifier = class {
 			};
 		} catch (error) {
 			const code = error.code;
-			if (!code || !TOKEN_FAULT_CODES.has(code)) throw new Error(`vérification impossible : l'émetteur « ${trusted.issuer} » n'a pas fourni de jeu de clés utilisable (${code ?? error.message}).`, { cause: error });
+			if (!code || !TOKEN_FAULT_CODES.has(code)) {
+				const hint = untrustedAuthorityHint(error);
+				throw new Error(`vérification impossible : l'émetteur « ${trusted.issuer} » n'a pas fourni de jeu de clés utilisable (${code ?? describeTransportFailure(error)}).` + (hint === null ? "" : ` ${hint}.`), { cause: error });
+			}
 			this.#audit(`jeton refusé (${trusted.issuer}) : ${code}`);
 			return null;
 		}
@@ -254,5 +258,4 @@ function assertAsymmetric(issuer, algorithms) {
 	if (algorithms.length === 0) throw new Error(`émetteur « ${issuer} » : aucun algorithme accepté — la liste est la garde principale (RFC 8725 §3.1), elle ne peut pas être vide.`);
 	for (const alg of algorithms) if (alg.startsWith("HS") || alg.toLowerCase() === "none") throw new Error(`émetteur « ${issuer} » : algorithme « ${alg} » refusé. Les clés proviennent d'un jeu PUBLIC : un algorithme à secret partagé y transformerait la clé publique en secret de signature.`);
 }
-//#endregion
 export { RemoteJwtVerifier, RemoteJwtVerifier as default };

package/dist/nodefony/src/token/UserToken.js

@@ -1,5 +1,5 @@
 import { anonymousUser } from "@nodefony/user";
-//#region nodefony/src/token/UserToken.ts
+// nodefony/src/token/UserToken.ts
 /**
 * Jeton porteur d'un utilisateur réel — produit par les authenticators à
 * credential (`userpassword`, puis `session`/`jwt`...).
@@ -63,5 +63,4 @@ var UserToken = class {
 		(this.#attributes ??= /* @__PURE__ */ new Map()).set(key, value);
 	}
 };
-//#endregion
 export { UserToken, UserToken as default };

package/dist/nodefony/src/token/jwtRuntime.js

@@ -1,4 +1,4 @@
-//#region nodefony/src/token/jwtRuntime.ts
+// nodefony/src/token/jwtRuntime.ts
 /**
 * Dérive les paramètres effectifs depuis la config sécurité. `issuer` omis →
 * `"nodefony"` (DEVRAIT être surchargé en prod) ; `audiences` vide → l'app est sa
@@ -27,5 +27,4 @@ function resolveJwtRuntime(jwt) {
 function defaultAudience(runtime) {
 	return runtime.audiences[0] ?? runtime.issuer;
 }
-//#endregion
 export { defaultAudience, resolveJwtRuntime };

package/dist/nodefony/src/token/scopeGrants.js

@@ -0,0 +1,109 @@
+import { ADMIN_SCOPE_READ, ADMIN_SCOPE_WRITE, refusedAdminScopes } from "nodefony";
+// nodefony/src/token/scopeGrants.ts
+const SCOPE_TOKEN = /^[\x21\x23-\x5B\x5D-\x7E]+$/u;
+const WILDCARD_SUFFIX = ":*";
+/**
+* Clés que `grantableScopes` refuse : le plan d'administration est jugé par le
+* framework, et une déclaration ici serait soit sans effet, soit un
+* assouplissement — deux pièges que rien ne signalerait.
+*/
+const RESERVED_SCOPE_GRANT_KEYS = [
+	ADMIN_SCOPE_READ,
+	ADMIN_SCOPE_WRITE,
+	"admin:*"
+];
+/**
+* Dit pourquoi une clé de `grantableScopes` est invalide, ou `null` si elle
+* est acceptable.
+*
+* Une clé est un `scope-token` (RFC 6749 §3.3) ; un `*` n'y est admis qu'en
+* dernière position, juste après `:` (une famille `préfixe:*`).
+*
+* @param key - la clé déclarée.
+* @returns le motif du refus, ou `null`.
+*/
+function scopeGrantKeyProblem(key) {
+	if (!SCOPE_TOKEN.test(key)) return "n'est pas un scope valide (RFC 6749 §3.3 : ni espace, ni guillemet, ni barre oblique inverse)";
+	const star = key.indexOf("*");
+	if (star !== -1 && (star !== key.length - 1 || !key.endsWith(WILDCARD_SUFFIX) || key.length === 2)) return "porte un `*` ailleurs qu'en fin de famille (`préfixe:*`)";
+	if (RESERVED_SCOPE_GRANT_KEYS.includes(key)) return "est réservé au plan d'administration du framework (les scopes `admin:read`/`admin:write` sont accordés au seul rôle ROLE_NODEFONY_ADMIN)";
+	return null;
+}
+/**
+* Politique d'attribution des scopes d'application, compilée une fois au boot.
+*
+* Résolution : une clé EXACTE l'emporte sur une famille, et la famille la plus
+* longue sur une plus courte (`shop:admin:*` > `shop:*`). Le résultat ne dépend
+* donc pas de l'ordre des clés. Un scope qu'aucune clé ne couvre reste accordé
+* à tout porteur (comportement historique).
+*/
+var ScopeGrantPolicy = class {
+	#exact = /* @__PURE__ */ new Map();
+	#families = [];
+	/**
+	* @param grants - la section `grantableScopes`, déjà validée par le schéma.
+	*/
+	constructor(grants = {}) {
+		for (const [key, roles] of Object.entries(grants)) if (key.endsWith(WILDCARD_SUFFIX)) this.#families.push([key.slice(0, -1), roles]);
+		else this.#exact.set(key, roles);
+		this.#families.sort((a, b) => b[0].length - a[0].length);
+	}
+	/** `true` si aucune clé n'est déclarée — tout scope d'application est accordé. */
+	get isEmpty() {
+		return this.#exact.size === 0 && this.#families.length === 0;
+	}
+	/**
+	* Les rôles dont UN suffit pour obtenir ce scope.
+	*
+	* @param scope - un scope demandé.
+	* @returns les rôles de la clé la plus spécifique, ou `null` si aucune clé ne
+	*   le couvre (scope libre).
+	*/
+	rolesFor(scope) {
+		const exact = this.#exact.get(scope);
+		if (exact !== void 0) return exact;
+		for (const [prefix, roles] of this.#families) if (scope.startsWith(prefix)) return roles;
+		return null;
+	}
+};
+/**
+* Les scopes demandés que ce porteur ne peut pas obtenir, avec la règle qui
+* refuse chacun.
+*
+* Seul juge des DEUX familles, appelé par chaque émetteur de l'application
+* (jeton d'accès, clé API) : la règle d'administration du framework
+* ({@link refusedAdminScopes}, jugée sur les rôles PLATS du compte, comme le
+* plan d'administration) et la politique de l'application
+* ({@link ScopeGrantPolicy}, jugée hiérarchie de rôles comprise, comme un
+* `@IsGranted`).
+*
+* @param requested - scopes demandés (RFC 6749 §3.3).
+* @param roles - rôles du porteur, tels que son compte les porte.
+* @param policy - politique compilée de `grantableScopes`.
+* @param hierarchy - hiérarchie de rôles ; absente, seuls les rôles plats comptent.
+* @returns les refus, dans l'ordre de la demande — vide si tout est accordé.
+*/
+function refusedScopes(requested, roles, policy, hierarchy) {
+	const admin = refusedAdminScopes(requested, roles);
+	if (admin.length === 0 && policy.isEmpty) return [];
+	let reachable = null;
+	const out = [];
+	for (const scope of requested) {
+		if (admin.includes(scope)) {
+			out.push({
+				scope,
+				rule: "admin"
+			});
+			continue;
+		}
+		const allowed = policy.rolesFor(scope);
+		if (allowed === null) continue;
+		reachable ??= hierarchy ? hierarchy.reachableRoles(roles) : new Set(roles);
+		if (!allowed.some((role) => reachable?.has(role))) out.push({
+			scope,
+			rule: "application"
+		});
+	}
+	return out;
+}
+export { RESERVED_SCOPE_GRANT_KEYS, ScopeGrantPolicy, refusedScopes, scopeGrantKeyProblem };

package/dist/nodefony/src/token/secretFile.js

@@ -3,7 +3,7 @@ import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, write
 import { randomUUID } from "node:crypto";
 import { link, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 import process from "node:process";
-//#region nodefony/src/token/secretFile.ts
+// nodefony/src/token/secretFile.ts
 /**
 * Écrire un SECRET sur disque — la seule implémentation du dépôt.
 *
@@ -187,5 +187,4 @@ function writeSecretSync(file, content) {
 		chmodSync(file, 384);
 	} catch {}
 }
-//#endregion
 export { MODE_SECRET, createSecretExclusive, messageNonRestreint, modeNonRestreint, modeNonRestreintAsync, readIfPresent, readIfPresentSync, writeSecret, writeSecretSync };

package/dist/nodefony/src/token/tokenCriteria.js

@@ -1,4 +1,4 @@
-//#region nodefony/src/token/tokenCriteria.ts
+// nodefony/src/token/tokenCriteria.ts
 /**
 * Fragment de critère **portable** exprimant l'état de vie d'un jeton — la
 * traduction que les adapters SQL et Mongo partagent au lieu de la réécrire.
@@ -32,5 +32,4 @@ function tokenStatusCriteria(status, now) {
 		default: return {};
 	}
 }
-//#endregion
 export { tokenStatusCriteria };

package/dist/nodefony/src/token/tokenFilters.js

@@ -1,4 +1,4 @@
-//#region nodefony/src/token/tokenFilters.ts
+// nodefony/src/token/tokenFilters.ts
 /**
 * **Le vocabulaire de filtre des jetons**, en noms PUBLICS — ceux qu'un client
 * écrit dans l'URL (`?status=revoked`), jamais des noms de colonne.
@@ -68,5 +68,4 @@ const TOKEN_FACETS = {
 * Un test verrouille l'accord entre cette liste et {@link TOKEN_FACETS}.
 */
 const TOKEN_STATS_FILTERS = { subjectId: "string" };
-//#endregion
 export { TOKEN_FACETS, TOKEN_FILTERS, TOKEN_STATS_FILTERS };

package/dist/nodefony/src/token/tokenSort.js

@@ -1,4 +1,4 @@
-//#region nodefony/src/token/tokenSort.ts
+// nodefony/src/token/tokenSort.ts
 /**
 * **Le vocabulaire de tri des jetons**, en noms PUBLICS — ceux qu'un client écrit
 * dans l'URL (`?order=createdAt:DESC`), jamais des noms de colonne.
@@ -36,5 +36,4 @@ const TOKEN_SORTABLE_FIELDS = [
 * ligne entre deux pages).
 */
 const TOKEN_DEFAULT_ORDER = [["createdAt", "DESC"], ["id", "DESC"]];
-//#endregion
 export { TOKEN_DEFAULT_ORDER, TOKEN_SORTABLE_FIELDS };

package/dist/nodefony/src/token/tokenStatus.js

@@ -1,4 +1,4 @@
-//#region nodefony/src/token/tokenStatus.ts
+// nodefony/src/token/tokenStatus.ts
 /**
 * **La** définition de l'état d'un jeton — un seul exemplaire, pour les backends
 * qui évaluent en mémoire (store mémoire, filtrage inline d'un batch `SCAN`).
@@ -31,5 +31,4 @@ function tokenStatusOf(token, now) {
 function matchesTokenStatus(token, status, now) {
 	return status === void 0 || tokenStatusOf(token, now) === status;
 }
-//#endregion
 export { matchesTokenStatus, tokenStatusOf };

package/dist/nodefony/src/token/tokenStoreRegistry.js

@@ -1,5 +1,5 @@
 import { MemoryTokenStore } from "./MemoryTokenStore.js";
-//#region nodefony/src/token/tokenStoreRegistry.ts
+// nodefony/src/token/tokenStoreRegistry.ts
 const factories = /* @__PURE__ */ new Map();
 /**
 * Enregistre (ou remplace) la fabrique d'un store de jetons. Appelée par le
@@ -21,5 +21,4 @@ registerTokenStore("memory", (ctx) => {
 	const days = ctx?.config?.tokenStore?.retentionRevokedDays;
 	return typeof days === "number" ? new MemoryTokenStore(Date.now, days * 864e5) : new MemoryTokenStore();
 });
-//#endregion
 export { getTokenStoreFactory, listTokenStores, registerTokenStore };

package/dist/nodefony/src/totp/MemoryTotpSecretStore.js

@@ -1,5 +1,5 @@
 import { assertPageQuery } from "nodefony";
-//#region nodefony/src/totp/MemoryTotpSecretStore.ts
+// nodefony/src/totp/MemoryTotpSecretStore.ts
 /**
 * Projette un secret en vue d'introspection — **le seul endroit** où l'on
 * décide ce qui sort d'un store TOTP en mémoire. `secretEnc` et les condensats
@@ -105,5 +105,4 @@ var MemoryTotpSecretStore = class {
 		for (const secret of snapshot.secrets) this.#byUser.set(secret.userId, secret);
 	}
 };
-//#endregion
 export { MemoryTotpSecretStore, MemoryTotpSecretStore as default, matchesTotpQuery, toTotpEnrollment };

package/dist/nodefony/src/totp/totpCipher.js

@@ -1,6 +1,6 @@
 import { decryptSecret, deriveKey, encryptSecret, generateEphemeralKey } from "../crypto/secretCipher.js";
 import { Buffer } from "node:buffer";
-//#region nodefony/src/totp/totpCipher.ts
+// nodefony/src/totp/totpCipher.ts
 /**
 * Chiffrement réversible du secret TOTP au repos — façade de domaine au-dessus
 * de la brique générique {@link ../crypto/secretCipher}.
@@ -26,5 +26,4 @@ const TOTP_DERIVATION = {
 function deriveTotpKey(material) {
 	return deriveKey(material, TOTP_DERIVATION);
 }
-//#endregion
 export { decryptSecret, deriveTotpKey, encryptSecret, generateEphemeralKey };

package/dist/nodefony/src/totp/totpCrypto.js

@@ -1,5 +1,5 @@
 import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
-//#region nodefony/src/totp/totpCrypto.ts
+// nodefony/src/totp/totpCrypto.ts
 /** Paramètres TOTP — défauts interopérables (Google Authenticator). */
 const TOTP_DEFAULTS = {
 	/** Taille du secret en octets (RFC 4226 R6 : 160 bits recommandés). */
@@ -222,5 +222,4 @@ function matchRecoveryCode(presented, hashes) {
 	}
 	return found;
 }
-//#endregion
 export { TOTP_DEFAULTS, base32Decode, base32Encode, buildOtpauthUri, generateRecoveryCodes, generateTotpSecret, hashRecoveryCode, hotp, matchRecoveryCode, totpCode, totpCounter, unbiasedIndices, verifyTotp };

package/dist/nodefony/src/totp/totpOperations.js

@@ -1,7 +1,7 @@
 import { decryptSecret, encryptSecret } from "../crypto/secretCipher.js";
 import "./totpCipher.js";
 import { base32Encode, buildOtpauthUri, generateRecoveryCodes, generateTotpSecret, hashRecoveryCode, matchRecoveryCode, verifyTotp } from "./totpCrypto.js";
-//#region nodefony/src/totp/totpOperations.ts
+// nodefony/src/totp/totpOperations.ts
 /**
 * Démarre l'enrôlement : génère un secret aléatoire, le **chiffre** au repos et
 * l'enregistre en attente de confirmation (`confirmedAt: null`). Retourne le
@@ -125,5 +125,4 @@ async function totpStatus(deps, userId) {
 		recoveryCodesRemaining: record.recoveryCodes.length
 	};
 }
-//#endregion
 export { beginTotpEnrollment, confirmTotpEnrollment, disableTotp, totpStatus, verifyTotpLogin };

package/dist/nodefony/src/totp/totpSecretStoreRegistry.js

@@ -1,5 +1,5 @@
 import { MemoryTotpSecretStore } from "./MemoryTotpSecretStore.js";
-//#region nodefony/src/totp/totpSecretStoreRegistry.ts
+// nodefony/src/totp/totpSecretStoreRegistry.ts
 const factories = /* @__PURE__ */ new Map();
 /** Enregistre (ou remplace) la fabrique d'un store de secrets TOTP. */
 function registerTotpStore(name, factory) {
@@ -14,5 +14,4 @@ function listTotpStores() {
 	return [...factories.keys()];
 }
 registerTotpStore("memory", () => new MemoryTotpSecretStore());
-//#endregion
 export { getTotpStoreFactory, listTotpStores, registerTotpStore };