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

package/dist/nodefony/keycloak/keycloakRealm.js

@@ -0,0 +1,260 @@
+//#region nodefony/keycloak/keycloakRealm.ts
+/** Le type du mapper qui ajoute une audience au jeton d'accès. */
+const AUDIENCE_MAPPER = "oidc-audience-mapper";
+/**
+* Le nom d'un mapper d'audience — stable, pour qu'une régénération réécrive
+* le même mapper au lieu d'en ajouter un.
+*/
+function audienceMapperName(realm, index) {
+	return index === 0 ? `audience-${realm}-api` : `audience-${realm}-api-${index + 1}`;
+}
+function audienceMappers(input) {
+	return input.audiences.map((audience, index) => ({
+		name: audienceMapperName(input.realm, index),
+		protocol: "openid-connect",
+		protocolMapper: AUDIENCE_MAPPER,
+		config: {
+			"included.custom.audience": audience,
+			"access.token.claim": "true",
+			"id.token.claim": "false",
+			"introspection.token.claim": "true"
+		}
+	}));
+}
+function roleObjects(roles) {
+	return roles.map((role) => role.description === void 0 ? { name: role.name } : {
+		name: role.name,
+		description: role.description
+	});
+}
+function browserClient(input) {
+	const attributes = {
+		"pkce.code.challenge.method": "S256",
+		"post.logout.redirect.uris": input.postLogoutRedirectUris.join("##")
+	};
+	if (input.backchannelLogoutUrl !== null) {
+		attributes["backchannel.logout.url"] = input.backchannelLogoutUrl;
+		attributes["backchannel.logout.session.required"] = "true";
+		attributes["backchannel.logout.revoke.offline.tokens"] = "false";
+	}
+	return {
+		clientId: input.clientId,
+		...input.clientName === void 0 ? {} : { name: input.clientName },
+		...input.clientDescription === void 0 ? {} : { description: input.clientDescription },
+		enabled: true,
+		protocol: "openid-connect",
+		publicClient: false,
+		clientAuthenticatorType: "client-secret",
+		...input.clientSecret === null ? {} : { secret: input.clientSecret },
+		standardFlowEnabled: true,
+		implicitFlowEnabled: false,
+		directAccessGrantsEnabled: false,
+		serviceAccountsEnabled: false,
+		frontchannelLogout: false,
+		redirectUris: [...input.redirectUris],
+		webOrigins: ["+"],
+		attributes,
+		protocolMappers: audienceMappers(input)
+	};
+}
+function machineClient(input, machine) {
+	return {
+		clientId: machine.clientId,
+		...machine.name === void 0 ? {} : { name: machine.name },
+		...machine.description === void 0 ? {} : { description: machine.description },
+		enabled: true,
+		protocol: "openid-connect",
+		publicClient: false,
+		clientAuthenticatorType: "client-secret",
+		...machine.secret === null ? {} : { secret: machine.secret },
+		standardFlowEnabled: false,
+		implicitFlowEnabled: false,
+		directAccessGrantsEnabled: false,
+		serviceAccountsEnabled: true,
+		protocolMappers: audienceMappers(input)
+	};
+}
+/**
+* Le rôle composite que Keycloak donne à tout compte CRÉÉ dans le realm —
+* `manage-account`, `view-profile`, `offline_access`, `uma_authorization`.
+*
+* ⚠️ Un compte IMPORTÉ ne le reçoit pas : l'import n'accorde que les rôles
+* qu'il liste. Sans lui, la console du compte rend 401 sur le profil même de
+* l'utilisateur.
+*
+* @param realm - nom du realm
+* @returns le nom du rôle par défaut
+*/
+function keycloakDefaultRole(realm) {
+	return `default-roles-${realm}`;
+}
+function userObject(realm, clientId, user) {
+	return {
+		id: user.id,
+		username: user.username,
+		enabled: true,
+		email: user.email,
+		emailVerified: true,
+		firstName: user.firstName,
+		lastName: user.lastName,
+		credentials: [{
+			type: "password",
+			value: user.password,
+			temporary: false
+		}],
+		realmRoles: [keycloakDefaultRole(realm)],
+		...user.clientRoles === void 0 || user.clientRoles.length === 0 ? {} : { clientRoles: { [clientId]: [...user.clientRoles] } }
+	};
+}
+/**
+* Construit le realm d'import complet d'une application.
+*
+* @param input - ce que la configuration de l'application dit du realm
+* @returns le realm, prêt à être sérialisé par {@link renderKeycloakRealm}
+*/
+function buildKeycloakRealm(input) {
+	const roles = {};
+	if (input.realmRoles.length > 0) roles.realm = roleObjects(input.realmRoles);
+	if (input.clientRoles.length > 0) roles.client = { [input.clientId]: roleObjects(input.clientRoles) };
+	const clients = [browserClient(input)];
+	if (input.machine !== null) clients.push(machineClient(input, input.machine));
+	return {
+		realm: input.realm,
+		displayName: input.displayName ?? input.realm,
+		enabled: true,
+		sslRequired: "external",
+		registrationAllowed: false,
+		loginWithEmailAllowed: true,
+		...input.themes?.login === void 0 ? {} : { loginTheme: input.themes.login },
+		...input.themes?.account === void 0 ? {} : { accountTheme: input.themes.account },
+		...input.themes?.email === void 0 ? {} : { emailTheme: input.themes.email },
+		...input.themes?.admin === void 0 ? {} : { adminTheme: input.themes.admin },
+		internationalizationEnabled: true,
+		supportedLocales: ["fr", "en"],
+		defaultLocale: "fr",
+		clients,
+		...Object.keys(roles).length === 0 ? {} : { roles },
+		...input.users === void 0 || input.users.length === 0 ? {} : { users: input.users.map((u) => userObject(input.realm, input.clientId, u)) },
+		rememberMe: true
+	};
+}
+function isObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function objects(value) {
+	return Array.isArray(value) ? value.filter(isObject) : [];
+}
+/**
+* Les champs qu'un client hérite du realm existant quand il y figure : un nom,
+* un texte, un secret machine sont écrits par un humain, pas par la config.
+*/
+const CLIENT_KEPT = /* @__PURE__ */ new Set(["name", "description"]);
+function mergeClient(existing, derived, keepSecret) {
+	const merged = { ...existing };
+	for (const [key, value] of Object.entries(derived)) {
+		if (CLIENT_KEPT.has(key) && key in existing) continue;
+		if (key === "secret" && keepSecret && key in existing) continue;
+		if (key === "attributes" && isObject(existing.attributes) && isObject(value)) {
+			merged.attributes = {
+				...existing.attributes,
+				...value
+			};
+			continue;
+		}
+		if (key === "protocolMappers") {
+			merged.protocolMappers = [...objects(existing.protocolMappers).filter((m) => m.protocolMapper !== AUDIENCE_MAPPER), ...objects(value)];
+			continue;
+		}
+		merged[key] = value;
+	}
+	return merged;
+}
+function mergeRoles(existing, derived) {
+	const kept = objects(existing);
+	const names = new Set(kept.map((r) => r.name));
+	return [...kept, ...objects(derived).filter((r) => !names.has(r.name))];
+}
+/**
+* Fond un realm dérivé de la config dans le realm d'import existant.
+*
+* Ce que la configuration DIT est réécrit : nom du realm, thèmes déclarés,
+* client navigateur (flux, URL de retour, audience, déconnexion), client
+* machine (flux, audience). Ce qu'un humain a écrit SURVIT : comptes,
+* titre, noms et textes des clients, secret machine, rôles déjà déclarés,
+* mappers qui ne sont pas d'audience, clients et clés inconnus. Régénérer
+* ne détruit donc rien de ce que la console a ajouté.
+*
+* @param existing - le realm lu sur disque (JSON quelconque)
+* @param derived - le realm construit par {@link buildKeycloakRealm}
+* @returns le realm fusionné
+* @throws Si `existing` n'est pas un objet JSON
+*/
+function mergeKeycloakRealm(existing, derived) {
+	if (!isObject(existing)) throw new TypeError("le realm existant n'est pas un objet JSON");
+	const merged = { ...existing };
+	for (const [key, value] of Object.entries(derived)) if (!(key in merged)) merged[key] = value;
+	merged.realm = derived.realm ?? merged.realm ?? null;
+	for (const key of [
+		"loginTheme",
+		"accountTheme",
+		"emailTheme",
+		"adminTheme"
+	]) {
+		const theme = derived[key];
+		if (theme !== void 0) merged[key] = theme;
+	}
+	const derivedClients = objects(derived.clients);
+	const existingClients = objects(existing.clients);
+	const browserId = derivedClients[0]?.clientId;
+	const clients = existingClients.map((client) => {
+		const match = derivedClients.find((d) => d.clientId === client.clientId);
+		if (match === void 0) return client;
+		return mergeClient(client, match, match.clientId !== browserId);
+	});
+	for (const client of derivedClients) if (!existingClients.some((c) => c.clientId === client.clientId)) clients.push(client);
+	merged.clients = clients;
+	if (isObject(derived.roles)) {
+		const roles = isObject(existing.roles) ? { ...existing.roles } : {};
+		if (derived.roles.realm !== void 0) roles.realm = mergeRoles(roles.realm, derived.roles.realm);
+		if (isObject(derived.roles.client)) {
+			const byClient = isObject(roles.client) ? { ...roles.client } : {};
+			for (const [clientId, list] of Object.entries(derived.roles.client)) byClient[clientId] = mergeRoles(byClient[clientId], list);
+			roles.client = byClient;
+		}
+		merged.roles = roles;
+	}
+	return merged;
+}
+/** Largeur au-delà de laquelle un tableau se déplie (celle de prettier). */
+const PRINT_WIDTH = 80;
+function renderValue(value, indent, lead) {
+	if (value === null || typeof value !== "object") return JSON.stringify(value);
+	const inner = `${indent}  `;
+	if (Array.isArray(value)) {
+		if (value.length === 0) return "[]";
+		if (value.every((v) => v === null || typeof v !== "object")) {
+			const flat = `[${value.map((v) => JSON.stringify(v)).join(", ")}]`;
+			if (lead + flat.length + 1 <= PRINT_WIDTH) return flat;
+		}
+		return `[\n${value.map((v) => `${inner}${renderValue(v, inner, inner.length)}`).join(",\n")}\n${indent}]`;
+	}
+	const entries = Object.entries(value);
+	if (entries.length === 0) return "{}";
+	return `{\n${entries.map(([key, v]) => {
+		const head = `${inner}${JSON.stringify(key)}: `;
+		return `${head}${renderValue(v, inner, head.length)}`;
+	}).join(",\n")}\n${indent}}`;
+}
+/**
+* Sérialise un realm comme le dépôt l'écrit : deux espaces, tableaux de
+* valeurs simples sur une ligne quand ils tiennent en 80 colonnes, fin de
+* ligne — la forme que prettier donne au fichier versionné.
+*
+* @param realm - le realm à écrire
+* @returns le texte du fichier d'import
+*/
+function renderKeycloakRealm(realm) {
+	return `${renderValue(realm, "", 0)}\n`;
+}
+//#endregion
+export { buildKeycloakRealm, keycloakDefaultRole, mergeKeycloakRealm, renderKeycloakRealm };

