@nodefony/user 10.0.0-alpha.4 → 10.0.0-alpha.6

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

@@ -3,10 +3,17 @@ import { nodefonyError } from "nodefony";
  * Mot de passe refusé par la politique (connu-compromis / interdit) — `code = 400`.
  *
  * Levée par `UserService.createUser`/`changePassword` quand le
- * {@link IPasswordBlocklist} branché rejette le candidat. Le message reste
- * générique : ni la source de la liste ni le mot de passe ne sont exposés.
+ * {@link IPasswordBlocklist} branché rejette le candidat. Le message NOMME la
+ * règle enfreinte quand la politique sait la dire, et rien d'autre : ni la
+ * source de la liste, ni le mot de passe — il finirait dans un journal.
  */
 export declare class WeakPasswordError extends nodefonyError {
-    constructor();
+    /** La règle enfreinte, telle que la politique l'a nommée (`null` si muette). */
+    readonly violation: string | null;
+    /**
+     * @param violation - règle enfreinte, en français. Omise, le message reste
+     *   générique — c'est le cas d'une implémentation qui ne rend qu'un booléen.
+     */
+    constructor(violation?: string | null);
 }
 export default WeakPasswordError;

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

@@ -46,10 +46,14 @@ export declare class UserService extends AbstractCrudService<IPasswordAuthentica
     #private;
     protected readonly encoder: IPasswordEncoder;
     /**
-     * Liste de blocage des mots de passe compromis (NIST SP 800-63B §5.1.1.2) —
-     * hook opt-in consulté à la création/changement (jamais au login). `null`
-     * par défaut : le framework fournit le point d'extension, l'application
-     * branche sa source (top-10k, fichier, API k-anonymity).
+     * Politique de mot de passe (NIST SP 800-63B §5.1.1.2) — consultée à la
+     * création et au changement, jamais au login.
+     *
+     * **Posée PAR DÉFAUT**, et c'est le point : un défaut `null` ne se voit pas,
+     * et personne ne l'écrasait — `security:user:add compta --password abc`
+     * réussissait. L'application REMPLACE cet objet pour durcir ou pour brancher
+     * sa propre source ; la mettre à `null` désactive tout contrôle, et c'est
+     * alors un geste explicite, pas un oubli.
      */
     passwordBlocklist: IPasswordBlocklist | null;
     /**

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

@@ -65,7 +65,17 @@ export interface IUserRevokedEvent {
     id: string;
     identifier: string;
     tenantId: string | null;
-    reason: "deleted" | "disabled" | "locked";
+    /**
+     * Ce qui a coupé l'accès du porteur.
+     *
+     * `password_changed` n'est pas une révocation de COMPTE — le compte reste
+     * actif — mais c'en est une de ses ACCÈS EN COURS : on change un mot de passe
+     * parce qu'il est perdu ou compromis, et laisser vivre les sessions ouvertes
+     * laisserait l'accès à qui l'a volé. La cascade est la même, et c'est le
+     * but : un seul canal, les abonnés futurs (webhooks) n'ont rien à savoir de
+     * la cause.
+     */
+    reason: "deleted" | "disabled" | "locked" | "password_changed";
 }
 /**
  * Statut du sous-système utilisateur — miroir consommé par la console Studio

package/dist/types/nodefony/src/password/commonPasswordHashes.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Empreintes des mots de passe les plus courants — **fichier GÉNÉRÉ, ne pas éditer**.
+ *
+ * Regénérer :
+ * `node scripts/generate-password-blocklist.mjs <fichier-source>`
+ *
+ * Contenu : les 4 premiers octets du SHA-1 de chaque mot de passe, triés, en
+ * base64 d'un `Uint32Array` gros-boutien. Le clair n'est PAS embarqué — ni
+ * lisible, ni reconstructible depuis ce fichier.
+ *
+ * Sources :
+ * - `xato-net-10-million-passwords-10000.txt` — 9999 entrées, SHA-256 `c63d5e4ccc31344d662583cc39ca4bd5…`
+ *
+ * Corpus : SecLists (`danielmiessler/SecLists`), **licence MIT** — attribution
+ * portée ici, telle que la licence l'exige. Le corpus lui-même n'est pas
+ * redistribué : seules ces empreintes le sont.
+ */
+/** 9999 empreintes triées (39996 octets décodés). */
+export declare const COMMON_PASSWORD_HASHES_BASE64: string;
+/** Nombre d'empreintes — sert de contrôle au décodage. */
+export declare const COMMON_PASSWORD_HASH_COUNT = 9999;

