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

package/dist/nodefony/config/config.js

@@ -1,3 +1,6 @@
+import { parseKeySet } from "../src/token/JwtKeystore.js";
+import { PLATFORM_ROLE_PREFIX, isPlatformRole } from "../src/oauth/providerRoles.js";
+import { DEFAULT_LOGIN_PAGE_SKIN, LOGIN_PAGE_LAYOUTS, LOGIN_PAGE_PATH, LOGIN_PAGE_SKINS, parseDiscoveryUrl, safeRedirectPath } from "nodefony";
 import { z } from "zod";
 //#region nodefony/config/config.ts
 /**
@@ -45,10 +48,18 @@ const areaSchema = z.strictObject({
 	mode: z.enum(["first", "all"]).default("first").describe("Chaîne d'authenticators : 'first' = le premier qui reconnaît la requête authentifie (ex. cookie OU bearer) ; 'all' = tous doivent passer (ex. mtls+jwt zone admin)."),
 	authenticators: z.array(z.string()).default([]).describe("Authenticators de la zone (sémantique selon `mode`). Validés au boot contre le registre."),
 	roles: z.array(z.string()).default([]).describe("Rôle(s) exigés PAR DÉFAUT dans la zone, en OU (l'un suffit ; hiérarchie comprise). Vide (défaut) = la zone n'exige qu'une identité, et toute route qu'elle couvre est ouverte à n'importe quel compte authentifié — c'est un défaut OUVERT, qu'une surface d'administration ne doit pas garder. Renseigné, le rôle s'applique à toute route de la zone qui ne décide PAS elle-même de son autorisation : une route gardée (`@IsGranted`, `@RequireScope`) et le pont du plan d'administration (qui résout un rôle par point d'entrée) gardent la main — sans quoi une zone fermée à l'administrateur écraserait un point d'entrée voulu accessible à son propriétaire (`me`, `sessions/mine`). Un refus ici est un 403 (authentifié, pas autorisé), jamais un 401."),
-	entryPoint: z.string().optional().describe("Route de login/redirect si non authentifié."),
+	entryPoint: z.string().refine((value) => safeRedirectPath(value, "") === value, { message: "entryPoint doit être un chemin de CETTE origine (`/login`), jamais une adresse externe" }).optional().describe("Page de connexion vers laquelle conduire un visiteur anonyme qui NAVIGUE (GET ou HEAD, `Accept: text/html`, `Sec-Fetch-Mode: navigate` s'il est présent) : 302 vers `<entryPoint>?from=<chemin demandé>`, et la page de connexion ramène au chemin demandé. Tout le reste — appel d'API, `fetch`, POST, WebSocket — garde son 401 et son `WWW-Authenticate`. Le refus reste journalisé (`auth.denied`). Absent (défaut) : 401 pour tous."),
 	host: z.string().optional().describe("Domaine/vhost de la zone (ex. admin.exemple.com). Omis = tous domaines."),
 	resource: z.string().optional().describe("URI canonique de la ressource protégée — l'AUDIENCE qu'un jeton doit porter pour être accepté ici (RFC 8707 §2). Obligatoire dès que la zone liste un authenticator de jetons TIERS (`external-jwt`), qui refuse de démarrer sans elle. C'est ce qui empêche un jeton valide, délivré au même porteur pour un AUTRE service, d'être rejoué sur celui-ci. Elle s'ÉCRIT et ne se dérive pas du `Host` : derrière un relais, ce que le processus croit être son adresse n'est pas ce que le client a demandé, et l'audience doit être exactement celle que le serveur d'autorisation a inscrite dans le jeton. Ex. « https://api.example.com/mcp »."),
-	realtime: z.boolean().default(true).describe("Zone valable AUSSI pour les frames WebSocket (api.request + subscribe), pas seulement HTTP. Défaut `true` (Zero Trust : une zone protégée ferme TOUS ses transports — un opt-IN laisserait le WS anonyme par omission = fail-open). `false` = opt-out explicite pour une zone strictement HTTP. Le verrou WS consulte la MÊME zone que HTTP — invariant : `api.request {path}` n'accorde jamais plus que `GET {path}`.")
+	realtime: z.boolean().default(true).describe("Zone valable AUSSI pour les frames WebSocket (api.request + subscribe), pas seulement HTTP. Défaut `true` (Zero Trust : une zone protégée ferme TOUS ses transports — un opt-IN laisserait le WS anonyme par omission = fail-open). `false` = opt-out explicite pour une zone strictement HTTP. Le verrou WS consulte la MÊME zone que HTTP — invariant : `api.request {path}` n'accorde jamais plus que `GET {path}`."),
+	subjectPolicy: z.enum(["require", "ephemeral"]).optional().describe("Surcharge, pour CETTE zone, de `resourceServer.subjectPolicy` — comment le sujet d'un jeton TIERS devient un utilisateur. Omis (défaut) = la politique globale. Sert à faire cohabiter une zone d'appelants machine (« ephemeral » : aucun compte local exigé) et une zone de personnes (« require ») dans la même application ; une politique globale ne sait pas l'exprimer. N'a de sens que si la zone liste `external-jwt` : déclarée ailleurs, le boot la refuse."),
+	ephemeralRoles: z.array(z.string().min(1)).optional().describe("Rôles accordés à l'appelant accepté par CETTE zone en mode « ephemeral ». Exige `subjectPolicy: \"ephemeral\"` écrit dans la zone même : un pouvoir local ne s'hérite pas d'un réglage écrit ailleurs. Une zone qui déclare « ephemeral » sans ses rôles n'en accorde AUCUN — jamais ceux de `resourceServer.ephemeralRoles`, qui protègent une autre surface.")
+}).refine((area) => area.subjectPolicy === void 0 || area.authenticators.includes("external-jwt"), {
+	message: "subjectPolicy ne s'applique qu'aux jetons tiers : la zone doit lister l'authenticator « external-jwt »",
+	path: ["subjectPolicy"]
+}).refine((area) => area.ephemeralRoles === void 0 || area.subjectPolicy === "ephemeral", {
+	message: "ephemeralRoles exige subjectPolicy: \"ephemeral\" écrit dans la MÊME zone — un pouvoir local ne s'hérite pas",
+	path: ["ephemeralRoles"]
 });
 const corsSchema = z.strictObject({
 	enabled: z.boolean().default(true).describe("Active la gestion CORS."),
@@ -152,7 +163,14 @@ const jwtSchema = z.strictObject({
 	audiences: z.array(z.string()).default([]).describe("Audiences acceptées à la vérification ET **demandables à l'émission** (claim `aud`, RFC 8707) — une liste BLANCHE de ressources, pas une simple valeur par défaut. Un client nomme sa cible par le paramètre `resource` du grant ; absente de cette liste, la demande est REFUSÉE (`invalid_target`, RFC 8707 §2) au lieu d'être servie avec l'audience par défaut — sans quoi tout porteur d'un identifiant valide obtiendrait un jeton pour la ressource de son choix. La PREMIÈRE entrée est l'audience par défaut (jeton demandé sans `resource`). Vide = l'audience de l'app (= `issuer`). Déclarer ici l'URI canonique d'une ressource protégée (porte MCP, API interne) est ce qui la rend joignable avec un jeton émis par cette application. La validation d'audience est OBLIGATOIRE côté resource (RFC 9700)."),
 	issuer: z.string().optional().describe("Émetteur (claim `iss`, RFC 7519). Omis = `\"nodefony\"` — suffisant tant que l'app émet ET vérifie ses propres jetons, mais PAS publiable (RFC 8414 §2 exige une URL https) : sans valeur explicite, aucune découverte n'est offerte. Ne se DEVINE pas — derrière un relais, `Host`/`X-Forwarded-*` viennent du client. STABLE : gravé dans chaque jeton déjà émis, le changer les invalide."),
 	keystore: z.strictObject({
-		keySetJson: z.string().optional().describe("JWK Set (clé(s) privée(s) Ed25519) injecté par l'app depuis son env — SECRET, jamais loggé. Présent = source `env` (prod cloud)."),
+		keySetJson: z.string().refine((json) => {
+			try {
+				parseKeySet(json);
+				return true;
+			} catch {
+				return false;
+			}
+		}, { message: "jeu de clés illisible — attendu le JSON produit par `npx nodefony security:secrets --jwt-keyset` ({ active, keys: [JWK privé avec kid] }), sur une ligne" }).optional().describe("JWK Set (clé(s) privée(s) Ed25519) PARTAGÉ par tous les process de l'app (pods, workers de cluster) — variable `NF_JWT_KEYSET` d'une application générée. SECRET, jamais loggé. Présent = source `env`, prioritaire sur `dir`."),
 		dir: z.string().optional().describe("Dossier de persistance `keyset.json` (chmod 600), généré si absent — opt-in dev/VPS. Sans `keySetJson` ni `dir` = clé ÉPHÉMÈRE en mémoire + warning (refresh non durables).")
 	}).default(() => ({})).describe("Source du matériel de signature JWT (priorité) : env (`keySetJson`) → fichier (`dir`) → mémoire+warn. SecretProvider (Vault/KMS) = P16.")
 }).describe("JWT — réservé API service↔service / agents (le web/navigateur utilise la session BFF).");
@@ -223,8 +241,17 @@ const remoteJwtAlgSchema = z.enum([
 	"EdDSA",
 	"Ed25519"
 ]);
+const discoveryUrlSchema = z.string().refine((value) => {
+	try {
+		parseDiscoveryUrl(value);
+		return true;
+	} catch {
+		return false;
+	}
+}, "adresse http(s) complète du document attendue, sans identifiants ni fragment").optional().describe("Adresse COMPLÈTE où lire le document de métadonnées, quand l'application ne joint pas l'émetteur par son adresse publique — en Kubernetes, le service interne : « http://keycloak.sso:8080/realms/app/.well-known/openid-configuration ». Seul le lieu de lecture change : le document doit toujours se déclarer de `issuer` (RFC 8414 §3.3), sinon refus. Les points appelés de serveur à serveur (jeton, clés) peuvent alors être en http sur l'origine exacte de cette adresse ; le point d'autorisation, où le navigateur est envoyé, reste en https. Keycloak publie ses points internes avec `--hostname-backchannel-dynamic=true`. Omis = découverte sur l'émetteur.");
 const trustedIssuerSchema = z.strictObject({
 	issuer: z.string().min(1).describe("Identifiant de l'émetteur (claim `iss`), en https, sans requête ni fragment (RFC 8414 §2) — ex. « https://auth.example.com/realms/mon-royaume ». C'est une ALLOWLIST : un jeton dont l'`iss` n'est pas ici est refusé avant toute requête sortante."),
+	discoveryUrl: discoveryUrlSchema,
 	jwksUri: z.string().optional().describe("Jeu de clés publiques de l'émetteur. Omis = découvert par les points bien connus RFC 8414/OpenID (3 URL essayées dans l'ordre normatif). Déclaré = aucune découverte (émetteur sans métadonnées, ou démarrage à froid sans requête)."),
 	algorithms: z.array(remoteJwtAlgSchema).min(1).default([
 		"RS256",
@@ -301,25 +328,71 @@ const studioSchema = z.strictObject({
 		description: "INERTE — l'audit des mutations admin est posé point par point par `SecurityAdminApi` (certaines mutations émettent, pas toutes) ; ce drapeau ne pilote aucune couverture globale."
 	})
 }).describe("Sécurité de la console Studio — durcissement exposition publique.");
+const loginPageSchema = z.strictObject({
+	enabled: z.boolean().default(true).describe("Sert la page de connexion par défaut. false = l'application sert la sienne au même chemin (`useNodefonyLogin`) : les redirections continuent d'y mener."),
+	path: z.string().default(LOGIN_PAGE_PATH).refine((p) => p.length > 0 && safeRedirectPath(p, "") === p && !/[?#]/.test(p), "chemin local attendu, sans requête ni fragment (`/login`)").describe("Chemin de la page de connexion. La redirection d'échec d'un fournisseur et le retour après déconnexion fédérée le suivent, sauf s'ils sont réglés."),
+	title: z.string().min(1).optional().describe("Titre de la page. Omis = titre par défaut."),
+	logo: z.string().min(1).optional().describe("Adresse du logo affiché (chemin servi par l'application ou URL). Omis = logo Nodefony."),
+	template: z.string().min(1).optional().describe("Chemin d'un gabarit `.eta` de l'application qui REMPLACE celui du framework. Dernier recours : `stylesheet` (variables `--nf-login-*`), `layout` et les textes (`heading`, `subtitle`, `hero`) suffisent à l'habillage, et survivent aux évolutions du balisage — un gabarit copié, non."),
+	stylesheet: z.string().min(1).optional().describe("Adresse d'une feuille de l'application chargée APRÈS celle du framework : elle redéfinit les variables `--nf-login-*` (couleurs, rayons, `--nf-login-hero-image` pour la photo du panneau). Chemin servi par l'application de préférence — une URL d'un autre site doit être autorisée par la CSP (`style-src`)."),
+	heading: z.string().min(1).optional().describe("Titre de la carte et de l'onglet. Omis = « Se connecter ». Le nom de l'application, lui, vient de `title`."),
+	subtitle: z.string().min(1).optional().describe("Ligne sous le titre. Omis = phrase déduite des moyens proposés (identifiant local, compte de l'organisation, ou les deux)."),
+	providersFirst: z.boolean().default(true).describe("Les boutons des fournisseurs passent AVANT le formulaire identifiant et mot de passe. false = le formulaire d'abord. Sans fournisseur proposé, sans effet."),
+	hero: z.union([z.literal(false), z.strictObject({
+		heading: z.string().min(1).describe("Accroche du panneau."),
+		text: z.string().min(1).optional().describe("Phrase sous l'accroche.")
+	})]).optional().describe("Panneau d'illustration de la mise en page `split`. Omis = vitrine Nodefony. `{ heading, text }` = votre texte à la place. false = la marque seule, sur l'image du panneau. L'image se règle dans `stylesheet` (`--nf-login-hero-image`), jamais ici."),
+	footer: z.boolean().default(true).describe("Pied de page : protections de la session (cookie HttpOnly, anti-CSRF, CSP) et mention « Propulsé par Nodefony ». false = retiré."),
+	password: z.boolean().default(true).describe("Propose le formulaire identifiant et mot de passe. false = connexion par fournisseur seulement (SSO)."),
+	skin: z.enum(LOGIN_PAGE_SKINS).default(DEFAULT_LOGIN_PAGE_SKIN).describe("Habillage : `frontispiece` (défaut), `ledger`, `horizon`, `console`, `blueprint`, `dots`, `minimal`, `enterprise`, `photo-card`. Une feuille du framework chargée avant `stylesheet` ; aucune ne fournit de photo — elle vient de `stylesheet` (`--nf-login-hero-image`). En développement, `?skin=` et `?layout=` en donnent un aperçu."),
+	layout: z.enum(LOGIN_PAGE_LAYOUTS).optional().describe("Mise en page : `split` (illustration et formulaire côte à côte), `card` (panneau centré), `bare` (formulaire seul). Omis = celle pour laquelle l'habillage est dessiné."),
+	previewPicker: z.boolean().default(false).describe("En DÉVELOPPEMENT seulement : un sélecteur d'habillage et de mise en page sur la page, qui recharge avec `?skin=` et `?layout=`. Sans effet en production, où ces paramètres sont ignorés. Pour choisir son habillage à l'écran, pas pour le livrer."),
+	previewHook: z.string().regex(/^\/(?![/\\])/u, "chemin de l'application attendu (« /… »), jamais une autre origine").optional().describe("Avec `previewPicker`, en DÉVELOPPEMENT : chemin de l'application appelé en POST (`{ skin, layout }`, même origine) AVANT chaque rechargement de l'aperçu. Pour qu'un tiers suive l'habillage choisi — le thème d'un Keycloak de développement (`applyKeycloakLoginTheme`). Un échec n'empêche pas le rechargement.")
+}).describe("Page de connexion servie par le framework, sans front (ADR-0015).");
 const oauthProviderSchema = z.strictObject({
 	clientId: z.string().min(1).describe("Identifiant client OAuth délivré par le fournisseur."),
 	clientSecret: z.string().min(1).describe("Secret client OAuth — SECRET, fourni par env, jamais loggé."),
 	clientAuthMethod: z.enum(["client_secret_basic", "client_secret_post"]).optional().describe("Comment le client s'authentifie au point de jeton (RFC 6749 §2.3). OMIS = `client_secret_basic`, ce que la RFC demande de préférer et ce que la plupart des serveurs annoncent par défaut. Poser `client_secret_post` quand le serveur l'EXIGE — il le publie dans ses métadonnées (`token_endpoint_auth_methods_supported`). La méthode `none` (client public) n'est pas offerte ici : ce schéma exige un secret non vide."),
 	redirectUri: z.string().min(1).describe("URL de callback EXACTE (RFC 9700 : exact string matching) enregistrée chez le fournisseur — doit pointer sur .../oauth2/<provider>/callback."),
 	issuer: z.string().optional().describe("Émetteur OIDC self-hosted (Keycloak : URL du realm, ex. https://kc.example/realms/app). REQUIS pour keycloak ; ignoré par les fournisseurs à endpoints fixes (Google/GitHub)."),
+	discoveryUrl: discoveryUrlSchema,
 	scopes: z.array(z.string()).default([]).describe("Scopes demandés. Vide = défauts du fournisseur (Google: openid/profile/email ; GitHub: read:user/user:email)."),
 	successRedirect: z.string().optional().describe("Redirection succès — surcharge le global pour CE fournisseur."),
 	failureRedirect: z.string().optional().describe("Redirection échec — surcharge le global pour CE fournisseur."),
+	postLogoutRedirectUri: z.url().optional().describe("Adresse ABSOLUE où le fournisseur renvoie le navigateur après la déconnexion (`post_logout_redirect_uri`, OpenID Connect RP-Initiated Logout) — doit être enregistrée chez lui. OMIS = l'écran d'échec (`failureRedirect`, la page de connexion) résolu contre `redirectUri`. Sans effet pour un fournisseur qui ne publie pas de point de déconnexion."),
 	defaultRoles: z.array(z.string()).optional().describe("Rôles du Shadow User à la création — surcharge le global pour CE fournisseur."),
+	roleMapping: z.record(z.string().min(1), z.string().min(1)).optional().describe("Rôles du FOURNISSEUR traduits en rôles de l'application, recalculés à chaque connexion ET à chaque jeton présenté à l'API : `{ \"app-admin\": \"ROLE_ADMIN\" }`. Un rôle du fournisseur absent de la table est ignoré, jamais recopié. Les rôles donnés à la main sont conservés. OMIS = les rôles restent entièrement locaux (posés à la création, puis la base fait foi). Un rôle `ROLE_NODEFONY_*` refuse le démarrage, sauf `allowPlatformRoles`."),
+	audiences: z.array(z.string().min(1)).optional().describe("Ressources pour lesquelles CE fournisseur émet des jetons à l'application — la mention « valable pour » (`aud`) qu'il doit imprimer. Chaque entrée est la `resource` d'une zone `external-jwt`. Lue par `security:keycloak:realm`, qui en écrit les mappers d'audience ; sans effet sur la vérification, que la `resource` de la zone porte seule. OMIS = la `resource` de TOUTES les zones `external-jwt`. À écrire dès qu'une zone existe pour REFUSER les jetons de ce fournisseur : la déduire ferait imprimer son adresse."),
+	allowPlatformRoles: z.boolean().default(false).describe("Autorise `roleMapping` à accorder des rôles de PLATEFORME (`ROLE_NODEFONY_*` : console d'administration, génération de code, secrets). OMIS = refusé au démarrage. L'ouvrir fait de l'administrateur de l'annuaire un administrateur de l'instance, et d'un annuaire compromis une prise de contrôle complète — un avertissement le rappelle à chaque démarrage."),
+	rolesSource: z.array(z.enum([
+		"client",
+		"realm",
+		"groups"
+	])).min(1).optional().describe("Où lire les rôles du fournisseur pour `roleMapping`. `client` (défaut) : les rôles du client de CETTE application (`resource_access.<clientId>.roles`, Keycloak). `realm` : les rôles du realm (`realm_access.roles`). `groups` : le claim `groups` (mapper de groupes à poser chez le fournisseur). Sans `roleMapping`, sans effet."),
 	label: z.string().min(1).optional().describe("Libellé du bouton sur l'écran de connexion. OMIS = dérivé du nom du fournisseur (`keycloak` → « Keycloak », `oidc` → « OIDC », `mon-idp` → « Mon Idp »). À poser quand la marque ne se devine pas du nom de la clé (« Connexion agent », « Annuaire interne »)."),
+	icon: z.string().min(1).optional().describe("Image du bouton sur l'écran de connexion (chemin servi par l'application, ou URL autorisée par la CSP `img-src`). OMIS = icône du framework : la marque pour `github`, une clé sinon."),
+	admin: z.strictObject({
+		username: z.string().min(1).describe("Identifiant administrateur."),
+		password: z.string().min(1).describe("Mot de passe administrateur — SECRET, jamais loggé.")
+	}).optional().describe("DÉVELOPPEMENT seulement — compte d'administration du serveur Keycloak (realm `master`). Sert à poser le thème de connexion qui suit `loginPage.skin` sur un realm EXISTANT (`security:keycloak:realm --apply`, aperçu de `/login`), ce que le fichier d'import ne fait pas. Refusé hors développement : ne le passer qu'en `ctx.isDev`."),
 	hidden: z.boolean().default(false).describe("Retire le bouton de l'écran de connexion SANS désactiver le fournisseur : le flux `/authorize` reste ouvert et fonctionnel. C'est la seule différence avec le fait de ne pas le configurer. Deux usages : une FIXTURE de développement qui pointe vers un serveur fictif (bouton mort), et un fournisseur réservé à un point d'entrée particulier (lien direct, sous-domaine) plutôt qu'offert à tout visiteur.")
+}).superRefine((provider, ctx) => {
+	if (provider.allowPlatformRoles) return;
+	for (const [from, to] of Object.entries(provider.roleMapping ?? {})) {
+		if (!isPlatformRole(to)) continue;
+		ctx.addIssue({
+			code: "custom",
+			path: ["roleMapping", from],
+			message: `« ${to} » est un rôle de PLATEFORME (${PLATFORM_ROLE_PREFIX}*) : un annuaire externe ne l'accorde pas sans \`allowPlatformRoles: true\` écrit sur ce fournisseur. Sinon, le donner à la main (\`security:user:add --admin\`, console d'administration) — il survit alors à chaque connexion.`
+		});
+	}
 }).describe("Fournisseur OAuth/OIDC (secrets via env).");
 const oauth2Schema = z.strictObject({
 	enabled: z.boolean().default(true).describe("Active le social login (les routes ne montent que si ≥1 provider)."),
-	defaultRoles: z.array(z.string()).default(["ROLE_USER"]).describe("Rôles du Shadow User à la CRÉATION uniquement (OAuth = authentification, pas autorisation : les rôles ne sont jamais réécrits ensuite, la base fait foi)."),
+	defaultRoles: z.array(z.string()).default(["ROLE_USER"]).describe("Rôles du Shadow User à la CRÉATION uniquement. Les rôles ne sont jamais réécrits ensuite, la base fait foi — sauf ceux qu'un fournisseur gère par sa `roleMapping`."),
 	allowSignup: z.boolean().default(true).describe("true = crée une ligne locale au 1er login (JIT, Shadow User). false = un compte préexistant lié est requis (fail-closed)."),
 	successRedirect: z.string().default("/").describe("Redirection après login réussi."),
-	failureRedirect: z.string().default("/login").describe("Redirection après échec (state invalide, refus utilisateur...)."),
+	failureRedirect: z.string().optional().describe("Redirection après échec (state invalide, refus utilisateur...). Omis = la page de connexion (`loginPage.path`)."),
 	providers: z.record(z.string(), oauthProviderSchema).default({}).describe("Fournisseurs activés par nom (doit correspondre au registre : builtins google/keycloak/oidc/github ; tout autre serveur OpenID Connect en enregistrant une fabrique, décrit par son seul émetteur).")
 }).describe("Social login OAuth 2.0 — Authorization Code + PKCE, session BFF.");
 /**
@@ -352,6 +425,8 @@ const securityConfigSchema = z.strictObject({
 		description: "RÉSERVÉ — Token Exchange RFC 8693 (délégation agents/MCP). Slot P12, aucun champ encore lu par le runtime."
 	}),
 	oauth2: oauth2Schema.default(() => oauth2Schema.parse({})),
+	loginPage: loginPageSchema.default(() => loginPageSchema.parse({})),
+	allowInsecureCredentials: z.boolean().default(false).describe("Laisse passer, en production, un mot de passe ou un code de second facteur reçu en clair (HTTP). false (défaut) : refus 403 AVANT toute vérification, sur toutes les portes — formulaire de session, second facteur, Basic, émission de jeton. Le refus se décide sur le scheme EFFECTIF : derrière un proxy qui termine TLS, déclarer ce proxy de confiance (`trustProxy` de @nodefony/http) suffit, et c'est la bonne réponse — pas cette clé. Ne la passer à true que pour un réseau où le clair est un choix assumé (maillage chiffré au niveau inférieur). Hors production, sans effet."),
 	apiKeys: apiKeysSchema.default(() => apiKeysSchema.parse({})),
 	webhooks: webhooksSchema.default(() => webhooksSchema.parse({})),
 	audit: auditSchema.default(() => auditSchema.parse({})),

package/dist/nodefony/contracts/index.js

@@ -1,2 +1 @@
-import { VoterVote } from "./IAccessVoter.js";
-export { VoterVote };
+export { VoterVote } from "./IAccessVoter.js";

package/dist/nodefony/errors/InsecureTransportError.js

@@ -0,0 +1,24 @@
+import { INSECURE_TRANSPORT_MESSAGE, nodefonyError } from "nodefony";
+//#region nodefony/errors/InsecureTransportError.ts
+/**
+* Secret refusé parce qu'il arrive en clair — `code = 403` (RFC 9110 §15.5.4 :
+* le serveur a compris la requête mais refuse de l'honorer).
+*
+* Message constant ({@link INSECURE_TRANSPORT_MESSAGE}, cœur) : le navigateur
+* le reconnaît, et il ne dit rien de la topologie.
+*
+* Levée AVANT toute vérification, quand un mot de passe ou un code de second
+* facteur arrive en production sur une requête dont le scheme effectif n'est
+* pas `https` (cf {@link CredentialTransportPolicy}). Ce n'est pas un 401 :
+* aucune preuve n'a été jugée, et rien de ce que le client corrigera dans son
+* secret ne changera la réponse — c'est le canal qu'il doit changer. Pas de
+* `WWW-Authenticate` non plus : un défi Basic ferait rouvrir au navigateur la
+* fenêtre qui renverrait le mot de passe par le même canal.
+*/
+var InsecureTransportError = class extends nodefonyError {
+	constructor() {
+		super(INSECURE_TRANSPORT_MESSAGE, 403);
+	}
+};
+//#endregion
+export { InsecureTransportError, InsecureTransportError as default };

