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

package/dist/types/nodefony/config/config.d.ts

@@ -13,6 +13,11 @@ declare const areaSchema: z.ZodObject<{
     host: z.ZodOptional<z.ZodString>;
     resource: z.ZodOptional<z.ZodString>;
     realtime: z.ZodDefault<z.ZodBoolean>;
+    subjectPolicy: z.ZodOptional<z.ZodEnum<{
+        ephemeral: "ephemeral";
+        require: "require";
+    }>>;
+    ephemeralRoles: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
 export declare const securityConfigSchema: z.ZodObject<{
     encoders: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
@@ -40,6 +45,11 @@ export declare const securityConfigSchema: z.ZodObject<{
         host: z.ZodOptional<z.ZodString>;
         resource: z.ZodOptional<z.ZodString>;
         realtime: z.ZodDefault<z.ZodBoolean>;
+        subjectPolicy: z.ZodOptional<z.ZodEnum<{
+            ephemeral: "ephemeral";
+            require: "require";
+        }>>;
+        ephemeralRoles: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>>;
     realtimeChannels: z.ZodDefault<z.ZodArray<z.ZodObject<{
         pattern: z.ZodString;
@@ -187,6 +197,7 @@ export declare const securityConfigSchema: z.ZodObject<{
     resourceServer: z.ZodDefault<z.ZodObject<{
         issuers: z.ZodDefault<z.ZodArray<z.ZodObject<{
             issuer: z.ZodString;
+            discoveryUrl: z.ZodOptional<z.ZodString>;
             jwksUri: z.ZodOptional<z.ZodString>;
             algorithms: z.ZodDefault<z.ZodArray<z.ZodEnum<{
                 ES256: "ES256";
@@ -226,7 +237,7 @@ export declare const securityConfigSchema: z.ZodObject<{
         defaultRoles: z.ZodDefault<z.ZodArray<z.ZodString>>;
         allowSignup: z.ZodDefault<z.ZodBoolean>;
         successRedirect: z.ZodDefault<z.ZodString>;
-        failureRedirect: z.ZodDefault<z.ZodString>;
+        failureRedirect: z.ZodOptional<z.ZodString>;
         providers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
             clientId: z.ZodString;
             clientSecret: z.ZodString;
@@ -236,14 +247,65 @@ export declare const securityConfigSchema: z.ZodObject<{
             }>>;
             redirectUri: z.ZodString;
             issuer: z.ZodOptional<z.ZodString>;
+            discoveryUrl: z.ZodOptional<z.ZodString>;
             scopes: z.ZodDefault<z.ZodArray<z.ZodString>>;
             successRedirect: z.ZodOptional<z.ZodString>;
             failureRedirect: z.ZodOptional<z.ZodString>;
+            postLogoutRedirectUri: z.ZodOptional<z.ZodURL>;
             defaultRoles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            roleMapping: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            audiences: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            allowPlatformRoles: z.ZodDefault<z.ZodBoolean>;
+            rolesSource: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                client: "client";
+                groups: "groups";
+                realm: "realm";
+            }>>>;
             label: z.ZodOptional<z.ZodString>;
+            icon: z.ZodOptional<z.ZodString>;
+            admin: z.ZodOptional<z.ZodObject<{
+                username: z.ZodString;
+                password: z.ZodString;
+            }, z.core.$strict>>;
             hidden: z.ZodDefault<z.ZodBoolean>;
         }, z.core.$strict>>>;
     }, z.core.$strict>>;
+    loginPage: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        path: z.ZodDefault<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+        logo: z.ZodOptional<z.ZodString>;
+        template: z.ZodOptional<z.ZodString>;
+        stylesheet: z.ZodOptional<z.ZodString>;
+        heading: z.ZodOptional<z.ZodString>;
+        subtitle: z.ZodOptional<z.ZodString>;
+        providersFirst: z.ZodDefault<z.ZodBoolean>;
+        hero: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
+            heading: z.ZodString;
+            text: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>]>>;
+        footer: z.ZodDefault<z.ZodBoolean>;
+        password: z.ZodDefault<z.ZodBoolean>;
+        skin: z.ZodDefault<z.ZodEnum<{
+            blueprint: "blueprint";
+            console: "console";
+            dots: "dots";
+            enterprise: "enterprise";
+            frontispiece: "frontispiece";
+            horizon: "horizon";
+            ledger: "ledger";
+            minimal: "minimal";
+            "photo-card": "photo-card";
+        }>>;
+        layout: z.ZodOptional<z.ZodEnum<{
+            bare: "bare";
+            card: "card";
+            split: "split";
+        }>>;
+        previewPicker: z.ZodDefault<z.ZodBoolean>;
+        previewHook: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    allowInsecureCredentials: z.ZodDefault<z.ZodBoolean>;
     apiKeys: z.ZodDefault<z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         prefix: z.ZodDefault<z.ZodString>;

package/dist/types/nodefony/contracts/IAuthenticator.d.ts

@@ -33,7 +33,7 @@ export interface IAuthenticator {
     /** Hook échec — log audit, throttling (J2)… Le 401 + challenge sont posés par le firewall. */
     onFailure(context: ContextType, error: Error): Promise<void>;
     /**
-     * Challenge `WWW-Authenticate` (RFC 7235 : tout 401 DOIT en porter un).
+     * Challenge `WWW-Authenticate` (RFC 9110 §11 : tout 401 DOIT en porter un).
      * Le firewall pose celui du premier authenticator de la zone qui en déclare.
      * Ex. `'Basic realm="nodefony", charset="UTF-8"'`, `'Bearer'`.
      *

package/dist/types/nodefony/contracts/IFirewallDescription.d.ts

@@ -29,6 +29,23 @@ export interface IFirewallZoneDescription {
     host: string | null;
     /** Zone valable aussi pour les frames WebSocket (api.request + subscribe). */
     realtime: boolean;
+    /** Rôles exigés par défaut dans la zone (en OU) ; vide = toute identité authentifiée. */
+    roles?: readonly string[] | undefined;
+    /**
+     * Zone ouverte à tout compte que la connexion OAuth crée à la volée : sans
+     * rôle, avec `session`, et `oauth2.allowSignup` actif. Un constat, pas une
+     * faute — `roles: ["ROLE_USER"]` l'assume en une ligne.
+     */
+    openToSignup?: boolean | undefined;
+    /**
+     * Le constat et ses deux gestes, rédigés par le pare-feu — `null` quand la
+     * zone n'est pas ouverte. Un lecteur (console, `doctor`) les rend TELS
+     * QUELS : deux rédactions du même fait finiraient par se contredire.
+     */
+    openToSignupNotice?: {
+        message: string;
+        action: string;
+    } | null | undefined;
 }
 /** Un authenticator : disponible (registre de fabriques) et/ou monté (≥1 zone). */
 export interface IFirewallAuthenticatorDescription {
@@ -38,7 +55,7 @@ export interface IFirewallAuthenticatorDescription {
     mounted: boolean;
     /** Présent dans le registre de fabriques (utilisable en config). */
     available: boolean;
-    /** Déclare un challenge `WWW-Authenticate` (RFC 7235). */
+    /** Déclare un challenge `WWW-Authenticate` (RFC 9110 §11). */
     challenge: boolean;
 }
 /** Défenses transverses résolues (CSRF/CORS/headers/throttle) — sans secret. */
@@ -111,10 +128,34 @@ export interface IRoleDescription {
     /** Tous les rôles atteignables transitivement (hors le rôle lui-même), triés. */
     inherits: string[];
 }
+/**
+ * Table de correspondance des rôles d'UN fournisseur d'identité
+ * (`oauth2.providers.<nom>.roleMapping`) — des noms de rôles, rien d'autre de
+ * sa configuration.
+ */
+export interface IProviderRoleMappingDescription {
+    /** Nom du fournisseur (`keycloak`). */
+    provider: string;
+    /** Où ses rôles sont lus (`client`, `realm`, `groups`). */
+    sources: string[];
+    /**
+     * Rôle du fournisseur → rôle de l'application, triés par rôle du
+     * fournisseur ; `platform` = rôle de plateforme (`ROLE_NODEFONY_*`).
+     */
+    mappings: {
+        from: string;
+        to: string;
+        platform: boolean;
+    }[];
+    /** `true` si la table peut accorder des rôles de plateforme. */
+    allowPlatformRoles: boolean;
+}
 /** Hiérarchie de rôles : déclaration brute + résolution aplatie. */
 export interface IRoleHierarchyDescription {
     /** Déclaration directe (`{ ROLE_ADMIN: ["ROLE_USER"] }`). */
     hierarchy: Record<string, string[]>;
     /** Résolution transitive précalculée par le {@link RoleHierarchyWalker}. */
     roles: IRoleDescription[];
+    /** Rôles accordés par des fournisseurs d'identité — vide sans `roleMapping`. */
+    providerMappings: IProviderRoleMappingDescription[];
 }

package/dist/types/nodefony/contracts/IOAuthProvider.d.ts

@@ -27,6 +27,19 @@ export interface IIssuerPolicy {
      */
     readonly requireIssParameter: boolean;
 }
+/**
+ * Ce que porte une déconnexion initiée par l'application
+ * (OpenID Connect RP-Initiated Logout 1.0 §2).
+ */
+export interface ILogoutRequest {
+    /**
+     * ID token reçu au login (`id_token_hint`) : il dit au fournisseur QUELLE
+     * session fermer, et lui évite de demander une confirmation à l'utilisateur.
+     */
+    readonly idTokenHint: string;
+    /** Adresse de retour, enregistrée chez le fournisseur (`post_logout_redirect_uri`). */
+    readonly postLogoutRedirectUri: string;
+}
 /**
  * Adaptateur d'**un fournisseur OAuth/OIDC**, façade UNIFORME au-dessus d'un client
  * OAuth 2.0 — masque les divergences entre fournisseurs derrière un contrat stable
@@ -79,4 +92,39 @@ export interface IOAuthProvider {
      * @throws Si le fournisseur ne renvoie pas d'identifiant stable.
      */
     fetchProfile(tokens: OAuth2Tokens): Promise<IOAuthProfile>;
+    /**
+     * Construit l'adresse de déconnexion chez le fournisseur (RP-Initiated
+     * Logout). ABSENTE quand le fournisseur n'en publie aucune (GitHub, OIDC sans
+     * `end_session_endpoint`) : la déconnexion reste alors locale, et l'ID token
+     * n'est pas conservé.
+     */
+    createLogoutURL?(request: ILogoutRequest): URL;
+    /**
+     * Vérifie un jeton de déconnexion reçu sur le canal arrière (OpenID Connect
+     * Back-Channel Logout 1.0 §2.6) et rend ce qu'il désigne. ABSENTE quand le
+     * fournisseur ne sait pas en émettre (GitHub, OAuth sans OpenID Connect).
+     *
+     * @param logoutToken - le paramètre `logout_token` reçu, brut.
+     * @returns les claims qui désignent les sessions à fermer, ou `null` si le
+     *   jeton est refusé (signature, émetteur, audience, expiration, forme).
+     * @throws Error si la vérification est IMPOSSIBLE (jeu de clés injoignable) —
+     *   une panne n'est pas un jeton invalide.
+     */
+    verifyLogoutToken?(logoutToken: string): Promise<ILogoutTokenClaims | null>;
+}
+/**
+ * Ce qu'un jeton de déconnexion VÉRIFIÉ désigne (OpenID Connect Back-Channel
+ * Logout 1.0 §2.4) : au moins l'un de `subject` et `sid`.
+ */
+export interface ILogoutTokenClaims {
+    /** Émetteur canonique — celui de la liste fermée qui a servi à vérifier. */
+    readonly issuer: string;
+    /** `sub` : l'utilisateur chez le fournisseur, ou `null`. */
+    readonly subject: string | null;
+    /** `sid` : LA session du fournisseur à fermer, ou `null` (= toutes celles de `subject`). */
+    readonly sid: string | null;
+    /** `jti` : identifiant unique du jeton, la clé de l'anti-rejeu. */
+    readonly tokenId: string;
+    /** `exp` : fin de validité, en secondes depuis l'époque. */
+    readonly expiresAt: number;
 }

package/dist/types/nodefony/contracts/ISecuredArea.d.ts

@@ -45,6 +45,28 @@ export interface ISecuredArea extends ISecurityZone {
      * n'en ont pas besoin (session, mot de passe, jetons maison).
      */
     readonly resource?: string | undefined;
+    /**
+     * Politique de rattachement du sujet d'un jeton TIERS propre à cette zone,
+     * ou `undefined` pour suivre `resourceServer.subjectPolicy`.
+     *
+     * C'est ce qui fait cohabiter une zone d'appelants machine (`ephemeral`) et
+     * une zone de personnes (`require`) dans la même application.
+     */
+    readonly subjectPolicy?: "require" | "ephemeral" | undefined;
+    /**
+     * Rôles accordés par cette zone à un appelant `ephemeral` — définis dès que
+     * la zone déclare `subjectPolicy: "ephemeral"` (vide si elle n'en écrit
+     * aucun : un pouvoir local ne s'hérite jamais de la politique globale).
+     */
+    readonly ephemeralRoles?: readonly string[] | undefined;
+    /**
+     * Page de connexion vers laquelle le pare-feu conduit un visiteur anonyme
+     * qui NAVIGUE (`302` vers `<entryPoint>?from=<chemin demandé>`), au lieu du
+     * `401`. Un appel d'API, un POST ou un WebSocket gardent leur `401` : un
+     * client qui attend du JSON casserait sur une page HTML. Omis = `401` pour
+     * tous. Chemin de l'origine, vérifié au boot.
+     */
+    readonly entryPoint?: string | undefined;
     /**
      * Zone valable AUSSI pour le WebSocket (frames `api.request` + `subscribe`),
      * pas seulement HTTP. Défaut `true` (Zero Trust : une zone protégée ferme TOUS

package/dist/types/nodefony/contracts/ITotpSecret.d.ts

@@ -8,7 +8,10 @@ import type { TotpAlgorithm } from "../src/totp/totpCrypto.js";
  * API). Les codes de récupération, eux, sont **hachés** (verify-only).
  */
 export interface ITotpSecret {
-    /** Identifiant de l'utilisateur propriétaire (clé naturelle). */
+    /**
+     * Propriétaire = `IUser.identifier` (clé naturelle), jamais `IUser.id` —
+     * cf `ITotpSecretStore`.
+     */
     readonly userId: string;
     /**
      * Secret partagé `K` **chiffré** (blob opaque : `iv.tag.ciphertext` base64url).

package/dist/types/nodefony/contracts/ITotpSecretStore.d.ts

@@ -60,7 +60,13 @@ export interface TotpSecretUpdate {
  * d'`IWebAuthnCredentialStore` / `ITokenStore` : le builtin `memory` est sans
  * dépendance, les adapters lourds s'enregistrent depuis leur propre module.
  *
- * Modèle **1 secret / utilisateur** (clé = `userId`) — `save` est un **upsert**.
+ * Modèle **1 secret / utilisateur** — `save` est un **upsert**.
+ *
+ * **Clé = `userId` = `IUser.identifier` — immuable, la même clé que la session et les jetons —,
+ * jamais `IUser.id`. Un appelant qui ne connaît que l'`id` (route admin
+ * `users/{id}/…`) résout d'abord le compte (`users.findById`), puis passe son
+ * `identifier`. Les deux sont des `string` : le compilateur ne voit pas l'erreur,
+ * et une clé fausse rend un succès qui n'a rien touché.
  */
 export interface ITotpSecretStore {
     /** Secret TOTP de l'utilisateur, ou `null` si non enrôlé. */

package/dist/types/nodefony/contracts/IWebAuthnCredential.d.ts

@@ -10,7 +10,10 @@
 export interface IWebAuthnCredential {
     /** Identifiant du credential (base64url) — unique, fourni par l'authenticator. */
     readonly id: string;
-    /** Identifiant de l'utilisateur propriétaire (sub / userHandle applicatif). */
+    /**
+     * Propriétaire = `IUser.identifier` (sub / userHandle applicatif), jamais
+     * `IUser.id` — cf `IWebAuthnCredentialStore`.
+     */
     readonly userId: string;
     /** Clé publique **COSE** encodée base64url — vérifie la signature des assertions. */
     readonly publicKey: string;

package/dist/types/nodefony/contracts/IWebAuthnCredentialStore.d.ts

@@ -67,6 +67,12 @@ export interface WebAuthnAuthUpdate {
  * persistance (mémoire / ORM / Redis). Convention-frère d'`ITokenStore` :
  * le builtin `memory` est sans dépendance, les adapters lourds s'enregistrent
  * depuis leur propre module (inversion de dépendance).
+ *
+ * **Clé de propriétaire = `userId` = `IUser.identifier` — immuable, la même clé que la session et les jetons —,
+ * jamais `IUser.id`. Un appelant qui ne connaît que l'`id` (route admin
+ * `users/{id}/…`) résout d'abord le compte (`users.findById`), puis passe son
+ * `identifier`. Les deux sont des `string` : le compilateur ne voit pas l'erreur,
+ * et une clé fausse rend un succès qui n'a rien touché.
  */
 export interface IWebAuthnCredentialStore {
     /** Credential par son id (base64url), ou `null` — résolution à l'authentification. */

package/dist/types/nodefony/errors/InsecureTransportError.d.ts

@@ -0,0 +1,20 @@
+import { nodefonyError } from "nodefony";
+/**
+ * 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.
+ */
+export declare class InsecureTransportError extends nodefonyError {
+    constructor();
+}
+export default InsecureTransportError;

package/dist/types/nodefony/errors/index.d.ts

@@ -6,3 +6,4 @@ export { InvalidTargetError } from "./InvalidTargetError.js";
 export { CsrfError } from "./CsrfError.js";
 export { SsrfError } from "./SsrfError.js";
 export { WebAuthnError } from "./WebAuthnError.js";
+export { InsecureTransportError } from "./InsecureTransportError.js";

package/dist/types/nodefony/keycloak/keycloakAdmin.d.ts

@@ -0,0 +1,154 @@
+import type { LoginPageSkin } from "nodefony";
+import type { IOAuthCheck } from "../src/oauth/providerDiagnosis.js";
+import type { ISecurityConfig } from "../config/config.js";
+/**
+ * Client de l'API d'administration de Keycloak — le point d'entrée UNIQUE de
+ * Nodefony vers cette API.
+ *
+ * Premier besoin : le thème de connexion d'un realm EXISTANT, que
+ * `security:keycloak:realm --write` ne peut pas changer (Keycloak ne relit le
+ * fichier d'import qu'à la création du realm). Les suivants — fermer une
+ * session Keycloak, lire un compte, exporter — s'ajoutent ici en méthodes, sur
+ * le même jeton et les mêmes gardes, au lieu de recopier l'appel.
+ *
+ * Il exige le compte d'administration du SERVEUR (realm `master`) : il est
+ * refusé hors développement, quoi que dise la configuration. Le service
+ * `keycloak` (`KeycloakService.admin()`) le rend, un par fournisseur.
+ *
+ * @module
+ */
+/** Le compte d'administration du serveur Keycloak (realm `master`). */
+export interface IKeycloakAdminCredentials {
+    readonly username: string;
+    readonly password: string;
+}
+/** Le serveur à joindre et le compte qui l'administre. */
+export interface IKeycloakAdminTarget {
+    /** Émetteur du fournisseur — l'adresse du realm (`https://…/realms/<nom>`). */
+    readonly issuer: string;
+    readonly admin: IKeycloakAdminCredentials;
+}
+/** Ce que le client doit savoir. */
+export interface IKeycloakAdminClientOptions extends IKeycloakAdminTarget {
+    /** Environnement du kernel : tout autre que `development` est refusé. */
+    readonly environment: string;
+    /** Transport (défaut : `fetch` global) — injecté par les tests. */
+    readonly fetch?: typeof globalThis.fetch | undefined;
+    /** Délai de chaque appel, en millisecondes (défaut 10 s). */
+    readonly timeoutMs?: number | undefined;
+}
+/**
+ * Issue de {@link KeycloakAdminClient.applyLoginTheme} :
+ * - `applied` : le thème a changé ;
+ * - `unchanged` : le realm portait déjà ce thème ;
+ * - `unmanaged` : le realm porte un thème qui n'est pas de Nodefony (ou
+ *   aucun) — il appartient à l'application, rien n'est touché.
+ */
+export type KeycloakLoginThemeOutcome = "applied" | "unchanged" | "unmanaged";
+/** Ce que le geste a constaté et fait. */
+export interface IKeycloakLoginThemeResult {
+    readonly realm: string;
+    /** Thème du realm AVANT le geste ; `null` s'il n'en déclarait aucun. */
+    readonly previous: string | null;
+    /** Thème que l'habillage demande. */
+    readonly theme: string;
+    readonly outcome: KeycloakLoginThemeOutcome;
+}
+/** Refus ou échec d'un appel ; le message nomme la cause et le geste suivant. */
+export declare class KeycloakAdminError extends Error {
+    readonly status: number | null;
+    /**
+     * @param message - phrase destinée à l'opérateur
+     * @param status - statut HTTP de Keycloak, `null` s'il n'a pas répondu
+     */
+    constructor(message: string, status?: number | null);
+}
+/**
+ * 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
+ */
+export declare function keycloakAdminTarget(config: ISecurityConfig, providerName?: string): IKeycloakAdminTarget;
+/**
+ * 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.
+ */
+export declare class KeycloakAdminClient {
+    #private;
+    /** Nom du realm administré. */
+    readonly realm: string;
+    /** Origine du serveur (`https://hôte:port`). */
+    readonly origin: string;
+    /**
+     * @param options - realm, compte, environnement, transport
+     * @throws {KeycloakAdminError} Hors développement, émetteur qui n'est pas un
+     *   realm, ou émetteur en clair
+     */
+    constructor(options: IKeycloakAdminClientOptions);
+    /**
+     * 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é
+     */
+    request(method: string, path: string, body?: unknown): Promise<Response>;
+    /**
+     * La représentation du realm.
+     *
+     * @returns l'objet JSON rendu par Keycloak
+     * @throws {KeycloakAdminError} Realm introuvable ou lecture refusée
+     */
+    getRealm(): Promise<Record<string, unknown>>;
+    /**
+     * 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
+     */
+    updateRealm(changes: Record<string, unknown>): Promise<void>;
+    /**
+     * 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
+     */
+    applyLoginTheme(skin: LoginPageSkin): Promise<IKeycloakLoginThemeResult>;
+}
+/**
+ * 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
+ */
+export declare function readKeycloakLoginTheme(html: string): string | null;
+/**
+ * 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
+ */
+export declare function keycloakLoginThemeCheck(skin: LoginPageSkin): (html: string) => IOAuthCheck | null;

package/dist/types/nodefony/keycloak/keycloakRealm.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Le realm Keycloak d'une application — construit, jamais recopié.
+ *
+ * Deux usages, UNE construction : la contribution du paquet à une application
+ * neuve (`nodefony/keycloak/scaffold.ts`, jouée par `create app` après
+ * l'installation) écrit son realm d'import, et `security:keycloak:realm` le
+ * réécrit depuis la configuration EFFECTIVE d'une application qui tourne. Le
+ * cœur n'en sait rien : Keycloak est l'affaire de ce paquet.
+ *
+ * Avant lui, deux realms écrits à la main — celui du dépôt et le gabarit de
+ * l'application générée — répétaient ce que disait la configuration
+ * (identifiant de client, URL de retour, audience). Ils avaient divergé : le
+ * realm généré était né sans audience, et tout jeton y était refusé.
+ *
+ * Fonctions PURES : aucune lecture de disque, aucun environnement.
+ *
+ * @module
+ */
+/** Une valeur JSON — ce qu'un realm d'import peut contenir. */
+export type TKeycloakJson = string | number | boolean | null | TKeycloakJson[] | {
+    [key: string]: TKeycloakJson;
+};
+/** Un objet JSON du realm (client, mapper, utilisateur…). */
+export type TKeycloakObject = {
+    [key: string]: TKeycloakJson;
+};
+/** Un rôle à déclarer dans le realm. */
+export interface IKeycloakRoleInput {
+    /** Nom du rôle CÔTÉ KEYCLOAK (la clé de `roleMapping`). */
+    readonly name: string;
+    /** Texte affiché dans la console Keycloak. */
+    readonly description?: string;
+}
+/** Un compte de démonstration semé dans le realm de développement. */
+export interface IKeycloakUserInput {
+    /** Identifiant FIXÉ : laissé à Keycloak, il change à chaque réimport. */
+    readonly id: string;
+    readonly username: string;
+    readonly email: string;
+    readonly firstName: string;
+    readonly lastName: string;
+    /** Mot de passe de DÉVELOPPEMENT, public par nature. */
+    readonly password: string;
+    /** Rôles du client navigateur accordés à ce compte. */
+    readonly clientRoles?: readonly string[];
+}
+/** Le client « machine » (compte de service, `client_credentials`). */
+export interface IKeycloakMachineInput {
+    readonly clientId: string;
+    /** Secret de développement ; `null` = laissé à Keycloak (production). */
+    readonly secret: string | null;
+    readonly name?: string;
+    readonly description?: string;
+}
+/** Tout ce que le realm dit de l'application. */
+export interface IKeycloakRealmInput {
+    /** Nom du realm — le dernier segment de l'émetteur (`…/realms/<nom>`). */
+    readonly realm: string;
+    /** Titre affiché sur la page de connexion. */
+    readonly displayName?: string;
+    /** Identifiant du client navigateur (`oauth2.providers.<p>.clientId`). */
+    readonly clientId: string;
+    /** Secret du client ; `null` = laissé à Keycloak (production). */
+    readonly clientSecret: string | null;
+    readonly clientName?: string;
+    readonly clientDescription?: string;
+    /** URL de retour EXACTES (RFC 9700 : comparaison au caractère près). */
+    readonly redirectUris: readonly string[];
+    /** Où Keycloak a le droit de renvoyer le navigateur après déconnexion. */
+    readonly postLogoutRedirectUris: readonly string[];
+    /** Point de déconnexion par canal arrière ; `null` = aucun. */
+    readonly backchannelLogoutUrl: string | null;
+    /**
+     * Ressources pour lesquelles Keycloak émet des jetons à cette application :
+     * un mapper d'audience par entrée, sur chaque client. Vide = aucun mapper,
+     * et le jeton porte alors `aud: "account"`, que toute zone refuse.
+     */
+    readonly audiences: readonly string[];
+    /** Rôles du client navigateur (`rolesSource: ["client"]`). */
+    readonly clientRoles: readonly IKeycloakRoleInput[];
+    /** Rôles du realm (`rolesSource: ["realm"]`). */
+    readonly realmRoles: readonly IKeycloakRoleInput[];
+    /** Client machine ; `null` = aucun. */
+    readonly machine: IKeycloakMachineInput | null;
+    /** Thèmes à déclarer ; absent = ceux de Keycloak. */
+    readonly themes?: {
+        readonly login?: string;
+        readonly account?: string;
+        readonly email?: string;
+        readonly admin?: string;
+    };
+    /** Comptes de démonstration (développement seulement). */
+    readonly users?: readonly IKeycloakUserInput[];
+}
+/**
+ * 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
+ */
+export declare function keycloakDefaultRole(realm: string): string;
+/**
+ * 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}
+ */
+export declare function buildKeycloakRealm(input: IKeycloakRealmInput): TKeycloakObject;
+/**
+ * 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
+ */
+export declare function mergeKeycloakRealm(existing: TKeycloakJson, derived: TKeycloakObject): TKeycloakObject;
+/**
+ * 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
+ */
+export declare function renderKeycloakRealm(realm: TKeycloakObject): string;