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

package/dist/types/nodefony/src/authenticator/ExternalJwtAuthenticator.d.ts

@@ -3,32 +3,8 @@ import type { ContextType } from "@nodefony/http";
 import type { IAuthenticator } from "../../contracts/IAuthenticator.js";
 import type { ISecuredArea } from "../../contracts/ISecuredArea.js";
 import type { IToken } from "../../contracts/IToken.js";
-import { type ExternalSubjectMapping } from "./externalSubject.js";
-/** Comment le sujet d'un jeton devient un utilisateur de cette application. */
-export type ExternalSubjectPolicy = "require" | "ephemeral";
-/** Un émetteur reconnu, et la façon dont ses sujets entrent chez nous. */
-export interface IExternalIssuerBinding {
-    /** Émetteur de confiance, sous sa forme canonique. */
-    issuer: string;
-    /** Comment le `sub` de CET émetteur devient un identifiant local. */
-    subjectMapping: ExternalSubjectMapping;
-}
-/** Ce que la fabrique doit fournir à l'authenticator. */
-export interface IExternalJwtAuthenticatorOptions {
-    /**
-     * Émetteurs de confiance, et leur politique de sujet.
-     *
-     * La liste sert à deux choses, qu'il ne faut pas confondre : reconnaître les
-     * jetons qui relèvent de cet authenticator (aiguillage — elle n'accorde
-     * rien, le vérificateur refait le contrôle sur sa propre liste), et savoir
-     * dans quel espace de noms lire le sujet de chacun.
-     */
-    issuers: readonly IExternalIssuerBinding[];
-    /** Politique de rattachement du sujet à un utilisateur local. */
-    subjectPolicy: ExternalSubjectPolicy;
-    /** Rôles accordés en mode `ephemeral`. */
-    ephemeralRoles: readonly string[];
-}
+import { type IExternalJwtAuthenticatorOptions } from "./ExternalSubjectResolver.js";
+export type { ExternalSubjectPolicy, IExternalIssuerBinding, IExternalJwtAuthenticatorOptions, } from "./ExternalSubjectResolver.js";
 /**
  * Authentification par **jeton d'accès émis par un serveur d'autorisation
  * TIERS** (Keycloak, Auth0, Entra, ou l'émetteur d'une flotte d'agents).

package/dist/types/nodefony/src/authenticator/ExternalSubjectResolver.d.ts

@@ -0,0 +1,99 @@
+import { type Container } from "nodefony";
+import { type IUser } from "@nodefony/user";
+import type { ISecuredArea } from "../../contracts/ISecuredArea.js";
+import { type ExternalSubjectMapping } from "./externalSubject.js";
+import type { ISecurityConfig } from "../../config/defineModuleConfig.js";
+import { type IProviderRoleMapping } from "../oauth/providerRoles.js";
+/** Comment le sujet d'un jeton devient un utilisateur de cette application. */
+export type ExternalSubjectPolicy = "require" | "ephemeral";
+/** Un émetteur reconnu, et la façon dont ses sujets entrent chez nous. */
+export interface IExternalIssuerBinding {
+    /** Émetteur de confiance, sous sa forme canonique. */
+    issuer: string;
+    /** Comment le `sub` de CET émetteur devient un identifiant local. */
+    subjectMapping: ExternalSubjectMapping;
+}
+/** Ce que la fabrique doit fournir à l'authenticator. */
+export interface IExternalJwtAuthenticatorOptions {
+    /**
+     * Émetteurs de confiance, et leur politique de sujet.
+     *
+     * La liste sert à deux choses, qu'il ne faut pas confondre : reconnaître les
+     * jetons qui relèvent de cet authenticator (aiguillage — elle n'accorde
+     * rien, le vérificateur refait le contrôle sur sa propre liste), et savoir
+     * dans quel espace de noms lire le sujet de chacun.
+     */
+    issuers: readonly IExternalIssuerBinding[];
+    /** Politique de rattachement du sujet à un utilisateur local. */
+    subjectPolicy: ExternalSubjectPolicy;
+    /** Rôles accordés en mode `ephemeral`. */
+    ephemeralRoles: readonly string[];
+    /**
+     * Fournisseurs de CONNEXION (`oauth2.providers`) qui déclarent leur émetteur.
+     *
+     * Quand l'émetteur d'un jeton est celui d'un fournisseur de connexion, la
+     * même personne a pu se connecter par le navigateur : son compte local porte
+     * alors le lien `(fournisseur, sub)`. Le chercher d'abord évite qu'un jeton
+     * d'API désigne un AUTRE compte que la session de son porteur.
+     */
+    oauthProviders?: readonly {
+        name: string;
+        issuer: string;
+        /**
+         * Table de correspondance des rôles du fournisseur, compilée — absente ou
+         * `null` : les rôles du compte lié restent locaux.
+         */
+        roleMapping?: IProviderRoleMapping | null;
+    }[];
+}
+/**
+ * Les options de rattachement des sujets externes, lues dans la configuration
+ * de sécurité — UNE lecture, pour la zone `external-jwt` comme pour le
+ * résolveur de compte d'une ressource protégée.
+ *
+ * @param config - configuration de sécurité validée
+ * @returns émetteurs, politique de sujet, fournisseurs de connexion liables
+ */
+export declare function externalSubjectOptions(config: ISecurityConfig): IExternalJwtAuthenticatorOptions;
+/**
+ * Établit l'utilisateur applicatif que désigne le sujet d'un jeton TIERS —
+ * la décision qui transforme « un annuaire a authentifié ce sujet » en « ce
+ * compte agit chez nous ».
+ *
+ * UNE implémentation, deux consommateurs : la zone `external-jwt` du pare-feu
+ * (`ExternalJwtAuthenticator`) et le résolveur de compte d'une ressource
+ * protégée (porte MCP). Recopiée, la règle d'espace de noms aurait divergé dès
+ * le premier émetteur ajouté — et c'est elle qui empêche un annuaire tiers de
+ * réclamer le compte local `admin`.
+ */
+export declare class ExternalSubjectResolver {
+    #private;
+    /**
+     * @param container - container DI (résolution lazy de `users`)
+     * @param options - émetteurs reconnus et politique de rattachement
+     */
+    constructor(container: Container, options: IExternalJwtAuthenticatorOptions);
+    /**
+     * L'émetteur revendiqué est-il l'un des nôtres ? Ne lève JAMAIS : la valeur
+     * vient d'un jeton que n'importe qui peut forger.
+     *
+     * @param issuer - émetteur lu dans le jeton, non vérifié
+     */
+    recognizes(issuer: string): boolean;
+    /**
+     * Établit l'utilisateur applicatif à partir du sujet d'un jeton VÉRIFIÉ.
+     *
+     * Les deux politiques répondent à deux questions différentes : « qui, chez
+     * nous, est cette personne ? » et « quel pouvoir accorde-t-on à une machine
+     * que l'annuaire a authentifiée ? ».
+     *
+     * @param issuer - émetteur canonique, tel que le vérificateur l'a établi
+     * @param subject - sujet brut (`sub`) chez cet émetteur
+     * @param claims - revendications du jeton (rôles d'annuaire)
+     * @param area - zone qui SURCHARGE la politique, s'il y en a une
+     * @throws AuthenticationError (401) — sujet sans compte local utilisable
+     * @throws UnverifiableTokenError (503) — émetteur vérifié mais absent de la
+     *   table de rattachement : configuration incohérente
+     */
+    resolve(issuer: string, subject: string, claims: Readonly<Record<string, unknown>> | undefined, area?: ISecuredArea): Promise<IUser>;
+}

