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

package/dist/types/nodefony/src/oauth/oauth2Client.d.ts

@@ -25,7 +25,16 @@ export declare class OAuth2RequestError extends Error {
     readonly code: string;
     /** Description lisible fournie par le serveur, ou `null`. */
     readonly description: string | null;
-    constructor(code: string, description: string | null);
+    /**
+     * Statut HTTP de la réponse, ou `null` s'il n'est pas connu.
+     *
+     * Le code `error` ne suffit pas toujours à dire QUI est refusé : la RFC 6749
+     * §5.2 réserve `401` à l'échec d'authentification du client, et Keycloak
+     * répond `unauthorized_client` en `401` sur un secret faux — le même code
+     * qu'en `400` pour un flux que le client n'a pas le droit d'employer.
+     */
+    readonly status: number | null;
+    constructor(code: string, description: string | null, status?: number | null);
 }
 /**
  * Jetons rendus par le point de jeton (RFC 6749 §5.1), enveloppés pour qu'un champ
@@ -88,6 +97,16 @@ export interface IAuthorizationRequest {
     readonly codeVerifier: string | null;
     /** Portées demandées ; aucune n'est ajoutée d'office. */
     readonly scopes: readonly string[];
+    /**
+     * Thème d'affichage que l'application a rendu (clair ou sombre), pour que
+     * l'écran du fournisseur le reprenne.
+     *
+     * Aucun paramètre normalisé ne le porte (OIDC n'a que `ui_locales`, pour la
+     * langue) : seul un fournisseur qui sait le lire le traduit — Keycloak, en
+     * `nf_theme` que lit le thème livré. Les autres l'ignorent, et ne le
+     * reçoivent jamais : un paramètre inconnu peut être refusé.
+     */
+    readonly theme?: "light" | "dark";
     /**
      * Paramètres versés TELS QUELS dans la requête d'autorisation.
      *
@@ -172,3 +191,33 @@ export declare class OAuth2Client {
      */
     validateAuthorizationCode(request: ITokenRequest): Promise<OAuth2Tokens>;
 }
+/** Ce qu'il faut savoir du client pour parler au point de jeton. */
+export interface ITokenEndpointClient {
+    /** Point de jeton (RFC 6749 §3.2). */
+    readonly tokenEndpoint: string;
+    /** Identifiant client délivré par le serveur d'autorisation. */
+    readonly clientId: string;
+    /** Secret client — vide seulement pour `none`. */
+    readonly clientSecret: string;
+    /** Comment le client s'authentifie (RFC 6749 §2.3). */
+    readonly clientAuthMethod: OAuth2ClientAuthMethod;
+    /** Implémentation de `fetch` (banc sans réseau). */
+    readonly fetch?: typeof globalThis.fetch | undefined;
+    /** Délai d'attente, en millisecondes. */
+    readonly timeoutMs?: number | undefined;
+}
+/**
+ * Présente une requête au point de jeton et rend les jetons (RFC 6749 §5.1).
+ *
+ * SEULE implémentation de l'authentification du client et de la lecture de la
+ * réponse : l'échange de code et le flux `client_credentials` y passent tous
+ * deux, pour qu'une règle (méthode déclarée, redirection refusée, réponse
+ * bornée, refus lu sur `error`) ne diverge jamais entre deux flux.
+ *
+ * @param client - point de jeton et identité du client.
+ * @param body - corps de la requête, `grant_type` compris ; l'identité du
+ *   client y est ajoutée selon la méthode déclarée.
+ * @throws OAuth2RequestError - le serveur a refusé, en nommant la cause (RFC 6749 §5.2).
+ * @throws Error - réponse inintelligible, hors gabarit, ou serveur injoignable.
+ */
+export declare function postTokenRequest(client: ITokenEndpointClient, body: URLSearchParams): Promise<OAuth2Tokens>;

package/dist/types/nodefony/src/oauth/oauthProviderRegistry.d.ts

@@ -14,7 +14,11 @@ import type { OAuth2ClientAuthMethod } from "./oauth2Client.js";
  * en une ligne dans l'application :
  *
  * ```ts
- * registerOAuthProvider("azure", (ctx) => createDiscoveredOidcProvider("azure", ctx));
+ * registerOAuthProvider(
+ *   "azure",
+ *   (ctx) => createDiscoveredOidcProvider("azure", ctx),
+ *   { requiresIssuer: true }, // un émetteur oublié refuse le démarrage
+ * );
  * ```
  */
 /** Contexte de construction d'un fournisseur (secrets et URL issus de la config). */
