@nodefony/user 10.0.0-alpha.1

package/dist/nodefony/contracts/IPasswordVerifier.js

@@ -0,0 +1 @@
+export {};

package/dist/nodefony/contracts/IUser.js

@@ -0,0 +1 @@
+export {};

package/dist/nodefony/contracts/IUserProfile.js

@@ -0,0 +1 @@
+export {};

package/dist/nodefony/contracts/IUserProvider.js

@@ -0,0 +1 @@
+export {};

package/dist/nodefony/contracts/IUserRepository.js

@@ -0,0 +1 @@
+export {};

package/dist/nodefony/contracts/index.js

@@ -0,0 +1 @@
+export {};

package/dist/nodefony/errors/UserNotFoundError.js

@@ -0,0 +1,19 @@
+import { nodefonyError } from "nodefony";
+//#region nodefony/errors/UserNotFoundError.ts
+/**
+* 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.
+*/
+var UserNotFoundError = class extends nodefonyError {
+	constructor(detail) {
+		super(`User not found: ${detail}`, 404);
+	}
+};
+//#endregion
+export { UserNotFoundError, UserNotFoundError as default };

package/dist/nodefony/errors/WeakPasswordError.js

@@ -0,0 +1,16 @@
+import { nodefonyError } from "nodefony";
+//#region nodefony/errors/WeakPasswordError.ts
+/**
+* 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.
+*/
+var WeakPasswordError = class extends nodefonyError {
+	constructor() {
+		super("Password rejected by policy", 400);
+	}
+};
+//#endregion
+export { WeakPasswordError, WeakPasswordError as default };

package/dist/nodefony/service/UserService.js