package/dist/nodefony/errors/index.js

@@ -1,3 +1,4 @@
+import { InsecureTransportError } from "./InsecureTransportError.js";
 import { CsrfError } from "./CsrfError.js";
 import { AuthenticationError } from "./AuthenticationError.js";
 import { ThrottledError } from "./ThrottledError.js";
@@ -6,4 +7,4 @@ import { InvalidTargetError } from "./InvalidTargetError.js";
 import { WebAuthnError } from "./WebAuthnError.js";
 import { SsrfError } from "./SsrfError.js";
 import { AccessDeniedError } from "./AccessDeniedError.js";
-export { AccessDeniedError, AuthenticationError, CsrfError, InvalidTargetError, SsrfError, ThrottledError, UnverifiableTokenError, WebAuthnError };
+export { AccessDeniedError, AuthenticationError, CsrfError, InsecureTransportError, InvalidTargetError, SsrfError, ThrottledError, UnverifiableTokenError, WebAuthnError };

package/dist/nodefony/keycloak/keycloakAdmin.js

@@ -0,0 +1,255 @@
+import { isNodefonyKeycloakTheme, keycloakLoginTheme, realmNameFromIssuer } from "./keycloakRealmInput.js";
+//#region nodefony/keycloak/keycloakAdmin.ts
+/** Refus ou échec d'un appel ; le message nomme la cause et le geste suivant. */
+var KeycloakAdminError = class extends Error {
+	status;
+	/**
+	* @param message - phrase destinée à l'opérateur
+	* @param status - statut HTTP de Keycloak, `null` s'il n'a pas répondu
+	*/
+	constructor(message, status = null) {
+		super(message);
+		this.status = status;
+		this.name = "KeycloakAdminError";
+	}
+};
+const DEFAULT_TIMEOUT_MS = 1e4;
+/**
+* Marge retirée à la durée de vie du jeton : un jeton qui expire PENDANT un
+* appel rend un 401 qu'on lirait comme un compte refusé.
+*/
+const TOKEN_MARGIN_MS = 1e4;
+/**
+* Le realm et le compte d'administration d'un fournisseur, lus dans la
+* configuration de sécurité VALIDÉE.
+*
+* @param config - configuration de sécurité (`defineSecurityConfig`)
+* @param providerName - nom dans `oauth2.providers` (défaut `keycloak`)
+* @returns l'émetteur et le compte
+* @throws {KeycloakAdminError} Fournisseur absent, sans émetteur ou sans
+*   compte d'administration
+*/
+function keycloakAdminTarget(config, providerName = "keycloak") {
+	const provider = Object.hasOwn(config.oauth2.providers, providerName) ? config.oauth2.providers[providerName] : void 0;
+	if (provider?.issuer === void 0) throw new KeycloakAdminError(`aucun fournisseur « ${providerName} » avec un issuer dans oauth2.providers — il n'est monté que si ses variables NF_KEYCLOAK_* sont posées`);
+	if (provider.admin === void 0) throw new KeycloakAdminError(`oauth2.providers.${providerName}.admin absent : l'API d'administration exige le compte administrateur de Keycloak (NF_KEYCLOAK_ADMIN_USERNAME / NF_KEYCLOAK_ADMIN_PASSWORD, passés en développement seulement)`);
+	return {
+		issuer: provider.issuer,
+		admin: provider.admin
+	};
+}
+/**
+* Client de l'API d'administration d'UN realm Keycloak.
+*
+* Le jeton `admin-cli` est demandé au premier appel puis GARDÉ jusqu'à son
+* expiration ; un 401 en cours de route le renouvelle une fois. Les gardes
+* (développement seulement, https seulement) sont tenues au constructeur :
+* un client qui existe a le droit de parler.
+*/
+var KeycloakAdminClient = class {
+	/** Nom du realm administré. */
+	realm;
+	/** Origine du serveur (`https://hôte:port`). */
+	origin;
+	#admin;
+	#fetch;
+	#timeoutMs;
+	#token = null;
+	/**
+	* @param options - realm, compte, environnement, transport
+	* @throws {KeycloakAdminError} Hors développement, émetteur qui n'est pas un
+	*   realm, ou émetteur en clair
+	*/
+	constructor(options) {
+		if (options.environment !== "development") throw new KeycloakAdminError(`refusé en « ${options.environment} » : l'API d'administration exige le compte administrateur de Keycloak, réservé au développement — en production, passer par la console (Realm settings)`);
+		try {
+			this.realm = realmNameFromIssuer(options.issuer);
+		} catch (error) {
+			throw new KeycloakAdminError(error instanceof Error ? error.message : String(error));
+		}
+		const url = new URL(options.issuer);
+		if (url.protocol !== "https:") throw new KeycloakAdminError(`émetteur « ${options.issuer} » en clair : le mot de passe administrateur ne part qu'en https`);
+		this.origin = url.origin;
+		this.#admin = options.admin;
+		this.#fetch = options.fetch ?? globalThis.fetch;
+		this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	}
+	/**
+	* Un appel à l'API d'administration du realm, jeton joint.
+	*
+	* @param method - verbe HTTP
+	* @param path - chemin SOUS `/admin/realms/<realm>` (`""` = le realm, `/users?…`)
+	* @param body - corps JSON, ou rien
+	* @returns la réponse brute — au consommateur de lire son statut
+	* @throws {KeycloakAdminError} Serveur injoignable ou compte refusé
+	*/
+	async request(method, path, body) {
+		const url = `${this.origin}/admin/realms/${encodeURIComponent(this.realm)}${path}`;
+		const send = async (token) => this.#call(url, {
+			method,
+			headers: {
+				authorization: `Bearer ${token}`,
+				accept: "application/json",
+				...body === void 0 ? {} : { "content-type": "application/json" }
+			},
+			...body === void 0 ? {} : { body: JSON.stringify(body) }
+		});
+		const response = await send(await this.#accessToken());
+		if (response.status !== 401) return response;
+		await response.body?.cancel();
+		this.#token = null;
+		return send(await this.#accessToken());
+	}
+	/**
+	* La représentation du realm.
+	*
+	* @returns l'objet JSON rendu par Keycloak
+	* @throws {KeycloakAdminError} Realm introuvable ou lecture refusée
+	*/
+	async getRealm() {
+		const response = await this.request("GET", "");
+		if (!response.ok) {
+			await response.body?.cancel();
+			throw new KeycloakAdminError(response.status === 404 ? `realm « ${this.realm} » introuvable sur ${this.origin}` : `lecture du realm « ${this.realm} » refusée (HTTP ${response.status})`, response.status);
+		}
+		const body = await response.json();
+		if (typeof body !== "object" || body === null || Array.isArray(body)) throw new KeycloakAdminError(`Keycloak a rendu autre chose qu'un realm pour « ${this.realm} »`);
+		return Object.fromEntries(Object.entries(body));
+	}
+	/**
+	* Change des champs du realm — et eux seuls : Keycloak ne touche pas aux
+	* champs absents d'un `PUT` partiel.
+	*
+	* @param changes - les champs à écrire
+	* @throws {KeycloakAdminError} Écriture refusée
+	*/
+	async updateRealm(changes) {
+		const response = await this.request("PUT", "", changes);
+		await response.body?.cancel();
+		if (!response.ok) throw new KeycloakAdminError(`écriture refusée sur le realm « ${this.realm} » (HTTP ${response.status})`, response.status);
+	}
+	/**
+	* Pose sur le realm le thème de connexion qui porte un habillage de `/login`.
+	*
+	* Un realm habillé par l'application (thème ni `nodefony` ni `nodefony-*`,
+	* ou aucun) n'est JAMAIS modifié : même règle que la dérivation du fichier
+	* d'import.
+	*
+	* @param skin - habillage (`loginPage.skin`, ou celui d'un aperçu)
+	* @returns le thème d'avant, celui demandé, et ce qui a été fait
+	* @throws {KeycloakAdminError} Keycloak injoignable, compte refusé, realm
+	*   introuvable
+	*/
+	async applyLoginTheme(skin) {
+		const theme = keycloakLoginTheme(skin);
+		const current = (await this.getRealm()).loginTheme;
+		const previous = typeof current === "string" && current.length > 0 ? current : null;
+		const realm = this.realm;
+		if (previous === null || !isNodefonyKeycloakTheme(previous)) return {
+			realm,
+			previous,
+			theme,
+			outcome: "unmanaged"
+		};
+		if (previous === theme) return {
+			realm,
+			previous,
+			theme,
+			outcome: "unchanged"
+		};
+		await this.updateRealm({ loginTheme: theme });
+		return {
+			realm,
+			previous,
+			theme,
+			outcome: "applied"
+		};
+	}
+	/** Le jeton `admin-cli`, gardé jusqu'à son expiration. */
+	async #accessToken() {
+		if (this.#token !== null && this.#token.expiresAt > Date.now()) return this.#token.value;
+		const response = await this.#call(`${this.origin}/realms/master/protocol/openid-connect/token`, {
+			method: "POST",
+			headers: { "content-type": "application/x-www-form-urlencoded" },
+			body: new URLSearchParams({
+				grant_type: "password",
+				client_id: "admin-cli",
+				username: this.#admin.username,
+				password: this.#admin.password
+			}).toString()
+		});
+		if (!response.ok) {
+			await response.body?.cancel();
+			throw new KeycloakAdminError(`compte administrateur refusé par Keycloak (HTTP ${response.status}, realm master) — vérifier NF_KEYCLOAK_ADMIN_USERNAME et NF_KEYCLOAK_ADMIN_PASSWORD`, response.status);
+		}
+		const payload = await response.json();
+		const field = (key) => typeof payload === "object" && payload !== null ? Object.getOwnPropertyDescriptor(payload, key)?.value : void 0;
+		const accessToken = field("access_token");
+		const expiresIn = field("expires_in");
+		if (typeof accessToken !== "string" || accessToken === "") throw new KeycloakAdminError("Keycloak n'a rendu aucun jeton d'administration");
+		const lifetimeMs = typeof expiresIn === "number" ? expiresIn * 1e3 : 0;
+		this.#token = {
+			value: accessToken,
+			expiresAt: Date.now() + lifetimeMs - TOKEN_MARGIN_MS
+		};
+		return accessToken;
+	}
+	/** Un appel réseau borné ; une panne devient une erreur qui nomme le serveur. */
+	async #call(url, init) {
+		try {
+			return await this.#fetch(url, {
+				...init,
+				signal: AbortSignal.timeout(this.#timeoutMs)
+			});
+		} catch (error) {
+			const cause = error instanceof Error && error.cause instanceof Error ? ` (${error.cause.message})` : "";
+			throw new KeycloakAdminError(`Keycloak injoignable à ${this.origin} : ${error instanceof Error ? error.message : String(error)}${cause}`);
+		}
+	}
+};
+/**
+* Le thème de connexion qu'une page servie par Keycloak charge.
+*
+* Lu sans aucun identifiant : la page d'autorisation publique charge ses
+* fichiers sous `/resources/<version>/login/<thème>/…`.
+*
+* @param html - début de la page d'autorisation
+* @returns le nom du thème, ou `null` si la page n'est pas celle de Keycloak
+*/
+function readKeycloakLoginTheme(html) {
+	const match = /\/resources\/[^/"'\s]+\/login\/([^/"'\s]+)\//u.exec(html);
+	return match?.[1] === void 0 ? null : decodeURIComponent(match[1]);
+}
+/**
+* La sonde « thème » du diagnostic d'un fournisseur : la page de Keycloak
+* suit-elle l'habillage de `/login` ?
+*
+* @param skin - habillage configuré (`loginPage.skin`)
+* @returns une fonction qui juge la page d'autorisation ; elle rend `null` —
+*   aucune sonde — sur une page qui n'est pas de Keycloak
+*/
+function keycloakLoginThemeCheck(skin) {
+	const expected = keycloakLoginTheme(skin);
+	return (html) => {
+		const active = readKeycloakLoginTheme(html);
+		if (active === null) return null;
+		if (!isNodefonyKeycloakTheme(active)) return {
+			name: "theme",
+			status: "ok",
+			message: `thème « ${active} » propre à l'application, laissé tel quel`
+		};
+		if (active === expected) return {
+			name: "theme",
+			status: "ok",
+			message: `la page de Keycloak suit l'habillage « ${skin} » (${active})`
+		};
+		return {
+			name: "theme",
+			status: "failed",
+			kind: "login-theme-mismatch",
+			message: `Keycloak affiche le thème « ${active} », l'habillage « ${skin} » demande « ${expected} » — la connexion marche, mais ne ressemble pas à /login : nodefony security:keycloak:realm --apply (ou Realm settings › Themes)`
+		};
+	};
+}
+//#endregion
+export { KeycloakAdminClient, KeycloakAdminError, keycloakAdminTarget, keycloakLoginThemeCheck, readKeycloakLoginTheme };