@nodefony/user 10.0.0-alpha.1

package/dist/types/nodefony/contracts/IUserRepository.d.ts

@@ -0,0 +1,129 @@
+import type { IRepository } from "@nodefony/orm-core";
+import type { IPage, IPageQuery, ISortableSource } from "nodefony";
+import type { IPasswordAuthenticatedUser } from "./IUser.js";
+/**
+ * Requête de **listing paginé** d'utilisateurs — le contrat de page standard du
+ * core ({@link IPageQuery}) enrichi des filtres propres à l'utilisateur.
+ *
+ * Ces filtres ne sont **pas portables** au `Criteria` générique de l'ORM (d'où un
+ * `listPage` natif par backend, pas un `paginate()` générique) :
+ * - `role` = appartenance dans le tableau **plat JSON** `roles` (containment :
+ *   `json_each`/`@>`/`JSON_CONTAINS` en SQL, élément de tableau en Mongo) ;
+ * - `q` (hérité) = sous-chaîne **insensible à la casse** sur `identifier`
+ *   (`LOWER(...) LIKE` en SQL, `$regex`/`i` en Mongo) — pas un `$eq`.
+ *
+ * `enabled`, lui, correspond à la colonne `enabled` (= `isActive()`) et serait
+ * portable ; il vit ici pour garder **un seul** objet de filtres du store.
+ */
+export interface IUserListQuery extends IPageQuery {
+    /** Rôle plat devant figurer dans `roles` (containment natif). Omis = tous rôles. */
+    role?: string;
+    /** Restreint à l'état actif (`isActive()`). Omis = actifs ET inactifs. */
+    enabled?: boolean;
+    /**
+     * Restreint aux comptes **verrouillés** (`isLocked()`), ou aux non verrouillés.
+     * Omis = les deux.
+     *
+     * Distinct d'`enabled` : un compte désactivé l'a été par décision
+     * d'administration, un compte verrouillé l'est par un mécanisme de défense
+     * (trop d'échecs d'authentification). Les deux peuvent coexister sur le même
+     * compte — les compter séparément est le seul moyen de savoir lequel des deux
+     * bloque une population.
+     */
+    locked?: boolean;
+    /**
+     * Restreint aux comptes liés à **au moins un fournisseur d'identité externe**
+     * (OAuth), ou à ceux qui n'en ont aucun. Omis = les deux.
+     *
+     * Répond à « combien de comptes dépendent d'un fournisseur tiers ? », question
+     * de gouvernance qu'aucun filtre existant ne posait — la console la calculait
+     * en rapatriant l'annuaire.
+     */
+    hasSocial?: boolean;
+}
+/**
+ * Repository **spécialisé utilisateur** — `IRepository<IPasswordAuthenticatedUser>`
+ * enrichi de finders métier.
+ *
+ * Étend le contrat CRUD portable de `@nodefony/orm-core` (`find`, `create`,
+ * `withTransaction`...) avec les accès propres à l'authentification. Implémenté
+ * une fois par adapter (Mongoose/Drizzle, P5.8–5.9) ; l'ORM concret
+ * reste invisible des consommateurs (DI : `@Inject('repository.user')`).
+ *
+ * ## Écrire un champ MÉTIER de l'application
+ *
+ * Ce contrat est typé sur {@link IPasswordAuthenticatedUser} : `create()` et
+ * `updateOne()` **refusent** en TypeScript un champ que l'application a ajouté à
+ * sa table (`firstName`, `department`…). Ce n'est pas un oubli — le framework ne
+ * connaît que les colonnes de son contrat.
+ *
+ * La porte d'écriture est le **repository générique** de l'entité, obtenu depuis
+ * l'ORM et déjà exercé sur cette table :
+ *
+ * ```typescript
+ * const users = orm.getRepository<MonUtilisateur>("User");
+ * await users.create({ identifier: "carol@example.com", firstName: "Carol" });
+ * ```
+ *
+ * En LECTURE, rien à faire : les dépôts reportent sur l'utilisateur rendu toute
+ * colonne hors contrat, champs métier compris. Un champ écrit se relit donc, quel
+ * que soit le moteur.
+ *
+ * @remarks Type d'entité = {@link IPasswordAuthenticatedUser} (credential inclus),
+ * pas `IUser`. Le repository **est** la frontière de persistance du mot de passe :
+ * seul composant qui lit/écrit le hash (consommé par `UserService` et
+ * `@nodefony/security`). Le split credential protège les consommateurs *en aval*
+ * (framework/authz reçoivent `IUser` via `IUserProvider`), pas la couche de
+ * stockage qui, par nature, manipule le hash.
+ */
+export interface IUserRepository extends IRepository<IPasswordAuthenticatedUser>, ISortableSource {
+    /**
+     * Retrouve un utilisateur par son identifiant fonctionnel (email, login...).
+     *
+     * @param identifier - identifiant unique.
+     * @returns l'utilisateur (credential inclus), ou `null` s'il n'existe pas.
+     */
+    findByIdentifier(identifier: string): Promise<IPasswordAuthenticatedUser | null>;
+    /**
+     * Retrouve un utilisateur lié à un compte d'un fournisseur OAuth/OIDC.
+     *
+     * @param provider - fournisseur (`"google"`, `"github"`...).
+     * @param providerId - identifiant du compte chez le fournisseur.
+     * @returns l'utilisateur lié, ou `null` si aucun lien.
+     */
+    findBySocialProvider(provider: string, providerId: string): Promise<IPasswordAuthenticatedUser | null>;
+    /**
+     * Liste **paginée NATIVEMENT** d'utilisateurs — ne matérialise **jamais** plus
+     * d'une page en mémoire (règle perf/mémoire absolue de Nodefony). Applique les
+     * filtres {@link IUserListQuery} au niveau du store (SQL `WHERE`/`LIMIT/OFFSET`,
+     * Mongo `find/skip/limit`), pas après un chargement complet.
+     *
+     * Tri par défaut = `identifier ASC` (ordre **déterministe** requis par la
+     * pagination offset ; surchargé par `query.order`).
+     *
+     * @param query - filtres + fenêtre de page ({@link IUserListQuery}).
+     * @returns une {@link IPage} : au plus `limit` items, `hasNext`, et `total` si
+     *   `withTotal` n'est pas `false`.
+     */
+    listPage(query: IUserListQuery): Promise<IPage<IPasswordAuthenticatedUser>>;
+    /**
+     * Compte les administrateurs **actifs** (`isActive()` **et** porteurs de
+     * `adminRole`) — garde-fou anti-lockout, calculé **au store** (SQL `COUNT` avec
+     * containment de rôle), jamais en chargeant tous les utilisateurs.
+     *
+     * @param adminRole - rôle d'administration à dénombrer (ex. `ROLE_NODEFONY_ADMIN`).
+     * @returns le nombre d'admins actifs portant ce rôle.
+     */
+    countActiveAdmins(adminRole: string): Promise<number>;
+    /**
+     * Compte les comptes correspondant aux filtres, **sans les énumérer**.
+     *
+     * Alimente les compteurs de tête de la console d'administration, qui portent
+     * sur l'annuaire entier et non sur la page affichée. `limit`/`offset` sont
+     * ignorés : un comptage n'a pas de fenêtre.
+     *
+     * @param query - les filtres seuls ({@link IUserListQuery}).
+     * @returns le nombre de comptes correspondants.
+     */
+    countUsers(query: IUserListQuery): Promise<number>;
+}