package/dist/types/nodefony/src/authenticator/FirewallRealtimeAuthenticator.d.ts

@@ -1,3 +1,4 @@
+import type { IUserProvider } from "@nodefony/user";
 import type { IRealtimeAuthenticator, IRealtimeHandshake, IRealtimeToken } from "../realtime/realtimeContracts.js";
 /**
  * Authenticator realtime des identités résolues par le **firewall** — équivalent
@@ -50,8 +51,10 @@ export declare class FirewallRealtimeAuthenticator implements IRealtimeAuthentic
      * @param resolveStore - fournit le store de révocation des jetons (le firewall
      *   passe une closure sur son container). Omis → mode dégradé documenté :
      *   seules les bornes portées par le jeton lui-même sont vérifiables.
+     * @param resolveUsers - fournit l'annuaire des comptes (`users`). Omis → pas
+     *   de confirmation du compte avant `api.request`.
      */
-    constructor(resolveStore?: (() => IRealtimeRevocationStore | null) | null);
+    constructor(resolveStore?: (() => IRealtimeRevocationStore | null) | null, resolveUsers?: (() => IUserProvider | null) | null);
     /** Une identité authentifiée a-t-elle été résolue (par le firewall) au handshake ? */
     supports(_handshake: IRealtimeHandshake): boolean;
     /**
@@ -62,6 +65,19 @@ export declare class FirewallRealtimeAuthenticator implements IRealtimeAuthentic
      *   filet défensif fail-closed → le hub ferme la socket en 4001).
      */
     authenticate(_handshake: IRealtimeHandshake): Promise<IRealtimeToken>;
