@nodefony/security 10.0.0-beta.2 → 10.0.0-beta.4

package/dist/nodefony/keycloak/scaffold.js

@@ -0,0 +1,231 @@
+import { buildKeycloakRealm, renderKeycloakRealm } from "./keycloakRealm.js";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+// 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.
+*
+* Appelé par le point de contribution du paquet (`scaffold/contribute.ts`,
+* déclaré dans son `package.json` sous `nodefony.contribute`), que le cœur
+* joue sans en rien connaître : `create app` après l'installation, puis
+* `nodefony scaffold:sync` à la demande. Un fichier déjà présent n'est jamais
+* remplacé — il appartient à l'application, qui a pu le retoucher.
+*
+* @module
+*/
+/** Le nom du paquet — sert à retrouver sa racine, en source comme en `dist`. */
+const PACKAGE_NAME = "@nodefony/security";
+/** Le nom du thème, tel que le realm le déclare et que Keycloak le monte. */
+const KEYCLOAK_THEME_NAME = "nodefony";
+/** Où l'application reçoit le décor Keycloak (chemins qui voyagent : `/`). */
+const APP_KEYCLOAK_REALM_FILE = "docker/keycloak/import/realm.json";
+const APP_KEYCLOAK_THEMES_DIR = "docker/keycloak/themes";
+const APP_KEYCLOAK_THEME_DIR = `${APP_KEYCLOAK_THEMES_DIR}/${KEYCLOAK_THEME_NAME}`;
+/** Fichier de configuration de sécurité d'une application générée. */
+const APP_SECURITY_CONFIG_FILE = "nodefony/config/security.ts";
+/**
+* Ressource de l'API partenaire d'une application neuve en développement :
+* ce que rend `partnerResource()` du gabarit `complete` sans `NF_JWT_ISSUER`
+* ni `NF_PORT_HTTPS` — le port HTTPS par défaut, comme les URL de retour du
+* realm. Deux paquets, une valeur : le test de contribution compare le
+* gabarit rendu à cette constante.
+*/
+const APP_PARTNER_DEV_RESOURCE = "https://localhost:5152/api/partner";
+/** Les types de thème que le realm sait déclarer, et la clé qui les porte. */
+const THEME_TYPES = [
+	"login",
+	"account",
+	"email",
+	"admin"
+];
+/**
+* La racine du paquet, trouvée en remontant depuis ce fichier : il vit à une
+* profondeur différente en source (`nodefony/scaffold/`) et une fois bâti
+* (`dist/nodefony/scaffold/`).
+*
+* @returns le dossier qui porte le `package.json` du paquet
+* @throws Si aucun ancêtre n'est le paquet (installation corrompue)
+*/
+function packageRoot() {
+	let dir = path.dirname(fileURLToPath(import.meta.url));
+	for (;;) {
+		const manifest = path.join(dir, "package.json");
+		if (existsSync(manifest)) {
+			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`);
+		dir = parent;
+	}
+}
+/**
+* Le dossier du thème Keycloak livré par le paquet.
+*
+* @returns chemin natif absolu (`<paquet>/keycloak/themes/nodefony`)
+*/
+function keycloakThemeSource() {
+	return path.join(keycloakThemesSource(), KEYCLOAK_THEME_NAME);
+}
+/**
+* Le dossier de TOUS les thèmes Keycloak livrés : `nodefony` et ses thèmes
+* enfants `nodefony-<habillage>`, un par habillage de la page `/login`.
+* Keycloak les monte côte à côte (`/opt/keycloak/themes/`).
+*
+* @returns chemin natif absolu (`<paquet>/keycloak/themes`)
+*/
+function keycloakThemesSource() {
+	return path.join(packageRoot(), "keycloak", "themes");
+}
+/**
+* Les types que le thème livré couvre — un dossier par type. Le realm ne
+* déclare QUE ceux-là : déclarer un type absent ferait retomber Keycloak sur
+* son thème par défaut, avec un avertissement à chaque page.
+*
+* @param themeDir - dossier du thème
+* @returns les types présents, dans l'ordre de {@link THEME_TYPES}
+*/
+function deliveredThemeTypes(themeDir) {
+	const present = new Set(readdirSync(themeDir));
+	return THEME_TYPES.filter((type) => present.has(type));
+}
+/**
+* Le secret du client navigateur dans le décor de développement d'une app.
+*
+* ⚠️ Même règle que le gabarit `.env` du cœur (`keycloak.clientSecret` dans
+* `engine.ts`) : la frontière de paquets empêche de l'appeler, un test de ce
+* paquet compare donc les deux sorties.
+*
+* @param appName - nom de l'application
+* @returns le secret, PUBLIC par nature (écrit dans le realm versionné)
+*/
+function devClientSecret(appName) {
+	return `${appName}-dev-keycloak-secret`;
+}
+/**
+* Le secret de l'appelant machine (`<app>-machine`) dans le décor de
+* développement d'une app.
+*
+* ⚠️ Même règle que le gabarit `.env` du cœur (`keycloak.machineSecret` dans
+* `engine.ts`), comparée par le même test que {@link devClientSecret}.
+*
+* @param appName - nom de l'application
+* @returns le secret, PUBLIC par nature (écrit dans le realm versionné)
+*/
+function devMachineSecret(appName) {
+	return `${appName}-machine-dev-secret`;
+}
+/**
+* Ce que dit la configuration rendue par le gabarit `security.ts` d'une app
+* neuve : client `<app>`, URL de retour sur les deux ports de développement,
+* rôle client `admin` (`roleMapping: { admin: "ROLE_ADMIN" }`), et les
+* audiences des zones `external-jwt` que la configuration rendue déclare.
+*
+* @param appName - nom de l'application (= realm = identifiant de client)
+* @param themes - types de thème à déclarer
+* @param ids - `sub` des comptes de démonstration, FIXÉS dans le fichier :
+*   laissés à Keycloak, ils changent à chaque réimport et la connexion
+*   suivante est refusée (identifiant déjà lié à un autre `sub`)
+* @param audiences - ressources que les jetons du realm doivent porter
+*   (mapper sur les deux clients) ; vide = aucune zone ne les accepte
+* @returns l'entrée du constructeur de realm
+*/
+function appDevRealmInput(appName, themes, ids, audiences = []) {
+	const callback = "/nodefony/security/api/oauth2/keycloak/callback";
+	return {
+		realm: appName,
+		clientId: appName,
+		clientSecret: devClientSecret(appName),
+		clientName: `${appName} (dev)`,
+		clientDescription: "Client confidentiel de l'application en développement — secret PUBLIC, jamais en production.",
+		redirectUris: [`https://localhost:5152${callback}`, `http://localhost:5151${callback}`],
+		postLogoutRedirectUris: ["https://localhost:5152/*", "http://localhost:5151/*"],
+		backchannelLogoutUrl: "http://host.docker.internal:5151/nodefony/security/api/oauth2/keycloak/backchannel-logout",
+		audiences,
+		clientRoles: [{
+			name: "admin",
+			description: "Administrateur de l'application — traduit en ROLE_ADMIN par la table roleMapping du fournisseur keycloak."
+		}],
+		realmRoles: [],
+		machine: {
+			clientId: `${appName}-machine`,
+			secret: devMachineSecret(appName),
+			name: `${appName} — appelant machine (compte de service)`,
+			description: "Appelant machine : obtient un jeton d'accès par client_credentials, sans utilisateur. Secret PUBLIC, jamais en production."
+		},
+		themes: Object.fromEntries(themes.map((type) => [type, KEYCLOAK_THEME_NAME])),
+		users: [{
+			id: ids.user,
+			username: "alice",
+			email: `alice@${appName}.test`,
+			firstName: "Alice",
+			lastName: "Keycloak",
+			password: "alice-dev"
+		}, {
+			id: ids.admin,
+			username: "bob",
+			email: `bob@${appName}.test`,
+			firstName: "Bob",
+			lastName: "Keycloak",
+			password: "bob-dev",
+			clientRoles: ["admin"]
+		}]
+	};
+}
+/**
+* L'application monte-t-elle un décor Keycloak ? Seul son compose le dit : on
+* ne pose que ce que quelqu'un lit — une application sans profil `keycloak`
+* (preset minimal, sécurité ajoutée plus tard) ne reçoit rien.
+*
+* @param context - contexte de contribution
+* @returns `true` si le compose monte `./docker/keycloak/…`
+*/
+function mountsKeycloak(context) {
+	return [
+		"compose.yaml",
+		"compose.yml",
+		"docker-compose.yml"
+	].some((file) => context.read(file)?.includes("./docker/keycloak/") === true);
+}
+/**
+* Les audiences que la configuration RENDUE de l'application déclare. Le
+* gabarit `complete` ouvre la zone `partner` (`jwt` + `external-jwt`) : sans
+* son audience dans le realm, le jeton du client machine y est refusé dès le
+* premier essai, et `security:keycloak:realm --check` trouve le realm né en
+* désaccord avec la configuration.
+*
+* @param context - contexte de contribution
+* @returns les ressources à inscrire dans les jetons du realm
+*/
+function renderedAudiences(context) {
+	return context.read(APP_SECURITY_CONFIG_FILE)?.includes("partnerResource(") === true ? [APP_PARTNER_DEV_RESOURCE] : [];
+}
+/**
+* Recopie les thèmes livrés dans l'application — `nodefony` et ses thèmes
+* d'habillage —, fichier par fichier, sans jamais remplacer un fichier présent.
+*
+* @param context - contexte de contribution
+*/
+function copyKeycloakTheme(context) {
+	context.copyTree(keycloakThemesSource(), APP_KEYCLOAK_THEMES_DIR);
+}
+/**
+* Pose le realm d'import et le thème Keycloak, si l'application monte un
+* décor Keycloak.
+*
+* @param context - contexte fourni par le cœur (`runAppContributions`)
+*/
+function contributeKeycloak(context) {
+	if (!mountsKeycloak(context)) return;
+	const themes = deliveredThemeTypes(keycloakThemeSource());
+	const realm = buildKeycloakRealm(appDevRealmInput(context.appName, themes, {
+		user: randomUUID(),
+		admin: randomUUID()
+	}, renderedAudiences(context)));
+	context.write(APP_KEYCLOAK_REALM_FILE, renderKeycloakRealm(realm));
+	copyKeycloakTheme(context);
+}
+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 };