package/dist/types/nodefony/contracts/index.d.ts

@@ -0,0 +1,7 @@
+export type { IUser, IPasswordAuthenticatedUser, ISocialProvider, } from "./IUser.js";
+export type { IPasswordBlocklist } from "./IPasswordBlocklist.js";
+export type { IPasswordEncoder } from "./IPasswordEncoder.js";
+export type { IPasswordVerifier } from "./IPasswordVerifier.js";
+export type { IUserProvider } from "./IUserProvider.js";
+export type { IUserRepository, IUserListQuery } from "./IUserRepository.js";
+export type { IOAuthProfile, IOAuthProvisionPolicy, IOAuthUserProvisioner, } from "./IOAuthUserProvisioner.js";

package/dist/types/nodefony/errors/UserNotFoundError.d.ts

@@ -0,0 +1,15 @@
+import { nodefonyError } from "nodefony";
+/**
+ * Utilisateur introuvable dans la source d'identité — levée par les méthodes
+ * {@link IUserProvider} (contrat : jamais `null`, l'absence d'identité est un
+ * échec explicite).
+ *
+ * `code = 404` (sémantique interne). Les authenticators de `@nodefony/security`
+ * la convertissent en `AuthenticationError` générique : le détail (identifiant
+ * inconnu vs mauvais mot de passe) ne doit JAMAIS atteindre le client
+ * (anti-énumération de comptes) — il reste réservé aux logs/audit serveur.
+ */
+export declare class UserNotFoundError extends nodefonyError {
+    constructor(detail: string);
+}
+export default UserNotFoundError;

package/dist/types/nodefony/errors/WeakPasswordError.d.ts

@@ -0,0 +1,12 @@
+import { nodefonyError } from "nodefony";
+/**
+ * Mot de passe refusé par la politique (connu-compromis / interdit) — `code = 400`.
+ *
+ * Levée par `UserService.createUser`/`changePassword` quand le
+ * {@link IPasswordBlocklist} branché rejette le candidat. Le message reste
+ * générique : ni la source de la liste ni le mot de passe ne sont exposés.
+ */
+export declare class WeakPasswordError extends nodefonyError {
+    constructor();
+}
+export default WeakPasswordError;

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

