@nodefony/user 10.0.0-alpha.1

package/dist/nodefony/src/encoders/BcryptEncoder.js

@@ -0,0 +1,75 @@
+//#region nodefony/src/encoders/BcryptEncoder.ts
+let bcrypt = null;
+const loadBcrypt = async () => bcrypt ??= await import("@node-rs/bcrypt");
+/** Coût bcrypt par défaut — 2^12 itérations (recommandation OWASP courante). */
+const DEFAULT_ROUNDS = 12;
+const BCRYPT_HASH_RE = /^\$2[aby]\$(\d{2})\$/;
+/**
+* Encodeur de mot de passe **bcrypt** — implémentation de référence d'{@link IPasswordEncoder}.
+*
+* Délègue à `@node-rs/bcrypt` (binding NAPI Rust) : hachage/vérification réellement
+* asynchrones (exécutés hors thread principal), ne bloquent pas la boucle
+* d'événements même au coût 12. `@node-rs/bcrypt` est une **peerDependency
+* optionnelle** : seules les applications qui authentifient par mot de passe local
+* la tirent ; un consommateur qui n'importe que `IUser`/`BaseUser` ne charge jamais
+* ce module ni le binaire natif.
+*
+* @remarks Le binding natif est importé DYNAMIQUEMENT au premier `hash`/`verify`
+* (instancier l'encodeur ne charge rien — la peerDep optionnelle n'est requise
+* qu'au premier usage réel). Le coût est paramétrable au constructeur pour
+* permettre un re-hash progressif via {@link BcryptEncoder.needsRehash}.
+*/
+var BcryptEncoder = class {
+	/** Coût bcrypt utilisé pour produire les nouveaux hashs. */
+	rounds;
+	/**
+	* @param rounds - coût bcrypt (log2 des itérations). Entier dans `[4, 31]`.
+	* @throws {RangeError} si `rounds` est hors de l'intervalle valide.
+	*/
+	constructor(rounds = DEFAULT_ROUNDS) {
+		if (!Number.isInteger(rounds) || rounds < 4 || rounds > 31) throw new RangeError(`BcryptEncoder: rounds must be an integer in [4, 31], got ${rounds}`);
+		this.rounds = rounds;
+	}
+	/**
+	* Reconnaît un hash bcrypt (`$2a$`/`$2b$`/`$2y$` + coût) — parsing pur, sync.
+	*
+	* @param hash - hash stocké à inspecter.
+	* @returns `true` si le hash est au format bcrypt.
+	*/
+	supports(hash) {
+		return BCRYPT_HASH_RE.test(hash);
+	}
+	/**
+	* Hache un mot de passe en clair (sel généré et inclus dans la sortie).
+	*
+	* @param plain - mot de passe en clair.
+	* @returns le hash bcrypt à persister.
+	*/
+	async hash(plain) {
+		return (await loadBcrypt()).hash(plain, this.rounds);
+	}
+	/**
+	* Vérifie un mot de passe en clair contre un hash stocké (temps constant interne).
+	*
+	* @param plain - mot de passe fourni à la connexion.
+	* @param hash - hash bcrypt stocké.
+	* @returns `true` si la correspondance est valide.
+	*/
+	async verify(plain, hash) {
+		return (await loadBcrypt()).verify(plain, hash);
+	}
+	/**
+	* Indique si un hash doit être recalculé (coût stocké inférieur au coût courant,
+	* ou format non bcrypt).
+	*
+	* @param hash - hash stocké à inspecter.
+	* @returns `true` si un re-hash est recommandé au prochain login réussi.
+	*/
+	needsRehash(hash) {
+		const match = BCRYPT_HASH_RE.exec(hash);
+		if (match === null) return true;
+		return Number.parseInt(match[1], 10) < this.rounds;
+	}
+};
+//#endregion
+export { BcryptEncoder };

package/dist/nodefony/src/encoders/MigratingEncoder.js