@@ -0,0 +1,280 @@
+import { USER_FACETS } from "../src/userFilters.js";
+import { UserNotFoundError } from "../errors/UserNotFoundError.js";
+import { WeakPasswordError } from "../errors/WeakPasswordError.js";
+import { profileFromClaims } from "../src/userProfile.js";
+import { countFacets } from "nodefony";
+import { AbstractCrudService } from "@nodefony/orm-core";
+//#region nodefony/service/UserService.ts
+const DUMMY_PLAINTEXT = "nodefony.dummy.timing.guard";
+/**
+* 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).
+*/
+var UserService = class extends AbstractCrudService {
+	encoder;
+	#dummyHash = null;
+	/**
+	* 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 = 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, encoder, ...wiring) {
+		super("users", repository, ...wiring);
+		this.encoder = encoder;
+	}
+	/**
+	* 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é).
+	*/
+	async createUser(input) {
+		if (input.plainPassword != null) await this.#assertNotBlocked(input.plainPassword);
+		const password = input.plainPassword != null ? await this.encoder.hash(input.plainPassword) : null;
+		return this.create({
+			identifier: input.identifier,
+			roles: input.roles ?? [],
+			password
+		});
+	}
+	/**
+	* Charge un utilisateur par son identifiant fonctionnel (email, login...).
+	*
+	* @param identifier - identifiant unique.
+	* @returns l'utilisateur, ou `null`.
+	*/
+	findByIdentifier(identifier) {
+		return this.repository.findByIdentifier(identifier);
+	}
+	/**
+	* 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) {
+		return this.repository.listPage(query);
+	}
+	/**
+	* 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() {
+		return this.repository.sortableFields ?? [];
+	}
+	/**
+	* 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) {
+		return this.repository.countActiveAdmins(adminRole);
+	}
+	/**
+	* 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).
+	*/
+	async countUserFacets(adminRole, query) {
+		const repo = this.repository;
+		const [facets, admins] = await Promise.all([countFacets(USER_FACETS, (facet) => repo.countUsers({
+			...query,
+			...facet
+		})), repo.countUsers({
+			...query,
+			role: adminRole
+		})]);
+		return {
+			...facets,
+			admins: admins >= 0 ? admins : null
+		};
+	}
+	/**
+	* 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`.
+	*/
+	async changePassword(id, plainPassword) {
+		await this.#assertNotBlocked(plainPassword);
+		const password = await this.encoder.hash(plainPassword);
+		const updated = await this.repository.updateOne({ id }, { password });
+		if (updated !== null) this.fire("onPasswordChanged", updated);
+		return updated;
+	}
+	/**
+	* 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).
+	*/
+	async authenticate(identifier, plain) {
+		const user = await this.repository.findByIdentifier(identifier);
+		if (user === null) {
+			await this.consumeDummy(plain);
+			return this.fail(identifier, "unknown_identifier");
+		}
+		if (user.isLocked()) {
+			await this.consumeDummy(plain);
+			return this.fail(identifier, "locked");
+		}
+		if (!user.isActive()) {
+			await this.consumeDummy(plain);
+			return this.fail(identifier, "disabled");
+		}
+		const hash = user.password;
+		if (hash === null) {
+			await this.consumeDummy(plain);
+			return this.fail(identifier, "no_password");
+		}
+		let ok = false;
+		try {
+			ok = await this.encoder.verify(plain, hash);
+		} catch {
+			ok = false;
+		}
+		if (!ok) return this.fail(identifier, "bad_credentials");
+		if (this.encoder.needsRehash(hash)) {
+			const fresh = await this.encoder.hash(plain);
+			const rehashed = await this.repository.updateOne({ id: user.id }, { password: fresh });
+			this.fire("onPasswordChanged", rehashed ?? user);
+		}
+		this.fire("onAuthenticated", user);
+		return user;
+	}
+	/**
+	* {@inheritDoc IUserProvider.loadUserByIdentifier}
+	*/
+	async loadUserByIdentifier(identifier) {
+		const user = await this.repository.findByIdentifier(identifier);
+		if (user === null) throw new UserNotFoundError(`identifier "${identifier}"`);
+		return user;
+	}
+	/**
+	* {@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.
+	*/
+	async loadUserByOAuth(provider, providerId) {
+		const user = await this.repository.findBySocialProvider(provider, providerId);
+		if (user === null) throw new UserNotFoundError(`social ${provider}:${providerId}`);
+		return user;
+	}
+	/**
+	* {@inheritDoc IUserProvider.refreshUser}
+	*/
+	async refreshUser(user) {
+		const fresh = await this.findById(user.id);
+		if (fresh === null) throw new UserNotFoundError(`id "${user.id}" (compte supprimé)`);
+		return fresh;
+	}
+	/**
+	* {@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).
+	*/
+	async provisionOAuthUser(profile, policy) {
+		const existing = await this.repository.findBySocialProvider(profile.provider, profile.providerId);
+		if (existing !== null) return existing;
+		if (!policy.allowSignup) throw new UserNotFoundError(`social ${profile.provider}:${profile.providerId} (signup disabled)`);
+		const identifier = profile.email ?? `${profile.provider}:${profile.providerId}`;
+		const link = {
+			provider: profile.provider,
+			providerId: profile.providerId,
+			createdAt: /* @__PURE__ */ new Date()
+		};
+		const claims = { ...profile.raw };
+		if (profile.name) claims.name = profile.name;
+		if (profile.email) claims.email = profile.email;
+		const oauthProfile = profileFromClaims(claims);
+		const data = {
+			identifier,
+			roles: [...policy.defaultRoles],
+			password: null,
+			socialProviders: [link]
+		};
+		if (Object.keys(oauthProfile).length > 0) data.metadata = { profile: oauthProfile };
+		return this.create(data);
+	}
+	async #assertNotBlocked(plain) {
+		if (this.passwordBlocklist === null) return;
+		if (await this.passwordBlocklist.isBlocked(plain)) throw new WeakPasswordError();
+	}
+	fail(identifier, reason) {
+		this.fire("onAuthenticationFailure", identifier, reason);
+		return null;
+	}
+	async consumeDummy(plain) {
+		if (this.#dummyHash === null) this.#dummyHash = await this.encoder.hash(DUMMY_PLAINTEXT);
+		try {
+			await this.encoder.verify(plain, this.#dummyHash);
+		} catch {}
+	}
+};
+//#endregion
+export { UserService };

package/dist/nodefony/src/AnonymousUser.js

@@ -0,0 +1,37 @@
+//#region nodefony/src/AnonymousUser.ts
+/** Rôle unique d'un utilisateur non authentifié. */
+const ROLE_ANONYMOUS = "ROLE_ANONYMOUS";
+const ANONYMOUS_ROLES = [ROLE_ANONYMOUS];
+Object.freeze(ANONYMOUS_ROLES);
+/**
+* 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.
+*/
+var AnonymousUser = class {
+	id = "anonymous";
+	identifier = "anon.";
+	roles = ANONYMOUS_ROLES;
+	hasRole(role) {
+		return role === ROLE_ANONYMOUS;
+	}
+	/** Un anonyme est utilisable (non désactivé). @returns `true`. */
+	isActive() {
+		return true;
+	}
+	/** Un anonyme n'est jamais verrouillé. @returns `false`. */
+	isLocked() {
+		return false;
+	}
+};
+/**
+* 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).
+*/
+const anonymousUser = Object.freeze(new AnonymousUser());
+//#endregion
+export { AnonymousUser, ROLE_ANONYMOUS, anonymousUser };

package/dist/nodefony/src/BaseUser.js

@@ -0,0 +1,121 @@
+//#region nodefony/src/BaseUser.ts
+/**
+* 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.
+*/
+var BaseUser = class {
+	id;
+	identifier;
+	roles;
+	password;
+	/** Profil de rôle actif en session (P5.11) — distinct des rôles plats. */
+	currentRole;
+	socialProviders;
+	metadata;
+	enabled;
+	locked;
+	constructor(options) {
+		this.id = options.id;
+		this.identifier = options.identifier;
+		this.roles = options.roles ? [...options.roles] : [];
+		this.password = options.password ?? null;
+		this.enabled = options.enabled ?? true;
+		this.locked = options.locked ?? false;
+		this.currentRole = options.currentRole ?? null;
+		this.socialProviders = options.socialProviders ? [...options.socialProviders] : [];
+		this.metadata = options.metadata ?? {};
+	}
+	hasRole(role) {
+		return this.roles.includes(role);
+	}
+	isActive() {
+		return this.enabled;
+	}
+	isLocked() {
+		return this.locked;
+	}
+	/**
+	* 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) {
+		if (!this.roles.includes(role)) this.roles.push(role);
+		return this;
+	}
+	/**
+	* Retire un rôle s'il est présent (idempotent).
+	*
+	* @param role - rôle à révoquer.
+	* @returns `this` (chaînable).
+	*/
+	removeRole(role) {
+		const i = this.roles.indexOf(role);
+		if (i !== -1) this.roles.splice(i, 1);
+		return 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) {
+		if (!this.socialProviders.some((p) => p.provider === link.provider && p.providerId === link.providerId)) this.socialProviders.push(link);
+		return this;
+	}
+	/** Active le compte. @returns `this`. */
+	enable() {
+		this.enabled = true;
+		return this;
+	}
+	/** Désactive le compte. @returns `this`. */
+	disable() {
+		this.enabled = false;
+		return this;
+	}
+	/** Verrouille le compte. @returns `this`. */
+	lock() {
+		this.locked = true;
+		return this;
+	}
+	/** Déverrouille le compte. @returns `this`. */
+	unlock() {
+		this.locked = false;
+		return 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) {
+		this.currentRole = role;
+		return 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) {
+		this.password = hash;
+		return this;
+	}
+};
+//#endregion
+export { BaseUser };