@@ -42,6 +46,11 @@ export interface IOAuthProviderContext {
      * l'émetteur est connu d'avance (Google) ou qui n'en publient pas (GitHub).
      */
     readonly issuer?: string | undefined;
+    /**
+     * Adresse où lire les métadonnées de l'émetteur quand elle diffère de lui
+     * (service interne d'un cluster) — cf `IDiscoveryOptions.discoveryUrl`.
+     */
+    readonly discoveryUrl?: string | undefined;
 }
 /**
  * Fabrique d'un fournisseur OAuth pour un nom donné.
@@ -51,12 +60,47 @@ export interface IOAuthProviderContext {
  * (le service mémoïse le fournisseur résolu).
  */
 export type OAuthProviderFactory = (ctx: IOAuthProviderContext) => IOAuthProvider | Promise<IOAuthProvider>;
+/**
+ * Ce qu'une fabrique EXIGE de la configuration — lu au démarrage, avant que le
+ * moindre utilisateur ne clique.
+ *
+ * @remarks La fabrique est une fonction opaque : rien, à sa seule lecture, ne
+ * dit qu'elle lèvera faute d'émetteur. Sans déclaration, l'oubli ne se
+ * découvrait qu'au premier login.
+ */
+export interface IOAuthProviderRegistration {
+    /**
+     * `true` si le fournisseur ne peut se construire sans `issuer` dans sa
+     * configuration — typiquement un serveur OpenID Connect découvert par son
+     * émetteur. Absent : l'émetteur est facultatif (connu d'avance, ou inutile).
+     */
+    readonly requiresIssuer?: boolean;
+}
 /**
  * Enregistre (ou remplace) la fabrique d'un fournisseur OAuth. Appelée par les
  * builtins au chargement, et par une application pour ses fournisseurs.
+ *
+ * @param name - nom sous lequel le fournisseur se configure (`oauth2.providers.<name>`).
+ * @param factory - fabrique du fournisseur.
+ * @param registration - exigences de configuration, vérifiées au démarrage.
  */
-export declare function registerOAuthProvider(name: string, factory: OAuthProviderFactory): void;
+export declare function registerOAuthProvider(name: string, factory: OAuthProviderFactory, registration?: IOAuthProviderRegistration): void;
 /** Fabrique d'un fournisseur par nom, ou `undefined` si inconnu. */
 export declare function getOAuthProviderFactory(name: string): OAuthProviderFactory | undefined;
+/** `true` si le fournisseur nommé a déclaré exiger un émetteur en configuration. */
+export declare function oauthProviderRequiresIssuer(name: string): boolean;
 /** Noms enregistrés (validation boot, introspection Studio, tests). */
 export declare function listOAuthProviders(): string[];
+/**
+ * Paramètre d'autorisation que lit le thème Keycloak livré (`template.ftl`)
+ * pour afficher l'écran dans le thème de l'application (`light` | `dark`).
+ */
+export declare const KEYCLOAK_THEME_PARAMETER = "nf_theme";
+/**
+ * Ajoute le thème demandé ({@link IAuthorizationRequest.theme}) à l'URL
+ * d'autorisation d'un fournisseur Keycloak, sous {@link KEYCLOAK_THEME_PARAMETER}.
+ *
+ * @param provider - fournisseur OIDC découvert, inchangé pour tout le reste
+ * @returns le même fournisseur, dont l'URL d'autorisation porte le thème
+ */
+export declare function withKeycloakThemeHint(provider: IOAuthProvider): IOAuthProvider;

package/dist/types/nodefony/src/oauth/providerDiagnosis.d.ts