package/dist/types/nodefony/src/password/passwordHash.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Les 4 premiers octets du SHA-1, en entier non signé.
+ *
+ * @param plain - mot de passe candidat.
+ * @returns l'empreinte tronquée, comparable aux entrées de la liste.
+ */
+export declare function truncatedPasswordHash(plain: string): number;

package/dist/types/nodefony/src/password/passwordPolicy.d.ts

@@ -0,0 +1,60 @@
+import type { IPasswordBlocklist, IPasswordSubjectHint } from "../../contracts/IPasswordBlocklist.js";
+/** Réglages d'une politique — tout est optionnel, les défauts sont sains. */
+export interface IPasswordPolicyOptions {
+    /**
+     * Longueur minimale acceptée. Défaut : 10.
+     *
+     * Le plancher du NIST est 8 ; on retient 10 parce que le contrôle de liste le
+     * permet sans exiger de composition — et parce qu'en deçà, les empreintes des
+     * mots de passe courants couvrent déjà presque tout l'espace saisi.
+     */
+    minLength?: number;
+    /** Mots de passe refusés en propre (noms métier, du produit, du client). */
+    blocklist?: readonly string[];
+    /**
+     * Fichier de mots de passe refusés, une valeur par ligne (UTF-8). Lu au
+     * PREMIER contrôle, comme les empreintes — un fichier absent ou illisible est
+     * une erreur FRANCHE, jamais un contrôle qui se tait.
+     */
+    blocklistFile?: string | null;
+    /** Consulter les empreintes embarquées. Défaut : `true`. */
+    checkCommonPasswords?: boolean;
+}
+/** Défauts de la politique — source unique, relue par les tests. */
+export declare const DEFAULT_PASSWORD_POLICY: Required<IPasswordPolicyOptions>;
+/**
+ * Politique par défaut : six règles, de la moins chère à la plus chère.
+ *
+ * Implémente {@link IPasswordBlocklist} — donc remplaçable par l'application,
+ * et composable (une implémentation maison peut l'appeler avant sa propre source).
+ */
+export declare class PasswordPolicy implements IPasswordBlocklist {
+    #private;
+    readonly options: Required<IPasswordPolicyOptions>;
+    /**
+     * @param options - réglages ; chaque clé absente prend le défaut sain.
+     */
+    constructor(options?: IPasswordPolicyOptions);
+    /**
+     * La règle enfreinte, ou `null` si le mot de passe est accepté.
+     *
+     * Le texte rendu nomme la règle SANS jamais citer le mot de passe : il finit
+     * dans un message d'erreur, donc potentiellement dans un journal.
+     *
+     * @param plain - mot de passe candidat.
+     * @param subject - ce qu'on sait du compte (son identifiant).
+     * @returns la règle enfreinte, en français, ou `null`.
+     */
+    violation(plain: string, subject?: IPasswordSubjectHint): Promise<string | null>;
+    /**
+     * Le mot de passe doit-il être refusé ?
+     *
+     * Même règle, même code que {@link violation} — une seule implémentation, deux
+     * portes : le contrat ne demande qu'un booléen, l'appelant qui veut expliquer
+     * prend l'autre.
+     *
+     * @param plain - mot de passe candidat.
+     * @param subject - ce qu'on sait du compte.
+     */
+    isBlocked(plain: string, subject?: IPasswordSubjectHint): Promise<boolean>;
+}

