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

package/dist/nodefony/service/keycloak.js

@@ -0,0 +1,208 @@
+import { readIfPresentSync } from "../src/token/secretFile.js";
+import { defineSecurityConfig } from "../config/defineModuleConfig.js";
+import { buildKeycloakRealm, mergeKeycloakRealm, renderKeycloakRealm } from "../keycloak/keycloakRealm.js";
+import { KeycloakRealmError, deriveKeycloakRealmInput, keycloakLoginTheme } from "../keycloak/keycloakRealmInput.js";
+import { KeycloakAdminClient, keycloakAdminTarget } from "../keycloak/keycloakAdmin.js";
+import { Service } from "nodefony";
+import path from "node:path";
+import { mkdirSync, readdirSync, writeFileSync } from "node:fs";
+// nodefony/service/keycloak.ts
+const serviceName = "keycloak";
+/** Où le compose d'une application importe ses realms (chemin natif). */
+const IMPORT_DIR = path.join("docker", "keycloak", "import");
+/**
+* Le fichier de realm par défaut : l'UNIQUE `.json` du dossier d'import, sinon
+* `realm.json` (le nom que `create app` écrit).
+*/
+function defaultRealmFile(root) {
+	const dir = path.join(root, IMPORT_DIR);
+	let json = [];
+	try {
+		json = readdirSync(dir).filter((f) => f.endsWith(".json"));
+	} catch {}
+	const only = json.length === 1 ? json[0] : void 0;
+	return path.join(dir, only ?? "realm.json");
+}
+/** Un objet indexable, sans rien affirmer de son contenu. */
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Un objet JSON de realm. Le contenu vient de `JSON.parse` : seules des
+* valeurs JSON peuvent s'y trouver, la garde ne vérifie donc que la forme.
+*/
+function isKeycloakObject(value) {
+	return isRecord(value);
+}
+/** Un port lu dans `servers.<nom>` de la config ; `null` si le serveur est coupé. */
+function portOf(servers, name, fallback) {
+	if (!isRecord(servers)) return fallback;
+	const server = servers[name];
+	if (server === false) return null;
+	if (!isRecord(server)) return fallback;
+	const port = Number(server.port);
+	return Number.isInteger(port) && port > 0 ? port : fallback;
+}
+/**
+* Le client machine à tenir à jour : celui qu'on nomme, sinon le compte de
+* service que le realm existant déclare déjà (flux `client_credentials` seul).
+*/
+function machineClient(existing, named) {
+	if (named !== void 0) return {
+		clientId: named,
+		secret: null
+	};
+	const clients = Array.isArray(existing?.clients) ? existing.clients : [];
+	for (const client of clients) {
+		if (typeof client !== "object" || client === null || Array.isArray(client)) continue;
+		if (client.serviceAccountsEnabled === true && client.standardFlowEnabled !== true) {
+			if (typeof client.clientId === "string") return {
+				clientId: client.clientId,
+				secret: null
+			};
+		}
+	}
+	return null;
+}
+/**
+* Service `keycloak` — toutes les actions de Nodefony sur un serveur Keycloak,
+* en un point du conteneur.
+*
+* - **le realm** que la configuration implique : dérivé, fusionné avec le
+*   fichier d'import existant, comparé, écrit ({@link realmPlan},
+*   {@link writeRealm}) ;
+* - **l'API d'administration** d'un realm vivant ({@link admin}), et ce qui s'y
+*   fait : le thème de connexion qui suit `loginPage.skin`
+*   ({@link applyLoginTheme}).
+*
+* Les commandes `security:keycloak:*` et les routes de développement
+* l'appellent ; elles ne gardent que l'affichage. Seule la contribution de
+* scaffold (`create app`, `scaffold:sync`) appelle les fonctions pures en
+* direct : elle tourne SANS démarrer l'application, donc sans conteneur.
+*
+* Rien n'est construit au démarrage : la configuration est lue à l'appel, et
+* les clients d'administration (un par fournisseur, jeton gardé) au premier
+* usage.
+*/
+var KeycloakService = class extends Service {
+	module;
+	#clients = null;
+	constructor(module) {
+		super(serviceName, module.container ?? void 0, module.notificationsCenter, module.options);
+		this.module = module;
+	}
+	/**
+	* La configuration de sécurité VALIDÉE, relue à chaque appel (chemin froid).
+	*
+	* @returns la configuration
+	*/
+	config() {
+		return defineSecurityConfig(this.options);
+	}
+	/**
+	* Le realm que la configuration implique, fusionné avec le fichier d'import.
+	*
+	* Le realm d'import répète ce que la config dit déjà (client, URL de retour,
+	* audiences, rôles de `roleMapping`) : écrit à la main, il diverge. Ce plan
+	* le DÉRIVE, puis le fusionne pour que ce qu'un humain a ajouté survive
+	* (comptes, titres, secret machine, mappers posés dans la console).
+	*
+	* @param request - fournisseur, fichier, client machine, canal arrière
+	* @returns le fichier, son contenu, le realm à écrire et les constats
+	* @throws {KeycloakRealmError} Fournisseur absent ou mal décrit, fichier qui
+	*   n'est pas un realm
+	*/
+	realmPlan(request = {}) {
+		const root = this.kernel?.path ?? process.cwd();
+		const file = request.file === void 0 ? defaultRealmFile(root) : path.resolve(root, request.file);
+		const current = readIfPresentSync(file);
+		let existing = null;
+		if (current !== null) {
+			const parsed = JSON.parse(current);
+			if (!isKeycloakObject(parsed)) throw new KeycloakRealmError(`${file} n'est pas un realm (objet JSON attendu)`);
+			existing = parsed;
+		}
+		const kernelOptions = this.kernel?.options;
+		const servers = isRecord(kernelOptions) ? kernelOptions.servers : void 0;
+		const appServers = {
+			httpPort: portOf(servers, "http", 5151),
+			httpsPort: portOf(servers, "https", 5152)
+		};
+		const derivation = deriveKeycloakRealmInput({
+			providerName: request.provider ?? "keycloak",
+			config: this.config(),
+			servers: appServers,
+			production: this.kernel?.environment === "production",
+			machine: machineClient(existing, request.machine),
+			currentLoginTheme: typeof existing?.loginTheme === "string" ? existing.loginTheme : null,
+			...request.backchannelOrigin === void 0 ? {} : { backchannelOrigin: request.backchannelOrigin }
+		});
+		const derived = buildKeycloakRealm(derivation.input);
+		const realm = existing === null ? derived : mergeKeycloakRealm(existing, derived);
+		const text = renderKeycloakRealm(realm);
+		return {
+			file,
+			current,
+			text,
+			warnings: derivation.warnings,
+			upToDate: current === text
+		};
+	}
+	/**
+	* Écrit le realm d'un plan — rien si le fichier est déjà à jour.
+	*
+	* ⚠️ Keycloak n'importe un realm qu'à sa CRÉATION : un realm déjà présent ne
+	* relit pas ce fichier ({@link applyLoginTheme} pour le thème, import
+	* partiel dans la console pour le reste).
+	*
+	* @param plan - le rendu de {@link realmPlan}
+	* @returns `true` si le fichier a été écrit
+	*/
+	writeRealm(plan) {
+		if (plan.upToDate) return false;
+		mkdirSync(path.dirname(plan.file), { recursive: true });
+		writeFileSync(plan.file, plan.text);
+		return true;
+	}
+	/**
+	* Le client de l'API d'administration d'un fournisseur Keycloak.
+	*
+	* @param providerName - nom dans `oauth2.providers` (défaut `keycloak`)
+	* @returns le client, construit au premier appel puis gardé (jeton réutilisé)
+	* @throws {KeycloakAdminError} Hors développement, fournisseur absent, sans
+	*   émetteur ou sans compte d'administration
+	*/
+	admin(providerName = "keycloak") {
+		const cached = this.#clients?.get(providerName);
+		if (cached !== void 0) return cached;
+		const client = new KeycloakAdminClient({
+			...keycloakAdminTarget(this.config(), providerName),
+			environment: this.kernel?.environment ?? "production"
+		});
+		this.#clients ??= /* @__PURE__ */ new Map();
+		this.#clients.set(providerName, client);
+		return client;
+	}
+	/**
+	* Le thème de connexion qu'un habillage demande à Keycloak.
+	*
+	* @param skin - habillage ; défaut : `loginPage.skin` de la configuration
+	* @returns `nodefony` ou `nodefony-<habillage>`
+	*/
+	expectedLoginTheme(skin) {
+		return keycloakLoginTheme(skin ?? this.config().loginPage.skin);
+	}
+	/**
+	* Pose sur le realm VIVANT le thème de connexion d'un habillage.
+	*
+	* @param options - fournisseur (défaut `keycloak`) et habillage (défaut :
+	*   `loginPage.skin` ; un aperçu de `/login` passe le sien)
+	* @returns le thème d'avant, celui demandé, et ce qui a été fait
+	* @throws {KeycloakAdminError} Hors développement, compte absent ou refusé,
+	*   Keycloak injoignable
+	*/
+	applyLoginTheme(options = {}) {
+		return this.admin(options.provider).applyLoginTheme(options.skin ?? this.config().loginPage.skin);
+	}
+};
+export { KeycloakService, KeycloakService as default };