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

package/dist/types/nodefony/service/oauth2.d.ts

@@ -1,4 +1,31 @@
 import { Service, Module } from "nodefony";
+import { type IOAuthDiagnosis } from "../src/oauth/providerDiagnosis.js";
+/**
+ * Ce que la session retient d'un login fédéré pour pouvoir fermer AUSSI la
+ * session du fournisseur (RP-Initiated Logout). Stocké côté serveur ; l'ID
+ * token ne traverse le navigateur qu'une fois, dans l'adresse de déconnexion
+ * (`id_token_hint`), la session locale déjà détruite.
+ *
+ * @remarks L'ID token est une exception assumée à « les jetons du fournisseur
+ * ne sont pas conservés » : il n'ouvre aucun accès (ni API, ni rafraîchissement),
+ * il désigne la session à fermer. Jetons d'accès et de rafraîchissement restent
+ * jetés.
+ */
+export interface IFederatedLogoutHint {
+    /** Fournisseur qui a ouvert la session. */
+    readonly provider: string;
+    /** ID token reçu au login, rejoué en `id_token_hint`. */
+    readonly idToken: string;
+    /** Identifiant de session du fournisseur (claim `sid`), ou `null`. */
+    readonly sid: string | null;
+}
+/** Vue minimale d'une session — celle que porte le contexte. */
+interface IHintSession {
+    get(key: string): unknown;
+    set(key: string, value: unknown): unknown;
+    /** Métadonnée énumérable — absente d'une session réduite (tests). */
+    setMetaBag?(key: string, value: unknown): unknown;
+}
 /**
  * Libellé affichable d'un fournisseur, quand sa configuration n'en donne pas.
  *
@@ -20,6 +47,8 @@ export interface IOAuthDisplayProvider {
     readonly name: string;
     /** Libellé du bouton : celui de la config, sinon dérivé du nom. */
     readonly label: string;