@@ -0,0 +1,179 @@
+import { AbstractCrudService } from "@nodefony/orm-core";
+import type { ServiceWiring } from "@nodefony/orm-core";
+import type { IPage } from "nodefony";
+import { type IUserCounts } from "../src/userFilters.js";
+import type { IUser, IPasswordAuthenticatedUser } from "../contracts/IUser.js";
+import type { IUserListQuery } from "../contracts/IUserRepository.js";
+import type { IPasswordBlocklist } from "../contracts/IPasswordBlocklist.js";
+import type { IPasswordEncoder } from "../contracts/IPasswordEncoder.js";
+import type { IPasswordVerifier } from "../contracts/IPasswordVerifier.js";
+import type { IUserProvider } from "../contracts/IUserProvider.js";
+import type { IUserRepository } from "../contracts/IUserRepository.js";
+import type { IOAuthProfile, IOAuthProvisionPolicy, IOAuthUserProvisioner } from "../contracts/IOAuthUserProvisioner.js";
+/**
+ * Données d'entrée de création d'un utilisateur — le mot de passe est fourni en
+ * **clair** puis haché par {@link UserService.createUser} (jamais persisté tel quel).
+ */
+export interface ICreateUserInput {
+    /** Identifiant fonctionnel (email, login...). Unique. */
+    identifier: string;
+    /** Mot de passe en clair, ou `null`/absent pour un compte sans credential local. */
+    plainPassword?: string | null;
+    /** Rôles plats initiaux. Défaut : `[]`. */
+    roles?: string[];
+}
+/** Raison d'un échec d'authentification (émise avec `onAuthenticationFailure`). */
+export type AuthFailureReason = "unknown_identifier" | "disabled" | "locked" | "no_password" | "bad_credentials";
+/**
+ * Service applicatif **utilisateur** — CRUD haché + authentification + events de cycle de vie.
+ *
+ * Spécialisation d'{@link AbstractCrudService} sur l'entité utilisateur : hérite du
+ * CRUD générique (`find`/`findOne`/`findById`/`count`/`create`/`update`/`delete` +
+ * events `onCreated`/`onUpdated`/`onDeleted`) et n'ajoute que le **spécifique
+ * credential** : hachage à la création (`createUser`), changement de mot de passe
+ * (`changePassword`), recherche par identifiant fonctionnel et authentification.
+ *
+ * Singleton DI stateless (cf {@link AbstractCrudService}) : aucun état par requête
+ * (le credential est lu depuis le repository, le hash leurre est un cache immuable).
+ *
+ * Events propres (en plus des events CRUD hérités) : `onPasswordChanged`,
+ * `onAuthenticated`, `onAuthenticationFailure` (avec {@link AuthFailureReason}).
+ *
+ * @typeParam — fixé : `T = IPasswordAuthenticatedUser` (le repository est la
+ *   frontière credential), `R = IUserRepository` (conserve les finders métier).
+ */
+export declare class UserService extends AbstractCrudService<IPasswordAuthenticatedUser, IUserRepository> implements IUserProvider, IPasswordVerifier, IOAuthUserProvisioner {
+    #private;
+    protected readonly encoder: IPasswordEncoder;
+    /**
+     * Liste de blocage des mots de passe compromis (NIST SP 800-63B §5.1.1.2) —
+     * hook opt-in consulté à la création/changement (jamais au login). `null`
+     * par défaut : le framework fournit le point d'extension, l'application
+     * branche sa source (top-10k, fichier, API k-anonymity).
+     */
+    passwordBlocklist: IPasswordBlocklist | null;
+    /**
+     * @param repository - source de persistance des utilisateurs (credential inclus).
+     * @param encoder - encodeur de mot de passe (hash/verify/needsRehash).
+     * @param wiring - câblage Service ({@link ServiceWiring}) — quasi toujours omis.
+     */
+    constructor(repository: IUserRepository, encoder: IPasswordEncoder, ...wiring: ServiceWiring);
+    /**
+     * Crée un utilisateur — hache le mot de passe en clair s'il est fourni, puis
+     * délègue au `create` générique (hooks + event `onCreated`).
+     *
+     * @param input - identité + mot de passe en clair optionnel + rôles.
+     * @returns l'utilisateur persisté (id généré, hash stocké).
+     */
+    createUser(input: ICreateUserInput): Promise<IPasswordAuthenticatedUser>;
+    /**
+     * Charge un utilisateur par son identifiant fonctionnel (email, login...).
+     *
+     * @param identifier - identifiant unique.
+     * @returns l'utilisateur, ou `null`.
+     */
+    findByIdentifier(identifier: string): Promise<IPasswordAuthenticatedUser | null>;
+    /**
+     * Liste **paginée nativement** d'utilisateurs (filtres role/enabled/q) — délègue
+     * au repository, qui ne matérialise jamais plus d'une page. À préférer
+     * systématiquement à `find()` pour tout listing (data plane admin, écran).
+     *
+     * @param query - filtres + fenêtre de page.
+     * @returns une page d'utilisateurs ({@link IPage}).
+     */
+    listPage(query: IUserListQuery): Promise<IPage<IPasswordAuthenticatedUser>>;
+    /**
+     * Champs de tri que le repository **actuellement branché** sait honorer.
+     *
+     * La capacité se CONSTATE au runtime plutôt que de se déduire : un adapter
+     * tiers qui ne trierait pas rend une liste vide, et le data plane refuse alors
+     * tout `?order=` (400) au lieu de servir une page dans un ordre arbitraire.
+     *
+     * @returns les champs triables, liste vide si le repository ne trie pas.
+     */
+    sortableFields(): readonly string[];
+    /**
+     * Compte les administrateurs actifs porteurs de `adminRole` — garde-fou
+     * anti-lockout calculé au store (jamais en chargeant tous les utilisateurs).
+     *
+     * @param adminRole - rôle d'administration à dénombrer.
+     * @returns le nombre d'admins actifs.
+     */
+    countActiveAdmins(adminRole: string): Promise<number>;
+    /**
+     * Les compteurs de tête de la console — posés sur l'annuaire ENTIER, pas sur
+     * la page affichée.
+     *
+     * Les populations se **recoupent** (un compte peut être désactivé ET
+     * verrouillé, un administrateur peut avoir un lien social) : chacune est
+     * comptée, aucune n'est déduite d'une autre.
+     *
+     * `admins` est composé ici et non déclaré dans {@link USER_FACETS} : le rôle
+     * d'administration est une valeur de configuration, pas une constante du
+     * vocabulaire — l'inscrire dans la table figerait `ROLE_NODEFONY_ADMIN` pour
+     * une plateforme qui peut le renommer.
+     *
+     * @param adminRole - rôle d'administration à dénombrer.
+     * @param query - filtres à appliquer avant comptage (sans fenêtre).
+     */
+    countUserFacets(adminRole: string, query?: Partial<IUserListQuery>): Promise<IUserCounts>;
+    /**
+     * Change le mot de passe d'un utilisateur — hache le clair avant persistance.
+     *
+     * Distinct du `update` générique : émet l'event credential `onPasswordChanged`,
+     * pas `onUpdated`.
+     *
+     * @param id - identifiant interne ciblé.
+     * @param plainPassword - nouveau mot de passe en clair.
+     * @returns l'utilisateur mis à jour, ou `null`.
+     */
+    changePassword(id: string, plainPassword: string): Promise<IPasswordAuthenticatedUser | null>;
+    /**
+     * Authentifie par identifiant + mot de passe.
+     *
+     * Vérifie l'existence, l'état du compte (actif, non verrouillé), la présence d'un
+     * credential local, puis le mot de passe. Au succès, re-hache de façon transparente
+     * si le coût stocké est obsolète ({@link IPasswordEncoder.needsRehash}). **Tous** les
+     * chemins d'échec (identifiant inconnu, compte verrouillé/désactivé, compte sans
+     * password, mauvais mot de passe) consomment exactement une opération de hachage
+     * (vérification réelle ou hash leurre) pour niveler le temps de réponse : le message
+     * 401 est uniforme, le timing doit l'être aussi (anti énumération de comptes, OWASP).
+     *
+     * @param identifier - identifiant fonctionnel saisi.
+     * @param plain - mot de passe en clair saisi.
+     * @returns l'utilisateur authentifié, ou `null` en cas d'échec. Émet
+     *   `onAuthenticated` (succès) ou `onAuthenticationFailure` (échec + raison).
+     */
+    authenticate(identifier: string, plain: string): Promise<IPasswordAuthenticatedUser | null>;
+    /**
+     * {@inheritDoc IUserProvider.loadUserByIdentifier}
+     */
+    loadUserByIdentifier(identifier: string): Promise<IUser>;
+    /**
+     * {@inheritDoc IUserProvider.loadUserByOAuth}
+     *
+     * @remarks Pas de provisionnement *Shadow User* ici : la création de la ligne
+     * locale au premier login externe est portée par `provisionOAuthUser()`, que
+     * `OAuth2Service.exchangeAndProvision()` (`@nodefony/security`) appelle après
+     * l'échange du code — le provider, lui, ne fait que lire.
+     */
+    loadUserByOAuth(provider: string, providerId: string): Promise<IUser>;
+    /**
+     * {@inheritDoc IUserProvider.refreshUser}
+     */
+    refreshUser(user: IUser): Promise<IUser>;
+    /**
+     * {@inheritDoc IOAuthUserProvisioner.provisionOAuthUser}
+     *
+     * @remarks Implémentation **par défaut** (find-or-create) : lit le lien
+     * existant, sinon — si `allowSignup` — crée une ligne locale 100 % OAuth
+     * (`password: null`, rôles = `policy.defaultRoles`) liée au compte externe.
+     * **Aucune liaison automatique** à un compte local existant par email (un email
+     * non vérifié serait un vecteur d'usurpation, OWASP) : un compte externe non lié
+     * donne TOUJOURS un nouvel utilisateur. Le rattachement à un compte existant se
+     * fait explicitement, utilisateur connecté (hors P6).
+     */
+    provisionOAuthUser(profile: IOAuthProfile, policy: IOAuthProvisionPolicy): Promise<IUser>;
+    private fail;
+    private consumeDummy;
+}

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

