@nodefony/user 10.0.0-alpha.1

package/dist/types/nodefony/src/encoders/Argon2idEncoder.d.ts

@@ -0,0 +1,83 @@
+import type { IPasswordEncoder } from "../../contracts/IPasswordEncoder.js";
+/**
+ * Paramètres de coût Argon2id (RFC 9106).
+ *
+ * Les défauts suivent le minimum OWASP 2026 (m=19 MiB, t=2, p=1) — déjà imposé
+ * par le schéma Zod de `@nodefony/security` (`encoders.memoryKiB.min(19456)`).
+ * L'encodeur ne valide ici que les bornes TECHNIQUES de l'algorithme : la
+ * politique de sécurité vit dans la config (et permet aux tests d'utiliser des
+ * coûts bas, rapides).
+ */
+export interface Argon2idOptions {
+    /** Mémoire par hash en KiB (défaut 19456 = 19 MiB, minimum OWASP). */
+    memoryKiB?: number;
+    /** Nombre de passes sur la mémoire (défaut 3 — voir DEFAULT_TIME_COST). */
+    timeCost?: number;
+    /** Nombre de threads/lanes (défaut 1 — chaque lane alloue `memoryKiB`). */
+    parallelism?: number;
+}
+/**
+ * Encodeur de mot de passe **Argon2id** (RFC 9106) — recommandation NIST/OWASP 2026.
+ *
+ * Fonction de dérivation à MÉMOIRE DURE : chaque vérification exige `memoryKiB`
+ * de RAM en plus du CPU, ce qui ruine les attaques massivement parallèles
+ * (GPU/ASIC ont des milliers de cœurs mais pas 19 MiB de mémoire dédiée par
+ * cœur). Le variant `id` est hybride : résistant aux canaux auxiliaires
+ * (première moitié indépendante du mot de passe) ET aux compromis temps-mémoire.
+ *
+ * Délègue à `@node-rs/argon2` (binding NAPI Rust, exécuté hors thread principal,
+ * **peerDependency optionnelle**) : le binaire natif est importé DYNAMIQUEMENT
+ * au premier `hash`/`verify` — instancier l'encodeur ne charge rien.
+ */
+export declare class Argon2idEncoder implements IPasswordEncoder {
+    /** Mémoire par hash (KiB) utilisée pour produire les nouveaux hashs. */
+    readonly memoryKiB: number;
+    /** Passes sur la mémoire utilisées pour produire les nouveaux hashs. */
+    readonly timeCost: number;
+    /** Lanes parallèles utilisées pour produire les nouveaux hashs. */
+    readonly parallelism: number;
+    /**
+     * @param options - coûts Argon2id ; défauts = minimum OWASP (19 MiB, t=2, p=1).
+     * @throws {RangeError} si un paramètre viole les bornes techniques de
+     *   l'algorithme (entiers, `t ≥ 1`, `1 ≤ p ≤ 255`, `m ≥ 8×p`).
+     */
+    constructor(options?: Argon2idOptions);
+    /**
+     * Reconnaît un hash argon2 (tous variants `$argon2d|i|id$`) — parsing pur, sync.
+     *
+     * Tous les variants sont supportés à la VÉRIFICATION (le binding parse le
+     * format PHC) ; {@link needsRehash} se charge de moderniser `d`/`i` vers `id`.
+     *
+     * @param hash - hash stocké à inspecter.
+     * @returns `true` si le hash est au format argon2.
+     */
+    supports(hash: string): boolean;
+    /**
+     * Hache un mot de passe en clair (sel généré, paramètres inclus dans la sortie PHC).
+     *
+     * @param plain - mot de passe en clair.
+     * @returns le hash argon2id à persister.
+     */
+    hash(plain: string): Promise<string>;
+    /**
+     * Vérifie un mot de passe en clair contre un hash stocké (temps constant interne).
+     *
+     * Les paramètres de vérification sont LUS DANS le hash PHC (pas ceux de
+     * l'encodeur) : un hash produit avec d'anciens coûts reste vérifiable.
+     *
+     * @param plain - mot de passe fourni à la connexion.
+     * @param hash - hash argon2 stocké.
+     * @returns `true` si la correspondance est valide.
+     */
+    verify(plain: string, hash: string): Promise<boolean>;
+    /**
+     * Indique si un hash doit être recalculé : format non argon2, variant non
+     * `id`, version antérieure à 0x13, ou coûts stockés INFÉRIEURS aux coûts
+     * courants (politique affaiblie). Des coûts supérieurs ne déclenchent pas de
+     * re-hash (jamais de downgrade silencieux).
+     *
+     * @param hash - hash stocké à inspecter.
+     * @returns `true` si un re-hash est recommandé au prochain login réussi.
+     */
+    needsRehash(hash: string): boolean;
+}