+    /**
+     * Le revalidateur de l'identité que le firewall a posée sur la requête
+     * COURANTE (ALS), pour toute connexion longue — socket WebSocket ou flux SSE.
+     *
+     * Une seule règle décide qu'une identité est morte, quel que soit le
+     * transport qui la porte : c'est celle-ci, et le hub comme le noyau HTTP
+     * l'appellent au lieu de la recopier.
+     *
+     * @returns `null` pour un anonyme (rien à révoquer), sinon la fonction qui
+     *   dit si l'identité est TOUJOURS valable — fail-closed : `false` quand elle
+     *   ne peut pas le prouver.
+     */
+    currentRevalidator(): ((nowMs?: number) => Promise<boolean>) | null;
 }
 /**
  * Surface MINIMALE du store de jetons consommée ici : les deux lectures qui

package/dist/types/nodefony/src/authenticator/JwtAuthenticator.d.ts

@@ -1,5 +1,6 @@
-import type { Container } from "nodefony";
+import type { Container, IAccessPrincipal } from "nodefony";
 import type { ContextType } from "@nodefony/http";
+import type { IUser } from "@nodefony/user";
 import type { IAuthenticator } from "../../contracts/IAuthenticator.js";
 import type { IToken } from "../../contracts/IToken.js";
 import type { IJwtRuntime } from "../token/jwtRuntime.js";
@@ -59,6 +60,41 @@ export declare class JwtAuthenticator implements IAuthenticator {
      *   firewall puis 401 fail-closed (rien ne fuite au client).
      */
     authenticate(token: IToken): Promise<IToken>;
+    /**
+     * Vérifie un jeton émis par CETTE application pour une ressource protégée
+     * nommée par l'appelant — la porte d'une ressource (RFC 8707), pas une zone.
+     *
+     * Les MÊMES règles que {@link authenticate}, appliquées par la même fonction :
+     * signature par le keyset local, `iss`, `typ: at+jwt`, révocation ciblée
+     * (`jti`) et en masse (`invalidBefore`), compte encore actif. Seule
+     * l'audience diffère : c'est celle de la ressource qui appelle, et elle est
+     * exigée. Un jeton révoqué, ou celui d'un compte désactivé, n'ouvre donc pas
+     * plus une porte MCP qu'une route — ce que la vérification par le seul jeu de
+     * clés publiques laissait passer jusqu'à l'expiration.
+     *
+     * @param raw - le jeton présenté, brut
+     * @param audience - l'URI canonique de la ressource qui le reçoit
+     * @returns le principal établi, ou `null` pour tout refus (contrat
+     *   `IAccessTokenVerifier` : un refus n'est jamais une exception)
+     * @throws Error si le câblage manque (keystore, store, annuaire) — la porte
+     *   le traduit en `503`, jamais en jeton accepté
+     */
+    verifyForResource(raw: string, audience: string): Promise<IAccessPrincipal | null>;
+    /**
+     * Recharge le compte que désigne un principal établi par
+     * {@link verifyForResource} — pour une ressource protégée qui fait agir un
+     * outil au nom du propriétaire du jeton.
+     *
+     * La MÊME règle que la zone ({@link loadBoundAccount}), rejouée sur les
+     * revendications du principal : le vérificateur ne garde pas le compte qu'il
+     * a lu, et une seconde lecture de l'annuaire est le coût accepté d'un outil
+     * qui la demande — les autres ne la paient pas.
+     *
+     * @param principal - principal d'un jeton émis par CETTE application
+     * @returns le compte, ou `null` s'il n'est pas (ou plus) celui du jeton
+     * @throws Error si l'annuaire des comptes n'est pas câblé
+     */
+    resolveAccount(principal: IAccessPrincipal): Promise<IUser | null>;
     /** Slot audit (J4b). */
     onSuccess(_context: ContextType, _token: IToken): Promise<void>;
     /** Slot audit (J4b) — le 401 + challenge sont posés par le firewall. */

package/dist/types/nodefony/src/authenticator/UserPasswordAuthenticator.d.ts