package/dist/nodefony/keycloak/security-keycloak-realm.js

@@ -0,0 +1,130 @@
+import { KeycloakRealmError } from "./keycloakRealmInput.js";
+import { KeycloakAdminError } from "./keycloakAdmin.js";
+import { Command } from "nodefony";
+import path from "node:path";
+// nodefony/keycloak/security-keycloak-realm.ts
+const options = {
+	helpGroup: "COMPTES ET SECRETS",
+	showBanner: false,
+	kernelEvent: "onReady",
+	quietBoot: true
+};
+const GREEN = "\x1B[32m";
+const YELLOW = "\x1B[33m";
+const DIM = "\x1B[2m";
+const RESET = "\x1B[0m";
+/** Codes de sortie (sysexits). */
+const EXIT_DIFFERS = 1;
+const EXIT_CONFIG = 78;
+/**
+* `nodefony security:keycloak:realm` — le realm Keycloak que la configuration
+* de l'application implique.
+*
+* Le realm d'import répète ce que la config dit déjà : identifiant du client,
+* URL de retour, audience de chaque zone, rôles de `roleMapping`. Écrit à la
+* main, il diverge — et le symptôme est un 401 ou une URL de retour refusée,
+* jamais un message qui nomme la cause. Cette commande le DÉRIVE, par le
+* service `keycloak` — qui porte toutes les actions Keycloak ; elle n'en
+* garde que l'affichage et les codes de sortie.
+*
+* Elle FUSIONNE dans le fichier existant au lieu de l'écraser : comptes de
+* démonstration, titres, secret machine, mappers posés dans la console
+* survivent (`mergeKeycloakRealm`, cœur — le même constructeur que
+* `create app`).
+*
+* - sans option : affiche le realm fusionné ;
+* - `--write` : l'écrit (le fichier par défaut est l'unique `.json` de
+*   `docker/keycloak/import/`) ;
+* - `--check` : sort en 1 si le fichier n'est plus à jour — la garde de CI ;
+* - `--apply` : pose sur le realm EXISTANT le thème de connexion qui suit
+*   `loginPage.skin`, par l'API d'administration (service `keycloak`) —
+*   développement seulement, compte `oauth2.providers.<nom>.admin` requis.
+*
+* ⚠️ Keycloak n'importe un realm qu'à sa CRÉATION : un realm déjà présent
+* n'est pas relu. Après `--write`, le porter par un import PARTIEL (clients en
+* « Overwrite » : comptes et seconds facteurs survivent) ; retirer le volume
+* ne se fait que sur un realm qui ne porte rien à garder.
+*/
+var SecurityKeycloakRealm = class extends Command {
+	constructor(cli) {
+		super("security:keycloak:realm", "écrit le realm Keycloak déduit de la configuration", cli, {
+			...options,
+			examples: ["nodefony security:keycloak:realm --check", "nodefony security:keycloak:realm --write"]
+		});
+		this.addOption("-w, --write [fichier]", "écrit le realm fusionné dans le fichier d'import");
+		this.addOption("-c, --check [fichier]", "sort en 1 si le fichier d'import n'est plus à jour");
+		this.addOption("-a, --apply", "pose le thème de connexion sur le realm existant (développement)");
+		this.addOption("-p, --provider <nom>", "fournisseur de oauth2.providers (défaut keycloak)");
+		this.addOption("-m, --machine <clientId>", "client machine dont l'audience suit la config");
+		this.addOption("--backchannel-origin <url>", "origine par laquelle Keycloak joint l'application (canal arrière)");
+	}
+	/** Le service `keycloak`, ou `null` (code de sortie posé). */
+	#service() {
+		const service = this.kernel?.container?.get("keycloak");
+		if (service) return service;
+		this.log("service keycloak absent — module security non chargé ?", "ERROR");
+		process.exitCode = EXIT_CONFIG;
+		return null;
+	}
+	async generate(opts) {
+		const service = this.#service();
+		if (service === null) return this;
+		if (opts.apply === true) {
+			if (!await this.#apply(service, opts.provider) || opts.write === void 0 && opts.check === void 0) return this;
+		}
+		let plan;
+		try {
+			plan = service.realmPlan({
+				provider: opts.provider,
+				machine: opts.machine,
+				backchannelOrigin: opts.backchannelOrigin,
+				file: typeof opts.write === "string" ? opts.write : typeof opts.check === "string" ? opts.check : void 0
+			});
+		} catch (error) {
+			if (!(error instanceof KeycloakRealmError)) throw error;
+			this.log(error.message, "ERROR");
+			process.exitCode = EXIT_CONFIG;
+			return this;
+		}
+		for (const warning of plan.warnings) process.stderr.write(`${YELLOW}⚠ ${warning}${RESET}\n`);
+		const relative = path.relative(this.kernel?.path ?? process.cwd(), plan.file);
+		if (opts.check !== void 0) {
+			if (plan.upToDate) {
+				process.stdout.write(`${GREEN}✓${RESET} ${relative} est à jour\n`);
+				return this;
+			}
+			process.stderr.write(`${relative} ne correspond plus à la configuration — nodefony security:keycloak:realm --write\n`);
+			process.exitCode = EXIT_DIFFERS;
+			return this;
+		}
+		if (opts.write !== void 0) {
+			if (!service.writeRealm(plan)) {
+				process.stdout.write(`${GREEN}✓${RESET} ${relative} déjà à jour, rien d'écrit\n`);
+				return this;
+			}
+			process.stdout.write(`${GREEN}✓${RESET} ${relative} écrit\n${DIM}  Keycloak n'importe un realm qu'à sa CRÉATION — un realm déjà là ne relit pas ce fichier :\n  · thème de connexion : nodefony security:keycloak:realm --apply ;\n  · le reste : console › Realm settings › Action › Partial import, clients en « Overwrite » (comptes et seconds facteurs gardés) ;\n  · ou recréer le realm (retirer le volume Keycloak) s'il ne porte rien à garder.${RESET}\n`);
+			return this;
+		}
+		process.stdout.write(plan.text);
+		return this;
+	}
+	/**
+	* `--apply` : le thème que l'habillage demande, posé sur le realm vivant.
+	*
+	* @returns `false` si le geste a échoué (code de sortie posé)
+	*/
+	async #apply(service, provider) {
+		try {
+			const result = await service.applyLoginTheme(provider === void 0 ? {} : { provider });
+			const line = result.outcome === "applied" ? `${GREEN}✓${RESET} realm « ${result.realm} » : thème « ${result.previous ?? "—"} » → « ${result.theme} »` : result.outcome === "unchanged" ? `${GREEN}✓${RESET} realm « ${result.realm} » : déjà sur « ${result.theme} »` : `${YELLOW}⚠${RESET} realm « ${result.realm} » : thème « ${result.previous ?? "aucun"} » propre à l'application, laissé tel quel`;
+			process.stdout.write(`${line}\n`);
+			return true;
+		} catch (error) {
+			if (!(error instanceof KeycloakAdminError)) throw error;
+			this.log(error.message, "ERROR");
+			process.exitCode = EXIT_CONFIG;
+			return false;
+		}
+	}
+};
+export { SecurityKeycloakRealm as default };