package/dist/types/nodefony/src/encoders/BcryptEncoder.d.ts

@@ -0,0 +1,55 @@
+import type { IPasswordEncoder } from "../../contracts/IPasswordEncoder.js";
+/**
+ * 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}.
+ */
+export declare class BcryptEncoder implements IPasswordEncoder {
+    /** Coût bcrypt utilisé pour produire les nouveaux hashs. */
+    readonly rounds: number;
+    /**
+     * @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?: number);
+    /**
+     * 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: string): boolean;
+    /**
+     * 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.
+     */
+    hash(plain: string): Promise<string>;
+    /**
+     * 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.
+     */
+    verify(plain: string, hash: string): Promise<boolean>;
+    /**
+     * 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: string): boolean;
+}

package/dist/types/nodefony/src/encoders/MigratingEncoder.d.ts

@@ -0,0 +1,68 @@
+import type { IPasswordEncoder } from "../../contracts/IPasswordEncoder.js";
+/**
+ * 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.
+ */
+export declare class MigratingEncoder implements IPasswordEncoder {
+    #private;
+    /** Encodeur cible — produit tous les nouveaux hashs. */
+    readonly primary: IPasswordEncoder;
+    /** Encodeurs acceptés en lecture seule pendant la migration. */
+    readonly legacy: readonly IPasswordEncoder[];
+    /**
+     * @param primary - encodeur cible (format des nouveaux hashs).
+     * @param legacy - encodeurs des formats encore présents en base (vérification seule).
+     */
+    constructor(primary: IPasswordEncoder, legacy: readonly IPasswordEncoder[]);
+    /**
+     * 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: string): boolean;
+    /**
+     * Hache avec l'encodeur PRINCIPAL uniquement (jamais un format legacy).
+     *
+     * @param plain - mot de passe en clair.
+     * @returns le hash au format cible.
+     */
+    hash(plain: string): Promise<string>;
+    /**
+     * 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.
+     */
+    verify(plain: string, hash: string): Promise<boolean>;
+    /**
+     * 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: string): boolean;
+}

package/dist/types/nodefony/src/encoders/encoderFromConfig.d.ts

@@ -0,0 +1,36 @@
+import type { IPasswordEncoder } from "../../contracts/IPasswordEncoder.js";
+/**
+ * Spécification déclarative d'UN encodeur de mot de passe — miroir structurel
+ * de la section `encoders` du schéma Zod de `@nodefony/security` (qui valide
+ * bornes et défauts), SANS en dépendre : ce module reste la couche basse,
+ * l'inversion de dépendance est préservée (security consomme user, jamais
+ * l'inverse).
+ */
+export interface IEncoderSpec {
+    /** Algorithme : `argon2id` (RFC 9106, défaut) ou `bcrypt` (legacy). */
+    type: "argon2id" | "bcrypt";
+    /** Argon2id : mémoire par hash (KiB). */
+    memoryKiB?: number;
+    /** Argon2id : passes d'itération. */
+    timeCost?: number;
+    /** Argon2id : lanes parallèles. */
+    parallelism?: number;
+    /** bcrypt : coût (ignoré par argon2id). */
+    rounds?: number;
+}
+/**
+ * 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).
+ */
+export declare function encoderFromConfig(specs: readonly IEncoderSpec[]): IPasswordEncoder;

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

@@ -0,0 +1,198 @@
+import type { ISocialProvider } from "../contracts/IUser.js";
+/**
+ * Type **logique** d'une colonne de l'utilisateur — ce que la donnée EST, jamais
+ * comment un moteur la range.
+ *
+ * Chaque adaptateur traduit ce vocabulaire dans le sien (`text`/`json`/`bool`
+ * du colKit SQL, `String`/`Array`/`Object` d'un schéma Mongoose). Le contrat
+ * reste donc lisible par un développeur qui n'a choisi aucune base, et un
+ * troisième adaptateur ne demande pas de le rouvrir.
+ */
+export type UserColumnType = "uuid" | "string" | "string[]" | "boolean" | "object" | "object[]" | "date";
+/**
+ * D'où vient la valeur d'une colonne — ce qui décide si un adaptateur doit la
+ * DÉCLARER ou peut la laisser au moteur.
+ *
+ * - `identity` : la clé primaire. Déclarée en SQL (`text` + UUID applicatif),
+ *   fournie par le moteur en document (`_id` + virtuel `id`).
+ * - `column` : une colonne ordinaire. **Tout adaptateur doit la déclarer** —
+ *   c'est sur elle que porte le test de correspondance.
+ * - `audit` : un horodatage. Déclaré en SQL, délégué au moteur en document
+ *   (`timestamps: true`).
+ */
+export type UserColumnOrigin = "identity" | "column" | "audit";
+/**
+ * Une colonne du contrat utilisateur : son nom, ce qu'elle contient, et **qui la
+ * lit**.
+ *
+ * `readers` n'est pas de la documentation d'agrément : c'est ce qui permet à un
+ * refus de démarrage de nommer le lecteur en même temps que la colonne absente
+ * (« `socialProviders` manque — `findBySocialProvider` la lit »), au lieu de
+ * laisser chercher qui casse. N'y figurent donc que les lecteurs qui touchent la
+ * BASE — requête, filtre, tri, projection du dépôt — pas tout code qui manipule
+ * un utilisateur déjà chargé.
+ */
+export interface IUserColumn {
+    /** Nom de la colonne, identique sur tous les moteurs (figé en v1). */
+    readonly name: string;
+    /** Ce que la colonne contient, indépendamment du moteur. */
+    readonly type: UserColumnType;
+    /** `true` si la colonne accepte l'absence de valeur. */
+    readonly nullable: boolean;
+    /** `true` si la valeur doit être unique dans l'annuaire (implique un index). */
+    readonly unique?: boolean;
+    /** Qui fournit la valeur — cf {@link UserColumnOrigin}. */
+    readonly origin: UserColumnOrigin;
+    /**
+     * Fabrique du défaut, appelée à CHAQUE insertion.
+     *
+     * C'est une fabrique et non une valeur parce qu'un défaut structuré (`[]`,
+     * `{}`) partagé par référence serait le MÊME objet pour tous les utilisateurs :
+     * une modification en mémoire les contaminerait tous.
+     */
+    readonly makeDefault?: () => unknown;
+    /**
+     * `true` si la valeur est régénérée à CHAQUE écriture (horodatage de
+     * modification). Déclaré ici plutôt que déduit du nom de la colonne : un
+     * adaptateur qui reconnaîtrait `"updatedAt"` rendrait la règle invisible, et
+     * fausse le jour où une seconde colonne se comporte pareil.
+     */
+    readonly refreshedOnWrite?: boolean;
+    /** Les lecteurs qui cassent si la colonne manque — nommés dans les refus. */
+    readonly readers: readonly string[];
+    /** Rôle de la colonne, en une phrase. */
+    readonly description: string;
+}
+/**
+ * **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.
+ */
+export declare const USER_TABLE_NAME = "User";
+export declare const USER_COLUMNS: readonly IUserColumn[];
+/**
+ * Forme plate d'un utilisateur tel qu'un dépôt le rend, avant reconstruction en
+ * `BaseUser` — pendant TypeScript de {@link USER_COLUMNS}.
+ *
+ * Déclarée ici, et non dans chaque adaptateur, pour la raison qui fonde tout ce
+ * fichier : deux copies de la même forme divergent sans que rien ne le dise.
+ * Les colonnes JSON arrivent déjà désérialisées, et les dates en `Date` — c'est
+ * le travail du pilote, pas celui du dépôt.
+ */
+export interface IUserRow {
+    id: string;
+    identifier: string;
+    password: string | null;
+    roles: string[];
+    enabled: boolean;
+    locked: boolean;
+    currentRole: string | null;
+    socialProviders: ISocialProvider[];
+    metadata: Record<string, unknown>;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * 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(...)`.
+ */
+export declare function attachExtraColumns<T extends object>(user: T, row: Readonly<Record<string, unknown>>, skip?: ReadonlySet<string>): T;
+/**
+ * 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).
+ */
+export declare function missingUserColumns(present: Iterable<string>, expected?: readonly IUserColumn[]): readonly IUserColumn[];
+/**
+ * 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é ».
+ */
+export declare function assertUserContract(present: Iterable<string>, origin: string, expected?: readonly IUserColumn[]): void;

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

@@ -0,0 +1,80 @@
+import type { FacetCount, FacetCounts } from "nodefony";
+/**
+ * **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"`.
+ */
+export declare const USER_FILTERS: {
+    /** Rôle plat devant figurer dans `roles` (containment natif). */
+    readonly role: "string";
+    /** `true` = actifs seulement, `false` = inactifs seulement, absent = les deux. */
+    readonly enabled: "boolean";
+    /** `true` = verrouillés seulement (défense anti-force brute), absent = les deux. */
+    readonly locked: "boolean";
+    /** `true` = liés à au moins un fournisseur externe (OAuth), absent = les deux. */
+    readonly 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.
+ */
+export declare const USER_FACETS: {
+    /** Tous les comptes de l'annuaire. */
+    readonly total: {};
+    /** Comptes utilisables : activés et non verrouillés. */
+    readonly active: {
+        readonly enabled: true;
+        readonly locked: false;
+    };
+    /** Comptes désactivés par décision d'administration. */
+    readonly disabled: {
+        readonly enabled: false;
+    };
+    /** Comptes verrouillés par la défense anti-force brute. */
+    readonly locked: {
+        readonly locked: true;
+    };
+    /** Comptes liés à au moins un fournisseur d'identité externe. */
+    readonly social: {
+        readonly hasSocial: true;
+    };
+};
+/**
+ * Les compteurs rendus par `GET /nodefony/user/api/users/stats` — les facettes
+ * déclarées, plus `admins` que le service compose depuis le rôle configuré.
+ */
+export type IUserCounts = FacetCounts<typeof USER_FACETS> & {
+    /** Comptes portant le rôle d'administration de la plateforme. */
+    admins: FacetCount;
+};
+/**
+ * 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.
+ */
+export declare const USER_STATS_FILTERS: {
+    readonly role: "string";
+};

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

@@ -0,0 +1,56 @@
+import type { IUserProfile } from "../contracts/IUserProfile.js";
+/**
+ * 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). */
+export declare const PROFILE_FIELDS: readonly ["givenName", "familyName", "displayName", "email", "locale", "picture"];
+export type ProfileField = (typeof PROFILE_FIELDS)[number];
+/**
+ * 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.
+ */
+export declare function validateProfilePatch(input: unknown): {
+    ok: true;
+    value: Partial<Record<ProfileField, string>>;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * 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).
+ */
+export declare function projectProfile(metadata: unknown): IUserProfile;
+/**
+ * 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}.
+ */
+export declare function mergeProfileIntoMetadata(metadata: unknown, patch: Partial<Record<ProfileField, string>>): Record<string, unknown>;
+/**
+ * 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}`).
+ */
+export declare function profileFromClaims(claims: Record<string, unknown>): Partial<Record<ProfileField, string>>;

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

@@ -0,0 +1,41 @@
+import type { IPageQuery } from "nodefony";
+/**
+ * **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.
+ */
+export declare const USER_SORTABLE_FIELDS: readonly ["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é.
+ */
+export declare const USER_SORTABLE_FIELDS_IN_MEMORY: readonly ["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.
+ */
+export declare const USER_SORTABLE_FIELDS_COMMON: readonly ["identifier", "enabled", "id"];
+/**
+ * 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.
+ */
+export declare const USER_DEFAULT_ORDER: NonNullable<IPageQuery["order"]>;

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

@@ -0,0 +1,15 @@
+/**
+ * Déclare un backend de persistance utilisateur disponible (idempotent).
+ *
+ * @param name - nom court du backend (`"memory"`, `"drizzle"`, `"mongoose"`).
+ */
+export declare function registerUserStore(name: string): void;
+/**
+ * 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`).
+ */
+export declare function listUserStores(): string[];