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

package/dist/types/nodefony/command/{security-token.d.ts → security-mcp-token.d.ts}

@@ -11,7 +11,16 @@ import { CliKernel, Command } from "nodefony";
  */
 export declare function ttlSeconds(raw: string | undefined): number | undefined | Error;
 /**
- * `nodefony security:token` — émet un jeton d'accès pour une porte de cette
+ * Durée demandée à l'émetteur : `--ttl` explicite, sinon 8 h quand le jeton
+ * part chez les agents, sinon rien — la configuration décide.
+ *
+ * @param raw - la valeur de `--ttl` telle que tapée, ou rien
+ * @param write - le jeton sera posé dans la configuration des agents
+ * @returns les secondes, `undefined` pour le défaut de configuration, une `Error` sinon
+ */
+export declare function tokenTtlSeconds(raw: string | undefined, write: boolean): number | undefined | Error;
+/**
+ * `nodefony security:mcp:token` — émet un jeton d'accès pour une porte de cette
  * application (la porte MCP par défaut).
  *
  * **Pourquoi une commande, et pas un `curl`.** Le jeton s'obtenait par un appel
@@ -25,11 +34,12 @@ export declare function ttlSeconds(raw: string | undefined): number | undefined
  * raison d'être de la liaison d'audience. La commande la vise d'elle-même,
  * `--resource` ne sert qu'à en viser une autre.
  *
- * Suit `security:secrets` : `--write` pose la valeur là où l'AGENT la lit
- * (gitignoré), jamais dans le `.env` commité, et ne remplace jamais une valeur
- * existante — une rotation est un geste explicite.
+ * `--write` pose la valeur là où l'AGENT la lit (gitignoré), jamais dans le
+ * `.env` de l'application. Relancée, elle REMPLACE le jeton chez les agents qui
+ * le portent déjà — la rotation est le geste le plus fréquent — et n'en câble
+ * aucun nouveau sans le proposer.
  */
-declare class SecurityToken extends Command {
+declare class SecurityMcpToken extends Command {
     #private;
     constructor(cli: CliKernel);
     generate(identifierArg: string | undefined, opts: {
@@ -41,4 +51,4 @@ declare class SecurityToken extends Command {
         json?: boolean;
     }): Promise<this>;
 }
-export default SecurityToken;
+export default SecurityMcpToken;

package/dist/types/nodefony/command/security-oauth-doctor.d.ts

@@ -0,0 +1,23 @@
+import { CliKernel, Command } from "nodefony";
+/**
+ * `nodefony security:oauth:doctor` — dit POURQUOI un fournisseur OAuth refuse
+ * l'application, sans qu'un humain ait à se connecter.
+ *
+ * Trois verdicts distincts là où le journal ne montre qu'un 401 : l'émetteur
+ * se déclare autrement que la configuration ne l'écrit, l'URL de retour n'est
+ * pas enregistrée, le secret est faux. La même analyse alimente
+ * `nodefony doctor --live` (famille « Fournisseurs OAuth ») et l'endpoint
+ * d'administration `security/oauth/diagnosis` : une seule implémentation, celle
+ * du service `oauth2`.
+ *
+ * Valable pour tout fournisseur : les sondes passent par le fournisseur que le
+ * login construit, Keycloak n'y a rien de particulier.
+ */
+declare class SecurityOAuthDoctor extends Command {
+    constructor(cli: CliKernel);
+    generate(opts: {
+        provider?: string;
+        json?: boolean;
+    }): Promise<this>;
+}
+export default SecurityOAuthDoctor;

package/dist/types/nodefony/command/security-secrets.d.ts

@@ -19,6 +19,8 @@ declare class SecuritySecrets extends Command {
     generate(opts: {
         json?: boolean;
         write?: boolean;
+        jwtKeyset?: boolean;
+        env?: boolean;
     }): Promise<this>;
 }
 export default SecuritySecrets;

package/dist/types/nodefony/command/security-user-delete.d.ts

@@ -12,9 +12,10 @@ import { CliKernel, Command } from "nodefony";
  * seul recours est une écriture directe en base. Le même garde-fou existe côté
  * data plane (`UserAdminApi`) — ici il est constaté, pas supposé.
  *
- * La révocation des sessions et jetons du compte suit d'elle-même : la
- * suppression émet `onUserRevoked`, auquel `@nodefony/security` réagit en
- * éjectant sessions et jetons. Rien à faire de plus ici.
+ * La suppression passe par `users.delete`, qui émet `onUserRevoked`
+ * (`reason: "deleted"`) et ATTEND la cascade de `@nodefony/security` : sessions
+ * et jetons éjectés, secret TOTP et passkeys retirés. La commande n'émet rien
+ * elle-même — le service est le seul émetteur du cycle de vie d'un compte.
  */
 declare class SecurityUserDelete extends Command {
     constructor(cli: CliKernel);

package/dist/types/nodefony/command/security-user-password.d.ts

@@ -20,10 +20,10 @@ import { CliKernel, Command } from "nodefony";
  *
  * 🔒 **Les sessions et les jetons du compte sont RÉVOQUÉS**, et ce n'est pas une
  * option : on change un mot de passe parce qu'il est compromis ou perdu, et
- * laisser vivre les sessions ouvertes laisserait l'accès à qui l'a volé. La
- * révocation passe par l'événement que la suppression emploie déjà — une
- * cascade, un seul canal, et les abonnés futurs (webhooks) en profitent sans
- * rien changer ici.
+ * laisser vivre les sessions ouvertes laisserait l'accès à qui l'a volé.
+ * `UserService.changePassword` émet la révocation lui-même — la même que pour
+ * le plan d'administration et la page « mon mot de passe » : un seul émetteur,
+ * aucun transport ne peut l'oublier.
  */
 declare class SecurityUserPassword extends Command {
     constructor(cli: CliKernel);

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<{
@@ -26,6 +31,7 @@ export declare const securityConfigSchema: z.ZodObject<{
         rounds: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strict>>>;
     roleHierarchy: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+    grantableScopes: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
     areas: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         pattern: z.ZodString;
         security: z.ZodDefault<z.ZodBoolean>;
@@ -40,6 +46,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 +198,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 +238,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 +248,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/ApiKeyError.d.ts

@@ -5,6 +5,8 @@ import { nodefonyError } from "nodefony";
  * classes de `@nodefony/security`).
  *
  *  - `400` — entrée invalide (nom vide, scope hors catalogue) ;
+ *  - `403` — scope demandé que le porteur ne peut pas obtenir (`grantableScopes`,
+ *    ou `admin:*` sans le rôle d'administration) ;
  *  - `409` — plafond `apiKeys.maxPerSubject` atteint ;
  *  - `503` — store de jetons indisponible (clés activées mais non provisionnées).
  *
@@ -12,6 +14,6 @@ import { nodefonyError } from "nodefony";
  * 401, message uniforme anti-énumération).
  */
 export declare class ApiKeyError extends nodefonyError {
-    constructor(message: string, code: 400 | 409 | 503);
+    constructor(message: string, code: 400 | 403 | 409 | 503);
 }
 export default ApiKeyError;

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;