@@ -3,6 +3,7 @@ import type { IPasswordVerifier } from "@nodefony/user";
 import type { IAuthenticator } from "../../contracts/IAuthenticator.js";
 import type { IToken } from "../../contracts/IToken.js";
 import type { LoginThrottler } from "../throttle/LoginThrottler.js";
+import type { CredentialTransportPolicy } from "../transport/CredentialTransportPolicy.js";
 /**
  * Authentification par identifiant + mot de passe — schéma **HTTP Basic**
  * (RFC 7617) : `Authorization: Basic base64(identifiant:motdepasse)`, charset
@@ -25,11 +26,18 @@ export declare class UserPasswordAuthenticator implements IAuthenticator {
      * @param resolveVerifier - résolution lazy de la source de vérification
      *   (typiquement `container.get("users")`) — appelée au premier login.
      * @param throttler - limiteur de tentatives (backoff NIST), `null` = désactivé.
+     * @param transport - politique du transport des secrets, `null` = aucune.
      */
-    constructor(resolveVerifier: () => IPasswordVerifier, throttler?: LoginThrottler | null);
+    constructor(resolveVerifier: () => IPasswordVerifier, throttler?: LoginThrottler | null, transport?: CredentialTransportPolicy | null);
     /** La requête porte-t-elle un en-tête `Authorization: Basic ...` ? */
     supports(context: ContextType): boolean;
-    /** Décode l'enveloppe Basic — un contenu malformé donne un credential vide (échec uniforme). */
+    /**
+     * Décode l'enveloppe Basic — un contenu malformé donne un credential vide
+     * (échec uniforme).
+     *
+     * @throws InsecureTransportError (403) — en production, en-tête reçu hors
+     *   TLS : refusé avant même d'être décodé.
+     */
     createToken(context: ContextType): Promise<IToken>;
     /**
      * Vérifie le credential via le verifier ou lève un 401 au message uniforme.
@@ -47,7 +55,7 @@ export declare class UserPasswordAuthenticator implements IAuthenticator {
     onSuccess(_context: ContextType, _token: IToken): Promise<void>;
     /** Slot J3+ (audit events). Le throttling vit dans `authenticate` (clé = identifiant) ; le 401 + challenge sont posés par le firewall. */
     onFailure(_context: ContextType, _error: Error): Promise<void>;
-    /** Challenge RFC 7235 posé par le firewall sur les 401 de la zone. */
+    /** Challenge RFC 9110 §11 posé par le firewall sur les 401 de la zone. */
     challenge(): string;
 }
 export default UserPasswordAuthenticator;

package/dist/types/nodefony/src/boot/publicRoutesNotice.d.ts

@@ -0,0 +1,16 @@
+import type { IBootNotice, IFirewallZoneView } from "nodefony";
+/**
+ * Le point d'attention « routes métier publiques » du bilan de démarrage.
+ *
+ * Hors d'une zone du pare-feu, une requête n'est jamais authentifiée : son
+ * identité n'est pas résolue, et une route métier qu'on croyait protégée
+ * répond à n'importe qui. Les seules zones présentes sont alors les aires du
+ * framework (`/nodefony/*`) ; on le DIT au démarrage, avec la recette.
+ *
+ * La classification « applicative ou framework » n'est pas recopiée : elle
+ * vient du cœur (`isFrameworkZone`), qui l'applique aussi au tableau des zones.
+ *
+ * @param zones - zones montées (`firewall.describe().zones`).
+ * @returns le point à déclarer, ou `null` si une zone applicative existe.
+ */
+export declare function publicRoutesNotice(zones: readonly IFirewallZoneView[]): IBootNotice | null;

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