package/dist/nodefony/scaffold/contribute.js

@@ -0,0 +1,19 @@
+import { contributeKeycloak } from "../keycloak/scaffold.js";
+// nodefony/scaffold/contribute.ts
+/**
+* Le point de contribution de `@nodefony/security` : ce que le paquet livre à
+* une application, déclaré dans son `package.json` (`nodefony.contribute`) et
+* joué par le cœur, qui n'en connaît rien.
+*
+* @module
+*/
+/**
+* La contribution du paquet — aujourd'hui le seul décor Keycloak de
+* développement (`nodefony/keycloak/`).
+*
+* @param context - contexte fourni par le cœur (`runAppContributions`)
+*/
+function contribute(context) {
+	contributeKeycloak(context);
+}
+export { contribute };

package/dist/nodefony/service/accessTokenVerifier.js

@@ -1,25 +1,52 @@
+import { AuthenticationError } from "../errors/AuthenticationError.js";
 import { defineSecurityConfig } from "../config/defineModuleConfig.js";
+import { UserToken } from "../src/token/UserToken.js";
+import peekIssuer from "../src/authenticator/peekIssuer.js";
+import { JwtAuthenticator } from "../src/authenticator/JwtAuthenticator.js";
+import { ExternalSubjectResolver, externalSubjectOptions } from "../src/authenticator/ExternalSubjectResolver.js";
+import { resolveJwtRuntime } from "../src/token/jwtRuntime.js";
 import { RemoteJwtVerifier } from "../src/token/RemoteJwtVerifier.js";