@@ -0,0 +1,88 @@
+//#region nodefony/src/encoders/MigratingEncoder.ts
+/**
+* Encodeur composite de **migration d'algorithme** — accepte les hashs legacy à
+* la vérification, ne produit que des hashs au format courant.
+*
+* Une base existante (ex. bcrypt) ne peut pas être convertie hors-ligne : les
+* mots de passe n'existent qu'au moment du login. Ce composite fait la
+* transition sans rien casser :
+*
+* - {@link hash} → toujours l'encodeur PRINCIPAL (le format cible) ;
+* - {@link verify} → routé vers le premier encodeur qui {@link IPasswordEncoder.supports | reconnaît}
+*   le hash stocké (principal d'abord, puis legacy dans l'ordre) ;
+* - {@link needsRehash} → `true` dès que le hash n'est pas au format principal
+*   → `UserService.authenticate` re-hashe au prochain login réussi (seul moment
+*   où le clair existe) = migration transparente, comptes legacy compris.
+*
+* Exemple — migration bcrypt → argon2id :
+* ```ts
+* new MigratingEncoder(new Argon2idEncoder(), [new BcryptEncoder()]);
+* ```
+* Le jour où plus aucun hash bcrypt ne subsiste, retirer le legacy.
+*/
+var MigratingEncoder = class {
+	/** Encodeur cible — produit tous les nouveaux hashs. */
+	primary;
+	/** Encodeurs acceptés en lecture seule pendant la migration. */
+	legacy;
+	/**
+	* @param primary - encodeur cible (format des nouveaux hashs).
+	* @param legacy - encodeurs des formats encore présents en base (vérification seule).
+	*/
+	constructor(primary, legacy) {
+		this.primary = primary;
+		this.legacy = legacy;
+	}
+	/**
+	* Reconnaît un hash si l'UN des encodeurs (principal ou legacy) le reconnaît.
+	*
+	* @param hash - hash stocké à inspecter.
+	* @returns `true` si un membre du composite sait vérifier ce hash.
+	*/
+	supports(hash) {
+		return this.#resolve(hash) !== null;
+	}
+	/**
+	* Hache avec l'encodeur PRINCIPAL uniquement (jamais un format legacy).
+	*
+	* @param plain - mot de passe en clair.
+	* @returns le hash au format cible.
+	*/
+	async hash(plain) {
+		return this.primary.hash(plain);
+	}
+	/**
+	* Vérifie en routant vers l'encodeur dont le format correspond au hash stocké.
+	*
+	* Hash d'un format inconnu de tous → `false` (jamais d'erreur : un credential
+	* invérifiable est un credential invalide — l'égalisation de temps des chemins
+	* d'échec reste portée par `UserService`).
+	*
+	* @param plain - mot de passe fourni à la connexion.
+	* @param hash - hash stocké (format courant ou legacy).
+	* @returns `true` si la correspondance est valide.
+	*/
+	async verify(plain, hash) {
+		const encoder = this.#resolve(hash);
+		if (encoder === null) return false;
+		return encoder.verify(plain, hash);
+	}
+	/**
+	* Recommande un re-hash si le hash n'est pas au format principal (migration),
+	* ou si le principal lui-même le juge obsolète (coûts augmentés).
+	*
+	* @param hash - hash stocké à inspecter.
+	* @returns `true` si un re-hash est recommandé au prochain login réussi.
+	*/
+	needsRehash(hash) {
+		if (!this.primary.supports(hash)) return true;
+		return this.primary.needsRehash(hash);
+	}
+	#resolve(hash) {
+		if (this.primary.supports(hash)) return this.primary;
+		for (const encoder of this.legacy) if (encoder.supports(hash)) return encoder;
+		return null;
+	}
+};
+//#endregion
+export { MigratingEncoder };

package/dist/nodefony/src/encoders/encoderFromConfig.js