@@ -0,0 +1,117 @@
+import type { IOAuthProvider } from "../../contracts/IOAuthProvider.js";
+import { type OAuth2ClientAuthMethod } from "./oauth2Client.js";
+/**
+ * **Diagnostic d'un fournisseur OAuth sans connexion humaine** — dit POURQUOI un
+ * branchement échoue, là où le journal ne montre qu'un 401 ou une page d'erreur
+ * du fournisseur.
+ *
+ * Trois sondes, dans l'ordre où l'une éclaire l'autre :
+ *
+ * 1. **découverte** — le fournisseur se construit comme au premier login
+ *    (métadonnées, émetteur identique RFC 8414 §3.3, PKCE S256 annoncé) ;
+ * 2. **point d'autorisation** — la requête que le bouton enverrait, sans la
+ *    suivre : le serveur accepte-t-il ce client et cette URL de retour ?
+ * 3. **point de jeton** — un code INVENTÉ présenté avec le vrai secret :
+ *    `invalid_grant` prouve que le client s'est authentifié (seul le code est
+ *    refusé), un refus d'authentification prouve le contraire (RFC 6749 §5.2).
+ *
+ * 🔴 **Rien n'est réécrit ici.** Les sondes passent par le fournisseur que la
+ * fabrique construit pour le login — mêmes points d'entrée, même méthode
+ * d'authentification, même URL de retour. Un diagnostic qui reconstruirait sa
+ * propre requête prouverait que SA requête passe, pas celle du login.
+ *
+ * @remarks Chemin froid (une commande, un écran d'administration). La sonde
+ * d'autorisation ouvre côté fournisseur une session de connexion vide, qui
+ * expire seule ; aucun compte n'est touché, aucun jeton n'est émis.
+ */
+/**
+ * Les sondes, dans leur ordre. `theme` n'existe que si l'appelant fournit un
+ * {@link IOAuthDiagnosisInput.pageCheck} ET que la page d'autorisation s'y
+ * prête (Keycloak).
+ */
+export type OAuthCheckName = "discovery" | "authorization" | "token" | "theme";
+/**
+ * Verdict d'une sonde. `inconclusive` = le serveur a répondu quelque chose
+ * qu'on ne sait pas lire — ni un quitus, ni un manquement ; `skipped` = une
+ * sonde précédente a rendu celle-ci impossible.
+ */
+export type OAuthCheckStatus = "ok" | "failed" | "inconclusive" | "skipped";
+/** La cause d'un échec, lisible par une machine (rapport, console, tests). */
+export type OAuthFailureKind = 
+/** Le document de métadonnées se déclare d'un autre émetteur (RFC 8414 §3.3). */
+"issuer-mismatch"
+/** Émetteur injoignable, document absent ou incomplet, PKCE S256 non annoncé. */
+ | "discovery-failed"
+/** Le point d'autorisation refuse l'URL de retour (non enregistrée). */
+ | "redirect-uri-rejected"
+/** Le point d'autorisation refuse la demande pour une autre raison. */
+ | "authorization-refused"
+/** Le point d'autorisation n'a pas répondu. */
+ | "authorization-unreachable"
+/** Le client existe (le point d'autorisation l'accepte), son secret est refusé. */
+ | "secret-rejected"
+/** Authentification du client refusée : client inconnu, ou secret refusé. */
+ | "client-rejected"
+/** Le point de jeton refuse pour une autre raison (flux non autorisé…). */
+ | "token-refused"
+/** Le point de jeton n'a pas répondu. */
+ | "token-unreachable"
+/** La page du fournisseur ne porte pas l'habillage de `/login`. */
+ | "login-theme-mismatch";
+/** Le résultat d'une sonde. */
+export interface IOAuthCheck {
+    readonly name: OAuthCheckName;
+    readonly status: OAuthCheckStatus;
+    /** Présent si et seulement si `status === "failed"`. */
+    readonly kind?: OAuthFailureKind;
+    /** Phrase destinée à l'opérateur : le constat, puis le geste. */
+    readonly message: string;
+}
+/** Le diagnostic d'un fournisseur. */
+export interface IOAuthDiagnosis {
+    /** Nom du fournisseur (`oauth2.providers.<name>`). */
+    readonly provider: string;
+    /** `true` si aucune sonde n'a échoué. Une sonde non concluante ne l'empêche pas. */
+    readonly ok: boolean;
+    readonly checks: readonly IOAuthCheck[];
+}
+/** Ce que le diagnostic d'un fournisseur doit savoir. */
+export interface IOAuthDiagnosisInput {
+    /** Nom du fournisseur. */
+    readonly name: string;
+    /** Construit le fournisseur comme pour un login — découverte comprise. */
+    readonly build: () => IOAuthProvider | Promise<IOAuthProvider>;
+    /** Identifiant du client, tel que configuré. */
+    readonly clientId: string;
+    /** URL de retour configurée — celle que le fournisseur doit connaître. */
+    readonly redirectUri: string;
+    /** Méthode d'authentification déclarée ; `"none"` = client public. */
+    readonly clientAuthMethod?: OAuth2ClientAuthMethod | undefined;
+    /** Portées configurées ; vides = celles du fournisseur. */
+    readonly scopes?: readonly string[] | undefined;
+    /**
+     * Transport de la sonde d'autorisation. Celle du point de jeton passe par le
+     * fournisseur, donc par le transport que SA fabrique a reçu.
+     */
+    readonly fetch?: typeof globalThis.fetch | undefined;
+    /** Délai d'attente de la sonde d'autorisation, en millisecondes. */
+    readonly timeoutMs?: number | undefined;
+    /**
+     * Juge la page de connexion que le point d'autorisation sert (ses premiers
+     * octets). Rend une sonde de plus, ou `null` quand la page ne s'y prête
+     * pas. Le diagnostic reste générique : c'est le kit Keycloak qui sait lire
+     * le thème d'une page de Keycloak.
+     */
+    readonly pageCheck?: ((html: string) => IOAuthCheck | null) | undefined;
+}
+/**
+ * Diagnostique un fournisseur OAuth sans connexion humaine.
+ *
+ * Ne lève jamais : un serveur muet ou hostile devient une sonde en échec, et
+ * les sondes que l'échec rend impossibles sont DITES sautées — un silence ne
+ * vaut pas quitus.
+ *
+ * @param input - fournisseur à construire et configuration à confronter.
+ * @returns les trois sondes et leur verdict.
+ */
+export declare function diagnoseOAuthProvider(input: IOAuthDiagnosisInput): Promise<IOAuthDiagnosis>;