-import { ACCESS_TOKEN_VERIFIER, Service, canonicalIssuer } from "nodefony";
-//#region nodefony/service/accessTokenVerifier.ts
+import { ACCESS_ACCOUNT_RESOLVER, ACCESS_TOKEN_VERIFIER, Service } from "nodefony";
+// nodefony/service/accessTokenVerifier.ts
 const serviceName = ACCESS_TOKEN_VERIFIER;
 /**
-* Pose (ou non) le vérificateur de jetons d'accès TIERS dans le conteneur.
+* Pose (ou non) le vérificateur de jetons d'accès dans le conteneur — celui
+* qu'une ressource protégée (porte MCP, zone `external-jwt`) interroge.
 *
-* Ce service est une **décision de câblage**, pas de la cryptographie : toute la
-* mécanique vit dans {@link RemoteJwtVerifier}, et la doctrine de refus dans le
-* cœur (`nodefony/src/oauth/`). Ici, on lit la configuration et on tranche une
-* seule question — cette application accepte-t-elle des jetons émis ailleurs ?
+* Ce service est une **décision de câblage**, pas de la cryptographie : la
+* vérification d'un jeton TIERS vit dans {@link RemoteJwtVerifier}, celle d'un
+* jeton de CETTE application dans {@link JwtAuthenticator}, et la doctrine de
+* refus dans le cœur (`nodefony/src/oauth/`). Ici, on tranche deux questions :
+* l'application signe-t-elle ses jetons, et en accepte-t-elle d'ailleurs ?
 *
-* **Aucun émetteur déclaré = rien n'est posé**, et c'est le comportement voulu :
-* une porte protégée qui ne trouve pas de vérificateur refuse de servir en le
-* disant (503 + CRITIC), là où un vérificateur présent mais vide refuserait
+* ⭐ **Un jeton signé par cette application est TOUJOURS vérifiable**, dès que
+* sa capacité JWT est active (`security.jwt.enabled`, le défaut) — sans rien
+* déclarer dans `resourceServer.issuers`. Une application qui émet un jeton
+* pour sa propre porte (`nodefony security:mcp:token --resource …`) doit pouvoir
+* le lire : sans cette règle, la porte refusait un jeton parfaitement valide,
+* et l'application était un serveur d'autorisation dont aucune ressource ne
+* reconnaissait la signature. Rien de nouveau ne devient valide : l'audience
+* reste exigée, et seules celles de `jwt.audiences` sont émises.
+*
+* 🔴 **Il est vérifié par les règles de l'authentificateur `jwt`, pas par son
+* jeu de clés seul** : révocation ciblée et en masse, compte encore actif. Lu
+* comme un jeton tiers, un jeton RÉVOQUÉ — ou celui d'un compte désactivé —
+* ouvrait encore la porte jusqu'à son expiration.
+*
+* L'aiguillage se fait sur l'émetteur revendiqué (`peekIssuer`), comme dans le
+* pare-feu : l'émetteur de l'application va à la vérification locale, tout
+* autre à la liste fermée des émetteurs tiers. Un émetteur inconnu est refusé
+* sans la moindre requête sortante.
+*
+* **Rien à vérifier = rien n'est posé** (capacité JWT coupée, aucun émetteur
+* tiers) : une porte protégée qui ne trouve pas de vérificateur refuse alors de
+* servir en le disant (503 + CRITIC), là où un vérificateur vide refuserait
 * chaque jeton un par un — même résultat pour l'appelant, diagnostic beaucoup
 * plus difficile pour l'exploitant.
 *
-* Le coût est nul quand la capacité n'est pas utilisée : rien n'est instancié,
-* aucune requête n'est faite au démarrage. La découverte des clés n'a lieu qu'au
-* PREMIER jeton réellement présenté, et une seule fois par émetteur.
+* Le coût est nul tant qu'aucun jeton n'est présenté : aucune requête au
+* démarrage, clés locales lues au premier jeton, découverte d'un émetteur tiers
+* au premier jeton qui s'en réclame.
 */
 var AccessTokenVerifierService = class extends Service {
 	module;
@@ -29,7 +56,7 @@ var AccessTokenVerifierService = class extends Service {
 		this.module = module;
 		this.kernel?.once("onBoot", () => this.#build());
 	}
-	/** Le vérificateur, ou `null` si aucun émetteur n'est déclaré. */
+	/** Le vérificateur posé, ou `null` si rien n'est vérifiable. */
 	get verifier() {
 		return this.#verifier;
 	}
@@ -40,23 +67,13 @@ var AccessTokenVerifierService = class extends Service {
 		} catch {
 			return;
 		}
+		const runtime = config.jwt.enabled ? resolveJwtRuntime(config.jwt) : null;
+		const local = runtime === null ? null : new JwtAuthenticator(this.container, runtime);
 		const { issuers, ...tuning } = config.resourceServer;
-		if (issuers.length === 0) {
-			this.log("aucun émetteur de confiance déclaré (security.resourceServer.issuers) — les jetons émis par un serveur d'autorisation tiers ne sont pas vérifiables ; une porte protégée refusera de servir.", "DEBUG");
-			return;
-		}
-		const localIssuer = config.jwt.issuer;
-		const armed = issuers.map((trusted) => localIssuer && canonicalIssuer(trusted.issuer) === canonicalIssuer(localIssuer) ? {
-			...trusted,
-			localJwks: async () => {
-				const keystore = this.container?.get("jwtKeystore");
-				if (!keystore) throw new Error(`l'émetteur « ${trusted.issuer} » est cette application, mais sa capacité JWT n'est pas armée (security.jwt) — aucune clé locale à présenter`);
-				return keystore.getPublicJWKS();
-			}
-		} : trusted);
-		try {
-			this.#verifier = new RemoteJwtVerifier({
-				issuers: armed,
+		let remote = null;
+		if (issuers.length > 0) try {
+			remote = new RemoteJwtVerifier({
+				issuers,
 				timeoutMs: tuning.timeoutMs,
 				cooldownMs: tuning.cooldownMs,
 				cacheMaxAgeMs: tuning.cacheMaxAgeMs,
@@ -67,11 +84,61 @@ var AccessTokenVerifierService = class extends Service {
 			this.log(`vérificateur de jetons non armé — ${error.message}`, "CRITIC");
 			return;
 		}
-		const verify = (token, audience) => this.#verifier.verify(token, audience);
+		if (local === null && remote === null) {
+			this.log("rien à vérifier — capacité JWT coupée (security.jwt.enabled) et aucun émetteur tiers (security.resourceServer.issuers) : une porte protégée refusera de servir.", "DEBUG");
+			return;
+		}
+		const localIssuer = runtime?.issuer ?? null;
+		const verify = (token, audience) => {
+			if (local !== null && peekIssuer(token) === localIssuer) return local.verifyForResource(token, audience);
+			return remote === null ? Promise.resolve(null) : remote.verify(token, audience);
+		};
+		this.#verifier = verify;
 		this.container?.set(serviceName, verify);
-		const locaux = armed.filter((i) => "localJwks" in i).length;
-		this.log(`vérificateur de jetons armé — ${issuers.length} émetteur(s) de confiance : ` + issuers.map((i) => i.issuer).join(", ") + (locaux > 0 ? ` (dont ${locaux} servi par les clés LOCALES, sans requête)` : ""), "INFO");
+		this.container?.set(ACCESS_ACCOUNT_RESOLVER, accountResolver(local, issuers.length > 0 ? new ExternalSubjectResolver(this.container, externalSubjectOptions(config)) : null));
+		const trusted = [...localIssuer === null ? [] : [`${localIssuer} (cette application)`], ...issuers.map((i) => i.issuer)];
+		this.log(`vérificateur de jetons armé — ${trusted.length} émetteur(s) de confiance : ` + trusted.join(", "), "INFO");
 	}
 };
-//#endregion
+/**
+* Le résolveur de compte posé à côté du vérificateur : il retrouve, pour un
+* principal que celui-ci vient d'établir, le compte de l'application qui agit.
+*
+* Aiguillé par l'émetteur, comme le vérificateur : un jeton maison rejoue la
+* règle de la zone `jwt` (`JwtAuthenticator.resolveAccount`), un jeton tiers
+* celle de la zone `external-jwt` (`ExternalSubjectResolver`). Aucune n'est
+* recopiée ici. Un refus rend `null` ; une panne (annuaire non câblé,
+* émetteur absent de la table de rattachement) traverse.
+*
+* Le jeton rendu est un `UserToken` de type `"mcp"` — hors des types humains
+* que le voteur de scopes laisse passer : les scopes du jeton bornent les
+* attributs `api:action`, et les rôles restent ceux du compte, comme dans une
+* zone `jwt`.
+*/
+function accountResolver(local, external) {
+	return async (principal) => {
+		let user = null;
+		if (local !== null) user = await local.resolveAccount(principal);
+		if (user === null && external !== null && principal.subject) {
+			if (!external.recognizes(principal.issuer)) return null;
+			try {
+				user = await external.resolve(principal.issuer, principal.subject, principal.claims);
+			} catch (error) {
+				if (error instanceof AuthenticationError) return null;
+				throw error;
+			}
+		}
+		if (user === null) return null;
+		const token = new UserToken("mcp").promote(user);
+		token.setAttribute("scopes", [...principal.scopes]);
+		token.setAttribute("issuer", principal.issuer);
+		token.setAttribute("subject", principal.subject);
+		if (principal.tokenId !== void 0) token.setAttribute("jti", principal.tokenId);
+		if (principal.claims !== void 0) token.setAttribute("claims", principal.claims);
+		return {
+			token,
+			user
+		};
+	};
+}
 export { AccessTokenVerifierService, AccessTokenVerifierService as default };

package/dist/nodefony/service/apiKeys.js

@@ -1,11 +1,13 @@
+import { ScopeGrantPolicy, refusedScopes } from "../src/token/scopeGrants.js";
 import { defineSecurityConfig } from "../config/defineModuleConfig.js";
+import { ACCOUNT_ID_KEY, CREDENTIALS_VERSION_KEY, credentialsVersionOf } from "../src/accountBinding.js";
 import { generateApiKey } from "../src/apikey/apiKeyFormat.js";
 import { recordAudit } from "../src/audit/recordAudit.js";
 import { TOKEN_FACETS } from "../src/token/tokenFilters.js";
 import { ApiKeyError } from "../errors/ApiKeyError.js";
 import { Service, countFacets } from "nodefony";
 import { randomUUID } from "node:crypto";
-//#region nodefony/service/apiKeys.ts
+// nodefony/service/apiKeys.ts
 const serviceName = "apiKeys";
 const MAX_NAME_LEN = 100;
 const MS_PER_DAY = 864e5;
@@ -32,6 +34,8 @@ var ApiKeyService = class extends Service {
 	#defaultExpiryDays = 90;
 	#maxPerSubject = 100;
 	#allowedScopes = null;
+	/** `grantableScopes` compilé au boot ; `null` tant que la config n'est pas lue. */
+	#scopeGrants = null;
 	constructor(module) {
 		super(serviceName, module.container, module.notificationsCenter, module.options);
 		this.module = module;
@@ -54,6 +58,7 @@ var ApiKeyService = class extends Service {
 		this.#defaultExpiryDays = ak.defaultExpiryDays;
 		this.#maxPerSubject = ak.maxPerSubject;
 		this.#allowedScopes = ak.allowedScopes;
+		this.#scopeGrants = new ScopeGrantPolicy(config.grantableScopes);
 		this.log(`api keys ready — prefix "${ak.prefix}_", max ${ak.maxPerSubject}/porteur`, "DEBUG");
 	}
 	/** `true` si les clés API sont activées en config. */
@@ -83,17 +88,31 @@ var ApiKeyService = class extends Service {
 	* Émet une nouvelle clé API pour un porteur — renvoie sa vue publique **+ le
 	* token en clair** (affiché une seule fois).
 	*
+	* Un scope que le porteur ne peut pas OBTENIR — réservé par
+	* `grantableScopes` à des rôles qu'il n'a pas, ou `admin:*` sans le rôle
+	* d'administration — refuse la création entière : une clé émise avec moins
+	* que demandé surprendrait sans qu'aucune réponse ne le dise. Même juge que
+	* l'émission des jetons ({@link refusedScopes}).
+	*
+	* @param roles - rôles du porteur tels que son compte les porte ; omis =
+	*   aucun rôle, donc tout scope réservé est refusé (fail-closed).
 	* @throws ApiKeyError 400 — nom vide/trop long, scope hors catalogue, expiry invalide.
+	* @throws ApiKeyError 403 — scope réservé à des rôles que le porteur n'a pas.
 	* @throws ApiKeyError 409 — plafond `maxPerSubject` atteint.
-	* @throws ApiKeyError 503 — store indisponible.
+	* @throws ApiKeyError 403 — aucun compte sous cet identifiant (la clé est liée
+	*   à l'`id` immuable du compte, lu dans l'annuaire).
+	* @throws ApiKeyError 503 — store ou annuaire `users` indisponible.
 	*/
-	async createForSubject(subjectId, subjectType, opts) {
+	async createForSubject(subjectId, subjectType, opts, roles = []) {
 		const store = this.#resolveStore();
 		const name = this.#normalizeName(opts.name);
 		const scopes = this.#normalizeScopes(opts.scopes);
+		const refusals = refusedScopes(scopes, roles, this.#scopeGrants ?? new ScopeGrantPolicy(), this.container?.get("roleHierarchy") ?? null);
+		if (refusals.length > 0) throw new ApiKeyError(`scope not grantable to this account: ${refusals.map((r) => r.scope).join(", ")}`, 403);
 		const now = Date.now();
 		const expiresAt = this.#resolveExpiry(opts.expiresInDays, now);
 		if ((await store.findBySubject(subjectId)).filter((r) => r.kind === "pat" && this.#isActive(r, now)).length >= this.#maxPerSubject) throw new ApiKeyError(`API key limit reached (${this.#maxPerSubject})`, 409);
+		const holder = await this.#resolveHolder(subjectId);
 		const generated = generateApiKey(this.#prefix);
 		const record = {
 			id: randomUUID(),
@@ -119,7 +138,10 @@ var ApiKeyService = class extends Service {
 			lastUsedUserAgent: null,
 			revokedAt: null,
 			revokedReason: null,
-			metadata: {}
+			metadata: {
+				[ACCOUNT_ID_KEY]: holder.id,
+				[CREDENTIALS_VERSION_KEY]: credentialsVersionOf(holder)
+			}
 		};
 		await store.put(record);
 		this.log(`api key created — id=${record.id} subject=${subjectId} scopes=[${scopes.join(",")}]`, "INFO");
@@ -253,6 +275,25 @@ var ApiKeyService = class extends Service {
 		});
 		return true;
 	}
+	/**
+	* Le compte qui reçoit la clé — son identifiant IMMUABLE et sa version
+	* d'identifiants sont la liaison qu'elle portera, contrôlée à chaque
+	* présentation (`isBoundToAccount`). Lu dans
+	* l'annuaire, jamais reçu de l'appelant : la clé appartient au compte qui
+	* existe MAINTENANT sous cet identifiant.
+	*
+	* @throws ApiKeyError 503 — annuaire `users` absent (câblage).
+	* @throws ApiKeyError 403 — aucun compte sous cet identifiant.
+	*/
+	async #resolveHolder(subjectId) {
+		const users = this.get("users");
+		if (!users) throw new ApiKeyError("user directory unavailable", 503);
+		try {
+			return await users.loadUserByIdentifier(subjectId);
+		} catch {
+			throw new ApiKeyError("API key holder unknown", 403);
+		}
+	}
 	#resolveStore() {
 		if (this.#store === null) {
 			const store = this.get("tokenStore");
@@ -306,5 +347,4 @@ var ApiKeyService = class extends Service {
 		};
 	}
 };
-//#endregion
 export { ApiKeyService, ApiKeyService as default };