@@ -0,0 +1,27 @@
+import type { IUser } from "../contracts/IUser.js";
+/** Rôle unique d'un utilisateur non authentifié. */
+export declare const ROLE_ANONYMOUS = "ROLE_ANONYMOUS";
+/**
+ * Utilisateur **non authentifié** — implémente {@link IUser} sans credential.
+ *
+ * Permet de typer le contexte de sécurité sans `null` (Zero Trust : un visiteur
+ * est un utilisateur anonyme, pas une absence d'utilisateur). `@CurrentUser`
+ * retourne `IUser | AnonymousUser`, jamais `null`. Sans état mutable : un
+ * {@link anonymousUser} singleton est réutilisé pour éviter toute allocation par
+ * requête.
+ */
+export declare class AnonymousUser implements IUser {
+    readonly id = "anonymous";
+    readonly identifier = "anon.";
+    readonly roles: string[];
+    hasRole(role: string): boolean;
+    /** Un anonyme est utilisable (non désactivé). @returns `true`. */
+    isActive(): boolean;
+    /** Un anonyme n'est jamais verrouillé. @returns `false`. */
+    isLocked(): boolean;
+}
+/**
+ * Singleton d'{@link AnonymousUser} — instance partagée et gelée à réutiliser à
+ * chaque requête non authentifiée (zéro allocation dans le hot path).
+ */
+export declare const anonymousUser: AnonymousUser;

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