package/dist/types/nodefony/src/oauth/providerRoles.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Traduction des rôles d'un fournisseur d'identité (Keycloak, tout serveur
+ * OpenID Connect) en rôles de l'application.
+ *
+ * Logique PURE, sans réseau ni base : la même fonction sert la connexion par
+ * navigateur (claims du jeton reçu du point de jeton) et l'API (claims d'un
+ * jeton dont la signature vient d'être vérifiée). Deux implémentations
+ * divergeraient — un rôle retiré dans l'annuaire disparaîtrait d'un côté et
+ * survivrait de l'autre.
+ */
+/** Où lire les rôles dans les claims du fournisseur. */
+export type ProviderRoleSource = "client" | "realm" | "groups";
+/** Source par défaut : les rôles du CLIENT — ceux que l'annuaire attribue à CETTE application. */
+export declare const DEFAULT_ROLE_SOURCES: readonly ProviderRoleSource[];
+/**
+ * Préfixe des rôles de PLATEFORME (console d'administration, plan
+ * d'administration) — jamais accordés par un annuaire externe.
+ */
+export declare const PLATFORM_ROLE_PREFIX = "ROLE_NODEFONY_";
+/** `true` si le rôle relève de la plateforme (`ROLE_NODEFONY_*`). */
+export declare function isPlatformRole(role: string): boolean;
+/** Table de correspondance compilée d'UN fournisseur. */
+export interface IProviderRoleMapping {
+    /** Client dont on lit les rôles (`resource_access.<clientId>.roles`). */
+    readonly clientId: string;
+    /** Sources lues, dans l'ordre. */
+    readonly sources: readonly ProviderRoleSource[];
+    /** Rôle du fournisseur → rôle de l'application (objet sans prototype). */
+    readonly table: Readonly<Record<string, string>>;
+}
+/** Ce que la configuration d'un fournisseur apporte à la correspondance. */
+export interface IProviderRoleConfig {
+    readonly clientId: string;
+    readonly roleMapping?: Readonly<Record<string, string>> | undefined;
+    readonly rolesSource?: readonly ProviderRoleSource[] | undefined;
+}
+/**
+ * Compile la table d'un fournisseur — `null` quand il n'en déclare aucune, ce
+ * qui laisse les rôles du compte entièrement locaux (comportement historique).
+ *
+ * @param config - configuration du fournisseur.
+ * @returns la table compilée, ou `null`.
+ */
+export declare function compileProviderRoleMapping(config: IProviderRoleConfig): IProviderRoleMapping | null;
+/**
+ * Rôles de l'application accordés par le fournisseur, d'après ses claims.
+ *
+ * Un rôle du fournisseur absent de la table est IGNORÉ — jamais recopié tel
+ * quel : l'annuaire ne fabrique pas de rôle que l'application n'a pas déclaré.
+ * Plusieurs jeux de claims (jeton d'accès, jeton d'identité) se cumulent : ils
+ * viennent du même émetteur, chacun peut porter une partie des rôles selon
+ * les « mappers » configurés chez lui.
+ *
+ * @param mapping - table compilée du fournisseur.
+ * @param claimSets - claims à lire ; `null`/`undefined` ignorés.
+ * @returns rôles de l'application, triés et sans doublon.
+ */
+export declare function mapProviderRoles(mapping: IProviderRoleMapping, ...claimSets: (Readonly<Record<string, unknown>> | null | undefined)[]): string[];