package/dist/types/nodefony/src/password/seedFailure.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Le message d'un **semis de compte qui a échoué** — celui que l'erreur, seule,
+ * ne peut pas écrire.
+ *
+ * Le problème est un partage d'information, pas un défaut de code.
+ * {@link WeakPasswordError} nomme la règle enfreinte et **rien d'autre** : ni le
+ * compte visé, ni la valeur refusée, parce qu'un message d'erreur finit dans un
+ * journal. Le seul à savoir QUI était semé, et D'OÙ venait le mot de passe, est
+ * l'appelant. Tant que les deux moitiés restent séparées, l'exploitant lit
+ * « Mot de passe refusé : contient l'identifiant du compte » sans savoir quel
+ * compte, ni quoi corriger — vécu : une application générée ne démarrait plus,
+ * et la seule trace utile était une ligne perdue dans un journal détaché.
+ *
+ * Ce module réunit les deux moitiés, une fois pour tout le monde : le gabarit
+ * d'application, le dépôt de développement du framework et toute application
+ * qui sème ses propres comptes appellent la MÊME fonction. Recopier ce message
+ * dans chaque semis le ferait diverger en silence — et c'est le message, pas le
+ * code, qui fait la différence entre dix secondes et une demi-heure.
+ */
+/** Ce que l'appelant sait du semis, et que l'erreur ignore. */
+export interface ISeedFailureContext {
+    /** Identifiant du compte qu'on tentait de semer (`"admin"`). */
+    identifier: string;
+    /**
+     * Variable d'environnement qui porte le mot de passe (`"NF_ADMIN_PASSWORD"`).
+     */
+    envVar: string;
+    /**
+     * Le mot de passe venait-il de {@link envVar} ?
+     *
+     * `false` = il vient d'un défaut écrit dans le code de l'application. Envoyer
+     * corriger une variable que personne n'a posée ferait chercher là où il n'y a
+     * rien : le remède n'est alors pas le même geste.
+     */
+    fromEnv: boolean;
+    /** Le compte visait-il un rôle d'administration ? Décide du `--admin` du remède. */
+    admin?: boolean;
+}
+/**
+ * Rédige le message d'un semis raté : QUEL compte, QUELLE règle, QUEL geste.
+ *
+ * Les trois sont indissociables. Un message qui nomme la règle sans le compte
+ * laisse chercher lequel ; un message qui nomme le compte sans le geste laisse
+ * l'exploitant devant un constat. Et la dernière phrase dit ce que le lecteur se
+ * demande immédiatement : l'application tourne-t-elle encore ?
+ *
+ * @param cause - ce que la création du compte a levé.
+ * @param context - ce que l'appelant est seul à savoir.
+ * @returns le message à journaliser, sans saut de ligne (il part en `ERROR`).
+ */
+export declare function describeSeedFailure(cause: unknown, context: ISeedFailureContext): string;

package/docs/ajouter-des-champs.md

@@ -58,7 +58,7 @@ parfois le pire : cette table n'est pas une table comme les autres.
 **La table des utilisateurs est relue à chaque requête portant une session authentifiée.** Ce n'est
 pas un détail d'implémentation, c'est le cœur du modèle : une session ne transporte qu'un
 identifiant, jamais l'utilisateur lui-même. À chaque requête, `SessionAuthenticator.authenticate()`
-(`src/packages/@nodefony/security/nodefony/src/authenticator/SessionAuthenticator.ts:63`) redemande
+(`src/packages/@nodefony/security/nodefony/src/authenticator/SessionAuthenticator.ts:96`) redemande
 l'identité vivante — `resolveSessionIdentity`
 (`src/packages/@nodefony/security/nodefony/src/authenticator/SessionAuthenticator.ts:70`) — pour que
 la désactivation d'un compte, un changement de rôle ou un verrouillage prennent effet

package/docs/index.md

@@ -24,7 +24,7 @@ status: stable
 updated: 2026-07-19
 source: "src/packages/@nodefony/user/docs/index.md"
 coverageModule: user
