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

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

@@ -0,0 +1,115 @@
+import { Service, Module } from "nodefony";
+import type { LoginPageSkin } from "nodefony";
+import type { ISecurityConfig } from "../config/config.js";
+import { KeycloakAdminClient, type IKeycloakLoginThemeResult } from "../keycloak/keycloakAdmin.js";
+/** Ce qu'on demande au realm dérivé. */
+export interface IKeycloakRealmRequest {
+    /** Nom dans `oauth2.providers` (défaut `keycloak`). */
+    readonly provider?: string | undefined;
+    /** Fichier d'import, relatif à la racine de l'application ou absolu. */
+    readonly file?: string | undefined;
+    /** Client machine dont l'audience suit la config. */
+    readonly machine?: string | undefined;
+    /** Origine par laquelle Keycloak joint l'application (canal arrière). */
+    readonly backchannelOrigin?: string | undefined;
+}
+/** Le realm que la configuration implique, confronté au fichier d'import. */
+export interface IKeycloakRealmPlan {
+    /** Fichier d'import visé (chemin natif absolu). */
+    readonly file: string;
+    /** Contenu actuel du fichier, `null` s'il n'existe pas. */
+    readonly current: string | null;
+    /** Le realm fusionné, tel qu'il serait écrit. */
+    readonly text: string;
+    /** Constats à DIRE (le realm reste écrivable). */
+    readonly warnings: readonly string[];
+    /** `true` si le fichier porte déjà exactement {@link text}. */
+    readonly upToDate: boolean;
+}
+/**
+ * Service `keycloak` — toutes les actions de Nodefony sur un serveur Keycloak,
+ * en un point du conteneur.
+ *
+ * - **le realm** que la configuration implique : dérivé, fusionné avec le
+ *   fichier d'import existant, comparé, écrit ({@link realmPlan},
+ *   {@link writeRealm}) ;
+ * - **l'API d'administration** d'un realm vivant ({@link admin}), et ce qui s'y
+ *   fait : le thème de connexion qui suit `loginPage.skin`
+ *   ({@link applyLoginTheme}).
+ *
+ * Les commandes `security:keycloak:*` et les routes de développement
+ * l'appellent ; elles ne gardent que l'affichage. Seule la contribution de
+ * scaffold (`create app`, `scaffold:sync`) appelle les fonctions pures en
+ * direct : elle tourne SANS démarrer l'application, donc sans conteneur.
+ *
+ * Rien n'est construit au démarrage : la configuration est lue à l'appel, et
+ * les clients d'administration (un par fournisseur, jeton gardé) au premier
+ * usage.
+ */
+declare class KeycloakService extends Service {
+    #private;
+    module: Module;
+    constructor(module: Module);
+    /**
+     * La configuration de sécurité VALIDÉE, relue à chaque appel (chemin froid).
+     *
+     * @returns la configuration
+     */
+    config(): ISecurityConfig;
+    /**
+     * Le realm que la configuration implique, fusionné avec le fichier d'import.
+     *
+     * Le realm d'import répète ce que la config dit déjà (client, URL de retour,
+     * audiences, rôles de `roleMapping`) : écrit à la main, il diverge. Ce plan
+     * le DÉRIVE, puis le fusionne pour que ce qu'un humain a ajouté survive
+     * (comptes, titres, secret machine, mappers posés dans la console).
+     *
+     * @param request - fournisseur, fichier, client machine, canal arrière
+     * @returns le fichier, son contenu, le realm à écrire et les constats
+     * @throws {KeycloakRealmError} Fournisseur absent ou mal décrit, fichier qui
+     *   n'est pas un realm
+     */
+    realmPlan(request?: IKeycloakRealmRequest): IKeycloakRealmPlan;
+    /**
+     * Écrit le realm d'un plan — rien si le fichier est déjà à jour.
+     *
+     * ⚠️ Keycloak n'importe un realm qu'à sa CRÉATION : un realm déjà présent ne
+     * relit pas ce fichier ({@link applyLoginTheme} pour le thème, import
+     * partiel dans la console pour le reste).
+     *
+     * @param plan - le rendu de {@link realmPlan}
+     * @returns `true` si le fichier a été écrit
+     */
+    writeRealm(plan: IKeycloakRealmPlan): boolean;
+    /**
+     * Le client de l'API d'administration d'un fournisseur Keycloak.
+     *
+     * @param providerName - nom dans `oauth2.providers` (défaut `keycloak`)
+     * @returns le client, construit au premier appel puis gardé (jeton réutilisé)
+     * @throws {KeycloakAdminError} Hors développement, fournisseur absent, sans
+     *   émetteur ou sans compte d'administration
+     */
+    admin(providerName?: string): KeycloakAdminClient;
+    /**
+     * Le thème de connexion qu'un habillage demande à Keycloak.
+     *
+     * @param skin - habillage ; défaut : `loginPage.skin` de la configuration
+     * @returns `nodefony` ou `nodefony-<habillage>`
+     */
+    expectedLoginTheme(skin?: LoginPageSkin): string;
+    /**
+     * Pose sur le realm VIVANT le thème de connexion d'un habillage.
+     *
+     * @param options - fournisseur (défaut `keycloak`) et habillage (défaut :
+     *   `loginPage.skin` ; un aperçu de `/login` passe le sien)
+     * @returns le thème d'avant, celui demandé, et ce qui a été fait
+     * @throws {KeycloakAdminError} Hors développement, compte absent ou refusé,
+     *   Keycloak injoignable
+     */
+    applyLoginTheme(options?: {
+        provider?: string;
+        skin?: LoginPageSkin;
+    }): Promise<IKeycloakLoginThemeResult>;
+}
+export { KeycloakService };
+export default KeycloakService;

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,60 @@ 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;
+/**
+ * Annonce qu'un annuaire accorde des rôles de PLATEFORME, à la sévérité de
+ * l'environnement — ou `null` quand il n'y a rien à dire.
+ *
+ * L'ouverture est ÉCRITE (`allowPlatformRoles`), donc voulue : l'annonce ne
+ * la conteste pas, elle la rappelle. Le risque — un annuaire compromis
+ * administre l'instance — n'est réel qu'en production : là, `WARNING` ;
+ * ailleurs le même fait est dit en `INFO`, sans sonner une alarme à chaque
+ * démarrage d'un décor de développement.
+ *
+ * @param name - nom du fournisseur (`oauth2.providers.<name>`).
+ * @param allowed - `allowPlatformRoles` tel que déclaré.
+ * @param granted - rôles de l'application que la table accorde.
+ * @param production - l'application tourne en production.
+ * @returns le message et sa sévérité, ou `null`.
+ */
+export declare function platformRolesNotice(name: string, allowed: boolean | undefined, granted: readonly string[], production: boolean): {
+    message: string;
+    severity: "WARNING" | "INFO";
+} | null;
 /**
  * **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}).
+ *
+ * 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 **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).
+ * 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 +147,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 +159,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 +176,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/accountBinding.d.ts

@@ -0,0 +1,82 @@
+import type { IUser, IUserProvider } from "@nodefony/user";
+/**
+ * Claim d'un jeton d'accès émis par l'application qui porte l'identifiant
+ * IMMUABLE du compte (`IUser.id`) — `sub` porte l'identifiant fonctionnel.
+ */
+export declare const ACCOUNT_ID_CLAIM = "uid";
+/**
+ * Clé, dans `metadata` d'un enregistrement de jeton (refresh, clé d'API) comme
+ * dans le `metaBag` d'une session, qui porte l'identifiant immuable du compte.
+ */
+export declare const ACCOUNT_ID_KEY = "accountId";
+/**
+ * Claim d'un jeton d'accès émis par l'application qui porte la version des
+ * identifiants du compte à l'émission (`IUser.credentialsVersion`).
+ */
+export declare const CREDENTIALS_VERSION_CLAIM = "cv";
+/**
+ * Clé, dans `metadata` d'un enregistrement de jeton comme dans le `metaBag`
+ * d'une session, qui porte la version des identifiants lue à l'émission.
+ */
+export declare const CREDENTIALS_VERSION_KEY = "credentialsVersion";
+/**
+ * La version des identifiants à inscrire dans un artefact qu'on émet pour ce
+ * compte — 0 quand le compte n'en porte pas encore.
+ *
+ * @param user - compte pour lequel l'artefact est émis.
+ * @returns la version courante, jamais `null`.
+ */
+export declare function credentialsVersionOf(user: IUser): number;
+/**
+ * Dit si un artefact d'accès (jeton, session, clé) appartient bien au compte
+ * qu'on vient de recharger par son identifiant fonctionnel, ET s'il a été émis
+ * depuis le dernier changement de mot de passe.
+ *
+ * Les artefacts sont rangés sous l'`identifier`, qu'un compte RECRÉÉ peut
+ * reprendre : supprimé hors du framework (`DELETE` SQL, restauration, import)
+ * puis revenu sous le même nom, l'identité se rechargerait et l'artefact de
+ * l'ancien titulaire ouvrirait le compte du nouveau. L'identifiant immuable
+ * lève l'ambiguïté sans dépendre d'aucun événement ni d'aucun stockage : deux
+ * comptes successifs portent deux `id` différents. SEULE règle de
+ * comparaison — chaque authentificateur l'appelle, aucun ne la recopie.
+ *
+ * Un artefact SANS liaison est refusé : il a été émis avant que la règle
+ * existe, et rien ne dit à qui il appartient.
+ *
+ * La version des identifiants fait de la coupure au changement de mot de passe
+ * un ÉTAT du compte, et non une suppression : si la cascade de révocation
+ * échoue, ou si une requête en vol sur un autre processus réécrit la session
+ * qu'on vient d'effacer, l'artefact porte toujours l'ancienne version, et il
+ * tombe ici. Un artefact émis avant cette règle n'en porte pas : il vaut 0,
+ * comme un compte qui n'a jamais changé de mot de passe — le déploiement ne
+ * déconnecte personne. Une valeur d'un autre type est refusée.
+ *
+ * ⚠️ Chemin chaud — appelée sur CHAQUE requête authentifiée : deux comparaisons
+ * de chaîne et d'entier, aucune allocation.
+ *
+ * @param user - compte rechargé par l'identifiant que porte l'artefact.
+ * @param boundAccountId - identifiant immuable inscrit dans l'artefact.
+ * @param boundCredentialsVersion - version des identifiants inscrite dans
+ *   l'artefact ({@link CREDENTIALS_VERSION_KEY}), `undefined` si absente.
+ *   Obligatoire dans la signature pour qu'aucune porte ne l'oublie.
+ * @returns `true` si l'artefact a été émis pour CE compte, à sa version courante.
+ */
+export declare function isBoundToAccount(user: IUser, boundAccountId: unknown, boundCredentialsVersion: unknown): boolean;
+/**
+ * Recharge le compte qu'un jeton d'accès de CETTE application désigne, ou
+ * `null` : sujet inconnu, compte inactif ou verrouillé, jeton émis pour un
+ * autre compte du même nom ou avant un changement de mot de passe.
+ *
+ * SEULE implémentation de la règle « ce jeton ouvre-t-il encore ce compte ? »
+ * pour un jeton maison : la zone `jwt` (`JwtAuthenticator`) et le résolveur de
+ * compte d'une ressource protégée l'appellent, aucun ne la recopie. Un refus
+ * est `null`, jamais une exception : chaque appelant le traduit dans son
+ * propre contrat (401 uniforme, outil en `isError`).
+ *
+ * @param provider - annuaire des comptes de l'application.
+ * @param identifier - identifiant fonctionnel porté par le jeton (`sub`).
+ * @param boundAccountId - identifiant immuable inscrit dans le jeton ({@link ACCOUNT_ID_CLAIM}).
+ * @param boundCredentialsVersion - version des identifiants inscrite ({@link CREDENTIALS_VERSION_CLAIM}).
+ * @returns le compte, ou `null` s'il n'est pas (ou plus) celui du jeton.
+ */
+export declare function loadBoundAccount(provider: IUserProvider, identifier: string, boundAccountId: unknown, boundCredentialsVersion: unknown): Promise<IUser | null>;

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