package/dist/types/nodefony/src/oauth/providers/oidc.d.ts

@@ -1,4 +1,4 @@
-import type { IOAuthProvider } from "../../../contracts/IOAuthProvider.js";
+import type { ILogoutTokenClaims, IOAuthProvider } from "../../../contracts/IOAuthProvider.js";
 import type { IOAuthProviderContext } from "../oauthProviderRegistry.js";
 import { type IAuthorizationRequest, type ITokenRequest, type OAuth2Tokens } from "../oauth2Client.js";
 import { type IDiscoveryOptions } from "../metadata.js";
@@ -30,7 +30,40 @@ export interface IOidcProviderOptions {
     readonly decodeIdToken: (idToken: string) => object | Promise<object>;
     /** Scopes par défaut si la config n'en précise aucun. */
     readonly defaultScopes?: string[];
+    /**
+     * Point de déconnexion du fournisseur (`end_session_endpoint`). Absent ou
+     * `null` : le fournisseur n'offre pas `createLogoutURL`.
+     */
+    readonly endSessionEndpoint?: string | null;
+    /**
+     * Vérifie la SIGNATURE d'un jeton de déconnexion (émetteur, audience,
+     * algorithme, `exp`/`iat`) et rend ses claims, ou `null` s'il est refusé ;
+     * lève sur une panne. Absente : le fournisseur n'offre pas
+     * `verifyLogoutToken`. Le sens du jeton (§2.4) est contrôlé ensuite par
+     * {@link readLogoutTokenClaims}, jamais par cette fonction.
+     */
+    readonly verifyLogoutTokenSignature?: (logoutToken: string) => Promise<{
+        issuer: string;
+        payload: Record<string, unknown>;
+    } | null>;
 }
+/**
+ * Lit ce qu'un jeton de déconnexion DÉSIGNE, une fois sa signature vérifiée —
+ * les points 5 à 7 de la validation (OpenID Connect Back-Channel Logout 1.0
+ * §2.6) : `sub` ou `sid` présent, `events` qui le déclare jeton de
+ * déconnexion, AUCUN `nonce`.
+ *
+ * @remarks Ces gardes ferment la confusion entre jetons (§4.1) : un ID token
+ * du même émetteur, pour le même client, porte une signature tout aussi
+ * valide — c'est `events` qui le distingue, et l'absence de `nonce` qui
+ * empêche le chemin inverse. Fonction PURE, éprouvable sans clé ni réseau.
+ *
+ * @param issuer - émetteur canonique rendu par la vérification de signature.
+ * @param payload - claims vérifiés.
+ * @returns les claims utiles, ou `null` si le jeton n'est pas un jeton de
+ *   déconnexion valide.
+ */
+export declare function readLogoutTokenClaims(issuer: string, payload: Record<string, unknown>): ILogoutTokenClaims | null;
 /**
  * Fabrique un {@link IOAuthProvider} **générique OIDC** — couvre TOUT fournisseur
  * OpenID Connect sans code spécifique : le profil se lit toujours pareil (claims

package/dist/types/nodefony/src/openToSignup.d.ts

@@ -0,0 +1,36 @@
+import type { ISecurityConfig } from "../config/config.js";
+/** Une zone que la connexion OAuth ouvre à quiconque obtient un compte. */
+export interface IOpenToSignupZone {
+    /** Nom de la zone (`areas.<nom>`). */
+    zone: string;
+    /** Fournisseurs OAuth qui créent les comptes à la volée, triés. */
+    providers: readonly string[];
+    /** Le constat, en une phrase — la MÊME au démarrage, dans la console et dans `doctor`. */
+    message: string;
+    /** Les deux gestes qui le soldent, prêts à taper. */
+    action: string;
+}
+/**
+ * Les zones protégées qui n'exigent aucun rôle alors que la connexion OAuth
+ * crée les comptes à la volée — c'est-à-dire ouvertes à tout compte que le
+ * fournisseur délivre.
+ *
+ * Une zone sans `roles` laisse passer toute identité authentifiée : c'est un
+ * défaut voulu. Il devient un piège quand `oauth2.allowSignup` vaut `true`
+ * (le défaut) : avec Google ou GitHub, « authentifié » veut dire « n'importe
+ * qui sur Internet ». Une zone est donc retenue quand TOUT ceci est vrai :
+ * protégée, sans `anonymous`, sans `roles`, avec `session` (c'est par la
+ * session qu'un compte OAuth entre), et `oauth2` actif avec au moins un
+ * fournisseur et `allowSignup`.
+ *
+ * Le remède est une DÉCLARATION : `roles: ["ROLE_USER"]` ne change rien au
+ * comportement (un compte créé reçoit ce rôle) mais écrit l'intention.
+ *
+ * Calculée au démarrage et dans `describe()`, jamais par requête. C'est la
+ * SEULE implémentation de la règle : `doctor` lit son résultat par le plan
+ * d'administration, il ne la recalcule pas.
+ *
+ * @param config - la configuration de sécurité validée.
+ * @returns les zones concernées, dans l'ordre de déclaration ; vide sinon.
+ */
+export declare function findZonesOpenToSignup(config: Pick<ISecurityConfig, "areas" | "oauth2">): IOpenToSignupZone[];