+    /** Image du bouton (`icon` de la config) — absente = icône du framework. */
+    readonly icon?: string;
 }
 /** Données à porter en session entre `authorize` et `callback` (anti-replay). */
 export interface IOAuthAuthorization {
@@ -30,20 +59,40 @@ export interface IOAuthAuthorization {
     /** `code_verifier` PKCE à stocker en session, ou `null` (fournisseur sans PKCE). */
     readonly codeVerifier: string | null;
 }
+/**
+ * Confronte l'émetteur configuré d'un fournisseur à ce que sa fabrique exige.
+ *
+ * Une URL qui ne peut pas être un émetteur est refusée QUEL QUE SOIT le
+ * fournisseur : aucune valeur mal formée n'est une configuration voulue. Une
+ * absence ne l'est que si la fabrique a déclaré l'émetteur requis.
+ *
+ * @param name - nom du fournisseur (`oauth2.providers.<name>`).
+ * @param issuer - émetteur lu dans sa configuration.
+ * @throws BootConfigurationError - émetteur requis absent, ou mal formé.
+ */
+export declare function checkProviderIssuer(name: string, issuer: string | undefined): void;
 /**
  * **Social login OAuth 2.0** (P6 J9) — orchestrateur du flux *Authorization Code*.
  *
  * Posture OAuth 2.1 (RFC 9700) : Authorization Code uniquement (jamais implicit /
  * ROPC), **PKCE S256** quand le fournisseur le supporte (RFC 7636), **state**
- * anti-CSRF, **iss** anti-mix-up (RFC 9207) ; aucun jeton n'atteint le navigateur
- * (le login produit une **session BFF**, gérée hors de ce service par le
- * controller + `AuthFlow`).
+ * anti-CSRF, **iss** anti-mix-up (RFC 9207) ; aucun jeton d'accès n'atteint le
+ * navigateur (le login produit une **session BFF**, gérée hors de ce service par
+ * le controller + `AuthFlow`) — seul l'ID token y passe, une fois, à la
+ * déconnexion ({@link IFederatedLogoutHint}).
  *
- * Les fournisseurs sont construits **au premier login** (cold path — jamais au boot
- * ni par requête) puis mémoïsés : c'est là que les points d'entrée d'un émetteur
- * OIDC sont découverts, une seule fois par processus. Au boot (si `oauth2.enabled`)
- * : seule la config est validée et les fournisseurs configurés sont confrontés au
- * registre (un nom inconnu = WARNING, pas fatal).
+ * Au boot (si `oauth2.enabled`), la configuration de chaque fournisseur est
+ * confrontée à ce que sa fabrique exige : un émetteur requis absent, ou qui n'est
+ * pas une URL d'émetteur valide, INTERROMPT le démarrage en nommant la clé — une
+ * faute d'écriture ne doit pas attendre le premier clic pour se montrer. Un nom
+ * inconnu du registre reste un WARNING.
+ *
+ * Les fournisseurs sont construits une fois puis mémoïsés : c'est là que les
+ * points d'entrée d'un émetteur OIDC sont découverts. Un run qui sert (ports
+ * ouverts) les construit DÈS le boot, sans l'attendre : un émetteur injoignable
+ * n'est pas une faute de configuration, il se journalise et son bouton quitte
+ * l'écran de connexion jusqu'à ce qu'une nouvelle tentative réussisse. Un run
+ * console ne touche jamais le réseau.
  *
  * Le service ne touche **ni HTTP ni session** : il rend à l'appelant les éléments
  * (URL, state, verifier) que le controller persiste en session — testable sans
@@ -78,6 +127,9 @@ declare class OAuth2Service extends Service {
     /**
      * Redirections post-login (succès / échec) — lues par le controller.
      * Surcharge PAR FOURNISSEUR si fournie, sinon valeur globale, sinon défaut.
+     *
+     * @remarks L'échec mène par défaut à la page de connexion (`loginPage.path`) :
+     * déplacer la page déplace la redirection, les deux ne peuvent pas diverger.
      */
     getRedirects(provider?: string): {
         success: string;
@@ -87,9 +139,13 @@ declare class OAuth2Service extends Service {
      * Étape 1 — prépare l'URL d'autorisation + les éléments anti-replay à stocker
      * en session (`state`, et `code_verifier` si PKCE).
      *
+     * @param options.theme - thème rendu par l'application, transmis au seul
+     *   fournisseur qui sait l'afficher (Keycloak) ; les autres l'ignorent
      * @throws AuthenticationError — fournisseur non configuré / inconnu du registre.
      */
-    createAuthorization(provider: string): Promise<IOAuthAuthorization>;
+    createAuthorization(provider: string, options?: {
+        theme?: "light" | "dark";
+    }): Promise<IOAuthAuthorization>;
     /**
      * Étape 2 — valide la réponse, échange le `code`, lit le profil et provisionne
      * l'utilisateur local (Shadow User). Retourne l'identifiant à ouvrir en session.
@@ -100,7 +156,67 @@ declare class OAuth2Service extends Service {
      */
     exchangeAndProvision(provider: string, code: string, codeVerifier: string | null, returnedIss: string | null): Promise<{
         identifier: string;
+        logoutHint: IFederatedLogoutHint | null;
     }>;
+    /**
+     * Retient en session l'indice de déconnexion d'un login fédéré — à appeler
+     * APRÈS l'ouverture de la session authentifiée (l'ID de session est
+     * régénéré à l'ouverture).
+     *
+     * @param session - session authentifiée de la requête.
+     * @param hint - indice rendu par {@link exchangeAndProvision}, ou `null`.
+     */
+    rememberLogout(session: IHintSession, hint: IFederatedLogoutHint | null): void;
+    /**
+     * Adresse de déconnexion chez le fournisseur qui a ouvert la session, ou
+     * `null` : session locale, fournisseur sans point de déconnexion, ou
+     * fournisseur devenu indisponible. À lire AVANT de détruire la session.
+     *
+     * @param session - session courante, ou `null`.
+     * @returns l'URL vers laquelle envoyer le navigateur, ou `null`.
+     */
+    logoutUrlFor(session: IHintSession | null): Promise<string | null>;
+    /**
+     * Déconnexion demandée PAR le fournisseur sur le canal arrière (OpenID
+     * Connect Back-Channel Logout 1.0) : vérifie le jeton, refuse un rejeu, puis
+     * détruit les sessions locales qu'il désigne.
+     *
+     * Une session est désignée si elle a été ouverte par CE fournisseur (index
+     * fédéré posé au login par {@link rememberLogout}) et, selon le jeton : porte son `sid` ; ou,
+     * sans `sid`, appartient à l'utilisateur lié à son `sub`. Une session ouverte
+     * par mot de passe ou par un autre fournisseur n'est jamais touchée — le
+     * fournisseur ne ferme que ce qu'il a ouvert.
+     *
+     * @remarks Les connexions WebSocket portées par une session détruite se
+     * ferment au tick de revalidation du hub temps réel (code `4001`).
+     *
+     * @param provider - fournisseur désigné par l'adresse appelée.
+     * @param logoutToken - paramètre `logout_token` reçu, brut.
+     * @returns `unsupported` si le fournisseur ne sait pas émettre de jeton de
+     *   déconnexion ; `refused` si le jeton est invalide ou rejoué ; sinon le
+     *   nombre de sessions détruites (0 : déjà déconnecté, c'est un succès §2.7).
+     * @throws Error - vérification impossible (jeu de clés injoignable) ou
+     *   sessions impossibles à parcourir : la déconnexion a ÉCHOUÉ.
+     */
+    backchannelLogout(provider: string, logoutToken: string): Promise<{
+        readonly outcome: "unsupported" | "refused";
+    } | {
+        readonly outcome: "done";
+        readonly destroyed: number;
+    }>;
+    /**
+     * Diagnostique les fournisseurs CONFIGURÉS sans connexion humaine : découverte
+     * et émetteur, URL de retour acceptée, secret accepté (cf
+     * `diagnoseOAuthProvider`).
+     *
+     * Le fournisseur est construit à NEUF, hors de la mémoïsation du login : un
+     * diagnostic doit voir le serveur tel qu'il est maintenant, et son échec ne
+     * doit pas retirer un bouton de l'écran de connexion.
+     *
+     * @param name - un seul fournisseur ; à défaut, tous ceux de la configuration.
+     * @returns un diagnostic par fournisseur ; vide si le social login est éteint.
+     */
+    diagnose(name?: string): Promise<IOAuthDiagnosis[]>;
 }
 export default OAuth2Service;
 export { OAuth2Service };

package/dist/types/nodefony/service/tokenService.d.ts

@@ -1,6 +1,7 @@
 import { Service, Module } from "nodefony";
 import type * as Jose from "jose";
 import type { IUser } from "@nodefony/user";
+import type { ICredentialTransportContext } from "../src/transport/CredentialTransportPolicy.js";
 /**
  * Réponse d'émission de jetons — nommage RFC 6749 §5.1 (snake_case, JSON).
  * Le JWT part en `Authorization: Bearer`, JAMAIS en cookie ni en URL.
@@ -76,10 +77,15 @@ declare class TokenService extends Service {
      * Émet un couple access/refresh après vérification d'un credential
      * identifiant/mot de passe (grant M2M/CLI). Throttling NIST partagé si activé.
      *
+     * @param context - requête HTTP qui porte le credential. Présente, elle
+     *   soumet l'appel au refus du clair en production ; absente (CLI, appel
+     *   programmatique), il n'y a pas de transport à juger. Un endpoint HTTP DOIT
+     *   la passer.
+     * @throws InsecureTransportError (403) — credential reçu en clair en production.
      * @throws ThrottledError (429) — backoff actif.
      * @throws AuthenticationError (401, message uniforme) — credential invalide.
      */
-    issueForCredentials(identifier: unknown, password: unknown, requestedScopes?: string[], resource?: unknown): Promise<ITokenResponse>;
+    issueForCredentials(identifier: unknown, password: unknown, requestedScopes?: string[], resource?: unknown, context?: ICredentialTransportContext): Promise<ITokenResponse>;
     issueTokens(user: IUser, requestedScopes?: string[], resource?: unknown, accessTtlS?: number): Promise<ITokenResponse>;
     /**
      * Rotation d'un refresh token (RFC 9700 §4.14) : valide le refresh présenté,

package/dist/types/nodefony/service/totp.d.ts

@@ -27,12 +27,36 @@ declare class TotpService extends Service {
     isEnabled(): boolean;
     /** Démarre l'enrôlement (secret + QR affichés 1×). */
     beginEnrollment(userId: string, account: string): Promise<ITotpEnrollment>;
-    /** Confirme l'enrôlement par un 1ᵉʳ code → active + codes de récupération clairs. */
-    confirmEnrollment(userId: string, code: string): Promise<ITotpActivation>;
+    /**
+     * Confirme l'enrôlement par un 1ᵉʳ code → active + codes de récupération clairs.
+     *
+     * Activer un second facteur est un geste de SÉCURITÉ : il est audité ici
+     * (`user.totp_enabled`), avec la requête qui l'a porté — sans trace, un facteur
+     * posé à l'insu du titulaire ne se retrouve pas.
+     *
+     * @param userId - compte dont on active le 2FA (le porteur de la session).
+     * @param code - premier code de l'application d'authentification.
+     * @param context - contexte de la requête (IP, navigateur, identifiant de
+     *   requête) recopié dans l'événement d'audit ; absent, l'événement part sans.
+     * @returns les codes de récupération, affichés une seule fois.
+     * @throws quand le code est faux, l'enrôlement absent ou déjà confirmé.
+     */
+    confirmEnrollment(userId: string, code: string, context?: unknown): Promise<ITotpActivation>;
     /** Vérifie un second facteur au login (code TOTP ou code de récupération). */
     verifyLogin(userId: string, code: string): Promise<ITotpLoginResult>;
-    /** Désactive le 2FA d'un utilisateur. */
-    disable(userId: string): Promise<void>;
+    /**
+     * Désactive le 2FA d'un utilisateur.
+     *
+     * Avec un `context`, c'est le TITULAIRE qui retire son facteur (porte
+     * libre-service) : le geste est audité ici (`user.totp_disabled`). Sans
+     * contexte, l'appelant porte lui-même l'audit — le plan d'administration le
+     * fait avec l'identité de l'administrateur (`viaAdmin`), qu'ici on ignore.
+     * Un seul événement par geste, jamais deux.
+     *
+     * @param userId - compte dont on retire le 2FA.
+     * @param context - contexte de la requête du titulaire (audit libre-service).
+     */
+    disable(userId: string, context?: unknown): Promise<void>;
     /** État 2FA d'un utilisateur (absent / pending / activé + codes restants). */
     status(userId: string): Promise<ITotpStatus>;
     /**

package/dist/types/nodefony/service/webAuthn.d.ts

@@ -5,13 +5,35 @@ import type { IWebAuthnCredential } from "../contracts/IWebAuthnCredential.js";
 import type { IWebAuthnCredentialSummary, IWebAuthnListQuery } from "../contracts/IWebAuthnCredentialStore.js";
 /** Sujet d'une cérémonie d'enregistrement — l'utilisateur qui crée un passkey. */
 export interface IWebAuthnUser {
-    /** Identifiant applicatif stable (sub / username) — devient le `userHandle`. */
+    /**
+     * Clé de propriétaire = `IUser.identifier` — range les credentials
+     * (`findByUser`), cf `IWebAuthnCredentialStore`. N'est PAS le `userHandle`.
+     */
     readonly id: string;
+    /**
+     * Source du `userHandle` WebAuthn : l'`IUser.id` (UUID) du compte. WebAuthn
+     * L3 (§4, « User Handle ») l'exige opaque, d'au plus 64 octets, et « MUST NOT
+     * contain personally identifying information » — l'identifiant de connexion,
+     * souvent un email, est donc exclu. Omis (ou trop long), le handle est le
+     * condensat SHA-256 de {@link IWebAuthnUser.id} : 32 octets, jamais l'identifiant
+     * en clair. Le handle n'est jamais relu par le serveur — l'authentification
+     * retrouve le compte par l'id du credential stocké.
+     */
+    readonly handle?: string;
     /** Nom de compte affiché par l'OS (email, identifiant…). */
     readonly name: string;
     /** Nom complet optionnel (UX de l'invite système). */
     readonly displayName?: string;
 }
+/**
+ * Octets du `userHandle` d'une cérémonie d'enregistrement — opaques, bornés, sans
+ * donnée personnelle (cf {@link IWebAuthnUser.handle}).
+ *
+ * @param user - sujet de la cérémonie.
+ * @returns `handle` encodé s'il est fourni et tient en 64 octets, sinon le
+ *   condensat SHA-256 de l'`id`.
+ */
+export declare function userHandleBytes(user: IWebAuthnUser): Uint8Array<ArrayBuffer>;
 /** Résultat d'une authentification WebAuthn vérifiée. */
 export interface IWebAuthnAssertionResult {
     /** Le credential résolu (état déjà mis à jour : compteur, sauvegarde, usage). */

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

@@ -9,6 +9,7 @@ import type { ISecurityAreaConfig } from "../config/defineModuleConfig.js";
  * spécificité au boot.
  */
 export declare class SecuredArea implements ISecuredArea {
+    #private;
     readonly name: string;
     readonly pattern: RegExp;
     readonly security: boolean;
@@ -18,6 +19,9 @@ export declare class SecuredArea implements ISecuredArea {
     readonly host?: string | undefined;
     readonly realtime: boolean;
     readonly resource?: string | undefined;
+    readonly entryPoint?: string | undefined;
+    readonly subjectPolicy?: "require" | "ephemeral" | undefined;
+    readonly ephemeralRoles?: readonly string[] | undefined;
     /**
      * Rôles exigés par défaut dans la zone, ou `null` quand elle n'en exige
      * aucun. `null` plutôt qu'un tableau vide : le hot path teste une référence,

package/dist/types/nodefony/src/admin/userRevocationCascade.d.ts

@@ -1,31 +1,73 @@
-import type { Container } from "nodefony";
+import type { Container, IBootNotice } from "nodefony";
 import { type IUserRevokedEvent } from "@nodefony/user";
+/** Résolution d'un service par nom — tout ce que la purge demande au container. */
+interface ServiceLookupLike {
+    get(name: string): unknown;
+}
 /** Bus d'événements minimal (kernel) capable d'abonner un handler. */
 interface KernelListenerLike {
-    on(event: string, handler: (...args: unknown[]) => void): unknown;
+    on(event: string, handler: (...args: unknown[]) => unknown): unknown;
 }
 /**
  * Cascade de révocation déclenchée par {@link USER_REVOKED_EVENT} : éjecte
  * **immédiatement** les artefacts d'accès du porteur — ses **sessions** (http,
  * `destroyByUser`) et ses **jetons/PAT** (`tokenStore.revokeAllForSubject`,
- * seuil `invalidBefore`). Best-effort par brique (une indispo n'empêche pas
- * l'autre) — l'accès était DÉJÀ neutralisé par le re-fetch des authenticators,
- * cette cascade est de la **propreté + défense en profondeur**, jamais l'unique
- * rempart. `tenantId` du payload est réservé (scoping non câblé en mono-tenant).
+ * seuil `invalidBefore`, qui couvre aussi les clés d'API). Best-effort par
+ * brique (une indispo n'empêche pas l'autre) — l'accès était DÉJÀ neutralisé par
+ * le re-fetch des authenticators. `tenantId` du payload est réservé (scoping non
+ * câblé en mono-tenant).
+ *
+ * **Suppression du compte** (`reason: "deleted"`) : retire AUSSI ses facteurs —
+ * secret TOTP (codes de récupération compris) et passkeys. Ils sont rangés sous
+ * l'`identifier`, qu'un compte recréé peut reprendre : laissés en place, le
+ * nouveau titulaire hériterait du second facteur de l'ancien. Un compte
+ * seulement désactivé ou verrouillé les GARDE — il les retrouve à sa
+ * réactivation.
  *
- * @param container - container du kernel (résolution lazy de `sessions`/`tokenStore`).
+ * @param container - container du kernel (résolution lazy de `sessions`, `tokenStore`, `totp`, `webauthn`).
  * @param event - charge utile de l'événement (porteur + raison).
  * @param now - horloge (epoch ms) injectable pour les tests.
  */
 export declare function cascadeUserRevocation(container: Container, event: IUserRevokedEvent, now?: number): Promise<void>;
 /**
- * Abonne la cascade au bus kernel. À appeler au `onKernelBoot` d'un module
- * bootable (ici `@nodefony/security`). **Extensible** : tout autre module
- * (webhooks…) peut s'abonner au MÊME `USER_REVOKED_EVENT` pour ses propres
- * artefacts, sans toucher à ce fichier.
+ * Retire les facteurs rangés sous un identifiant — secret TOTP (codes de
+ * récupération compris) et passkeys. SEULE implémentation du geste, appelée à
+ * la suppression d'un compte ET à la création d'un compte sous cet identifiant.
+ * Best-effort par brique : un TOTP indisponible n'empêche pas le retrait des
+ * passkeys.
+ *
+ * @param container - container du kernel (services `totp`, `webauthn`).
+ * @param identifier - `IUser.identifier` du compte.
+ */
+export declare function removeAccountFactors(container: ServiceLookupLike, identifier: string): Promise<void>;
+/**
+ * Abonne la cascade au bus kernel, UNE fois, au `onKernelBoot` de
+ * `@nodefony/security` — avant qu'aucun compte ne puisse être créé ou révoqué
+ * (les comptes semés au démarrage compris). Deux abonnements :
+ *  - {@link USER_REVOKED_EVENT} → {@link cascadeUserRevocation} ;
+ *  - {@link USER_CREATED_EVENT} → purge des facteurs HÉRITÉS : un compte qui
+ *    vient de naître n'a encore rien enrôlé, donc tout facteur déjà rangé sous
+ *    son identifiant appartient à un ancien titulaire. Règle exacte, aucune
+ *    date à comparer. ⚠️ Un import qui chargerait les facteurs AVANT les
+ *    comptes les verrait retirés : importer les comptes d'abord.
+ *
+ * Les deux sont émis par `UserService` seul, et attendus : chaque handler rend
+ * sa promesse. **Extensible** : tout autre module (webhooks…) s'abonne aux
+ * MÊMES événements pour ses propres artefacts, sans toucher à ce fichier.
  *
  * @param kernel - bus d'événements (kernel) exposant `on`.
- * @param container - container capturé par le handler.
+ * @param container - container capturé par les handlers.
  */
 export declare function registerUserRevocationCascade(kernel: KernelListenerLike, container: Container): void;
+/**
+ * Avis de démarrage quand le service `users` n'émet pas sur le bus du kernel —
+ * construit sans container (`new UserService(repo, encoder)`). Ses événements
+ * partent alors sur son propre bus, où personne n'écoute : supprimer un compte
+ * laisserait ses sessions, ses jetons et ses facteurs en place, SANS UN MOT.
+ *
+ * @param container - container du kernel.
+ * @param kernel - le kernel attendu comme bus des événements.
+ * @returns l'avis à déclarer, ou `null` si `users` est absent ou bien câblé.
+ */
+export declare function usersEventBusNotice(container: ServiceLookupLike, kernel: object): IBootNotice | null;
 export {};

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

@@ -4,6 +4,7 @@ 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";
+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. */
@@ -28,6 +29,23 @@ export interface IExternalJwtAuthenticatorOptions {
     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;
+    }[];
 }
 /**
  * Authentification par **jeton d'accès émis par un serveur d'autorisation

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

@@ -62,6 +62,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/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/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/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.
  */