@@ -0,0 +1,37 @@
+/** Ce que la décision lit d'une requête refusée — rien de plus. */
+export interface IEntryPointRequest {
+    /** Méthode HTTP (`GET`, `POST`…). */
+    readonly method: string | undefined;
+    /** En-tête `Accept`. */
+    readonly accept: string | undefined;
+    /** En-tête `Sec-Fetch-Mode` (Fetch Metadata), absent d'un client ancien. */
+    readonly fetchMode: string | undefined;
+    /** Chemin et requête demandés (`/compte?onglet=2`), jamais l'hôte. */
+    readonly path: string;
+}
+/**
+ * Dit si une requête refusée est la NAVIGATION d'un navigateur — le seul cas
+ * où conduire à la page de connexion aide, au lieu de casser un client.
+ *
+ * `GET` ou `HEAD`, `Accept` qui demande du HTML, et `Sec-Fetch-Mode: navigate`
+ * quand l'en-tête est présent : un `fetch()` d'une page porte `cors` ou
+ * `same-origin` même s'il accepte du HTML, et recevrait une page de connexion
+ * à la place de ses données.
+ *
+ * @param request - la requête refusée
+ * @returns `true` pour une navigation
+ */
+export declare function isBrowserNavigation(request: IEntryPointRequest): boolean;
+/**
+ * L'adresse de la page de connexion pour un visiteur refusé :
+ * `<entryPoint>?from=<chemin demandé>`, composée par `loginPagePath` (cœur).
+ * Le chemin demandé repasse par `safeRedirectPath` — la seule garde
+ * anti-redirection ouverte du framework, que la page de connexion appliquera
+ * de nouveau au retour.
+ *
+ * @param entryPoint - chemin de la page de connexion (vérifié au boot)
+ * @param request - la requête refusée
+ * @returns l'adresse du `Location`, ou `null` quand ce n'est pas une
+ *   navigation, ou quand la page demandée EST la page de connexion
+ */
+export declare function entryPointLocation(entryPoint: string, request: IEntryPointRequest): string | null;