@@ -0,0 +1,37 @@
+import { BcryptEncoder } from "./BcryptEncoder.js";
+import { Argon2idEncoder } from "./Argon2idEncoder.js";
+import { MigratingEncoder } from "./MigratingEncoder.js";
+//#region nodefony/src/encoders/encoderFromConfig.ts
+function buildOne(spec) {
+	switch (spec.type) {
+		case "bcrypt": return new BcryptEncoder(spec.rounds);
+		case "argon2id": return new Argon2idEncoder({
+			memoryKiB: spec.memoryKiB,
+			timeCost: spec.timeCost,
+			parallelism: spec.parallelism
+		});
+	}
+}
+/**
+* Traduit une liste ORDONNÉE de specs d'encodeurs en encodeur exécutable —
+* le pont entre la section `encoders` de la config sécurité et le
+* {@link UserService}.
+*
+* Sémantique de l'ordre : la **première** spec est l'encodeur PRINCIPAL
+* (produit tous les nouveaux hashs), les suivantes sont les formats LEGACY
+* acceptés en lecture seule — un login réussi sur un hash legacy est re-haché
+* au format principal ({@link MigratingEncoder}, migration transparente).
+*
+* @param specs - specs ordonnées (typiquement `Object.values(config.encoders)`,
+*   l'ordre d'insertion du record fait foi).
+* @returns l'encodeur seul (1 spec), un {@link MigratingEncoder} (N specs), ou
+*   l'Argon2id aux défauts OWASP si la liste est vide (défaut sûr).
+*/
+function encoderFromConfig(specs) {
+	if (specs.length === 0) return new Argon2idEncoder();
+	const [primary, ...legacy] = specs.map(buildOne);
+	if (legacy.length === 0) return primary;
+	return new MigratingEncoder(primary, legacy);
+}
+//#endregion
+export { encoderFromConfig };

package/dist/nodefony/src/userContract.js