package/dist/nodefony/keycloak/keycloakRealmInput.js

@@ -0,0 +1,124 @@
+import { KEYCLOAK_THEME_NAME } from "./scaffold.js";
+import { DEFAULT_LOGIN_PAGE_SKIN } from "nodefony";
+//#region nodefony/keycloak/keycloakRealmInput.ts
+/** Erreur de dérivation : la config ne permet pas d'écrire un realm. */
+var KeycloakRealmError = class extends Error {
+	name = "KeycloakRealmError";
+};
+/**
+* Le nom du realm, lu dans l'émetteur (`https://kc.example/realms/<nom>`).
+*
+* @throws {KeycloakRealmError} Si l'émetteur n'a pas la forme Keycloak
+*/
+function realmNameFromIssuer(issuer) {
+	if (issuer === void 0) throw new KeycloakRealmError("le fournisseur n'a pas d'`issuer` : c'est l'adresse du realm (https://…/realms/<nom>)");
+	let pathname;
+	try {
+		pathname = new URL(issuer).pathname;
+	} catch {
+		throw new KeycloakRealmError(`issuer « ${issuer} » n'est pas une URL`);
+	}
+	const match = /\/realms\/([^/]+)\/?$/u.exec(pathname);
+	if (match?.[1] === void 0) throw new KeycloakRealmError(`issuer « ${issuer} » ne finit pas par /realms/<nom> : ce n'est pas l'adresse d'un realm Keycloak`);
+	return decodeURIComponent(match[1]);
+}
+/** Les ressources de toutes les zones qui acceptent des jetons tiers. */
+function externalJwtResources(config) {
+	const resources = [];
+	for (const area of Object.values(config.areas)) {
+		if (!area.authenticators.includes("external-jwt")) continue;
+		if (area.resource !== void 0 && !resources.includes(area.resource)) resources.push(area.resource);
+	}
+	return resources;
+}
+/** Le chemin du callback, réécrit en celui de la déconnexion par canal arrière. */
+function backchannelPath(callbackPath) {
+	return callbackPath.replace(/\/callback\/?$/u, "/backchannel-logout");
+}
+/**
+* Dérive, depuis la configuration EFFECTIVE de l'application, ce que son realm
+* Keycloak doit dire.
+*
+* - **Client** : `clientId`, et son secret hors production.
+* - **URL de retour** : `redirectUri` du fournisseur, plus — hors production —
+*   le même chemin sur chaque serveur local (http ET https), parce que
+*   l'application répond sur les deux et que Keycloak compare au caractère près.
+* - **Audience** : `audiences` du fournisseur, sinon la `resource` de chaque
+*   zone `external-jwt`. Une audience qu'aucune zone ne porte est DITE : le
+*   jeton serait refusé partout.
+* - **Rôles** : les clés de `roleMapping`, rangées selon `rolesSource`.
+*
+* @param ctx - la configuration et le décor de l'application
+* @returns l'entrée du constructeur de realm et les constats
+* @throws {KeycloakRealmError} Si le fournisseur est absent ou sans émetteur
+*/
+/**
+* Le thème Keycloak de connexion qui porte un habillage de la page `/login`.
+*
+* @param skin - habillage (`loginPage.skin`)
+* @returns `nodefony` pour l'habillage par défaut, `nodefony-<habillage>` sinon
+*   (thème enfant livré sous `keycloak/themes/`)
+*/
+function keycloakLoginTheme(skin) {
+	return skin === DEFAULT_LOGIN_PAGE_SKIN ? KEYCLOAK_THEME_NAME : `${KEYCLOAK_THEME_NAME}-${skin}`;
+}
+/**
+* Dit si un thème Keycloak est l'un de ceux que livre Nodefony.
+*
+* @param theme - nom du thème
+* @returns `true` pour `nodefony` et `nodefony-<habillage>`
+*/
+function isNodefonyKeycloakTheme(theme) {
+	return theme === "nodefony" || theme.startsWith(`nodefony-`);
+}
+function deriveKeycloakRealmInput(ctx) {
+	const provider = ctx.config.oauth2.providers[ctx.providerName];
+	if (provider === void 0) {
+		const known = Object.keys(ctx.config.oauth2.providers);
+		throw new KeycloakRealmError(`aucun fournisseur « ${ctx.providerName} » dans oauth2.providers` + (known.length > 0 ? ` (déclarés : ${known.join(", ")})` : " — il n'est monté que si ses variables NF_KEYCLOAK_* sont posées"));
+	}
+	const warnings = [];
+	const realm = realmNameFromIssuer(provider.issuer);
+	const callback = new URL(provider.redirectUri);
+	const origins = [];
+	if (!ctx.production) {
+		const host = callback.hostname;
+		if (ctx.servers.httpsPort !== null) origins.push(`https://${host}:${ctx.servers.httpsPort}`);
+		if (ctx.servers.httpPort !== null) origins.push(`http://${host}:${ctx.servers.httpPort}`);
+	}
+	if (!origins.includes(callback.origin)) origins.unshift(callback.origin);
+	const redirectUris = origins.map((o) => `${o}${callback.pathname}`);
+	const backOrigin = ctx.backchannelOrigin ?? (ctx.production || ctx.servers.httpPort === null ? callback.origin : `http://host.docker.internal:${ctx.servers.httpPort}`);
+	const resources = externalJwtResources(ctx.config);
+	const audiences = provider.audiences ?? resources;
+	for (const audience of audiences) if (!resources.includes(audience)) warnings.push(`audience « ${audience} » : aucune zone external-jwt ne porte cette resource — un jeton qui la porte est refusé partout`);
+	if (provider.audiences === void 0 && resources.length > 1) warnings.push(`${resources.length} zones external-jwt, audiences déduites de TOUTES — écrire oauth2.providers.${ctx.providerName}.audiences si l'une doit refuser ses jetons`);
+	const sources = provider.rolesSource ?? ["client"];
+	const roles = Object.entries(provider.roleMapping ?? {}).map(([name, to]) => ({
+		name,
+		description: `Traduit en ${to} par la table roleMapping du fournisseur ${ctx.providerName}.`
+	}));
+	if (sources.includes("groups") && roles.length > 0) warnings.push("rolesSource « groups » : les groupes et leur mapper se déclarent dans la console Keycloak, ce realm ne les écrit pas");
+	const skin = ctx.config.loginPage.skin;
+	const current = ctx.currentLoginTheme ?? null;
+	const loginTheme = current !== null && isNodefonyKeycloakTheme(current) ? keycloakLoginTheme(skin) : null;
+	if (loginTheme === null && skin !== DEFAULT_LOGIN_PAGE_SKIN) warnings.push(`loginPage.skin « ${skin} » non appliqué à Keycloak : le realm ` + (current === null ? "ne déclare aucun thème de connexion" : `utilise le thème « ${current} », qui n'est pas un thème Nodefony`) + ` — poser loginTheme « ${keycloakLoginTheme(skin)} » à la main si c'est voulu`);
+	return {
+		input: {
+			realm,
+			clientId: provider.clientId,
+			clientSecret: ctx.production ? null : provider.clientSecret,
+			redirectUris,
+			postLogoutRedirectUris: origins.map((o) => `${o}/*`),
+			backchannelLogoutUrl: `${backOrigin}${backchannelPath(callback.pathname)}`,
+			audiences,
+			clientRoles: sources.includes("client") ? roles : [],
+			realmRoles: sources.includes("realm") ? roles : [],
+			machine: ctx.machine,
+			...loginTheme === null ? {} : { themes: { login: loginTheme } }
+		},
+		warnings
+	};
+}
+//#endregion
+export { KeycloakRealmError, deriveKeycloakRealmInput, isNodefonyKeycloakTheme, keycloakLoginTheme, realmNameFromIssuer };

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";
+//#region 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)) {
+			if (JSON.parse(readFileSync(manifest, "utf8")).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);
+}
+//#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 };