package/dist/types/nodefony/src/sessionAuthentication.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Facteurs d'authentification de Nodefony → méthodes RFC 8176, posées dans la
+ * session à son ouverture. Les clés et leur lecteur sont au cœur
+ * (`readSessionAuthentication`, `nodefony`) ; seule la POLITIQUE de
+ * correspondance vit ici.
+ */
+/**
+ * Valeurs RFC 8176 d'un facteur nommé par un chemin d'authentification.
+ *
+ * @param factor - le facteur tel que l'audit le nomme (`password`, `totp`,
+ *   `recovery`, `webauthn`, `oauth`…)
+ * @returns les méthodes vérifiées localement ; vide pour un facteur délégué
+ */
+export declare function amrForFactor(factor: string): readonly string[];

package/dist/types/nodefony/src/token/JwtKeystore.d.ts

@@ -1,4 +1,4 @@
-import type { JSONWebKeySet } from "jose";
+import type { JSONWebKeySet, JWK } from "jose";
 import type { IJwtKeystore, IJwtSigningKey } from "../../contracts/IJwtKeystore.js";
 /** Journalisation injectée (le keystore n'est pas un Service — il reçoit un log). */
 type LogFn = (message: string, severity: string) => void;
@@ -29,6 +29,43 @@ interface KeystoreSource {
  * @returns le message à journaliser, ou `null` quand le dossier est nettoyé.
  */
 export declare function keystoreLeaksIntoImage(dir: string): string | null;
+/** Clé telle que persistée : JWK privé (avec `d`) + métadonnées. */
+export interface IStoredKey extends JWK {
+    kid: string;
+    alg: string;
+    use?: string;
+    createdAt?: number;
+}
+/** Forme du fichier `keyset.json` / de la variable d'env `keySetJson`. */
+export interface IStoredKeySet {
+    /** `kid` de la clé qui signe (les autres ne servent qu'à vérifier). */
+    active: string;
+    keys: IStoredKey[];
+}
+/**
+ * Lit un jeu de clés sérialisé et en vérifie la FORME — la seule lecture du
+ * dépôt, appelée par le keystore ET par la validation de configuration.
+ *
+ * Ne vérifie que la structure (`keys` non vide, un `kid` par clé) : importer
+ * les clés exige `jose`, chargé paresseusement au premier jeton. Les messages
+ * ne recopient JAMAIS la valeur reçue — elle porte une clé privée.
+ *
+ * @param json - le jeu de clés, tel que `NF_JWT_KEYSET` ou `keyset.json` le porte.
+ * @returns le jeu de clés lu.
+ * @throws Error si le JSON est illisible ou la structure incomplète.
+ */
+export declare function parseKeySet(json: string): IStoredKeySet;
+/**
+ * Génère un jeu de clés de signature à partager entre tous les process d'une
+ * application — la valeur de `NF_JWT_KEYSET`.
+ *
+ * Même générateur que celui du keystore (une seule implémentation), sérialisé
+ * en JSON COMPACT : une ligne, sans quote simple, qu'un `.env` porte entre
+ * quotes simples et qu'un gestionnaire de secrets stocke tel quel.
+ *
+ * @returns le jeu de clés sérialisé — il contient la clé PRIVÉE.
+ */
+export declare function generateKeySet(): Promise<string>;
 /**
  * Keystore Ed25519 — implémentation de référence d'{@link IJwtKeystore}.
  *
@@ -49,10 +86,15 @@ export declare function keystoreLeaksIntoImage(dir: string): string | null;
  * usage ; le boot ne paie rien si le JWT n'est jamais sollicité. Le chargement
  * est mémoïsé (une seule résolution concurrente).
  *
- * @remarks Race au 1ᵉʳ boot d'un **cluster** sans clé pré-provisionnée : deux
- * workers peuvent générer puis écrire des clés différentes (le dernier `rename`
- * gagne). En prod, provisionner la clé hors-bande (`keySetJson`/SecretProvider
- * P16) élimine ce cas — c'est précisément la source recommandée.
+ * @remarks Plusieurs process qui servent la MÊME application doivent signer
+ * avec la même clé, sinon un jeton signé par l'un est refusé par l'autre :
+ * - **pods** (aucun disque partagé) → source `env` obligatoire, la même valeur
+ *   injectée partout (`NF_JWT_KEYSET`, générée par `security:secrets`) ;
+ * - **workers de `nodefony cluster`** → la source `env` est héritée au fork ; à
+ *   défaut, la source `fichier` est sûre : la création de `keyset.json` est
+ *   EXCLUSIVE ({@link createSecretExclusive}), un seul worker la génère et les
+ *   autres relisent la sienne ;
+ * - source `mémoire` → une clé par process, jamais cohérente.
  */
 export declare class JwtKeystore implements IJwtKeystore {
     #private;

package/dist/types/nodefony/src/token/RemoteJwtVerifier.d.ts

@@ -21,6 +21,13 @@ export interface ITrustedIssuer {
      * découvert.
      */
     jwksUri?: string | undefined;
+    /**
+     * Adresse où lire les métadonnées quand elle diffère de l'émetteur (service
+     * interne d'un cluster). Le document doit toujours se déclarer de `issuer` ;
+     * le `jwks_uri` peut alors être en `http` sur l'origine exacte de cette
+     * adresse (`isBackChannelTransportAllowed`, cœur).
+     */
+    discoveryUrl?: string | undefined;
     /**
      * Jeu de clés fourni LOCALEMENT — aucune requête, aucune découverte.
      *
@@ -123,8 +130,8 @@ export declare class RemoteJwtVerifier {
     #private;
     /**
      * @param options - émetteurs de confiance et réglages réseau
-     * @throws Error si un émetteur est invalide, dupliqué, ou déclare un
-     *         algorithme à secret partagé
+     * @throws Error si un émetteur est invalide, dupliqué, déclare un
+     *         algorithme à secret partagé ou une `discoveryUrl` invalide
      */
     constructor(options: IRemoteJwtVerifierOptions);
     /** Nombre d'émetteurs de confiance — pour l'introspection et les journaux. */
@@ -145,5 +152,25 @@ export declare class RemoteJwtVerifier {
      *         « jeton invalide »
      */
     verify(token: string, audience: string): Promise<IAccessPrincipal | null>;
+    /**
+     * Vérifie un jeton et rend ses claims BRUTS — pour un jeton qui n'est pas un
+     * jeton d'accès (jeton de déconnexion OpenID Connect, par exemple), dont le
+     * sens se lit dans des claims que {@link verify} ne remonte pas.
+     *
+     * Mêmes garanties et même contrat d'erreur que {@link verify} : signature,
+     * émetteur de la liste fermée, algorithme imposé, audience obligatoire,
+     * claims exigés par l'émetteur ; un refus est un `null`, une panne lève.
+     *
+     * @param token - le jeton brut, tel que présenté
+     * @param audience - audience que le jeton DOIT porter dans `aud`
+     * @returns l'émetteur canonique et les claims vérifiés, ou `null` si le jeton
+     *          est refusé
+     * @throws Error si l'émetteur ne peut pas être joint ou publie un jeu de clés
+     *         inutilisable
+     */
+    verifyClaims(token: string, audience: string): Promise<{
+        issuer: string;
+        payload: Jose.JWTPayload;
+    } | null>;
 }
 export default RemoteJwtVerifier;

package/dist/types/nodefony/src/token/secretFile.d.ts

@@ -66,5 +66,27 @@ export declare function messageNonRestreint(file: string, mode: number): string;
  * un fichier EXISTANT conserve, sur certains systèmes, le mode de la cible.
  */
 export declare function writeSecret(file: string, content: string): Promise<void>;
+/**
+ * Crée un secret SEULEMENT s'il n'existe pas encore : 0600, atomique, et un
+ * seul gagnant quand plusieurs process le tentent en même temps.
+ *
+ * ⭐ **Pourquoi pas {@link writeSecret}.** `rename` REMPLACE la cible : deux
+ * workers de `nodefony cluster` qui génèrent chacun une clé au premier boot
+ * l'écrivent tous les deux, le dernier gagne sur le disque — et l'autre garde
+ * en mémoire une clé que plus personne ne connaît. Ici, le temporaire est
+ * publié par un LIEN DUR, que le système refuse (`EEXIST`) si le nom existe :
+ * le perdant le sait, et relit la clé du gagnant. Le lecteur ne voit jamais un
+ * fichier à demi écrit, puisque le lien n'apparaît qu'une fois le contenu complet.
+ *
+ * ⚠️ Un système de fichiers sans liens durs (FAT, exFAT) retombe sur une
+ * création exclusive directe (`wx`) : toujours un seul gagnant, mais un lecteur
+ * concurrent peut lire le fichier pendant son écriture — il lève alors, au lieu
+ * de signer avec une clé divergente.
+ *
+ * @param file - chemin du secret.
+ * @param content - contenu à écrire.
+ * @returns `true` si ce process l'a créé, `false` s'il existait déjà.
+ */
+export declare function createSecretExclusive(file: string, content: string): Promise<boolean>;
 /** Forme synchrone de {@link writeSecret}. */
 export declare function writeSecretSync(file: string, content: string): void;

package/dist/types/nodefony/src/transport/CredentialTransportPolicy.d.ts

@@ -0,0 +1,47 @@
+/** Vue minimale du contexte : seul le scheme EFFECTIF compte. */
+export interface ICredentialTransportContext {
+    /**
+     * Scheme vu par le client — `https` derrière un proxy de confiance qui
+     * termine TLS (`trustProxy` + `X-Forwarded-Proto`), jamais le transport brut.
+     */
+    readonly scheme?: string;
+}
+/** Réglages de la politique, résolus UNE fois au boot du firewall. */
+export interface ICredentialTransportPolicyOptions {
+    /** `true` = un secret reçu hors TLS est refusé (production, sans échappement). */
+    readonly enforce: boolean;
+    /** Journal du premier refus (WARNING) — absent = silencieux. */
+    readonly log?: (message: string) => void;
+}
+/**
+ * Dit si un secret de connexion se refuse : en production, sans échappement
+ * explicite. Seule source de la décision — le firewall la compose au boot.
+ *
+ * @param environment - environnement normalisé du kernel.
+ * @param allowInsecureCredentials - échappement `security.allowInsecureCredentials`.
+ */
+export declare function shouldEnforceCredentialTransport(environment: string | undefined, allowInsecureCredentials: boolean): boolean;
+/**
+ * Refuse, avant toute vérification, un mot de passe ou un code de second
+ * facteur reçu en clair. Une instance partagée au conteneur (`credentialTransport`)
+ * sert TOUTES les portes qui reçoivent un secret : formulaire de session, second
+ * facteur, Basic, émission de jeton — une porte oubliée serait le canal clair.
+ *
+ * La décision se prend sur le scheme EFFECTIF (`context.scheme`) : derrière un
+ * proxy qui termine TLS et déclaré de confiance, il vaut `https` alors que le
+ * pod écoute en HTTP. C'est le cas de la plupart des déploiements ; c'est donc
+ * `trustProxy` que nomme le journal, pas « passez en HTTPS ».
+ */
+export declare class CredentialTransportPolicy {
+    #private;
+    readonly enforce: boolean;
+    constructor(options: ICredentialTransportPolicyOptions);
+    /**
+     * Laisse passer un secret reçu sur TLS, ou n'importe lequel hors production.
+     *
+     * @param context - contexte de la requête qui porte le secret.
+     * @param door - porte qui le reçoit, nommée dans le journal.
+     * @throws InsecureTransportError (403) — secret reçu en clair en production.
+     */
+    assert(context: ICredentialTransportContext, door: string): void;
+}