@@ -1,31 +1,91 @@
-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.
+ * Purge, à la NAISSANCE d'un compte, tout ce qu'un ancien titulaire du même
+ * identifiant a laissé derrière lui : sessions, jetons et facteurs. Un compte
+ * qui vient de naître n'a encore rien émis — tout artefact déjà rangé sous son
+ * identifiant appartient donc à quelqu'un d'autre. C'est ce qui ferme le cas
+ * d'un compte supprimé HORS du framework (`DELETE` SQL, aucun événement), dont
+ * l'accès redeviendrait valide dès qu'un compte renaît sous son nom.
+ *
+ * Le seuil est tronqué à la SECONDE : l'`iat` d'un JWT l'est aussi (RFC 7519
+ * §2, NumericDate), et un seuil à la milliseconde rejetterait le jeton du
+ * nouveau titulaire émis dans la même seconde que sa création.
+ *
+ * @param container - container du kernel.
+ * @param identifier - `IUser.identifier` du compte créé.
+ * @param now - horloge (epoch ms) injectable pour les tests.
+ */
+export declare function purgeInheritedAccess(container: ServiceLookupLike, identifier: string, now?: number): Promise<void>;
+/**
+ * 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} → {@link purgeInheritedAccess} : sessions,
+ *    jetons et facteurs HÉRITÉS. Un compte qui vient de naître n'a encore rien
+ *    émis ni enrôlé, donc tout artefact 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 {};