-coverageFiles: UserService.ts,BaseUser.ts,AnonymousUser.ts,InMemoryUserRepository.ts,userProfile.ts,UserAdminApi.ts,Argon2idEncoder.ts,BcryptEncoder.ts,MigratingEncoder.ts,encoderFromConfig.ts
+coverageFiles: UserService.ts,passwordPolicy.ts,BaseUser.ts,AnonymousUser.ts,InMemoryUserRepository.ts,userProfile.ts,UserAdminApi.ts,Argon2idEncoder.ts,BcryptEncoder.ts,MigratingEncoder.ts,encoderFromConfig.ts
 ---
 
 # @nodefony/user — l'identité, socle de toute la sécurité
@@ -289,7 +289,7 @@ use("@nodefony/security", {
 
 > [!NOTE]
 > Sans section `encoders`, le défaut du schéma Zod est **déjà** un Argon2id sûr
-> (`security/nodefony/config/config.ts:1079`). Tu ne déclares cette section que pour ajouter un format
+> (`security/nodefony/config/config.ts:1110`). Tu ne déclares cette section que pour ajouter un format
 > legacy, ou pour ajuster les coûts.
 
 ### 2. Déclarer le service `users` (`nodefony/security/provisionUsers.ts`)
@@ -464,7 +464,7 @@ lieu au seul moment où le mot de passe en clair existe côté serveur, un login
 ### L'ordre des vérifications
 
 `locked` → `disabled` → `no_password` → `bad_credentials`. Cet ordre est fixé
-(`UserService.ts:212`), mais il n'est pas observable de l'extérieur : la valeur de retour est `null`
+(`UserService.ts:270`), mais il n'est pas observable de l'extérieur : la valeur de retour est `null`
 dans tous les cas, et la raison précise part dans l'événement `onAuthenticationFailure` — donc dans
 l'audit serveur, jamais dans la réponse.
 
@@ -536,7 +536,7 @@ ajoute quatre accès que le `Criteria` générique ne sait pas exprimer.
 | `loadUserByIdentifier()`             | `IUserProvider` — **lève** `UserNotFoundError` si absent      | `UserService.ts:301` |
 | `loadUserByOAuth()`                  | `IUserProvider` — lit un lien social, ne crée jamais          | `UserService.ts:317` |
 | `refreshUser()`                      | recharge depuis la source (rôles frais, révocation immédiate) | `UserService.ts:331` |
-| `provisionOAuthUser()`               | Shadow User : lit, ou crée si la politique l'autorise         | `UserService.ts:306` |
+| `provisionOAuthUser()`               | Shadow User : lit, ou crée si la politique l'autorise         | `UserService.ts:363` |
 | `passwordBlocklist`                  | champ opt-in — branche ta liste de mots de passe compromis    | `UserService.ts:83`  |
 
 **La distinction à retenir** : `loadUserByOAuth()` **lit** (et lève si le lien est inconnu) ;
@@ -670,7 +670,7 @@ flowchart TD
 
 Le compte local est le **Shadow User** : ton application garde sa propre ligne, avec ses propres
 rôles, son propre état actif/verrouillé. Le fournisseur n'est qu'une façon de prouver qu'on est bien
-la personne rattachée à cette ligne (`UserService.ts:306`).
+la personne rattachée à cette ligne (`UserService.ts:363`).
 
 ### Trois invariants, et pourquoi ils existent
 
@@ -749,23 +749,93 @@ d'identité est un échec explicite, pas une valeur.
 Si tu veux seulement valider un couple identifiant/mot de passe contre un système externe, le contrat
 plus étroit `IPasswordVerifier` suffit (`IPasswordVerifier.ts:15`).
 
-### Sa liste de mots de passe compromis
+### La politique de mot de passe — posée par défaut, et remplaçable
 
-Le NIST (SP 800-63B §5.1.1.2) recommande de refuser les mots de passe connus des fuites. Le framework
-fournit le **point d'extension**, pas la liste : la source (top 10 000 embarqué, fichier
-d'exploitation, API k-anonymity) est une décision de déploiement.
+Le NIST (SP 800-63B §5.1.1.2) recommande de refuser les mots de passe prévisibles — et de NE PAS
+exiger de composition (majuscules, chiffres, caractères spéciaux), qui produit `Password1!` sans
+ajouter d'entropie réelle. Nodefony suit cette lecture : ce qui est mesuré, c'est la
+**prévisibilité**.
+
+**La politique est posée d'office** sur tout `UserService` : rien à brancher, et c'est le point —
+un point d'extension que personne ne remplit ne protège personne. Elle est consultée à la
+**création** et au **changement**, jamais au login : là, le clair n'est plus jugeable, et refuser
+une connexion existante enfermerait l'utilisateur dehors.
+
+Six règles, dans cet ordre — les gratuites d'abord, la liste en dernier :
+
+| #   | Ce qui est refusé                                        | Exemple refusé               |
+| --- | -------------------------------------------------------- | ---------------------------- |
+| 1   | plus court que `minLength` (défaut **10**)               | `abc`, `motdepas`            |
+| 2   | contient l'identifiant du compte                         | `marie.dupont-2026`          |
+| 3   | répète un même motif de bout en bout                     | `aaaaaaaaaa`, `abababababab` |
+| 4   | contient une suite de touches ou de chiffres             | `azertyuiop`, `0123456789`   |
+| 5   | figure dans la liste de l'application                    | ce que tu y mets             |
+| 6   | figure parmi les ~10 000 mots de passe les plus courants | `basketball`, `password123`  |
+
+Le refus **nomme la règle** : `Mot de passe refusé : figure parmi les mots de passe les plus
+courants`. C'est ce que rendent `security:user:add` et `security:user:password` (code de sortie non
+nul), et ce que la console d'administration renvoie en 400.
+
+#### Régler la politique
 
 ```ts ignore
+import { PasswordPolicy } from "@nodefony/user";
+
+users.passwordBlocklist = new PasswordPolicy({
+  minLength: 14, // durcir
+  blocklist: ["MaSociete2026", "NomDuProduit"], // quelques mots métier
+  blocklistFile: "var/mots-de-passe-interdits.txt", // une politique maintenue à part
+});
+```
+
+| Option                 | Défaut | Ce qu'elle fait                                             |
+| ---------------------- | ------ | ----------------------------------------------------------- |
+| `minLength`            | `10`   | longueur minimale                                           |
+| `blocklist`            | `[]`   | valeurs refusées, comparaison insensible à la casse         |
+| `blocklistFile`        | `null` | fichier UTF-8, une valeur par ligne, lu au premier contrôle |
+| `checkCommonPasswords` | `true` | consulter la liste embarquée                                |
+
+Un **fichier introuvable fait échouer le contrôle**, il ne le rend pas muet : une politique qu'on
+croit en place et qui n'a rien lu est pire qu'une politique absente.
+
+#### Brancher sa propre source
+
+`IPasswordBlocklist` reste le point d'extension — pour un annuaire d'entreprise, une base maison, ou
+une API k-anonymity (type Have I Been Pwned, qui n'envoie que cinq caractères du hash). Elle
+s'appelle en plus de la politique, pas à sa place :
+
+```ts ignore
+const politique = new PasswordPolicy();
 users.passwordBlocklist = {
-  async isBlocked(plain) {
-    return TOP_10K.has(plain.toLowerCase());
-  },
+  isBlocked: async (plain, subject) =>
+    (await politique.isBlocked(plain, subject)) ||
+    (await maSource.connu(plain)),
+  violation: async (plain, subject) =>
+    (await politique.violation(plain, subject)) ??
+    ((await maSource.connu(plain))
+      ? "figure dans notre annuaire de fuites"
+      : null),
 };
 ```
 
-Consultée à la **création** et au **changement**, jamais au login (`UserService.ts:359`) : au login,
-le clair n'est plus jugeable contre une politique, et refuser une connexion existante enfermerait
-l'utilisateur dehors. Un refus lève `WeakPasswordError` (400), avec un message générique.
+Mettre `users.passwordBlocklist = null` désactive tout contrôle. C'est permis — une application qui
+juge les mots de passe en amont n'a pas à payer deux fois — mais c'est alors un **geste explicite**,
+plus un défaut qu'on ne voit pas.
+
+#### La liste embarquée, et ce qu'elle coûte
+
+~10 000 empreintes de 4 octets (`Uint32Array` trié, recherche binaire) : **40 Ko**, et le module qui
+les porte est chargé par un `import()` dynamique au premier contrôle — une application qui ne crée
+aucun compte ne le lit jamais. Le clair n'est pas embarqué : seules les empreintes le sont, et elles
+ne sont pas réversibles. La troncature rend une collision possible (~2,3 × 10⁻⁶ par test) ; elle
+**refuse** alors un mot de passe sain, ce qui tombe du bon côté.
+
+Le corpus vient de [SecLists](https://github.com/danielmiessler/SecLists) (licence MIT, attribution
+portée dans l'artefact). Regénérer l'artefact :
+
+```bash
+node scripts/generate-password-blocklist.mjs <fichier-source>
+```
 
 ### Son propre provisionnement OAuth
 
@@ -939,7 +1009,7 @@ Une erreur d'administration ne doit pas fermer la porte définitivement. Cinq ga
 | supprimer ou désactiver le dernier admin actif | 409                                         |
 
 Le comptage passe par `countActiveAdmins()`, un `COUNT` natif au store — jamais un chargement complet
-en mémoire (`UserService.ts:154`).
+en mémoire (`UserService.ts:174`).
 
 ### Cascade de révocation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodefony/user",
-  "version": "10.0.0-alpha.4",
+  "version": "10.0.0-alpha.6",
   "description": "Contrats utilisateur de Nodefony, indépendants de l'ORM : interface IUser, utilisateurs de base, encodeurs de mot de passe et UserService — consommable sans @nodefony/security",
   "contributors": [],
   "type": "module",
@@ -40,8 +40,8 @@
   "peerDependencies": {
     "@node-rs/argon2": "^2.0.2",
     "@node-rs/bcrypt": "^1.10.0",
-    "@nodefony/orm-core": "^10.0.0-alpha.4",
-    "nodefony": "^10.0.0-alpha.4"
+    "@nodefony/orm-core": "^10.0.0-alpha.6",
+    "nodefony": "^10.0.0-alpha.6"
   },
   "peerDependenciesMeta": {
     "@node-rs/bcrypt": {
@@ -52,12 +52,12 @@
     }
   },
   "devDependencies": {
-    "@node-rs/argon2": "^2.1.0",
+    "@node-rs/argon2": "^2.2.1",
     "@node-rs/bcrypt": "^1.10.8",
-    "@nodefony/orm-core": "^10.0.0-alpha.4",
-    "@types/node": "26.4.1",
+    "@nodefony/orm-core": "^10.0.0-alpha.6",
+    "@types/node": "26.5.1",
     "@vitest/coverage-v8": "5.0.0",
-    "nodefony": "^10.0.0-alpha.4",
+    "nodefony": "^10.0.0-alpha.6",
     "rimraf": "6.1.3",
     "vitest": "5.0.0"
   },
@@ -66,11 +66,11 @@
     "url": "git+https://github.com/nodefony/nodefony-core.git",
     "directory": "src/packages/@nodefony/user"
   },
-  "license": "CECILL-B",
+  "license": "Apache-2.0",
   "licenses": [
     {
-      "type": "CECILL-B",
-      "url": "http://www.cecill.info/licences/Licence_CeCILL-B_V1-en.html"
+      "type": "Apache-2.0",
+      "url": "https://www.apache.org/licenses/LICENSE-2.0"
     }
   ],
   "author": "Christophe CAMENSULI <ccamensuli@gmail.com>",