package/dist/types/nodefony/src/net/transportFailure.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Rend un échec de transport LISIBLE : `fetch` (undici) ne dit que
+ * `fetch failed` et range la vraie raison dans `cause` — certificat refusé,
+ * connexion refusée, nom introuvable.
+ *
+ * @param error - ce que `fetch` (ou une bibliothèque qui l'appelle) a levé
+ * @returns `message (CODE : raison)`, ou le message seul faute de cause
+ */
+export declare function describeTransportFailure(error: unknown): string;
+/**
+ * Le remède d'un certificat signé par une autorité que le processus ne
+ * reconnaît pas — `null` pour tout autre échec.
+ *
+ * En développement, Nodefony reconnaît d'office l'autorité qu'il a générée ; en
+ * production jamais, et c'est voulu. Sans ce remède, le journal ne montrait que
+ * `SELF_SIGNED_CERT_IN_CHAIN` : la variable qui le règle n'était écrite que dans
+ * un commentaire du `.env`, fichier qu'un serveur de production n'a pas.
+ *
+ * @param error - ce que `fetch` (ou une bibliothèque qui l'appelle) a levé
+ * @returns une phrase d'action, ou `null`
+ */
+export declare function untrustedAuthorityHint(error: unknown): string | null;

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

@@ -0,0 +1,54 @@
+import type { OAuth2ClientAuthMethod, OAuth2Tokens } from "./oauth2Client.js";
+/**
+ * Ce qu'un programme présente pour obtenir un jeton EN SON PROPRE NOM
+ * (RFC 6749 §4.4) — un script, un service partenaire, un agent : aucun
+ * utilisateur, aucun navigateur.
+ */
+export interface IClientCredentialsRequest {
+    /**
+     * Identifiant de l'émetteur (claim `iss`), en https. Le point de jeton en est
+     * DÉCOUVERT (RFC 8414), jamais écrit à côté : un point de jeton recopié
+     * survit au déménagement de l'émetteur et envoie le secret ailleurs.
+     */
+    readonly issuer: string;
+    /** Identifiant du client confidentiel (ex. `<app>-machine` chez Keycloak). */
+    readonly clientId: string;
+    /** Secret du client — obligatoire : ce flux n'existe que pour un client confidentiel. */
+    readonly clientSecret: string;
+    /**
+     * Comment le client s'authentifie. Défaut `client_secret_basic`, la méthode
+     * que la RFC 6749 §2.3.1 rend obligatoire côté serveur. `none` n'existe pas
+     * ici : un client public ne peut pas obtenir de jeton en son nom.
+     */
+    readonly clientAuthMethod?: Exclude<OAuth2ClientAuthMethod, "none">;
+    /** Portées demandées ; aucune par défaut (le serveur applique les siennes). */
+    readonly scopes?: readonly string[];
+    /**
+     * Ressource visée (RFC 8707 §2) — l'audience que le jeton doit porter. Un
+     * serveur qui ne la connaît pas l'ignore ; Keycloak, lui, inscrit l'audience
+     * par un mapper déclaré sur le client.
+     */
+    readonly resource?: string;
+    /** Adresse où lire les métadonnées, si elle diffère de l'émetteur (cf `IDiscoveryOptions`). */
+    readonly discoveryUrl?: string | undefined;
+    /** Implémentation de `fetch` (banc sans réseau). */
+    readonly fetch?: typeof globalThis.fetch;
+    /** Délai d'attente de CHAQUE requête (découverte, puis jeton), en millisecondes. */
+    readonly timeoutMs?: number;
+}
+/**
+ * Obtient un jeton d'accès pour un programme, par le flux `client_credentials`
+ * (RFC 6749 §4.4), auprès d'un émetteur découvert (RFC 8414).
+ *
+ * C'est la voie de l'appelant MACHINE : il s'authentifie avec son propre
+ * secret, et le jeton rendu le désigne lui, pas un utilisateur. La même
+ * authentification de client que l'échange de code ({@link postTokenRequest}) —
+ * une seule implémentation, pour qu'aucune règle ne diverge d'un flux à l'autre.
+ *
+ * @param request - émetteur, identité du client, portées et ressource.
+ * @returns Les jetons rendus ; `accessToken()` est celui à présenter en `Bearer`.
+ * @throws Error - secret vide, émetteur invalide ou injoignable, métadonnées discordantes.
+ * @throws OAuth2RequestError - le serveur a refusé (`invalid_client` : secret
+ *   faux ; `unauthorized_client` : le client n'a pas droit à ce flux).
+ */
+export declare function requestClientCredentialsToken(request: IClientCredentialsRequest): Promise<OAuth2Tokens>;

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

@@ -1,11 +1,3 @@
-/**
- * Lecture BORNÉE d'un corps JSON — la brique de transport commune aux trois
- * appels sortants du social login (découverte, point de jeton, API d'un
- * fournisseur non-OIDC).
- *
- * Elle existe parce qu'une borne posée APRÈS `response.text()` ne protège plus
- * rien : le corps est déjà entièrement en mémoire quand on mesure sa longueur.
- */
 /**
  * Lit un corps JSON en refusant de dépasser une taille — la borne est vérifiée
  * PENDANT la lecture, pas après : un corps déjà entièrement en mémoire ne se

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

@@ -23,6 +23,19 @@ export interface IDiscoveredAuthorizationServer {
      * alors pas exiger ce qu'il n'a pas promis.
      */
     readonly issParameterSupported: boolean;
+    /**
+     * Point de déconnexion initiée par l'application (`end_session_endpoint`,
+     * OpenID Connect RP-Initiated Logout 1.0 §2.1), ou `null` si le serveur n'en
+     * publie aucun : la déconnexion reste alors locale.
+     */
+    readonly endSessionEndpoint: string | null;
+    /**
+     * Algorithmes de signature des ID tokens annoncés
+     * (`id_token_signing_alg_values_supported`, OpenID Connect Discovery §3), ou
+     * `null` si le serveur n'en publie aucun. Ce sont aussi ceux des jetons de
+     * déconnexion (OpenID Connect Back-Channel Logout 1.0 §2.6).
+     */
+    readonly idTokenSigningAlgValuesSupported: string[] | null;
 }
 /** Réglages de la découverte — l'injection de `fetch` est la voie pour éprouver sans TLS. */
 export interface IDiscoveryOptions {
@@ -36,6 +49,16 @@ export interface IDiscoveryOptions {
     readonly fetch?: typeof globalThis.fetch;
     /** Délai d'attente par URL candidate, en millisecondes. */
     readonly timeoutMs?: number;
+    /**
+     * Adresse où LIRE le document, quand elle diffère de l'émetteur — le service
+     * interne d'un cluster (`http://keycloak.sso:8080/realms/x/.well-known/openid-configuration`).
+     *
+     * @remarks Seul le lieu de lecture change : le document doit toujours se
+     * déclarer de l'émetteur attendu (RFC 8414 §3.3). Les points de serveur à
+     * serveur (jeton, clés) peuvent alors être en `http` sur l'origine exacte de
+     * cette adresse ; ceux vers lesquels le navigateur est envoyé restent en `https`.
+     */
+    readonly discoveryUrl?: string | undefined;
 }
 /**
  * Interroge un serveur d'autorisation et rend ses points d'entrée.
@@ -47,7 +70,7 @@ export interface IDiscoveryOptions {
  * d'entrée — la même attaque que le paramètre `iss` couvre au retour (RFC 9207).
  *
  * @param rawIssuer - identifiant d'émetteur tel qu'écrit en configuration.
- * @param options - transport injectable et délai d'attente.
+ * @param options - transport injectable, délai d'attente, adresse de découverte.
  * @returns Les points d'entrée, prêts pour `OAuth2Client`.
  * @throws Error - émetteur mal formé, document introuvable, incomplet, ou `issuer` discordant.
  */

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;