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

package/dist/nodefony/src/authenticator/UserPasswordAuthenticator.js

@@ -1,7 +1,7 @@
 import { AuthenticationError } from "../../errors/AuthenticationError.js";
 import { ThrottledError } from "../../errors/ThrottledError.js";
 import { UserToken } from "../token/UserToken.js";
-//#region nodefony/src/authenticator/UserPasswordAuthenticator.ts
+// nodefony/src/authenticator/UserPasswordAuthenticator.ts
 const BASIC_SCHEME = /^basic\s+/i;
 const INVALID_CREDENTIALS = "Invalid credentials";
 /**
@@ -24,22 +24,32 @@ var UserPasswordAuthenticator = class {
 	#verifier = null;
 	#resolveVerifier;
 	#throttler;
+	#transport;
 	/**
 	* @param resolveVerifier - résolution lazy de la source de vérification
 	*   (typiquement `container.get("users")`) — appelée au premier login.
 	* @param throttler - limiteur de tentatives (backoff NIST), `null` = désactivé.
+	* @param transport - politique du transport des secrets, `null` = aucune.
 	*/
-	constructor(resolveVerifier, throttler = null) {
+	constructor(resolveVerifier, throttler = null, transport = null) {
 		this.#resolveVerifier = resolveVerifier;
 		this.#throttler = throttler;
+		this.#transport = transport;
 	}
 	/** La requête porte-t-elle un en-tête `Authorization: Basic ...` ? */
 	supports(context) {
 		const auth = context.request?.headers.authorization;
 		return typeof auth === "string" && BASIC_SCHEME.test(auth);
 	}
-	/** Décode l'enveloppe Basic — un contenu malformé donne un credential vide (échec uniforme). */
+	/**
+	* Décode l'enveloppe Basic — un contenu malformé donne un credential vide
+	* (échec uniforme).
+	*
+	* @throws InsecureTransportError (403) — en production, en-tête reçu hors
+	*   TLS : refusé avant même d'être décodé.
+	*/
 	createToken(context) {
+		this.#transport?.assert(context, "basic");
 		const auth = context.request?.headers.authorization;
 		const decoded = Buffer.from(auth.replace(BASIC_SCHEME, ""), "base64").toString("utf8");
 		const sep = decoded.indexOf(":");
@@ -86,10 +96,9 @@ var UserPasswordAuthenticator = class {
 	onFailure(_context, _error) {
 		return Promise.resolve();
 	}
-	/** Challenge RFC 7235 posé par le firewall sur les 401 de la zone. */
+	/** Challenge RFC 9110 §11 posé par le firewall sur les 401 de la zone. */
 	challenge() {
 		return "Basic realm=\"nodefony\", charset=\"UTF-8\"";
 	}
 };
-//#endregion
 export { UserPasswordAuthenticator, UserPasswordAuthenticator as default };

package/dist/nodefony/src/authenticator/authenticatorRegistry.js

@@ -3,9 +3,10 @@ import { SessionAuthenticator } from "./SessionAuthenticator.js";
 import { UserPasswordAuthenticator } from "./UserPasswordAuthenticator.js";
 import { JwtAuthenticator } from "./JwtAuthenticator.js";
 import { ApiKeyAuthenticator } from "./ApiKeyAuthenticator.js";
+import { externalSubjectOptions } from "./ExternalSubjectResolver.js";
 import { ExternalJwtAuthenticator } from "./ExternalJwtAuthenticator.js";
 import { resolveJwtRuntime } from "../token/jwtRuntime.js";
-//#region nodefony/src/authenticator/authenticatorRegistry.ts
+// nodefony/src/authenticator/authenticatorRegistry.ts
 const factories = /* @__PURE__ */ new Map();
 /**
 * Enregistre (ou remplace) la fabrique d'un authenticator. Appelé par les
@@ -26,11 +27,12 @@ function listAuthenticatorFactories() {
 registerAuthenticatorFactory("anonymous", () => new AnonymousAuthenticator());
 registerAuthenticatorFactory("userpassword", ({ container }) => {
 	const throttler = container.get("loginThrottler") ?? null;
+	const transport = container.get("credentialTransport") ?? null;
 	return new UserPasswordAuthenticator(() => {
 		const verifier = container.get("users");
 		if (!verifier) throw new Error("UserPasswordAuthenticator: aucun service \"users\" (IPasswordVerifier) dans le container — enregistrer un UserService au boot de l'application.");
 		return verifier;
-	}, throttler);
+	}, throttler, transport);
 });
 registerAuthenticatorFactory("session", ({ container }) => {
 	return new SessionAuthenticator(() => {
@@ -43,15 +45,7 @@ registerAuthenticatorFactory("jwt", ({ container, config }) => {
 	return new JwtAuthenticator(container, resolveJwtRuntime(config.jwt));
 });
 registerAuthenticatorFactory("external-jwt", ({ container, config }) => {
-	const rs = config.resourceServer;
-	return new ExternalJwtAuthenticator(container, {
-		issuers: rs.issuers.map((i) => ({
-			issuer: i.issuer,
-			subjectMapping: i.subjectMapping
-		})),
-		subjectPolicy: rs.subjectPolicy,
-		ephemeralRoles: rs.ephemeralRoles
-	});
+	return new ExternalJwtAuthenticator(container, externalSubjectOptions(config));
 });
 registerAuthenticatorFactory("apikey", ({ container, config }) => {
 	return new ApiKeyAuthenticator(container, {
@@ -59,5 +53,4 @@ registerAuthenticatorFactory("apikey", ({ container, config }) => {
 		lastUsedThrottleS: config.apiKeys.lastUsedThrottleS
 	});
 });
-//#endregion
 export { getAuthenticatorFactory, listAuthenticatorFactories, registerAuthenticatorFactory };

package/dist/nodefony/src/authenticator/bearer.js

@@ -1,2 +1 @@
-import { bearerToken } from "nodefony";
-export { bearerToken };
+export { bearerToken } from "nodefony";

package/dist/nodefony/src/authenticator/externalSubject.js

@@ -1,4 +1,4 @@
-//#region nodefony/src/authenticator/externalSubject.ts
+// nodefony/src/authenticator/externalSubject.ts
 /**
 * Séparateur entre l'émetteur et le sujet.
 *
@@ -32,5 +32,4 @@ function localIdentifierFor(issuer, subject, mapping) {
 	if (mapping === "subject") return subject;
 	return `${issuer}${SEPARATOR}${subject}`;
 }
-//#endregion
 export { localIdentifierFor };

package/dist/nodefony/src/authenticator/peekIssuer.js

@@ -1,4 +1,4 @@
-//#region nodefony/src/authenticator/peekIssuer.ts
+// nodefony/src/authenticator/peekIssuer.ts
 /**
 * Lecture NON VÉRIFIÉE de l'émetteur d'un JWS compact.
 *
@@ -52,5 +52,4 @@ function peekIssuer(raw) {
 		return null;
 	}
 }
-//#endregion
 export { peekIssuer as default, peekIssuer };

package/dist/nodefony/src/boot/publicRoutesNotice.js

@@ -0,0 +1,26 @@
+import { isFrameworkZone } from "nodefony";
+// nodefony/src/boot/publicRoutesNotice.ts
+/**
+* Le point d'attention « routes métier publiques » du bilan de démarrage.
+*
+* Hors d'une zone du pare-feu, une requête n'est jamais authentifiée : son
+* identité n'est pas résolue, et une route métier qu'on croyait protégée
+* répond à n'importe qui. Les seules zones présentes sont alors les aires du
+* framework (`/nodefony/*`) ; on le DIT au démarrage, avec la recette.
+*
+* La classification « applicative ou framework » n'est pas recopiée : elle
+* vient du cœur (`isFrameworkZone`), qui l'applique aussi au tableau des zones.
+*
+* @param zones - zones montées (`firewall.describe().zones`).
+* @returns le point à déclarer, ou `null` si une zone applicative existe.
+*/
+function publicRoutesNotice(zones) {
+	if (zones.some((z) => !isFrameworkZone(z))) return null;
+	return {
+		code: "FIREWALL_PUBLIC_ROUTES",
+		level: "warning",
+		message: "Tes routes métier sont PUBLIQUES — aucune zone de pare-feu ne les couvre",
+		fix: "use(\"@nodefony/security\", { areas: { main: { pattern: \"^/api\", authenticators: [\"session\"] } } })"
+	};
+}
+export { publicRoutesNotice };

package/dist/nodefony/src/crypto/secretCipher.js

@@ -1,6 +1,6 @@
 import { createCipheriv, createDecipheriv, hkdfSync, randomBytes } from "node:crypto";
 import { Buffer } from "node:buffer";
-//#region nodefony/src/crypto/secretCipher.ts
+// nodefony/src/crypto/secretCipher.ts
 /**
 * Chiffrement **réversible** de secrets applicatifs au repos — AES-256-GCM
 * (authentifié). Brique générique partagée par tous les domaines qui doivent
@@ -75,5 +75,4 @@ function decryptSecret(blob, key) {
 	decipher.setAuthTag(tag);
 	return Buffer.concat([decipher.update(ct), decipher.final()]);
 }
-//#endregion
 export { decryptSecret, deriveKey, encryptSecret, generateEphemeralKey };

package/dist/nodefony/src/csp.js

@@ -1,4 +1,4 @@
-//#region nodefony/src/csp.ts
+// nodefony/src/csp.ts
 /**
 * Parse une chaîne CSP en directives ordonnées `[nom, sources[]]`. L'ordre des
 * directives et des sources est préservé (déterminisme : header stable, tests
@@ -49,5 +49,4 @@ function mergeCspFragments(base, fragments) {
 	}
 	return serializeCsp(directives);
 }
-//#endregion
 export { mergeCspFragments, parseCsp, serializeCsp };

package/dist/nodefony/src/csrfToken.js

@@ -1,5 +1,5 @@
 import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
-//#region nodefony/src/csrfToken.ts
+// nodefony/src/csrfToken.ts
 /**
 * Jeton synchronizer CSRF — modèle **double-submit signé** (OWASP CSRF Prevention
 * Cheat Sheet, « Signed Double-Submit Cookie »). Le token est
@@ -61,5 +61,4 @@ var CsrfTokenManager = class CsrfTokenManager {
 		return timingSafeEqual(ba, bb);
 	}
 };
-//#endregion
 export { CsrfTokenManager, CsrfTokenManager as default };

package/dist/nodefony/src/entryPoint.js

@@ -0,0 +1,38 @@
+import { loginPagePath, safeRedirectPath } from "nodefony";
+// nodefony/src/entryPoint.ts
+/**
+* Dit si une requête refusée est la NAVIGATION d'un navigateur — le seul cas
+* où conduire à la page de connexion aide, au lieu de casser un client.
+*
+* `GET` ou `HEAD`, `Accept` qui demande du HTML, et `Sec-Fetch-Mode: navigate`
+* quand l'en-tête est présent : un `fetch()` d'une page porte `cors` ou
+* `same-origin` même s'il accepte du HTML, et recevrait une page de connexion
+* à la place de ses données.
+*
+* @param request - la requête refusée
+* @returns `true` pour une navigation
+*/
+function isBrowserNavigation(request) {
+	const method = request.method?.toUpperCase();
+	if (method !== "GET" && method !== "HEAD") return false;
+	if (request.accept?.toLowerCase().includes("text/html") !== true) return false;
+	return request.fetchMode === void 0 || request.fetchMode.toLowerCase() === "navigate";
+}
+/**
+* L'adresse de la page de connexion pour un visiteur refusé :
+* `<entryPoint>?from=<chemin demandé>`, composée par `loginPagePath` (cœur).
+* Le chemin demandé repasse par `safeRedirectPath` — la seule garde
+* anti-redirection ouverte du framework, que la page de connexion appliquera
+* de nouveau au retour.
+*
+* @param entryPoint - chemin de la page de connexion (vérifié au boot)
+* @param request - la requête refusée
+* @returns l'adresse du `Location`, ou `null` quand ce n'est pas une
+*   navigation, ou quand la page demandée EST la page de connexion
+*/
+function entryPointLocation(entryPoint, request) {
+	if (!isBrowserNavigation(request)) return null;
+	if (request.path.split("?", 1)[0] === entryPoint.split("?", 1)[0]) return null;
+	return loginPagePath(safeRedirectPath(request.path), entryPoint);
+}
+export { entryPointLocation, isBrowserNavigation };

package/dist/nodefony/src/net/ssrfGuard.js

@@ -1,7 +1,7 @@
 import { SsrfError } from "../../errors/SsrfError.js";
 import { BlockList, isIP } from "node:net";
 import { lookup } from "node:dns/promises";
-//#region nodefony/src/net/ssrfGuard.ts
+// nodefony/src/net/ssrfGuard.ts
 /**
 * Protection **SSRF** (Server-Side Request Forgery) générique pour les URL
 * sortantes — endpoints webhook, fetch applicatif, futurs agents/RAG.
@@ -126,5 +126,4 @@ async function assertPublicUrl(rawUrl, options = {}) {
 		addresses
 	};
 }
-//#endregion
 export { assertPublicUrl, isBlockedAddress };

package/dist/nodefony/src/net/transportFailure.js

@@ -0,0 +1,57 @@
+// nodefony/src/net/transportFailure.ts
+/**
+* Codes TLS d'une chaîne de certificats qu'aucune autorité CONNUE ne signe.
+*
+* Leur remède est le même : faire reconnaître l'autorité. Un certificat expiré
+* (`CERT_HAS_EXPIRED`) ou émis pour un autre nom (`ERR_TLS_CERT_ALTNAME_INVALID`)
+* n'en fait pas partie : ajouter une autorité n'y changerait rien.
+*/
+const UNTRUSTED_AUTHORITY_CODES = /* @__PURE__ */ new Set([
+	"SELF_SIGNED_CERT_IN_CHAIN",
+	"DEPTH_ZERO_SELF_SIGNED_CERT",
+	"UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+	"UNABLE_TO_GET_ISSUER_CERT",
+	"UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
+	"CERT_UNTRUSTED"
+]);
+/** Le code porté par la `cause` d'un échec de `fetch`, s'il y en a un. */
+function causeCode(error) {
+	if (!(error instanceof Error)) return null;
+	const cause = error.cause;
+	if (!(cause instanceof Error)) return null;
+	const code = cause.code;
+	return typeof code === "string" ? code : null;
+}
+/**
+* Rend un échec de transport LISIBLE : `fetch` (undici) ne dit que
+* `fetch failed` et range la vraie raison dans `cause` — certificat refusé,
+* connexion refusée, nom introuvable.
+*
+* @param error - ce que `fetch` (ou une bibliothèque qui l'appelle) a levé
+* @returns `message (CODE : raison)`, ou le message seul faute de cause
+*/
+function describeTransportFailure(error) {
+	if (!(error instanceof Error)) return String(error);
+	const cause = error.cause;
+	if (!(cause instanceof Error)) return error.message;
+	const code = causeCode(error);
+	return code !== null ? `${error.message} (${code} : ${cause.message})` : `${error.message} (${cause.message})`;
+}
+/**
+* Le remède d'un certificat signé par une autorité que le processus ne
+* reconnaît pas — `null` pour tout autre échec.
+*
+* En développement, Nodefony reconnaît d'office l'autorité qu'il a générée ; en
+* production jamais, et c'est voulu. Sans ce remède, le journal ne montrait que
+* `SELF_SIGNED_CERT_IN_CHAIN` : la variable qui le règle n'était écrite que dans
+* un commentaire du `.env`, fichier qu'un serveur de production n'a pas.
+*
+* @param error - ce que `fetch` (ou une bibliothèque qui l'appelle) a levé
+* @returns une phrase d'action, ou `null`
+*/
+function untrustedAuthorityHint(error) {
+	const code = causeCode(error);
+	if (code === null || !UNTRUSTED_AUTHORITY_CODES.has(code)) return null;
+	return "le certificat de ce serveur est signé par une autorité que l'application ne reconnaît pas : déclare-la dans NF_TLS_CA_FILE (fichier PEM, `http.certificates.extraCaFiles`)";
+}
+export { describeTransportFailure, untrustedAuthorityHint };

package/dist/nodefony/src/oauth/clientCredentials.js

@@ -0,0 +1,39 @@
+import { postTokenRequest } from "./oauth2Client.js";
+import { discoverAuthorizationServer } from "./metadata.js";
+// nodefony/src/oauth/clientCredentials.ts
+/**
+* Obtient un jeton d'accès pour un programme, par le flux `client_credentials`
+* (RFC 6749 §4.4), auprès d'un émetteur découvert (RFC 8414).
+*
+* C'est la voie de l'appelant MACHINE : il s'authentifie avec son propre
+* secret, et le jeton rendu le désigne lui, pas un utilisateur. La même
+* authentification de client que l'échange de code ({@link postTokenRequest}) —
+* une seule implémentation, pour qu'aucune règle ne diverge d'un flux à l'autre.
+*
+* @param request - émetteur, identité du client, portées et ressource.
+* @returns Les jetons rendus ; `accessToken()` est celui à présenter en `Bearer`.
+* @throws Error - secret vide, émetteur invalide ou injoignable, métadonnées discordantes.
+* @throws OAuth2RequestError - le serveur a refusé (`invalid_client` : secret
+*   faux ; `unauthorized_client` : le client n'a pas droit à ce flux).
+*/
+async function requestClientCredentialsToken(request) {
+	if (request.clientSecret.length === 0) throw new Error(`client « ${request.clientId} » : secret vide — le flux client_credentials n'existe que pour un client confidentiel (RFC 6749 §4.4).`);
+	const server = await discoverAuthorizationServer(request.issuer, {
+		discoveryUrl: request.discoveryUrl,
+		...request.fetch ? { fetch: request.fetch } : {},
+		...request.timeoutMs !== void 0 ? { timeoutMs: request.timeoutMs } : {}
+	});
+	const body = new URLSearchParams();
+	body.set("grant_type", "client_credentials");
+	if (request.scopes !== void 0 && request.scopes.length > 0) body.set("scope", request.scopes.join(" "));
+	if (request.resource !== void 0) body.set("resource", request.resource);
+	return postTokenRequest({
+		tokenEndpoint: server.tokenEndpoint,
+		clientId: request.clientId,
+		clientSecret: request.clientSecret,
+		clientAuthMethod: request.clientAuthMethod ?? "client_secret_basic",
+		fetch: request.fetch,
+		timeoutMs: request.timeoutMs
+	}, body);
+}
+export { requestClientCredentialsToken };

package/dist/nodefony/src/oauth/httpJson.js

@@ -1,4 +1,5 @@
-//#region nodefony/src/oauth/httpJson.ts
+import { isPlainObject } from "nodefony";
+// nodefony/src/oauth/httpJson.ts
 /**
 * Lecture BORNÉE d'un corps JSON — la brique de transport commune aux trois
 * appels sortants du social login (découverte, point de jeton, API d'un
@@ -57,8 +58,7 @@ async function readJsonBounded(response, maxBytes, subject) {
 */
 async function readJsonObjectBounded(response, maxBytes, subject) {
 	const payload = await readJsonBounded(response, maxBytes, subject);
-	if (payload === null || typeof payload !== "object" || Array.isArray(payload)) throw new Error(`${subject} → corps inattendu (objet JSON attendu)`);
+	if (!isPlainObject(payload)) throw new Error(`${subject} → corps inattendu (objet JSON attendu)`);
 	return payload;
 }
-//#endregion
 export { readJsonBounded, readJsonObjectBounded };

package/dist/nodefony/src/oauth/metadata.js

@@ -1,6 +1,7 @@
+import { describeTransportFailure, untrustedAuthorityHint } from "../net/transportFailure.js";
 import { readJsonObjectBounded } from "./httpJson.js";
-import { canonicalIssuer, issuerMetadataUrls, validateIssuerMetadata } from "nodefony";
-//#region nodefony/src/oauth/metadata.ts
+import { canonicalIssuer, isBackChannelTransportAllowed, metadataCandidateUrls, validateIssuerMetadata } from "nodefony";
+// nodefony/src/oauth/metadata.ts
 /**
 * **Découverte des métadonnées d'un serveur d'autorisation** (RFC 8414) — la face
 * CLIENTE de la règle que le cœur porte déjà.
@@ -34,7 +35,7 @@ async function fetchMetadataDocument(url, options) {
 	if (!response.ok) throw new Error(`${url} → HTTP ${response.status}`);
 	return readJsonObjectBounded(response, MAX_METADATA_BYTES, url);
 }
-function requireEndpoint(document, field, issuer) {
+function requireEndpoint(document, field, issuer, backChannelOf) {
 	const value = document[field];
 	if (typeof value !== "string" || value.length === 0) throw new Error(`métadonnées de « ${issuer} » : champ « ${field} » absent (RFC 8414 §2).`);
 	let url;
@@ -43,10 +44,20 @@ function requireEndpoint(document, field, issuer) {
 	} catch {
 		throw new Error(`métadonnées de « ${issuer} » : « ${field} » n'est pas une URL.`);
 	}
-	if (url.protocol !== "https:") throw new Error(`métadonnées de « ${issuer} » : « ${field} » doit être en https.`);
+	if (!(backChannelOf === void 0 ? url.protocol === "https:" : isBackChannelTransportAllowed(url, backChannelOf))) throw new Error(`métadonnées de « ${issuer} » : « ${field} » doit être en https` + (backChannelOf === void 0 ? "." : ` (ou en http sur l'origine de discoveryUrl « ${backChannelOf} »).`));
 	return value;
 }
 /**
+* Point d'entrée FACULTATIF : absent ⇒ `null` ; présent, il obéit aux mêmes
+* règles qu'un point requis (URL https) — un serveur qui publie un point
+* malformé se signale à la découverte, pas au premier clic de l'utilisateur.
+*/
+function optionalEndpoint(document, field, issuer) {
+	const value = document[field];
+	if (value === void 0 || value === null) return null;
+	return requireEndpoint(document, field, issuer);
+}
+/**
 * Interroge un serveur d'autorisation et rend ses points d'entrée.
 *
 * Les URL candidates sont celles du cœur (`issuerMetadataUrls`, ordre normatif
@@ -56,33 +67,38 @@ function requireEndpoint(document, field, issuer) {
 * d'entrée — la même attaque que le paramètre `iss` couvre au retour (RFC 9207).
 *
 * @param rawIssuer - identifiant d'émetteur tel qu'écrit en configuration.
-* @param options - transport injectable et délai d'attente.
+* @param options - transport injectable, délai d'attente, adresse de découverte.
 * @returns Les points d'entrée, prêts pour `OAuth2Client`.
 * @throws Error - émetteur mal formé, document introuvable, incomplet, ou `issuer` discordant.
 */
 async function discoverAuthorizationServer(rawIssuer, options = {}) {
 	const issuer = canonicalIssuer(rawIssuer);
 	const failures = [];
-	for (const candidate of issuerMetadataUrls(issuer)) {
+	let hint = null;
+	const discoveryUrl = options.discoveryUrl;
+	for (const candidate of metadataCandidateUrls(issuer, discoveryUrl)) {
 		let document;
 		try {
 			document = await fetchMetadataDocument(candidate, options);
 		} catch (error) {
-			failures.push(error instanceof Error ? error.message : String(error));
+			failures.push(describeTransportFailure(error));
+			hint ??= untrustedAuthorityHint(error);
 			continue;
 		}
-		const identity = validateIssuerMetadata(document, issuer);
+		const identity = validateIssuerMetadata(document, issuer, discoveryUrl);
 		const methods = document.code_challenge_methods_supported;
+		const idTokenAlgs = document.id_token_signing_alg_values_supported;
 		return {
 			issuer: identity.issuer,
 			jwksUri: identity.jwksUri,
 			authorizationEndpoint: requireEndpoint(document, "authorization_endpoint", issuer),
-			tokenEndpoint: requireEndpoint(document, "token_endpoint", issuer),
+			tokenEndpoint: requireEndpoint(document, "token_endpoint", issuer, discoveryUrl),
 			codeChallengeMethodsSupported: Array.isArray(methods) ? methods.filter((m) => typeof m === "string") : null,
-			issParameterSupported: document.authorization_response_iss_parameter_supported === true
+			issParameterSupported: document.authorization_response_iss_parameter_supported === true,
+			endSessionEndpoint: optionalEndpoint(document, "end_session_endpoint", issuer),
+			idTokenSigningAlgValuesSupported: Array.isArray(idTokenAlgs) ? idTokenAlgs.filter((a) => typeof a === "string") : null
 		};
 	}
-	throw new Error(`métadonnées introuvables pour « ${issuer} » — ${failures.join(" ; ")}`);
+	throw new Error(`métadonnées introuvables pour « ${issuer} » — ${failures.join(" ; ")}` + (hint === null ? "" : ` — ${hint}`));
 }
-//#endregion
 export { discoverAuthorizationServer };

package/dist/nodefony/src/oauth/oauth2Client.js

@@ -1,6 +1,6 @@
 import { readJsonObjectBounded } from "./httpJson.js";
 import { createHash, randomBytes } from "node:crypto";
-//#region nodefony/src/oauth/oauth2Client.ts
+// nodefony/src/oauth/oauth2Client.ts
 /**
 * Client **OAuth 2.0 / Authorization Code** minimal — la face cliente du protocole
 * dont Nodefony écrit déjà la face serveur (émetteur de jetons, métadonnées,
@@ -79,11 +79,21 @@ var OAuth2RequestError = class extends Error {
 	code;
 	/** Description lisible fournie par le serveur, ou `null`. */
 	description;
-	constructor(code, description) {
+	/**
+	* Statut HTTP de la réponse, ou `null` s'il n'est pas connu.
+	*
+	* Le code `error` ne suffit pas toujours à dire QUI est refusé : la RFC 6749
+	* §5.2 réserve `401` à l'échec d'authentification du client, et Keycloak
+	* répond `unauthorized_client` en `401` sur un secret faux — le même code
+	* qu'en `400` pour un flux que le client n'a pas le droit d'employer.
+	*/
+	status;
+	constructor(code, description, status = null) {
 		super(description === null ? code : `${code}: ${description}`);
 		this.name = "OAuth2RequestError";
 		this.code = code;
 		this.description = description;
+		this.status = status;
 	}
 };
 /**
@@ -229,38 +239,54 @@ var OAuth2Client = class {
 		body.set("code", request.code);
 		body.set("redirect_uri", this.#options.redirectUri);
 		if (request.codeVerifier !== null) body.set("code_verifier", request.codeVerifier);
-		const headers = {
-			"Content-Type": "application/x-www-form-urlencoded",
-			Accept: "application/json",
-			"User-Agent": "nodefony"
-		};
-		switch (this.#options.clientAuthMethod) {
-			case "client_secret_basic":
-				headers.Authorization = `Basic ${this.#basicCredentials()}`;
-				break;
-			case "client_secret_post":
-				body.set("client_id", this.#options.clientId);
-				body.set("client_secret", this.#options.clientSecret);
-				break;
-			case "none": body.set("client_id", this.#options.clientId);
-		}
-		const response = await (this.#options.fetch ?? globalThis.fetch)(this.#options.tokenEndpoint, {
-			method: "POST",
-			headers,
-			body: body.toString(),
-			redirect: "error",
-			signal: AbortSignal.timeout(this.#options.timeoutMs ?? TOKEN_REQUEST_TIMEOUT_MS)
-		});
-		const data = await readJsonObjectBounded(response, MAX_TOKEN_RESPONSE_BYTES, `point de jeton (HTTP ${response.status})`);
-		if (typeof data.error === "string") throw new OAuth2RequestError(data.error, typeof data.error_description === "string" ? data.error_description : null);
-		if (!response.ok) throw new Error(`Point de jeton en échec (HTTP ${response.status}).`);
-		return new OAuth2Tokens(data);
-	}
-	#basicCredentials() {
-		const id = formUrlencode(this.#options.clientId);
-		const secret = formUrlencode(this.#options.clientSecret);
-		return Buffer.from(`${id}:${secret}`, "utf8").toString("base64");
+		return postTokenRequest(this.#options, body);
 	}
 };
-//#endregion
-export { OAuth2Client, OAuth2RequestError, OAuth2Tokens, createCodeChallenge, generateCodeVerifier, generateState };
+/**
+* Présente une requête au point de jeton et rend les jetons (RFC 6749 §5.1).
+*
+* SEULE implémentation de l'authentification du client et de la lecture de la
+* réponse : l'échange de code et le flux `client_credentials` y passent tous
+* deux, pour qu'une règle (méthode déclarée, redirection refusée, réponse
+* bornée, refus lu sur `error`) ne diverge jamais entre deux flux.
+*
+* @param client - point de jeton et identité du client.
+* @param body - corps de la requête, `grant_type` compris ; l'identité du
+*   client y est ajoutée selon la méthode déclarée.
+* @throws OAuth2RequestError - le serveur a refusé, en nommant la cause (RFC 6749 §5.2).
+* @throws Error - réponse inintelligible, hors gabarit, ou serveur injoignable.
+*/
+async function postTokenRequest(client, body) {
+	const headers = {
+		"Content-Type": "application/x-www-form-urlencoded",
+		Accept: "application/json",
+		"User-Agent": "nodefony"
+	};
+	switch (client.clientAuthMethod) {
+		case "client_secret_basic":
+			headers.Authorization = `Basic ${basicCredentials(client)}`;
+			break;
+		case "client_secret_post":
+			body.set("client_id", client.clientId);
+			body.set("client_secret", client.clientSecret);
+			break;
+		case "none": body.set("client_id", client.clientId);
+	}
+	const response = await (client.fetch ?? globalThis.fetch)(client.tokenEndpoint, {
+		method: "POST",
+		headers,
+		body: body.toString(),
+		redirect: "error",
+		signal: AbortSignal.timeout(client.timeoutMs ?? TOKEN_REQUEST_TIMEOUT_MS)
+	});
+	const data = await readJsonObjectBounded(response, MAX_TOKEN_RESPONSE_BYTES, `point de jeton (HTTP ${response.status})`);
+	if (typeof data.error === "string") throw new OAuth2RequestError(data.error, typeof data.error_description === "string" ? data.error_description : null, response.status);
+	if (!response.ok) throw new Error(`Point de jeton en échec (HTTP ${response.status}).`);
+	return new OAuth2Tokens(data);
+}
+function basicCredentials(client) {
+	const id = formUrlencode(client.clientId);
+	const secret = formUrlencode(client.clientSecret);
+	return Buffer.from(`${id}:${secret}`, "utf8").toString("base64");
+}
+export { OAuth2Client, OAuth2RequestError, OAuth2Tokens, createCodeChallenge, generateCodeVerifier, generateState, postTokenRequest };

package/dist/nodefony/src/oauth/oauthProviderRegistry.js

@@ -1,26 +1,58 @@
 import { createDiscoveredOidcProvider } from "./providers/oidc.js";
 import { createGithubProvider } from "./providers/github.js";
-//#region nodefony/src/oauth/oauthProviderRegistry.ts
+// nodefony/src/oauth/oauthProviderRegistry.ts
 const factories = /* @__PURE__ */ new Map();
 /**
 * Enregistre (ou remplace) la fabrique d'un fournisseur OAuth. Appelée par les
 * builtins au chargement, et par une application pour ses fournisseurs.
+*
+* @param name - nom sous lequel le fournisseur se configure (`oauth2.providers.<name>`).
+* @param factory - fabrique du fournisseur.
+* @param registration - exigences de configuration, vérifiées au démarrage.
 */
-function registerOAuthProvider(name, factory) {
-	factories.set(name, factory);
+function registerOAuthProvider(name, factory, registration = {}) {
+	factories.set(name, {
+		factory,
+		requiresIssuer: registration.requiresIssuer === true
+	});
 }
 /** Fabrique d'un fournisseur par nom, ou `undefined` si inconnu. */
 function getOAuthProviderFactory(name) {
-	return factories.get(name);
+	return factories.get(name)?.factory;
+}
+/** `true` si le fournisseur nommé a déclaré exiger un émetteur en configuration. */
+function oauthProviderRequiresIssuer(name) {
+	return factories.get(name)?.requiresIssuer === true;
 }
 /** Noms enregistrés (validation boot, introspection Studio, tests). */
 function listOAuthProviders() {
 	return [...factories.keys()];
 }
+/**
+* Paramètre d'autorisation que lit le thème Keycloak livré (`template.ftl`)
+* pour afficher l'écran dans le thème de l'application (`light` | `dark`).
+*/
+const KEYCLOAK_THEME_PARAMETER = "nf_theme";
+/**
+* Ajoute le thème demandé ({@link IAuthorizationRequest.theme}) à l'URL
+* d'autorisation d'un fournisseur Keycloak, sous {@link KEYCLOAK_THEME_PARAMETER}.
+*
+* @param provider - fournisseur OIDC découvert, inchangé pour tout le reste
+* @returns le même fournisseur, dont l'URL d'autorisation porte le thème
+*/
+function withKeycloakThemeHint(provider) {
+	return {
+		...provider,
+		createAuthorizationURL(request) {
+			const url = provider.createAuthorizationURL(request);
+			if (request.theme === "light" || request.theme === "dark") url.searchParams.set(KEYCLOAK_THEME_PARAMETER, request.theme);
+			return url;
+		}
+	};
+}
 const GOOGLE_ISSUER = "https://accounts.google.com";
 registerOAuthProvider("google", (ctx) => createDiscoveredOidcProvider("google", ctx, { issuer: GOOGLE_ISSUER }));
-registerOAuthProvider("keycloak", (ctx) => createDiscoveredOidcProvider("keycloak", ctx));
-registerOAuthProvider("oidc", (ctx) => createDiscoveredOidcProvider("oidc", ctx));
+registerOAuthProvider("keycloak", async (ctx) => withKeycloakThemeHint(await createDiscoveredOidcProvider("keycloak", ctx)), { requiresIssuer: true });
+registerOAuthProvider("oidc", (ctx) => createDiscoveredOidcProvider("oidc", ctx), { requiresIssuer: true });
 registerOAuthProvider("github", createGithubProvider);
-//#endregion
-export { getOAuthProviderFactory, listOAuthProviders, registerOAuthProvider };
+export { KEYCLOAK_THEME_PARAMETER, getOAuthProviderFactory, listOAuthProviders, oauthProviderRequiresIssuer, registerOAuthProvider, withKeycloakThemeHint };