@nodefony/user 10.0.0-alpha.1

package/dist/nodefony/src/userProfile.js

@@ -0,0 +1,195 @@
+//#region nodefony/src/userProfile.ts
+/**
+* Logique PURE du profil utilisateur (claims OIDC stockés dans
+* `metadata.profile`) — validation d'un patch client, projection en DTO par
+* allowlist, fusion dans la `metadata` existante. Aucun I/O, aucun service :
+* testable isolément (cœur de la garantie anti-fuite + anti-injection de clé).
+*/
+/** Clés de profil reconnues — allowlist STRICTE (toute autre clé est ignorée). */
+const PROFILE_FIELDS = [
+	"givenName",
+	"familyName",
+	"displayName",
+	"email",
+	"locale",
+	"picture"
+];
+/** Bornes de longueur par champ (anti-abus + cohérence du stockage JSON). */
+const MAX_LEN = {
+	givenName: 100,
+	familyName: 100,
+	displayName: 150,
+	email: 254,
+	locale: 35,
+	picture: 2048
+};
+const EMAIL_RE = /^[^@\s]+@[^@\s]+\.[^@\s]+$/;
+const LOCALE_RE = /^[A-Za-z]{2,3}([-_][A-Za-z0-9]{2,8})*$/;
+/**
+* Borne dure d'un avatar embarqué en **data URL** (image recadrée + redimensionnée
+* CÔTÉ CLIENT, ~256px WebP → ~20 KB). Le cap protège la row user (l'avatar vit
+* dans la DB, choix cloud-native) et borne la surface : un avatar bien compressé
+* reste très en dessous.
+*/
+const MAX_PICTURE_DATA_URL = 131072;
+/**
+* Data URL d'avatar ACCEPTÉE : base64 d'un raster `png`/`jpeg`/`webp` uniquement.
+* **SVG exclu** par construction (un SVG embarque du script → XSS au rendu de
+* l'avatar) ; `gif` exclu (animation/poids). Le base64 est validé (alphabet strict
+* + padding) → ni `javascript:`, ni polyglotte.
+*/
+const DATA_IMAGE_RE = /^data:image\/(?:png|jpe?g|webp);base64,(?:[A-Za-z0-9+/]+={0,2})$/i;
+/**
+* Valide une valeur `picture` : soit une **URL http(s)** (claim OIDC, Gravatar,
+* saisie), soit un **data URL image** raster (avatar uploadé + recadré côté
+* client, stocké en DB). Retourne un message d'erreur, ou `null` si valide.
+*/
+function validatePictureValue(v) {
+	if (/^https?:\/\//i.test(v)) return v.length > MAX_LEN.picture ? `picture too long (max ${MAX_LEN.picture})` : null;
+	if (/^data:/i.test(v)) {
+		if (v.length > MAX_PICTURE_DATA_URL) return "picture data URL too large (max 128KB)";
+		return DATA_IMAGE_RE.test(v) ? null : "picture data URL must be base64 png/jpeg/webp (svg/gif rejected)";
+	}
+	return "picture must be an http(s) URL or a png/jpeg/webp data URL";
+}
+/**
+* Valide + normalise un patch de profil reçu d'un client. Allowlist stricte :
+* seules les clés {@link PROFILE_FIELDS} sont lues (anti-injection d'une clé
+* `metadata` arbitraire). Chaque valeur est `trim`ée ; une chaîne vide ou `null`
+* = **effacement** du champ (matérialisé `""`, retiré au merge).
+*
+* @param input - corps client (`request.body.profile` admin, ou `request.body`
+*   self).
+* @returns `{ ok: true, value }` (patch normalisé) ou `{ ok: false, error }` si
+*   une valeur est mal typée, trop longue, ou syntaxiquement invalide.
+*/
+function validateProfilePatch(input) {
+	if (input === null || typeof input !== "object" || Array.isArray(input)) return {
+		ok: false,
+		error: "profile must be an object"
+	};
+	const src = input;
+	const value = {};
+	for (const field of PROFILE_FIELDS) {
+		if (!(field in src)) continue;
+		const raw = src[field];
+		if (raw === null) {
+			value[field] = "";
+			continue;
+		}
+		if (typeof raw !== "string") return {
+			ok: false,
+			error: `${field} must be a string`
+		};
+		const v = raw.trim();
+		if (v.length === 0) {
+			value[field] = "";
+			continue;
+		}
+		if (field === "picture") {
+			const err = validatePictureValue(v);
+			if (err) return {
+				ok: false,
+				error: err
+			};
+			value[field] = v;
+			continue;
+		}
+		if (v.length > MAX_LEN[field]) return {
+			ok: false,
+			error: `${field} too long (max ${MAX_LEN[field]})`
+		};
+		if (field === "email" && !EMAIL_RE.test(v)) return {
+			ok: false,
+			error: "email is not a valid address"
+		};
+		if (field === "locale" && !LOCALE_RE.test(v)) return {
+			ok: false,
+			error: "locale is not a valid BCP 47 tag"
+		};
+		value[field] = v;
+	}
+	return {
+		ok: true,
+		value
+	};
+}
+/**
+* Projette la `metadata` brute d'une entité vers un {@link IUserProfile} — lecture
+* par **allowlist** (seules les clés connues, typées string non vide). Garantit
+* qu'aucune autre clé de `metadata` (applicative/sensible) n'entre dans le DTO.
+*
+* @param metadata - `entity.metadata` (inconnu : l'entité ORM, pas le contrat).
+*/
+function projectProfile(metadata) {
+	const profile = {};
+	if (!metadata || typeof metadata !== "object") return profile;
+	const raw = metadata.profile;
+	if (!raw || typeof raw !== "object") return profile;
+	const src = raw;
+	for (const field of PROFILE_FIELDS) {
+		const v = src[field];
+		if (typeof v === "string" && v.length > 0) profile[field] = v;
+	}
+	return profile;
+}
+/**
+* Fusionne un patch validé dans la `metadata` existante en **préservant les autres
+* clés**. Les champs de profil vidés (`""`) sont RETIRÉS (pas de clé fantôme).
+* Rend la nouvelle `metadata` complète, prête pour `updateOne({ metadata })`.
+*
+* @param metadata - `metadata` actuelle de l'entité (préservée hors `profile`).
+* @param patch - patch validé par {@link validateProfilePatch}.
+*/
+function mergeProfileIntoMetadata(metadata, patch) {
+	const base = metadata && typeof metadata === "object" ? { ...metadata } : {};
+	const current = base.profile && typeof base.profile === "object" ? base.profile : {};
+	const merged = {};
+	for (const [k, v] of Object.entries({
+		...current,
+		...patch
+	})) if (typeof v === "string" && v.length > 0) merged[k] = v;
+	base.profile = merged;
+	return base;
+}
+/**
+* Pré-remplit un profil depuis des **claims OIDC/OAuth** (provisioning JIT d'un
+* Shadow User social). Mappe les claims standard (`given_name`/`family_name`/
+* `name`/`email`/`picture`/`locale`, + `avatar_url` GitHub) vers
+* {@link IUserProfile}, **best-effort par champ** : chaque valeur est validée
+* isolément (bornes/format) et un claim invalide est ignoré sans bloquer les
+* autres ni le login. Les claims viennent d'un tiers → lecture défensive.
+*
+* @param claims - claims/payload du fournisseur (ex. `{...raw, name, email}`).
+*/
+function profileFromClaims(claims) {
+	const pick = (...keys) => {
+		for (const k of keys) {
+			const v = claims[k];
+			if (typeof v === "string" && v.trim().length > 0) return v;
+		}
+	};
+	const candidate = {};
+	const givenName = pick("given_name", "givenName", "first_name");
+	const familyName = pick("family_name", "familyName", "last_name");
+	const displayName = pick("name", "displayName");
+	const email = pick("email");
+	const picture = pick("picture", "avatar_url");
+	const locale = pick("locale");
+	if (givenName) candidate.givenName = givenName;
+	if (familyName) candidate.familyName = familyName;
+	if (displayName) candidate.displayName = displayName;
+	if (email) candidate.email = email;
+	if (picture) candidate.picture = picture;
+	if (locale) candidate.locale = locale;
+	const result = {};
+	for (const field of PROFILE_FIELDS) {
+		const value = candidate[field];
+		if (value === void 0) continue;
+		const parsed = validateProfilePatch({ [field]: value });
+		if (parsed.ok && parsed.value[field]) result[field] = parsed.value[field];
+	}
+	return result;
+}
+//#endregion
+export { PROFILE_FIELDS, mergeProfileIntoMetadata, profileFromClaims, projectProfile, validateProfilePatch };

package/dist/nodefony/src/userSort.js

@@ -0,0 +1,53 @@
+//#region nodefony/src/userSort.ts
+/**
+* **Le vocabulaire de tri des utilisateurs** — source unique, en noms publics.
+*
+* Il existe parce que cette liste était écrite DEUX fois, et qu'elle avait déjà
+* divergé : l'adapter SQL autorisait `id`, l'adapter Mongo non. Un `?order=id`
+* triait donc en base SQL et se faisait ignorer en base Mongo, sans erreur ni
+* trace — le genre d'écart qui ne se voit qu'en production, sur l'installation
+* d'un tiers.
+*
+* Chaque store la consomme au lieu de la recopier ; ceux qui **concatènent** le
+* nom dans une requête (SQL) continuent de filtrer avec, en défense en
+* profondeur — mais ils filtrent alors sur la même liste que tout le monde.
+*/
+const USER_SORTABLE_FIELDS = [
+	"identifier",
+	"enabled",
+	"createdAt",
+	"updatedAt",
+	"id"
+];
+/**
+* Sous-ensemble réellement triable par l'annuaire **en mémoire**.
+*
+* `BaseUser` ne porte ni `createdAt` ni `updatedAt` — ce sont des colonnes des
+* schémas persistants, pas des attributs du modèle. Déclarer le vocabulaire
+* complet ici reviendrait à annoncer un tri que le store ne peut pas rendre :
+* la page sortirait dans un ordre arbitraire, sans erreur, et personne ne le
+* verrait. La capacité réduite est donc ANNONCÉE, pas simulée — même doctrine
+* que le store de sessions Redis, qui ne déclare aucun tri du tout.
+*
+* Ce que cela donne à l'usage : `?order=createdAt` trie sur une base SQL ou
+* Mongo, et rend **400** sur le backend mémoire. Un refus explicite vaut mieux
+* qu'un ordre inventé.
+*/
+const USER_SORTABLE_FIELDS_IN_MEMORY = [
+	"identifier",
+	"enabled",
+	"id"
+];
+/**
+* Socle garanti par **tous** les backends d'utilisateurs. C'est ce sur quoi une
+* interface peut compter sans savoir quelle base est branchée.
+*/
+const USER_SORTABLE_FIELDS_COMMON = USER_SORTABLE_FIELDS_IN_MEMORY;
+/**
+* Ordre appliqué quand le client n'en demande aucun : par identifiant croissant
+* — le seul champ toujours présent et unique, donc le seul qui rende une
+* pagination offset déterministe sans départage supplémentaire.
+*/
+const USER_DEFAULT_ORDER = [["identifier", "ASC"]];
+//#endregion
+export { USER_DEFAULT_ORDER, USER_SORTABLE_FIELDS, USER_SORTABLE_FIELDS_COMMON, USER_SORTABLE_FIELDS_IN_MEMORY };

package/dist/nodefony/src/userStoreRegistry.js

@@ -0,0 +1,41 @@
+//#region nodefony/src/userStoreRegistry.ts
+/**
+* Registre des BACKENDS de persistance utilisateur DISPONIBLES : `"memory"`
+* (builtin de ce module) + les adapters ORM chargés (`@nodefony/drizzle`,
+* `@nodefony/mongoose`).
+*
+* Différence avec les stores du framework (token/audit/idempotency/session…) : le
+* dépôt utilisateur n'est PAS résolu par `resolveAutoStore` + un registre par
+* brique — il est provisionné par l'APPLICATION (`provisionUsers`, piloté par
+* `NF_USER_STORE`). Ce registre ne SÉLECTIONNE donc rien : il ÉNUMÈRE ce qui est
+* branchable, pour que l'écran Studio « Stores » montre « résolu parmi disponibles »
+* comme pour les 7 autres briques (l'affichage ne doit pas mentir avec `[resolved]`).
+*
+* Convention-frère de `SessionsService.registerStorage` : chaque adapter déclare son
+* backend à son `onKernelRegister`. Lazy + process-wide (Set alloué au 1er ajout).
+*/
+let stores = null;
+/**
+* Déclare un backend de persistance utilisateur disponible (idempotent).
+*
+* @param name - nom court du backend (`"memory"`, `"drizzle"`, `"mongoose"`).
+*/
+function registerUserStore(name) {
+	(stores ??= /* @__PURE__ */ new Set()).add(name);
+}
+/**
+* Liste des backends utilisateur disponibles — alimente le champ `available` du
+* statut user (écran Studio « Stores »). `"memory"` est mis EN TÊTE (baseline
+* builtin, toujours disponible = le repli qui marche partout), les adapters ORM
+* suivent triés. L'ordre est celui affiché dans la colonne « Backends dispo ».
+*
+* @returns noms des backends enregistrés (vide si aucun — jamais `null`).
+*/
+function listUserStores() {
+	if (!stores) return [];
+	const rest = [...stores].filter((s) => s !== "memory").sort();
+	return stores.has("memory") ? ["memory", ...rest] : rest;
+}
+registerUserStore("memory");
+//#endregion
+export { listUserStores, registerUserStore };

package/dist/types/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `@nodefony/user` — socle utilisateur de Nodefony (User Core).
+ *
+ * Module **séparé** de `@nodefony/security` : il porte le contrat `IUser` et ses
+ * implémentations de base afin que tout consommateur (security, framework, orm-*,
+ * agent, llm, rag, realtime, studio) puisse manipuler un utilisateur **sans tirer
+ * toute la couche security** pour un simple type — l'identité est un concept plus
+ * large que l'authentification.
+ *
+ * Lib pure ORM-agnostique : les contrats sont effacés à la compilation, les classes
+ * de base (`BaseUser`, `AnonymousUser`, `BcryptEncoder`) et `UserService` sont
+ * consommés via DI. Les entités persistées (Mongoose/Drizzle) étendent
+ * `BaseUser` ou implémentent `IUser` dans chaque adapter.
+ *
+ * @remarks P5.5–5.9 livrés (contracts, base users, `UserService` + encoders,
+ * adapters Drizzle/Mongoose). `IRole`/`IPermission` différés à P6.8.
+ */
+export type { IUser, IPasswordAuthenticatedUser, ISocialProvider, IPasswordBlocklist, IPasswordEncoder, IPasswordVerifier, IUserProvider, IUserRepository, IUserListQuery, IOAuthProfile, IOAuthProvisionPolicy, IOAuthUserProvisioner, } from "./nodefony/contracts/index.js";
+export { BaseUser } from "./nodefony/src/BaseUser.js";
+export type { IBaseUserOptions } from "./nodefony/src/BaseUser.js";
+export { AnonymousUser, anonymousUser, ROLE_ANONYMOUS, } from "./nodefony/src/AnonymousUser.js";
+export { BcryptEncoder } from "./nodefony/src/encoders/BcryptEncoder.js";
+export { Argon2idEncoder } from "./nodefony/src/encoders/Argon2idEncoder.js";
+export type { Argon2idOptions } from "./nodefony/src/encoders/Argon2idEncoder.js";
+export { MigratingEncoder } from "./nodefony/src/encoders/MigratingEncoder.js";
+export { encoderFromConfig } from "./nodefony/src/encoders/encoderFromConfig.js";
+export type { IEncoderSpec } from "./nodefony/src/encoders/encoderFromConfig.js";
+export { InMemoryUserRepository } from "./nodefony/src/InMemoryUserRepository.js";
+export { USER_SORTABLE_FIELDS, USER_SORTABLE_FIELDS_IN_MEMORY, USER_SORTABLE_FIELDS_COMMON, USER_DEFAULT_ORDER, } from "./nodefony/src/userSort.js";
+export { USER_COLUMNS, USER_TABLE_NAME, attachExtraColumns, missingUserColumns, assertUserContract, } from "./nodefony/src/userContract.js";
+export type { IUserColumn, IUserRow, UserColumnType, UserColumnOrigin, } from "./nodefony/src/userContract.js";
+export { registerUserStore, listUserStores, } from "./nodefony/src/userStoreRegistry.js";
+export { UserService } from "./nodefony/service/UserService.js";
+export type { ICreateUserInput, AuthFailureReason, } from "./nodefony/service/UserService.js";
+export { UserNotFoundError } from "./nodefony/errors/UserNotFoundError.js";
+export { WeakPasswordError } from "./nodefony/errors/WeakPasswordError.js";
+export { createUserAdminApi, registerUserAdminApi, toUserSummary, USER_REVOKED_EVENT, } from "./nodefony/src/admin/UserAdminApi.js";
+export type { IUserSummary, IUserRevokedEvent, } from "./nodefony/src/admin/UserAdminApi.js";
+export type { IUserProfile } from "./nodefony/contracts/IUserProfile.js";
+export { validateProfilePatch, projectProfile, mergeProfileIntoMetadata, profileFromClaims, } from "./nodefony/src/userProfile.js";

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

@@ -0,0 +1,69 @@
+import type { IUser } from "./IUser.js";
+/**
+ * Profil d'identité **normalisé** extrait d'un fournisseur OAuth/OIDC.
+ *
+ * Forme pivot, indépendante du fournisseur : `@nodefony/security` traduit la
+ * réponse propre à chaque provider (ID token OIDC de Google, API REST de
+ * GitHub...) vers cette structure unique, que le provisioner consomme sans rien
+ * savoir du protocole. Aucun jeton n'y figure (il ne sert qu'à l'authentification,
+ * jamais persisté côté Nodefony).
+ */
+export interface IOAuthProfile {
+    /** Fournisseur (`"google"`, `"github"`...). */
+    readonly provider: string;
+    /** Identifiant **stable** du compte chez le fournisseur (`sub` OIDC, `id` GitHub). */
+    readonly providerId: string;
+    /** Email retourné par le fournisseur, ou `null` (compte sans email exposé). */
+    readonly email: string | null;
+    /**
+     * `true` si le fournisseur **certifie** l'email vérifié. Jamais utilisé pour
+     * lier automatiquement un compte local existant (un email non vérifié =
+     * vecteur d'usurpation, OWASP) — réservé à un provisioner applicatif averti.
+     */
+    readonly emailVerified: boolean;
+    /** Nom d'affichage, ou `null`. */
+    readonly name: string | null;
+    /** Charge utile brute du fournisseur (claims / payload) — pour un provisioner custom. */
+    readonly raw: Record<string, unknown>;
+}
+/**
+ * Politique de provisioning décidée par l'appelant (config `oauth2` de
+ * `@nodefony/security`) et transmise au provisioner — celui-ci ne lit aucune
+ * config, il applique ce qu'on lui passe (un provisioner applicatif peut ignorer
+ * ces valeurs et appliquer sa propre logique).
+ */
+export interface IOAuthProvisionPolicy {
+    /** Rôles plats accordés au Shadow User **à la création uniquement**. */
+    readonly defaultRoles: string[];
+    /**
+     * `true` : créer une ligne locale au premier login externe (JIT). `false` :
+     * un compte préexistant lié est requis, sinon échec (fail-closed).
+     */
+    readonly allowSignup: boolean;
+}
+/**
+ * Capability de **provisioning d'un utilisateur OAuth** — pattern *Shadow User*
+ * Just-In-Time.
+ *
+ * Distincte d'{@link IUserProvider} (qui ne fait que **lire** : `loadUserByOAuth`
+ * lève si le lien est inconnu). Le provisioning **écrit** : il crée la ligne
+ * locale au premier login. Capability optionnelle (duck-typée par
+ * `@nodefony/security`) : le framework fournit le point d'extension, l'application
+ * branche sa politique (le défaut est `UserService.provisionOAuthUser`).
+ *
+ * @remarks OAuth = **authentification**, pas autorisation : les rôles sont fixés
+ * à la création (`policy.defaultRoles`) puis **jamais réécrits** par un re-login —
+ * la base locale reste la source de vérité des droits.
+ */
+export interface IOAuthUserProvisioner {
+    /**
+     * Retourne l'utilisateur lié au compte externe, en le **créant** si absent
+     * (selon `policy.allowSignup`).
+     *
+     * @param profile - profil normalisé issu du fournisseur.
+     * @param policy - rôles par défaut + autorisation de création (JIT).
+     * @returns l'utilisateur lié (existant ou nouvellement provisionné).
+     * @throws Si le lien est inconnu et que `allowSignup` est `false`.
+     */
+    provisionOAuthUser(profile: IOAuthProfile, policy: IOAuthProvisionPolicy): Promise<IUser>;
+}

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

@@ -0,0 +1,20 @@
+/**
+ * Contrat de **liste de blocage de mots de passe compromis** (NIST SP 800-63B
+ * §5.1.1.2) — consulté à la CRÉATION et au CHANGEMENT de mot de passe, jamais
+ * au login (le hash stocké ne permet plus de juger le clair, et refuser un
+ * login existant verrouillerait l'utilisateur).
+ *
+ * Le cœur ne fournit QUE le point d'extension : la source de vérité (top-10k
+ * embarqué, fichier d'exploitation, API k-anonymity type HaveIBeenPwned) est un
+ * choix de déploiement, pas du ressort du framework. Brancher une implémentation
+ * via `UserService.passwordBlocklist`.
+ */
+export interface IPasswordBlocklist {
+    /**
+     * Le mot de passe en clair est-il connu-compromis / interdit ?
+     *
+     * @param plain - mot de passe candidat (jamais journalisé par l'implémentation).
+     * @returns `true` si le mot de passe doit être refusé.
+     */
+    isBlocked(plain: string): Promise<boolean>;
+}

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

@@ -0,0 +1,49 @@
+/**
+ * Contrat d'un encodeur de mot de passe — abstraction de l'algorithme de hachage.
+ *
+ * Implémenté par `BcryptEncoder` (P5.6, rounds: 12 par défaut), interchangeable
+ * (argon2, scrypt...) sans toucher au reste de la chaîne d'authentification.
+ * Consommé par `@nodefony/security` (`UserPasswordAuthenticator`) et `UserService`.
+ *
+ * Toutes les opérations sont asynchrones : le hachage est volontairement coûteux
+ * en CPU et ne doit jamais bloquer la boucle d'événements.
+ */
+export interface IPasswordEncoder {
+    /**
+     * Indique si un hash stocké est au format de CET encodeur (parsing pur, sync).
+     *
+     * Permet à un composite ({@link MigratingEncoder}) de router la vérification
+     * vers le bon algorithme sans connaître les formats — chaque encodeur
+     * reconnaît son propre préfixe PHC (`$2b$…` bcrypt, `$argon2id$…` argon2).
+     *
+     * @param hash - hash stocké à inspecter.
+     * @returns `true` si ce hash a été produit par cet algorithme.
+     */
+    supports(hash: string): boolean;
+    /**
+     * Hache un mot de passe en clair (sel inclus dans la sortie).
+     *
+     * @param plain - mot de passe en clair.
+     * @returns le hash à persister.
+     */
+    hash(plain: string): Promise<string>;
+    /**
+     * Vérifie qu'un mot de passe en clair correspond à un hash stocké.
+     *
+     * Comparaison en temps constant déléguée à l'implémentation (anti-timing).
+     *
+     * @param plain - mot de passe en clair fourni à la connexion.
+     * @param hash - hash stocké pour l'utilisateur.
+     * @returns `true` si la correspondance est valide.
+     */
+    verify(plain: string, hash: string): Promise<boolean>;
+    /**
+     * Indique si un hash devrait être recalculé (paramètres de coût obsolètes).
+     *
+     * Permet la migration transparente du coût (ex. rounds augmentés) au prochain login.
+     *
+     * @param hash - hash stocké à inspecter.
+     * @returns `true` si un re-hash est recommandé.
+     */
+    needsRehash(hash: string): boolean;
+}

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

@@ -0,0 +1,26 @@
+import type { IUser } from "./IUser.js";
+/**
+ * Contrat de **vérification d'un credential mot de passe** — le guichet auquel
+ * `@nodefony/security` présente un couple identifiant/mot de passe et qui répond
+ * par un verdict, jamais par un hash.
+ *
+ * Complète {@link IUserProvider} (fourniture d'identité, lecture seule) : ici on
+ * VALIDE un credential. Le hash ne traverse jamais cette frontière — la
+ * comparaison (encoder, leurre anti-timing, re-hash transparent) reste du côté
+ * de l'implémentation ({@link UserService.authenticate} en est la référence).
+ * Une source custom (LDAP, SSO maison) s'authentifie par mot de passe en
+ * implémentant ce seul contrat, sans rien connaître du firewall.
+ */
+export interface IPasswordVerifier {
+    /**
+     * Vérifie un couple identifiant/mot de passe.
+     *
+     * @param identifier - identifiant fonctionnel saisi (email, login...).
+     * @param plain - mot de passe en clair saisi.
+     * @returns l'utilisateur authentifié, ou `null` si le credential est invalide
+     *   (identifiant inconnu, compte inactif/verrouillé, mot de passe faux) — la
+     *   raison fine n'est PAS exposée ici (anti-énumération) ; elle part dans les
+     *   events d'audit de l'implémentation.
+     */
+    authenticate(identifier: string, plain: string): Promise<IUser | null>;
+}

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

@@ -0,0 +1,68 @@
+/**
+ * Référence à un compte d'un fournisseur d'identité externe (OAuth / OIDC).
+ *
+ * Stocké en **JSON** sur l'utilisateur (`BaseUser.socialProviders`) plutôt qu'en
+ * colonnes dédiées (`googleId`, `githubId`...) : ajouter un provider ne demande
+ * aucune migration de schéma. Support du pattern *Shadow User* (une ligne locale
+ * est créée même pour une authentification 100 % externe).
+ */
+export interface ISocialProvider {
+    /** Identifiant du fournisseur (`"google"`, `"github"`, `"microsoft"`...). */
+    readonly provider: string;
+    /** Identifiant du compte chez le fournisseur. */
+    readonly providerId: string;
+    /** Date de liaison du compte. */
+    readonly createdAt: Date;
+}
+/**
+ * Contrat **strict** d'un utilisateur Nodefony — surface minimale garantie au framework.
+ *
+ * C'est le type manipulé par la grande majorité des consommateurs (framework,
+ * adapters ORM, agent, llm, rag, realtime, studio) : il ne porte que l'identité
+ * et les rôles, jamais de credential ni de champ persistant. Les implémentations
+ * concrètes ({@link BaseUser}, entités ORM) l'enrichissent.
+ *
+ * Les rôles sont **plats** (`string[]`) : la résolution de hiérarchie
+ * (`roleHierarchy`) est du ressort de `@nodefony/security`, pas du modèle. Garder
+ * la liste plate sert la perf (lecture via ALS à chaque requête) et des logs
+ * structurés non ambigus.
+ */
+export interface IUser {
+    /** Identifiant interne — UUID (jamais `string | number`). */
+    readonly id: string;
+    /** Identifiant fonctionnel d'authentification (email, login...). Unique. */
+    readonly identifier: string;
+    /** Rôles **plats** accordés (sans hiérarchie résolue). */
+    readonly roles: string[];
+    /**
+     * Indique si l'utilisateur possède le rôle exact donné (sans hiérarchie).
+     *
+     * @param role - rôle recherché (ex. `"ROLE_ADMIN"`).
+     * @returns `true` si présent dans {@link roles}.
+     */
+    hasRole(role: string): boolean;
+    /**
+     * Indique si le compte est actif (activé et non expiré).
+     *
+     * @returns `false` désactive l'authentification, indépendamment des credentials.
+     */
+    isActive(): boolean;
+    /**
+     * Indique si le compte est verrouillé (ex. trop d'échecs de connexion).
+     *
+     * @returns `true` empêche l'authentification même avec des credentials valides.
+     */
+    isLocked(): boolean;
+}
+/**
+ * Utilisateur **porteur d'un credential mot de passe local** — extension de {@link IUser}.
+ *
+ * Séparé de `IUser` pour garder le contrat de base pur : seuls `@nodefony/security`
+ * (`UserPasswordAuthenticator`) et un {@link IPasswordEncoder} ont besoin du hash —
+ * 90 % des consommateurs (affichage, autorisation) n'ont rien à faire d'un credential.
+ * Un compte 100 % OAuth a `password === null`.
+ */
+export interface IPasswordAuthenticatedUser extends IUser {
+    /** Hash du mot de passe stocké, ou `null` pour un compte sans mot de passe local. */
+    readonly password: string | null;
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Profil **public** d'un utilisateur — sous-ensemble des *standard claims* OpenID
+ * Connect (OIDC §5.1) en camelCase (convention Nodefony). Stocké dans
+ * `BaseUser.metadata.profile`, PAS dans des colonnes dédiées : `IUser` reste
+ * identité + rôles (le profil = donnée d'affichage anti-migration). Exposé par
+ * **allowlist** dans le DTO admin (`IUserSummary.profile`) — les autres clés de
+ * `metadata` (applicatives, potentiellement sensibles) ne fuitent jamais.
+ *
+ * Générique par construction : ces claims sont fournis par tout fournisseur OAuth
+ * (le provisioning JIT pourra les pré-remplir). Les champs MÉTIER (société,
+ * service…) restent libres dans `metadata`, hors de cette allowlist typée.
+ *
+ * Tous les champs sont optionnels (un compte fraîchement créé n'a pas de profil).
+ */
+export interface IUserProfile {
+    /** Prénom — OIDC `given_name`. */
+    givenName?: string;
+    /** Nom de famille — OIDC `family_name`. */
+    familyName?: string;
+    /** Nom affiché — OIDC `name` (sinon dérivable « givenName familyName »). */
+    displayName?: string;
+    /** Adresse e-mail de contact — OIDC `email` (distincte de l'`identifier`). */
+    email?: string;
+    /** Préférence de langue — OIDC `locale` (BCP 47, ex. `fr-FR`). */
+    locale?: string;
+    /** URL d'avatar — OIDC `picture` (http/https). */
+    picture?: string;
+}
+export default IUserProfile;

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

@@ -0,0 +1,44 @@
+import type { IUser } from "./IUser.js";
+/**
+ * Contrat de **fourniture** d'utilisateurs — la source d'identité (DB, LDAP, SSO...).
+ *
+ * Consommé par les authenticators de `@nodefony/security` : il découple la
+ * stratégie d'authentification du stockage. Une implémentation typique s'appuie
+ * sur un {@link IUserRepository} ; un plugin externe (`@nodefony/auth-ldap`)
+ * implémente ce contrat sans dépendre du firewall.
+ *
+ * @remarks Les méthodes **lèvent** une erreur si l'utilisateur est introuvable
+ * (jamais `null`) — l'absence d'identité est un échec d'authentification explicite.
+ */
+export interface IUserProvider {
+    /**
+     * Charge un utilisateur par son identifiant fonctionnel (email, login...).
+     *
+     * @param identifier - identifiant unique recherché.
+     * @returns l'utilisateur correspondant.
+     * @throws Si aucun utilisateur ne correspond.
+     */
+    loadUserByIdentifier(identifier: string): Promise<IUser>;
+    /**
+     * Charge un utilisateur lié à un compte d'un fournisseur OAuth/OIDC.
+     *
+     * Support du pattern *Shadow User* : l'implémentation peut créer une ligne
+     * locale au premier login externe.
+     *
+     * @param provider - fournisseur (`"google"`, `"github"`...).
+     * @param providerId - identifiant du compte chez le fournisseur.
+     * @returns l'utilisateur (existant ou nouvellement provisionné).
+     * @throws Si le lien est introuvable et qu'aucun provisionnement n'est possible.
+     */
+    loadUserByOAuth(provider: string, providerId: string): Promise<IUser>;
+    /**
+     * Recharge un utilisateur depuis la source (rôles/état à jour) à chaque requête.
+     *
+     * Indispensable pour révoquer un accès sans attendre l'expiration du token.
+     *
+     * @param user - utilisateur (potentiellement périmé) à rafraîchir.
+     * @returns la version fraîche de l'utilisateur.
+     * @throws Si l'utilisateur n'existe plus (compte supprimé).
+     */
+    refreshUser(user: IUser): Promise<IUser>;
+}