@@ -0,0 +1,247 @@
+import { BootConfigurationError } from "nodefony";
+//#region nodefony/src/userContract.ts
+/**
+* **Le contrat de colonnes de l'utilisateur** — la seule description de ce que
+* le framework LIT sur un utilisateur persisté.
+*
+* Il existe parce que cette liste était écrite en cinq endroits : la table SQL,
+* le schéma document, la documentation publiée, et bientôt un générateur
+* d'entité et un contrôle de démarrage. Cinq copies d'une même règle divergent
+* en silence, et l'écart ne se voit alors que sur l'installation d'un tiers —
+* même raison, même remède que {@link USER_SORTABLE_FIELDS} et `USER_FILTERS`.
+*
+* Les adaptateurs le DÉRIVENT (`userTable` en SQL, `userSchema` en document) au
+* lieu de le recopier ; un test par adaptateur refuse toute colonne du contrat
+* qui n'aurait pas de correspondance dans la définition produite.
+*
+* ⚠️ **Ces noms sont figés en v1.** Le SQL natif du listing les écrit en dur, et
+* surtout : desserrer un nom est additif, le resserrer est une rupture. Ajouter
+* une colonne ici engage donc toute application qui possède déjà sa table.
+*/
+/**
+* Le nom de la TABLE (ou collection) qui porte les utilisateurs.
+*
+* Il fait partie du contrat au même titre que les noms de colonnes, et pour la
+* même raison : le SQL natif du framework l'écrit en dur — recherche par compte
+* externe, listing. Une divergence ne LÈVE PAS, elle rend des résultats vides,
+* si bien qu'une connexion par fournisseur externe crée un compte de plus à
+* chaque passage.
+*
+* Il vit ici plutôt que dans un adaptateur parce que trois lieux le lisent — la
+* spec de table SQL, les requêtes natives, et le générateur d'entité, qui écrit
+* l'entité DANS l'application. Trois copies divergent en silence ; le générateur
+* en portait déjà une, et elle disait `users`.
+*
+* ⚠️ **Figé en v1**, comme les noms de colonnes : le changer romprait toute
+* application qui possède déjà sa table.
+*/
+const USER_TABLE_NAME = "User";
+const USER_COLUMNS = [
+	{
+		name: "id",
+		type: "uuid",
+		nullable: false,
+		origin: "identity",
+		readers: ["IUserRepository.findById", "SessionAuthenticator"],
+		description: "Identifiant interne, stable pour la vie du compte — c'est lui que porte une session."
+	},
+	{
+		name: "identifier",
+		type: "string",
+		nullable: false,
+		unique: true,
+		origin: "column",
+		readers: [
+			"IUserRepository.findByIdentifier",
+			"UserService.authenticate",
+			"listUserIdsPage (recherche ?q= et tri par défaut)"
+		],
+		description: "Identifiant fonctionnel d'authentification (courriel, login) — unique dans l'annuaire."
+	},
+	{
+		name: "password",
+		type: "string",
+		nullable: true,
+		origin: "column",
+		readers: ["UserService.authenticate"],
+		description: "Empreinte du mot de passe, ou absente pour un compte sans mot de passe local (100 % externe)."
+	},
+	{
+		name: "roles",
+		type: "string[]",
+		nullable: false,
+		makeDefault: () => [],
+		origin: "column",
+		readers: ["listUserIdsPage (filtre ?role=)", "IUserRepository.countActiveAdmins"],
+		description: "Rôles plats accordés, sans hiérarchie résolue."
+	},
+	{
+		name: "enabled",
+		type: "boolean",
+		nullable: false,
+		makeDefault: () => true,
+		origin: "column",
+		readers: [
+			"UserService.authenticate",
+			"listUserIdsPage (filtre ?enabled=)",
+			"IUserRepository.countActiveAdmins"
+		],
+		description: "Compte utilisable, ou désactivé par décision d'administration."
+	},
+	{
+		name: "locked",
+		type: "boolean",
+		nullable: false,
+		makeDefault: () => false,
+		origin: "column",
+		readers: ["UserService.authenticate", "listUserIdsPage (filtre ?locked=)"],
+		description: "Compte verrouillé par la défense contre la force brute."
+	},
+	{
+		name: "currentRole",
+		type: "string",
+		nullable: true,
+		origin: "column",
+		readers: ["BaseUser.currentRole"],
+		description: "Rôle endossé pour la session en cours, parmi ceux que le compte détient."
+	},
+	{
+		name: "socialProviders",
+		type: "object[]",
+		nullable: false,
+		makeDefault: () => [],
+		origin: "column",
+		readers: ["IUserRepository.findBySocialProvider", "listUserIdsPage (filtre ?hasSocial=)"],
+		description: "Comptes externes liés — tableau libre, pour qu'un nouveau fournisseur ne demande aucune migration."
+	},
+	{
+		name: "metadata",
+		type: "object",
+		nullable: false,
+		makeDefault: () => ({}),
+		origin: "column",
+		readers: ["projectProfile", "mergeProfileIntoMetadata"],
+		description: "Dictionnaire libre du compte, dont le profil public — sans schéma, donc sans migration."
+	},
+	{
+		name: "createdAt",
+		type: "date",
+		nullable: false,
+		origin: "audit",
+		readers: ["listUserIdsPage (tri ?order=createdAt)", "toUserSummary"],
+		description: "Date de création du compte."
+	},
+	{
+		name: "updatedAt",
+		type: "date",
+		nullable: false,
+		origin: "audit",
+		refreshedOnWrite: true,
+		readers: ["listUserIdsPage (tri ?order=updatedAt)", "toUserSummary"],
+		description: "Date de dernière modification du compte."
+	}
+];
+/**
+* Les colonnes que `BaseUser` reconstruit lui-même — tout le reste d'une ligne
+* est « en plus », et doit donc être reporté sur l'objet rendu.
+*
+* La correspondance avec l'origine n'est pas une coïncidence : un horodatage
+* n'appartient pas au contrat `IUser` (il décrit la LIGNE, pas l'identité), donc
+* `BaseUser` ne le porte pas. Un test la garde, parce qu'elle se romprait sans
+* bruit le jour où une colonne changerait de statut.
+*/
+const REBUILT_BY_BASE_USER = new Set(USER_COLUMNS.filter((column) => column.origin !== "audit").map((column) => column.name));
+/**
+* Reporte sur un utilisateur reconstruit toutes les colonnes que `BaseUser` ne
+* porte pas — horodatages de la ligne, et **champs métier ajoutés par
+* l'application**.
+*
+* Sans ce report, l'écriture passe et la lecture perd, **sans une erreur** : le
+* développeur voit sa donnée en base et un objet vide dans son code. C'est
+* l'asymétrie qui est le défaut, et elle ne se corrige qu'ici — les trois dépôts
+* appellent cette fonction plutôt que d'en recopier chacun sa version, sinon
+* l'un d'eux divergerait en silence (c'était déjà le cas : le dépôt SQL
+* reportait les horodatages, le dépôt document non).
+*
+* ⚠️ Cette fonction est sur le chemin de CHAQUE requête portant une session
+* authentifiée : elle n'alloue rien, ne construit aucun tableau intermédiaire,
+* et ne parcourt que les clés propres de la ligne.
+*
+* @param user - l'utilisateur reconstruit, muté sur place.
+* @param row - la ligne rendue par le moteur.
+* @param skip - clés de plomberie propres au moteur (`_id`, `__v`…), à ne pas
+*   reporter. Le contrat ne peut pas les connaître : c'est au dépôt de les dire.
+* @returns le même objet `user`, pour permettre `return attachExtraColumns(...)`.
+*/
+function attachExtraColumns(user, row, skip) {
+	const target = user;
+	for (const key in row) {
+		if (!Object.prototype.hasOwnProperty.call(row, key)) continue;
+		if (REBUILT_BY_BASE_USER.has(key)) continue;
+		if (skip?.has(key)) continue;
+		if (key === "__proto__" || key === "constructor" || key === "prototype") continue;
+		target[key] = row[key];
+	}
+	return user;
+}
+/**
+* Les colonnes du contrat qu'une définition d'entité ne rend PAS.
+*
+* @param present - noms des colonnes que l'entité expose réellement.
+* @param expected - le sous-ensemble du contrat à exiger (défaut : tout).
+* @returns les colonnes manquantes, dans l'ordre du contrat (vide si complet).
+*/
+function missingUserColumns(present, expected = USER_COLUMNS) {
+	const known = new Set(present);
+	return expected.filter((column) => !known.has(column.name));
+}
+/**
+* Refuse une entité utilisateur incomplète, en nommant chaque colonne absente
+* ET ce qui la lit.
+*
+* Le refus existe parce que le manque est SILENCIEUX : une application qui
+* possède sa table `User` peut en retirer une colonne, la migration s'applique,
+* le démarrage réussit, et la commande qui liste les comptes affiche des
+* utilisateurs. Le défaut n'éclate qu'au premier accès à la colonne absente —
+* une authentification, un filtre par rôle — peut-être des semaines plus tard,
+* dans un chemin peu fréquenté. Échouer au démarrage déplace la découverte au
+* seul moment où elle ne coûte rien.
+*
+* Nommer le LECTEUR, et pas seulement la colonne, est ce qui rend le message
+* actionnable : « `roles` manque » n'apprend rien à qui a retiré la colonne
+* exprès ; « `roles`, lue par le filtre `?role=` et par le compte des
+* administrateurs actifs » dit ce qui cassera.
+*
+* @param present - noms des colonnes que l'entité expose réellement.
+* @param origin - d'où vient l'entité examinée, cité tel quel dans le refus
+*   (ex. `l'entité « User » de l'application, sur le connecteur « default »`).
+* @param expected - le sous-ensemble du contrat à exiger. Il existe parce que
+*   tous les stockages ne portent pas les mêmes colonnes EN PROPRE : un schéma
+*   document laisse la clé au moteur (`_id` + virtuel) et les horodatages à son
+*   option `timestamps`. Exiger le contrat entier là-bas refuserait une entité
+*   parfaitement correcte — et un refus faux apprend à passer outre les refus.
+*   L'appelant le DÉRIVE de ce qu'il produit lui-même, il ne le recopie pas.
+* @throws BootConfigurationError si une colonne attendue manque.
+*
+* **Pourquoi une `BootConfigurationError` et pas une `Error`.** Ce refus est
+* appelé pendant le boot d'un module, et le kernel y applique une politique de
+* résilience : un hook de boot qui lève est journalisé en WARNING, le module est
+* écarté, et l'application DÉMARRE — « BOOT dégradé », code de sortie nul.
+* Mesuré : une application générée dont l'entité `User` avait perdu six colonnes
+* du contrat démarrait, servait ses routes, et `orm:migrate:status` la déclarait
+* « à jour ». Le refus était écrit, parfaitement rédigé, et sans effet.
+*
+* Le fail-soft est le bon comportement pour une panne TRANSITOIRE (une base qui
+* ne répond pas encore) ; il est le mauvais pour une erreur de PROGRAMMATION,
+* qui ne se répare pas en continuant. `BootConfigurationError` est exactement la
+* frontière que le cœur a posée entre les deux — son propre TSDoc nomme le cas
+* « une entité non portée sur le dialecte demandé ».
+*/
+function assertUserContract(present, origin, expected = USER_COLUMNS) {
+	const missing = missingUserColumns(present, expected);
+	if (missing.length === 0) return;
+	const details = missing.map((column) => `  • ${column.name} (${column.type}) — lue par ${column.readers.join(", ")}\n    ${column.description}`).join("\n");
+	throw new BootConfigurationError(`${origin} ne porte pas ${missing.length === 1 ? "une colonne" : `${missing.length} colonnes`} que le framework LIT :\n${details}\n  → ajouter ${missing.length === 1 ? "cette colonne" : "ces colonnes"} à l'entité, puis : nodefony orm:generate --name user && nodefony orm:migrate\n(le contrat complet est exporté par @nodefony/user sous USER_COLUMNS.)`);
+}
+//#endregion
+export { USER_COLUMNS, USER_TABLE_NAME, assertUserContract, attachExtraColumns, missingUserColumns };