@@ -0,0 +1,98 @@
+import type { IPasswordAuthenticatedUser, ISocialProvider } from "../contracts/IUser.js";
+/**
+ * Options de construction d'un {@link BaseUser} — signature en objet (lisibilité + extensibilité).
+ */
+export interface IBaseUserOptions {
+    /** Identifiant interne (UUID). */
+    id: string;
+    /** Identifiant fonctionnel (email, login...). */
+    identifier: string;
+    /** Rôles plats accordés (copiés défensivement). Défaut : `[]`. */
+    roles?: string[];
+    /** Hash du mot de passe local, ou `null` (compte OAuth-only). Défaut : `null`. */
+    password?: string | null;
+    /** Compte activé. Défaut : `true`. */
+    enabled?: boolean;
+    /** Compte verrouillé. Défaut : `false`. */
+    locked?: boolean;
+    /** Profil de rôle actif en session. Défaut : `null`. */
+    currentRole?: string | null;
+    /** Comptes externes liés (OAuth/OIDC). Défaut : `[]`. */
+    socialProviders?: ISocialProvider[];
+    /** Métadonnées applicatives libres. Défaut : `{}`. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Implémentation POJO de référence d'un utilisateur — base partagée par tous les ORM.
+ *
+ * Porte le contrat {@link IPasswordAuthenticatedUser} plus les **champs
+ * anti-migration** : `socialProviders` (JSON, pas de colonnes par fournisseur),
+ * `metadata` (extras libres typés `Record<string, unknown>`, jamais `any`),
+ * `currentRole` (profil actif de session). Les entités persistées des adapters
+ * (`MongooseUser`, `DrizzleUser`...) étendent cette classe ; Drizzle la mappe.
+ *
+ * Hors hot path requête (instanciée à l'authentification, pas par requête) : les
+ * allocations de `roles`/`socialProviders`/`metadata` y sont acceptables. Pour un
+ * utilisateur anonyme (créé par requête non authentifiée), préférer
+ * {@link AnonymousUser} et son singleton.
+ */
+export declare class BaseUser implements IPasswordAuthenticatedUser {
+    readonly id: string;
+    readonly identifier: string;
+    roles: string[];
+    password: string | null;
+    /** Profil de rôle actif en session (P5.11) — distinct des rôles plats. */
+    currentRole: string | null;
+    socialProviders: ISocialProvider[];
+    metadata: Record<string, unknown>;
+    protected enabled: boolean;
+    protected locked: boolean;
+    constructor(options: IBaseUserOptions);
+    hasRole(role: string): boolean;
+    isActive(): boolean;
+    isLocked(): boolean;
+    /**
+     * Ajoute un rôle s'il n'est pas déjà présent (idempotent).
+     *
+     * @param role - rôle à accorder.
+     * @returns `this` (chaînable).
+     */
+    addRole(role: string): this;
+    /**
+     * Retire un rôle s'il est présent (idempotent).
+     *
+     * @param role - rôle à révoquer.
+     * @returns `this` (chaînable).
+     */
+    removeRole(role: string): this;
+    /**
+     * Lie un compte externe (OAuth/OIDC) — pattern Shadow User. Idempotent sur la
+     * paire `(provider, providerId)`.
+     *
+     * @param link - référence du compte externe.
+     * @returns `this` (chaînable).
+     */
+    addSocialProvider(link: ISocialProvider): this;
+    /** Active le compte. @returns `this`. */
+    enable(): this;
+    /** Désactive le compte. @returns `this`. */
+    disable(): this;
+    /** Verrouille le compte. @returns `this`. */
+    lock(): this;
+    /** Déverrouille le compte. @returns `this`. */
+    unlock(): this;
+    /**
+     * Définit le profil de rôle actif (session). N'altère pas {@link roles}.
+     *
+     * @param role - rôle actif, ou `null` pour réinitialiser.
+     * @returns `this`.
+     */
+    setCurrentRole(role: string | null): this;
+    /**
+     * Remplace le hash de mot de passe stocké.
+     *
+     * @param hash - nouveau hash (déjà produit par un {@link IPasswordEncoder}), ou `null`.
+     * @returns `this`.
+     */
+    setPassword(hash: string | null): this;
+}

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

@@ -0,0 +1,73 @@
+import type { Criteria, ITransaction } from "@nodefony/orm-core";
+import type { IPage } from "nodefony";
+import type { IBaseUserOptions } from "./BaseUser.js";
+import type { IPasswordAuthenticatedUser, IUserListQuery, IUserRepository } from "../contracts/index.js";
+/**
+ * Annuaire d'utilisateurs **en mémoire** — implémentation de référence du contrat
+ * {@link IUserRepository} sur une `Map` (aucun ORM).
+ *
+ * Trois usages :
+ * - **tests de charge** : zéro I/O (pas de sync SQLite) → la mesure n'est pas
+ *   polluée par la persistance ;
+ * - **scripts / tests manuels** : démarrer sans base de données ;
+ * - **fixture de banc** déterministe (l'état est reconstruit à chaque boot).
+ *
+ * La persistance réelle (`@nodefony/drizzle` / `@nodefony/mongoose`) prend ce rôle
+ * en application — **même contrat, zéro changement en aval** (`UserService`,
+ * authenticators). Branché sous `UserService` comme n'importe quel repository.
+ */
+export declare class InMemoryUserRepository implements IUserRepository {
+    #private;
+    /**
+     * Capacité RÉELLE de cet annuaire : `BaseUser` ne porte ni `createdAt` ni
+     * `updatedAt`, donc ils ne sont pas annoncés. Le data plane refuse alors ces
+     * champs en 400 au lieu de rendre un ordre arbitraire.
+     */
+    readonly sortableFields: readonly ["identifier", "enabled", "id"];
+    /**
+     * @param seed - comptes initiaux (identité + rôles + hash de mot de passe
+     *   éventuel). Hacher en amont (hash pré-calculé) évite tout coût CPU au boot.
+     */
+    constructor(seed?: IBaseUserOptions[]);
+    find(criteria?: Criteria<IPasswordAuthenticatedUser>): Promise<IPasswordAuthenticatedUser[]>;
+    findOne(criteria: Criteria<IPasswordAuthenticatedUser>): Promise<IPasswordAuthenticatedUser | null>;
+    create(data: Partial<IPasswordAuthenticatedUser>): Promise<IPasswordAuthenticatedUser>;
+    updateOne(criteria: Criteria<IPasswordAuthenticatedUser>, data: Partial<IPasswordAuthenticatedUser>): Promise<IPasswordAuthenticatedUser | null>;
+    upsert(criteria: Criteria<IPasswordAuthenticatedUser>, update: Partial<IPasswordAuthenticatedUser>, insertOnly?: Partial<IPasswordAuthenticatedUser>): Promise<IPasswordAuthenticatedUser>;
+    createMany(data: Partial<IPasswordAuthenticatedUser>[]): Promise<IPasswordAuthenticatedUser[]>;
+    exists(criteria: Criteria<IPasswordAuthenticatedUser>): Promise<boolean>;
+    deleteOne(criteria: Criteria<IPasswordAuthenticatedUser>): Promise<boolean>;
+    findOneAndDelete(criteria: Criteria<IPasswordAuthenticatedUser>): Promise<IPasswordAuthenticatedUser | null>;
+    increment(criteria: Criteria<IPasswordAuthenticatedUser>, changes: Partial<Record<keyof IPasswordAuthenticatedUser, number>>): Promise<IPasswordAuthenticatedUser | null>;
+    updateMany(criteria: Criteria<IPasswordAuthenticatedUser>, data: Partial<IPasswordAuthenticatedUser>): Promise<number>;
+    delete(criteria: Criteria<IPasswordAuthenticatedUser>): Promise<number>;
+    count(criteria?: Criteria<IPasswordAuthenticatedUser>): Promise<number>;
+    /**
+     * Déduplication en mémoire — l'annuaire est déjà entièrement chargé, il n'y a
+     * donc pas de parcours à éviter comme en SQL. `null`/`undefined` sont écartés
+     * pour tenir la même sémantique que `COUNT(DISTINCT col)`.
+     */
+    countDistinct(field: keyof IPasswordAuthenticatedUser & string, criteria?: Criteria<IPasswordAuthenticatedUser>): Promise<number>;
+    /** In-memory : pas de transaction — le repository est sa propre unité. */
+    withTransaction(_tx: ITransaction): IUserRepository;
+    findByIdentifier(identifier: string): Promise<IPasswordAuthenticatedUser | null>;
+    findBySocialProvider(provider: string, providerId: string): Promise<IPasswordAuthenticatedUser | null>;
+    /**
+     * {@inheritDoc IUserRepository.listPage}
+     *
+     * In-memory : la collection est déjà en RAM (bornée par conception), donc le
+     * filtrage/tri/slice se fait sur la structure — pas de matérialisation
+     * supplémentaire. `total` gratuit (longueur du filtré) sauf `withTotal: false`.
+     */
+    listPage(query: IUserListQuery): Promise<IPage<IPasswordAuthenticatedUser>>;
+    /** {@inheritDoc IUserRepository.countActiveAdmins} */
+    /**
+     * {@inheritDoc IUserRepository.countUsers}
+     *
+     * Réutilise `listPage` avec une fenêtre nulle : le filtrage est écrit une
+     * seule fois, donc compter et lister ne peuvent pas diverger.
+     */
+    countUsers(query: IUserListQuery): Promise<number>;
+    countActiveAdmins(adminRole: string): Promise<number>;
+}
+export default InMemoryUserRepository;

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

@@ -0,0 +1,119 @@
+import type { Container } from "nodefony";
+import type { IAdminApi, IAdminRegistry } from "nodefony";
+import type { IUser } from "../../contracts/IUser.js";
+import type { IUserProfile } from "../../contracts/IUserProfile.js";
+/**
+ * Projection **publique** d'un utilisateur pour l'ADMINISTRATION (Studio, P6.15).
+ * Redaction PAR CONSTRUCTION (allowlist) — ne porte **jamais** `password`, jamais
+ * `metadata` (peut contenir du sensible), et les liens sociaux sont exposés **sans
+ * jeton** (`provider`/`providerId`/`createdAt` seulement).
+ */
+export interface IUserSummary {
+    id: string;
+    identifier: string;
+    roles: string[];
+    /** Compte actif (`isActive()`), pilotable via PATCH `enabled`. */
+    enabled: boolean;
+    /** Compte verrouillé (`isLocked()`), pilotable via PATCH `locked`. */
+    locked: boolean;
+    /**
+     * `true` si le compte a un mot de passe LOCAL (par opposition à OAuth-only).
+     * Présence seulement — **jamais** le hash. Permet au self-service de proposer
+     * « changer » (re-auth possible) vs « pas de mot de passe » (compte externe).
+     */
+    hasPassword: boolean;
+    /** Profil de rôle actif en session (P5.11), ou `null`. */
+    currentRole: string | null;
+    /** Comptes externes liés — jamais de jeton, seulement la référence. */
+    socialProviders: {
+        provider: string;
+        providerId: string;
+        createdAt: number | null;
+    }[];
+    /**
+     * Profil d'affichage (claims OIDC : prénom/nom/email/locale/avatar), lu par
+     * allowlist depuis `metadata.profile` — jamais les autres clés de `metadata`.
+     */
+    profile: IUserProfile;
+    /** Création (epoch ms) si l'entité la porte (ORM), sinon `null`. */
+    createdAt: number | null;
+    /** Dernière mise à jour (epoch ms) si connue, sinon `null`. */
+    updatedAt: number | null;
+    /** Réserve multi-tenant (toujours `null` en mono-tenant — slot coût-0). */
+    tenantId: string | null;
+}
+/**
+ * Projette un {@link IUser} en {@link IUserSummary} redacté. Fonction **pure**
+ * (cœur de la garantie anti-fuite, testée isolément) : `currentRole`/
+ * `socialProviders`/timestamps sont lus **défensivement** (présents sur l'entité
+ * ORM, absents du contrat strict `IUser`) — `password`/`metadata` jamais lus.
+ */
+export declare function toUserSummary(user: IUser): IUserSummary;
+/**
+ * Nom de l'événement kernel émis quand l'accès d'un utilisateur doit être révoqué
+ * partout (suppression / désactivation / verrouillage). **Point d'extension** : un
+ * module qui possède des artefacts liés à un user (sessions, tokens, webhooks…)
+ * s'y abonne et nettoie LES SIENS — zéro couplage avec `@nodefony/user`.
+ */
+export declare const USER_REVOKED_EVENT = "onUserRevoked";
+/**
+ * Charge utile de {@link USER_REVOKED_EVENT}. `identifier` = clé de jointure des
+ * artefacts (session `user`, PAT `subjectId`). `tenantId` = slot multi-tenant
+ * (toujours `null` en mono-tenant — réserve coût-0 pour une cascade scopée).
+ */
+export interface IUserRevokedEvent {
+    id: string;
+    identifier: string;
+    tenantId: string | null;
+    reason: "deleted" | "disabled" | "locked";
+}
+/**
+ * Statut du sous-système utilisateur — miroir consommé par la console Studio
+ * (« où on écrit »). `store` = **backend** de persistance (`memory`/`drizzle`/
+ * `mongoose`, `null` si indéterminable) — aligné sur le vocabulaire config 0.8
+ * (données = `store`) et l'écran Studio « Stores ». `repository` = nom de la
+ * classe réelle du dépôt. Aucun secret/hash : seulement la topologie.
+ */
+export interface IUsersStatus {
+    enabled: boolean;
+    /** Backend de persistance (`memory`/`drizzle`/`mongoose`), ou `null` si indéterminable. */
+    store: "memory" | "drizzle" | "mongoose" | null;
+    /**
+     * Backends de persistance DISPONIBLES (`listUserStores()` : memory builtin +
+     * adapters ORM chargés) — le résolu `store` en fait toujours partie. Aligne la
+     * brique « user » sur les 7 autres de l'écran Studio « Stores » (résolu parmi
+     * disponibles), au lieu du trompeur `[store]`.
+     */
+    available: string[];
+    /** Nom de classe du repository réel (ex. `DrizzleUserRepository`), `"none"` si absent. */
+    repository: string;
+    /** Nombre d'utilisateurs si dénombrable (lecture défensive), sinon `null`. */
+    count: number | null;
+    /** Réserve multi-tenant (toujours `null` en mono-tenant — slot coût-0). */
+    tenantId: string | null;
+}
+/**
+ * Producteur `IAdminApi` du domaine **utilisateur** — exposé sous
+ * `/nodefony/user/api/users`. Défini DANS `@nodefony/user` (propriétaire du
+ * `UserService`/`IUser`) mais **enregistré par un module bootable**
+ * (`@nodefony/security`, via {@link registerUserAdminApi}) car `@nodefony/user`
+ * est une lib pure non-bootable — exactement le cas prévu par le core : un
+ * module qui ne dépend que de `nodefony` produit sa donnée d'admin.
+ *
+ * RBAC `ROLE_NODEFONY_ADMIN` (défaut broker, 403 sinon). Mutations = HTTP
+ * (pipeline CSRF), auditées (catégorie `authz`). Garde-fous **anti-lockout** :
+ * pas d'auto-déchéance, pas de suppression/désactivation du dernier admin actif.
+ *
+ * @param container - container du kernel (résolution lazy du service `users`).
+ */
+export declare function createUserAdminApi(container: Container): IAdminApi;
+/**
+ * Enregistre le producteur admin utilisateur sur le broker — **idempotent**.
+ * À appeler au `onKernelBoot` d'un module **bootable** qui dépend de
+ * `@nodefony/user` (typiquement `@nodefony/security`), `@nodefony/user` n'étant
+ * pas lui-même un module.
+ *
+ * @param registry - broker admin (`container.get("adminBroker")`).
+ * @param container - container du kernel (capturé par les handlers lazy).
+ */
+export declare function registerUserAdminApi(registry: IAdminRegistry, container: Container): void;