package/dist/nodefony/src/userFilters.js

@@ -0,0 +1,66 @@
+//#region nodefony/src/userFilters.ts
+/**
+* **Le vocabulaire de filtre des utilisateurs**, en noms PUBLICS — ceux qu'un
+* administrateur écrit dans l'URL (`?role=ROLE_ADMIN&enabled=false`).
+*
+* Frère de `USER_SORTABLE_FIELDS` (`userSort.ts`), et posé au même endroit pour
+* la même raison : le vocabulaire appartient au module propriétaire du contrat,
+* la mécanique de lecture au cœur (`parseFilters`).
+*
+* `role` reste une chaîne LIBRE : la hiérarchie de rôles est celle de
+* l'application (`ROLE_*` de tenant) autant que de la plateforme
+* (`ROLE_NODEFONY_*`), et aucune allowlist du framework ne peut la connaître.
+* `enabled` est un booléen strict — `?enabled=1` est désormais refusé plutôt que
+* lu comme `false`, ce que faisait la comparaison `enabled === "true"`.
+*/
+const USER_FILTERS = {
+	/** Rôle plat devant figurer dans `roles` (containment natif). */
+	role: "string",
+	/** `true` = actifs seulement, `false` = inactifs seulement, absent = les deux. */
+	enabled: "boolean",
+	/** `true` = verrouillés seulement (défense anti-force brute), absent = les deux. */
+	locked: "boolean",
+	/** `true` = liés à au moins un fournisseur externe (OAuth), absent = les deux. */
+	hasSocial: "boolean"
+};
+/**
+* **Les facettes des utilisateurs** — les questions fermées posées à l'annuaire
+* ENTIER pour les cartes de tête.
+*
+* Les populations se **recoupent** délibérément : un compte peut être désactivé
+* ET verrouillé, un administrateur peut avoir un lien social. Aucune facette
+* n'est donc déduite d'une autre — « désactivés » et « verrouillés » sont deux
+* questions distinctes, et les confondre en un seul « inactifs » masquait
+* lequel des deux mécanismes bloque réellement un compte.
+*
+* `admins` n'y figure pas : le rôle d'administration est une valeur de
+* configuration (`ROLE_NODEFONY_ADMIN` par défaut, surchargeable), pas une
+* constante du vocabulaire. Le service la lit et compose la facette lui-même.
+*/
+const USER_FACETS = {
+	/** Tous les comptes de l'annuaire. */
+	total: {},
+	/** Comptes utilisables : activés et non verrouillés. */
+	active: {
+		enabled: true,
+		locked: false
+	},
+	/** Comptes désactivés par décision d'administration. */
+	disabled: { enabled: false },
+	/** Comptes verrouillés par la défense anti-force brute. */
+	locked: { locked: true },
+	/** Comptes liés à au moins un fournisseur d'identité externe. */
+	social: { hasSocial: true }
+};
+/**
+* Ce que l'endpoint de COMPTEURS accepte de filtrer — `USER_FILTERS` **moins**
+* les champs que les facettes décomposent (`enabled`, `locked`, `hasSocial`).
+*
+* Les demander ici rendrait une réponse contradictoire : le total suivrait le
+* filtre pendant que chaque facette l'écraserait par le sien. `role` reste :
+* il découpe une AUTRE dimension, et « combien de `ROLE_SUPPORT`, et dans quel
+* état ? » est une question cohérente.
+*/
+const USER_STATS_FILTERS = { role: "string" };
+//#endregion
+export { USER_FACETS, USER_FILTERS, USER_STATS_FILTERS };