@nodefony/mongoose 10.0.0-alpha.8 → 10.0.0-beta.1

package/dist/nodefony/src/orm-core/MongooseRepository.js

@@ -1,7 +1,21 @@
+import { MONGO_ORDER_ALIASES } from "../mongoOrder.js";
+import { writeCount } from "../writeCount.js";
 import { RequestContext, redactSecrets } from "nodefony";
-import { UnknownCriteriaField, assertOrderOption, isFieldOperators, isUpdateOperators, likePatternToRegExp, queryFlowMonitor } from "@nodefony/orm-core";
+import { ReferencedEntityError, UnknownCriteriaField, assertOrderOption, isFieldOperators, isUpdateOperators, likePatternToRegExp, queryFlowMonitor } from "@nodefony/orm-core";
 //#region nodefony/src/orm-core/MongooseRepository.ts
 /**
+* Clé Mongo d'un champ de TRI — `id` public → `_id` au repos.
+*
+* Mongo ne se plaint pas d'un tri sur un champ absent : il rend les documents
+* dans un ordre arbitraire. `id` n'est qu'un virtuel de lecture ; sans cette
+* traduction, `order: [["id", "DESC"]]` — le départage du tri par défaut de
+* tout CRUD généré — serait silencieusement inerte ici et correct en SQL. Même
+* table que les stores Mongo ({@link MONGO_ORDER_ALIASES}).
+*/
+function sortKey(field) {
+	return MONGO_ORDER_ALIASES[field] ?? field;
+}
+/**
 * Repository portable (contrat {@link IRepository}) au-dessus d'un modèle Mongoose.
 *
 * Démontre la portabilité du contrat sur un **store documentaire hétérogène** :
@@ -19,15 +33,29 @@ var MongooseRepository = class MongooseRepository {
 	#session;
 	/** Connecteur ORM (clé du registre) — tag des métriques de flux. */
 	#connector;
+	/** Champs qui référencent cette entité — `null` si personne ne la vise (cas courant, coût nul). */
+	#referrers;
 	/**
 	* @param model - modèle Mongoose compilé.
 	* @param connector - nom de la connexion (clé du registre) — défaut `"nodefony"`.
 	* @param session - session transactionnelle à laquelle lier les ops (ou `null`).
+	* @param referrers - champs d'autres entités qui référencent celle-ci (index
+	*   inverse de {@link MongooseOrm}) ; `null` quand aucune ne la vise.
 	*/
-	constructor(model, connector = "nodefony", session = null) {
+	constructor(model, connector = "nodefony", session = null, referrers = null) {
 		this.#model = model;
 		this.#connector = connector;
 		this.#session = session;
+		this.#referrers = referrers;
+	}
+	/**
+	* Options de session pour les méthodes dont le type refuse `session: null`
+	* (`updateMany`, `deleteMany`, `countDocuments`…) : la clé est ABSENTE hors
+	* transaction. Un objet neuf par appel, comme le littéral qu'il remplace —
+	* Mongoose peut enrichir l'objet d'options qu'il reçoit.
+	*/
+	#sessionOptions() {
+		return this.#session === null ? {} : { session: this.#session };
 	}
 	/**
 	* Tap dev-only : mesure la durée d'une opération et alimente **deux** sondes
@@ -77,6 +105,13 @@ var MongooseRepository = class MongooseRepository {
 	* (`$eq`/`$ne`) — en Mongo `null` matche aussi le champ **absent**, ce qui est
 	* bien l'équivalent du `NULL` SQL (colonne sans valeur).
 	*
+	* `$ne`/`$nin` ne matchent JAMAIS l'absence de valeur, comme en SQL (où
+	* `col <> 'x'` est inconnu, donc faux, sur un NULL). Natifs, ils la
+	* matcheraient : `{ note: { $ne: "x" } }` ramenait sous MongoDB les documents
+	* sans note, que PostgreSQL écarte — la même requête rendait plus de lignes en
+	* production MongoDB, sans un mot. `null` est donc ajouté à l'ensemble exclu.
+	* Un `$nin` VIDE reste neutre (SQL : aucune exclusion, NULL compris).
+	*
 	* @throws Error si `$null` est combiné à `$eq`/`$ne` sur le même champ : les
 	*   deux viseraient la même clé Mongo et l'une écraserait l'autre **en
 	*   silence** (le contrat les déclare exclusifs — cf `FieldOperators.$null`).
@@ -90,6 +125,17 @@ var MongooseRepository = class MongooseRepository {
 			out[target] = null;
 		} else if ((key === "$eq" || key === "$ne") && key in out) throw new Error(`criteria: $null ne se combine pas avec ${key} sur le même champ (${this.#model.modelName})`);
 		else out[key] = value;
+		const ne = ops.$ne;
+		const nin = ops.$nin;
+		if (ne !== void 0 && ne !== null || nin !== void 0 && nin.length > 0) {
+			const excluded = [...nin ?? []];
+			if (ne !== void 0 && ne !== null) {
+				excluded.push(ne);
+				delete out.$ne;
+			}
+			excluded.push(null);
+			out.$nin = excluded;
+		}
 		return out;
 	}
 	/**
@@ -106,7 +152,7 @@ var MongooseRepository = class MongooseRepository {
 	#resolveField(field) {
 		const key = field === "id" ? "_id" : field;
 		const paths = this.#model.schema.paths;
-		if (key === "_id" || paths[key] !== void 0 || paths[key.split(".")[0]] !== void 0) return key;
+		if (key === "_id" || paths[key] !== void 0 || paths[key.split(".")[0] ?? key] !== void 0) return key;
 		throw new UnknownCriteriaField(field, this.#model.modelName, Object.keys(paths));
 	}
 	/**
@@ -141,7 +187,7 @@ var MongooseRepository = class MongooseRepository {
 			if (options?.relations?.length) query = query.populate(options.relations);
 			if (options?.offset !== void 0) query = query.skip(options.offset);
 			if (options?.limit !== void 0) query = query.limit(options.limit);
-			if (options?.order?.length) query = query.sort(Object.fromEntries(options.order.map(([field, dir]) => [field, dir === "DESC" ? -1 : 1])));
+			if (options?.order?.length) query = query.sort(Object.fromEntries(options.order.map(([field, dir]) => [sortKey(field), dir === "DESC" ? -1 : 1])));
 			return (await query.exec()).map((doc) => this.#plain(doc));
 		}, (docs) => docs.length);
 	}
@@ -152,21 +198,22 @@ var MongooseRepository = class MongooseRepository {
 			let query = this.#model.findOne(filter);
 			if (this.#session) query = query.session(this.#session);
 			if (options?.relations?.length) query = query.populate(options.relations);
-			if (options?.order?.length) query = query.sort(Object.fromEntries(options.order.map(([field, dir]) => [field, dir === "DESC" ? -1 : 1])));
+			if (options?.order?.length) query = query.sort(Object.fromEntries(options.order.map(([field, dir]) => [sortKey(field), dir === "DESC" ? -1 : 1])));
 			const doc = await query.exec();
 			return doc ? this.#plain(doc) : null;
 		}, (doc) => doc ? 1 : 0);
 	}
 	async create(data) {
 		return this.#prof(() => this.#descr("create"), async () => {
-			const [doc] = await this.#model.create([data], { session: this.#session ?? void 0 });
+			const [doc] = await this.#model.create([data], { session: this.#session });
+			if (doc === void 0) throw new Error(`create: le pilote n'a rendu aucun document (${this.#model.modelName})`);
 			return this.#plain(doc);
 		}, () => 1);
 	}
 	async createMany(data) {
 		if (data.length === 0) return [];
 		return this.#prof(() => this.#descr("insertMany"), async () => {
-			return (await this.#model.insertMany(data, { session: this.#session ?? void 0 })).map((doc) => this.#plain(doc));
+			return (await this.#model.insertMany(data, { session: this.#session })).map((doc) => this.#plain(doc));
 		}, (rows) => rows.length);
 	}
 	async updateOne(criteria, data) {
@@ -174,7 +221,7 @@ var MongooseRepository = class MongooseRepository {
 		return this.#prof(() => this.#descr("findOneAndUpdate", filter), async () => {
 			const doc = await this.#model.findOneAndUpdate(filter, data, {
 				returnDocument: "after",
-				session: this.#session ?? void 0
+				session: this.#session
 			}).exec();
 			return doc ? this.#plain(doc) : null;
 		}, (doc) => doc ? 1 : 0);
@@ -188,9 +235,8 @@ var MongooseRepository = class MongooseRepository {
 			}, {
 				upsert: true,
 				returnDocument: "after",
-				session: this.#session ?? void 0
+				session: this.#session
 			}).exec();
-			if (!doc) throw new Error("MongooseRepository.upsert: aucun document retourné");
 			return this.#plain(doc);
 		}, () => 1);
 	}
@@ -224,7 +270,8 @@ var MongooseRepository = class MongooseRepository {
 	async updateMany(criteria, data) {
 		const filter = this.#filter(criteria);
 		return this.#prof(() => this.#descr("updateMany", filter), async () => {
-			return (await this.#model.updateMany(filter, data, { session: this.#session ?? void 0 })).modifiedCount ?? 0;
+			const res = await this.#model.updateMany(filter, data, this.#sessionOptions());
+			return writeCount(res.modifiedCount);
 		}, (n) => n);
 	}
 	async increment(criteria, changes) {
@@ -232,33 +279,108 @@ var MongooseRepository = class MongooseRepository {
 		return this.#prof(() => this.#descr("findOneAndUpdate", filter), async () => {
 			const doc = await this.#model.findOneAndUpdate(filter, { $inc: changes }, {
 				returnDocument: "after",
-				session: this.#session ?? void 0
+				session: this.#session
 			}).exec();
 			return doc ? this.#plain(doc) : null;
 		}, (doc) => doc ? 1 : 0);
 	}
 	async delete(criteria) {
-		const filter = this.#filter(criteria);
-		return this.#prof(() => this.#descr("deleteMany", filter), async () => {
-			return (await this.#model.deleteMany(filter, { session: this.#session ?? void 0 })).deletedCount ?? 0;
+		let filter = this.#filter(criteria);
+		const ids = await this.#referencedTargets(filter, false);
+		if (ids !== null) {
+			if (ids.length === 0) return 0;
+			filter = { _id: { $in: ids } };
+		}
+		const removed = await this.#prof(() => this.#descr("deleteMany", filter), async () => {
+			const res = await this.#model.deleteMany(filter, this.#sessionOptions());
+			return writeCount(res.deletedCount);
 		}, (n) => n);
+		if (ids !== null && removed > 0) await this.#releaseOptional(ids);
+		return removed;
 	}
 	async deleteOne(criteria) {
-		const filter = this.#filter(criteria);
-		return this.#prof(() => this.#descr("deleteOne", filter), async () => {
-			return ((await this.#model.deleteOne(filter, { session: this.#session ?? void 0 })).deletedCount ?? 0) > 0;
+		let filter = this.#filter(criteria);
+		const ids = await this.#referencedTargets(filter, true);
+		if (ids !== null) {
+			if (ids.length === 0) return false;
+			filter = { _id: ids[0] };
+		}
+		const removed = await this.#prof(() => this.#descr("deleteOne", filter), async () => {
+			const res = await this.#model.deleteOne(filter, this.#sessionOptions());
+			return writeCount(res.deletedCount) > 0;
 		}, (ok) => ok ? 1 : 0);
+		if (ids !== null && removed) await this.#releaseOptional(ids);
+		return removed;
 	}
 	async findOneAndDelete(criteria) {
-		const filter = this.#filter(criteria);
-		return this.#prof(() => this.#descr("findOneAndDelete", filter), async () => {
-			const doc = await this.#model.findOneAndDelete(filter, { session: this.#session ?? void 0 }).exec();
-			return doc ? this.#plain(doc) : null;
-		}, (doc) => doc ? 1 : 0);
+		let filter = this.#filter(criteria);
+		const ids = await this.#referencedTargets(filter, true);
+		if (ids !== null) {
+			if (ids.length === 0) return null;
+			filter = { _id: ids[0] };
+		}
+		const doc = await this.#prof(() => this.#descr("findOneAndDelete", filter), async () => {
+			const found = await this.#model.findOneAndDelete(filter, { session: this.#session }).exec();
+			return found ? this.#plain(found) : null;
+		}, (d) => d ? 1 : 0);
+		if (ids !== null && doc !== null) await this.#releaseOptional(ids);
+		return doc;
+	}
+	/**
+	* Garde d'intégrité d'une suppression — le `restrict` que MongoDB ne tient pas.
+	*
+	* Rend `null` (et ne coûte rien) quand aucune entité ne référence celle-ci.
+	* Sinon, lit les `_id` que la suppression viserait, REFUSE si l'un d'eux est
+	* encore désigné par une référence obligatoire, et les rend : la suppression
+	* porte alors sur ces `_id` exacts, pas sur le filtre — ce qui a été contrôlé
+	* est ce qui part.
+	*
+	* ⚠️ Hors transaction, le contrôle et la suppression sont deux opérations : un
+	* enfant créé entre les deux n'est pas vu. Le SQL, lui, est atomique ; dans
+	* une transaction (`withTransaction`), les deux lisent la même session.
+	* ⚠️ Les `_id` visés sont tous chargés : une suppression en MASSE garde sa
+	* règle « un seul parent retenu bloque le lot », au prix d'une mémoire
+	* proportionnelle au lot. Le CRUD généré supprime par `id`, donc un à un.
+	*
+	* @param filter - filtre Mongo déjà traduit.
+	* @param single - vrai pour `deleteOne`/`findOneAndDelete` (un seul document).
+	* @returns les `_id` visés, ou `null` si l'entité n'est référencée par personne.
+	* @throws ReferencedEntityError si une référence obligatoire désigne l'un d'eux.
+	*/
+	async #referencedTargets(filter, single) {
+		const referrers = this.#referrers;
+		if (referrers === null) return null;
+		const session = this.#session;
+		const query = this.#model.find(filter, { _id: 1 }, { session }).lean();
+		if (single) query.limit(1);
+		const docs = await query.exec();
+		if (docs.length === 0) return [];
+		const ids = docs.map((d) => d._id);
+		for (const referrer of referrers) {
+			if (!referrer.required) continue;
+			if (await referrer.model.exists(referrer.model === this.#model ? {
+				[referrer.path]: { $in: ids },
+				_id: { $nin: ids }
+			} : { [referrer.path]: { $in: ids } }).session(session ?? null).exec() !== null) throw new ReferencedEntityError(this.#model.modelName, referrer.model.modelName, referrer.path);
+		}
+		return ids;
+	}
+	/**
+	* Remet à `null` les références FACULTATIVES aux documents supprimés — le
+	* `set null` du SQL généré : l'enfant survit à son parent, sans pointer dans
+	* le vide.
+	*
+	* @param ids - `_id` des documents supprimés.
+	*/
+	async #releaseOptional(ids) {
+		for (const referrer of this.#referrers ?? []) {
+			if (referrer.required) continue;
+			await referrer.model.updateMany({ [referrer.path]: { $in: ids } }, { $set: { [referrer.path]: null } }, this.#sessionOptions());
+		}
 	}
 	async count(criteria) {
 		const filter = this.#filter(criteria);
-		return this.#prof(() => this.#descr("countDocuments", filter), () => this.#model.countDocuments(filter, { session: this.#session ?? void 0 }));
+		return this.#prof(() => this.#descr("countDocuments", filter), () => this.#model.countDocuments(filter, this.#sessionOptions()));
 	}
 	/**
 	* `COUNT(DISTINCT …)` en agrégation — `$group` puis `$count`, donc la
@@ -293,7 +415,7 @@ var MongooseRepository = class MongooseRepository {
 		});
 	}
 	withTransaction(tx) {
-		return new MongooseRepository(this.#model, this.#connector, tx.getNative());
+		return new MongooseRepository(this.#model, this.#connector, tx.getNative(), this.#referrers);
 	}
 };
 //#endregion

package/dist/nodefony/src/orm-core/MongooseTransaction.js

@@ -1,3 +1,4 @@
+import { SavepointNotSupportedError } from "@nodefony/orm-core";
 //#region nodefony/src/orm-core/MongooseTransaction.ts
 /**
 * Adapte une `ClientSession` MongoDB au contrat portable {@link ITransaction}.
@@ -7,8 +8,8 @@
 * MongoDB **exigent un replica set** (un standalone ne les supporte pas).
 *
 * MongoDB n'a **pas de savepoints** : {@link MongooseTransaction.savepoint} /
-* {@link MongooseTransaction.rollbackTo} sont des no-op documentés (limite du
-* driver, prévue par le contrat).
+* {@link MongooseTransaction.rollbackTo} les REFUSENT (`SavepointNotSupportedError`).
+* Un no-op laissait croire un rollback partiel qui n'annulait rien.
 */
 var MongooseTransaction = class {
 	#session;
@@ -40,10 +41,22 @@ var MongooseTransaction = class {
 		this.#done = true;
 		await this.#session.abortTransaction();
 	}
-	/** No-op : MongoDB ne gère pas les savepoints. */
-	async savepoint(_name) {}
-	/** No-op : MongoDB ne gère pas les savepoints. */
-	async rollbackTo(_name) {}
+	/**
+	* Refusé : MongoDB n'a pas de savepoints.
+	*
+	* @throws SavepointNotSupportedError toujours.
+	*/
+	async savepoint(_name) {
+		throw new SavepointNotSupportedError("mongodb", "savepoint");
+	}
+	/**
+	* Refusé : MongoDB n'a pas de savepoints.
+	*
+	* @throws SavepointNotSupportedError toujours.
+	*/
+	async rollbackTo(_name) {
+		throw new SavepointNotSupportedError("mongodb", "rollbackTo");
+	}
 	/** Expose la `ClientSession` native (trappe bas niveau). */
 	getNative() {
 		return this.#session;

package/dist/nodefony/src/writeCount.js

@@ -0,0 +1,17 @@
+//#region nodefony/src/writeCount.ts
+/**
+* Compte rendu par une écriture MongoDB (`deletedCount`, `modifiedCount`), 0 s'il manque.
+*
+* Le pilote le type `number`, mais le recopie de la réponse du serveur
+* (`res.n`) : une écriture NON acquittée (`w: 0`) n'en reçoit aucune, et le
+* compte arrive `undefined`. Sans ce repli, un `gc()` rendrait `undefined` et
+* un `> 0` conclurait « rien écrit » pour une raison qui n'est pas la bonne.
+*
+* @param count - le compte tel que le pilote le rend.
+* @returns le compte, ou 0 quand le serveur n'en a rendu aucun.
+*/
+function writeCount(count) {
+	return count ?? 0;
+}
+//#endregion
+export { writeCount };

package/dist/types/index.d.ts

@@ -70,5 +70,14 @@ export { MongooseWebAuthnCredentialStore } from "./nodefony/src/MongooseWebAuthn
 export { webhookEndpointSchema, createWebhookEndpointEntity, registerWebhookEndpointEntity, WEBHOOK_ENDPOINT_ENTITY, } from "./nodefony/entity/webhookEndpointEntity.js";
 export type { WebhookEndpointRow } from "./nodefony/entity/webhookEndpointEntity.js";
 export { MongooseWebhookStore } from "./nodefony/src/MongooseWebhookStore.js";
+export { auditEventSchema, createAuditEntities, registerAuditEntities, AUDIT_ENTITY_NAMES, } from "./nodefony/entity/auditEventEntity.js";
+export type { AuditEventRow } from "./nodefony/entity/auditEventEntity.js";
+export { MongooseAuditStore } from "./nodefony/src/MongooseAuditStore.js";
+export { totpSecretSchema, createTotpSecretEntity, registerTotpSecretEntity, TOTP_SECRET_ENTITY, } from "./nodefony/entity/totpSecretEntity.js";
+export type { TotpSecretRow } from "./nodefony/entity/totpSecretEntity.js";
+export { MongooseTotpSecretStore } from "./nodefony/src/MongooseTotpSecretStore.js";
+export { idempotencyKeySchema, createIdempotencyEntities, registerIdempotencyEntities, IDEMPOTENCY_ENTITY_NAME, } from "./nodefony/entity/idempotencyEntity.js";
+export type { IdempotencyKeyRow } from "./nodefony/entity/idempotencyEntity.js";
+export { MongooseIdempotencyStore } from "./nodefony/src/MongooseIdempotencyStore.js";
 export { registerMongooseFrameworkStores, FRAMEWORK_CONNECTOR, } from "./nodefony/registerStores.js";
 export type { IFrameworkStoresReport } from "./nodefony/registerStores.js";

package/dist/types/nodefony/entity/auditEventEntity.d.ts

@@ -0,0 +1,76 @@
+import type { SchemaDefinition } from "mongoose";
+import type { IEntity } from "@nodefony/orm-core";
+import type { AuditCategory, AuditOutcome, IAuditEventFlags } from "@nodefony/security";
+/**
+ * Schéma Mongoose du **journal d'audit** `@nodefony/security` — pendant
+ * documentaire de la table Drizzle `audit_event`, implémentation NoSQL d'
+ * `IAuditStore` (append-only, tamper-evident).
+ *
+ * ⚠️ **`_id` = clé naturelle (String), PAS un ObjectId auto** : l'`id` d'un
+ * événement est posé par l'`AuditService` (corrélation + curseur de pagination)
+ * → on force `_id: String`, l'id EST la clé primaire. Même convention que
+ * `webhookEndpointEntity` et `tokenEntity`.
+ *
+ * ⚠️ **Horodatage = `Number` (epoch ms), `timestamps:false`** : `IAuditEvent.ts`
+ * porte un `number` (`Date.now()`), pas une `Date` — et c'est ce champ qui porte
+ * l'ordre du journal.
+ *
+ * **Index** — mêmes axes que la variante SQL, et pour la même raison (filtrage
+ * de la console d'audit) ; perf de lecture seule, jamais de sémantique.
+ *
+ * L'ORDRE TOTAL du store (`ts DESC, _id DESC`) est porté par un index
+ * COMPOSITE déclaré sur l'entité (`indexes`, cf `createAuditEntities`) : un
+ * `SchemaDefinition` plat n'exprime que des index par champ, et sans lui la
+ * requête du journal parcourait toute la collection puis triait en mémoire
+ * (plan `COLLSCAN` + `SORT`, mesuré). C'est lui qui garantit, au coût d'un
+ * parcours d'index, qu'aucun événement ne se répète ni ne se perd d'une page à
+ * l'autre — `audit-store.test.ts` en lit le plan d'exécution.
+ */
+export declare const auditEventSchema: SchemaDefinition;
+/**
+ * Forme **plate** d'une ligne du journal renvoyée par le repository Mongoose —
+ * `id` = virtuel (= `_id` = l'id d'événement). Miroir d'`IAuditEvent` avec les
+ * champs optionnels rendus explicitement `| null` (le document Mongo les porte
+ * à `null`, jamais absents). `MongooseAuditStore` mappe `Row ↔ IAuditEvent`.
+ */
+export interface AuditEventRow {
+    id: string;
+    ts: number;
+    category: AuditCategory;
+    action: string;
+    outcome: AuditOutcome;
+    actor: string | null;
+    resource: string | null;
+    reason: string | null;
+    ip: string | null;
+    userAgent: string | null;
+    requestId: string | null;
+    flags: IAuditEventFlags | null;
+    metadata: Record<string, unknown> | null;
+}
+/** Noms logiques des entités du store (clés de lookup `getRepository`). */
+export declare const AUDIT_ENTITY_NAMES: {
+    readonly events: "audit_event";
+};
+/**
+ * Construit les descripteurs d'entités du journal d'audit pour un ORM nommé.
+ *
+ * Le `connector` est **dynamique** (nom du connecteur de l'app, ex. `"nodefony"`) :
+ * le schéma est statique mais sa liaison à un ORM dépend de la config → pas
+ * d'`@entity` figé. Pas de dialecte (NoSQL) : le schéma est portable par
+ * construction. À enregistrer **avant** `orm.connect()` (modèle compilé au connect).
+ *
+ * `module: "security"` → la collection est regroupée sous @nodefony/security dans
+ * l'ERD Studio (l'audit est une feature security, hébergée par l'ORM).
+ *
+ * @param connector - clé de l'ORM cible dans le `ormRegistry`.
+ * @returns les descripteurs {@link IEntity} du journal d'audit.
+ */
+export declare function createAuditEntities(connector: string): IEntity[];
+/**
+ * Enregistre les entités du journal d'audit dans le `entityRegistry` pour un ORM
+ * donné. À appeler **avant** `orm.connect()` (le modèle est compilé au connect).
+ *
+ * @param connector - nom de la connexion cible (clé du registre).
+ */
+export declare function registerAuditEntities(connector: string): void;

package/dist/types/nodefony/entity/idempotencyEntity.d.ts

@@ -0,0 +1,75 @@
+import type { SchemaDefinition } from "mongoose";
+import type { IEntity } from "@nodefony/orm-core";
+import type { IdempotentResponse } from "nodefony";
+/**
+ * Schéma Mongoose du **store d'idempotence** — pendant documentaire de la table
+ * Drizzle `idempotency_key`, implémentation NoSQL d'`IIdempotencyStore` (contrat
+ * au CORE) pour dédoublonner les mutations rejouées PARTAGÉ cross-pod, là où le
+ * store mémoire par défaut reste affine à un pod.
+ *
+ * **Pourquoi MongoDB plutôt que Redis** : un cluster qui possède déjà une base
+ * Mongo mais pas de Redis obtient la dédup cross-pod sans nouvelle infra — le
+ * même argument qui fonde la variante SQL.
+ *
+ * ⚠️ **`_id` = la clé d'idempotence (String)** : c'est la contrainte d'unicité de
+ * la clé primaire qui porte la **réservation atomique** de `begin`
+ * (`findOneAndUpdate(… , {upsert:true})` → `E11000` pour le perdant). Faire
+ * porter l'unicité par un index secondaire serait un faux ami : Mongoose
+ * construit ses index en tâche de fond, donc la contrainte n'existerait pas
+ * pendant la fenêtre de construction, et deux `begin` concurrents renverraient
+ * tous deux `fresh` — exactement le double-effet que ce store existe pour
+ * empêcher. Sur `_id`, la contrainte existe dès le premier document.
+ *
+ * Le champ `key` est **dupliqué** à côté de `_id` : c'est lui que le vocabulaire
+ * public filtre (`q` = préfixe de clé) et que `listPage` rend. Les deux sont
+ * écrits ensemble, jamais séparément.
+ *
+ * ⚠️ **PAS de TTL index natif** (≠ `expireAfterSeconds`) : l'échéance d'une
+ * entrée n'est pas une durée fixe depuis sa création — c'est d'abord un **bail**
+ * *in-flight* (`now + lease`), puis une **rétention** (`now + ttl`) posée à la
+ * complétion. Un TTL index effacerait selon une règle qui ignore cette bascule.
+ * `expiresAt` est donc un `Number` (epoch ms) indexé, purgé par le `gc()`
+ * applicatif — même contrepartie que la variante SQL.
+ *
+ * `state` : `if` = réservation *in-flight* ; `done` = réponse mémorisée
+ * (rejouée en `replayed`). `response` = la réponse mémorisée, `null` tant
+ * qu'*in-flight* ; elle ne sort JAMAIS par `listPage` (anti-IDOR sur le cache).
+ */
+export declare const idempotencyKeySchema: SchemaDefinition;
+/**
+ * Forme plate d'une ligne du store d'idempotence telle que rendue par le
+ * repository Mongoose. Identique aux champs de {@link idempotencyKeySchema}
+ * → zéro mapping store ↔ entité.
+ */
+export interface IdempotencyKeyRow {
+    key: string;
+    fingerprint: string;
+    state: "if" | "done";
+    response: IdempotentResponse | null;
+    expiresAt: number;
+}
+/** Nom logique de l'entité (clé de lookup `getRepository` / `entityRegistry`). */
+export declare const IDEMPOTENCY_ENTITY_NAME: "idempotency_key";
+/**
+ * Construit le descripteur d'entité du store d'idempotence pour un ORM nommé.
+ *
+ * Le `connector` est **dynamique** (nom du connecteur de l'app, ex. `"nodefony"`) :
+ * le schéma est statique mais sa liaison à un ORM dépend de la config → pas
+ * d'`@entity` figé. À enregistrer **avant** `orm.connect()` (le modèle est
+ * compilé au connect).
+ *
+ * `module: "framework"` → la collection est regroupée sous @nodefony/framework
+ * dans l'ERD Studio (l'idempotence est une feature framework — data plane admin
+ * + `@Idempotent` — simplement hébergée par l'ORM).
+ *
+ * @param connector - clé de l'ORM cible dans le `ormRegistry`.
+ * @returns les descripteurs {@link IEntity} du store d'idempotence.
+ */
+export declare function createIdempotencyEntities(connector: string): IEntity[];
+/**
+ * Enregistre l'entité du store d'idempotence dans le `entityRegistry` pour un
+ * ORM donné. À appeler **avant** `orm.connect()`.
+ *
+ * @param connector - nom de la connexion cible (clé du registre).
+ */
+export declare function registerIdempotencyEntities(connector: string): void;

package/dist/types/nodefony/entity/totpSecretEntity.d.ts

@@ -0,0 +1,75 @@
+import type { SchemaDefinition } from "mongoose";
+import type { IEntity } from "@nodefony/orm-core";
+/**
+ * Algorithme HMAC du code TOTP (RFC 6238) — union littérale (miroir du
+ * `TotpAlgorithm` de `@nodefony/security`, non ré-exporté à la racine). Écrite en
+ * clair plutôt que dérivée d'`ITotpSecret["algorithm"]` : sinon le `.d.ts` généré
+ * référencerait un chemin interne du package security (non portable, TS2883).
+ */
+type TotpAlgorithm = "SHA1" | "SHA256" | "SHA512";
+/**
+ * Schéma Mongoose du **store de secrets TOTP** `@nodefony/security` (2FA) —
+ * pendant documentaire de la table Drizzle `totp_secret`, implémentation NoSQL
+ * d'`ITotpSecretStore`.
+ *
+ * ⚠️ **`_id` = `userId` (String)** : le modèle est **1 secret / utilisateur**, donc
+ * la clé naturelle EST l'utilisateur — `save` devient un upsert par `_id`, et
+ * l'unicité est portée par la clé primaire elle-même (aucun index à construire
+ * en tâche de fond, donc aucune fenêtre où la contrainte n'existerait pas).
+ *
+ * Le champ `userId` est **dupliqué** à côté de `_id` : c'est lui que le
+ * vocabulaire public trie et filtre (`q` = préfixe d'`userId`), et un document
+ * Mongo n'expose pas `_id` sous un autre nom. Les deux sont écrits ensemble par
+ * le store, jamais séparément.
+ *
+ * ⚠️ **`secretEnc` = secret déjà CHIFFRÉ** (AES-256-GCM par le service détenteur
+ * de la clé) : le store ne voit que des octets opaques, jamais le secret `K` en
+ * clair. Il ne sort JAMAIS par `listPage` (cf `ITotpEnrollmentSummary`).
+ *
+ * ⚠️ **Horodatages = `Number` (epoch ms), `timestamps:false`** — sauf
+ * `lastUsedStep`, qui est une **tranche `T`** RFC 6238 (`floor(epochSeconds /
+ * period)`), pas un horodatage.
+ *
+ * `recoveryCodes` = tableau de condensats `sha256` des codes NON consommés ; le
+ * store les réécrit en bloc (jamais de mutation partielle in-place).
+ */
+export declare const totpSecretSchema: SchemaDefinition;
+/**
+ * Forme **plate** d'une ligne de secret renvoyée par le repository Mongoose.
+ * Structure identique à `ITotpSecret` (tout `| null` déjà présent côté contrat)
+ * → mapping quasi-identité dans `MongooseTotpSecretStore`.
+ */
+export interface TotpSecretRow {
+    userId: string;
+    secretEnc: string;
+    algorithm: TotpAlgorithm;
+    digits: number;
+    period: number;
+    recoveryCodes: string[];
+    confirmedAt: number | null;
+    lastUsedStep: number | null;
+    createdAt: number;
+    lastUsedAt: number | null;
+}
+/** Nom logique de l'entité (clé de lookup `getRepository`). */
+export declare const TOTP_SECRET_ENTITY = "totp_secret";
+/**
+ * Construit le descripteur d'entité du store de secrets TOTP pour un ORM nommé.
+ *
+ * Le `connector` est **dynamique** (nom du connecteur de l'app, ex. `"nodefony"`) :
+ * le schéma est statique mais sa liaison à un ORM dépend de la config → pas
+ * d'`@entity` figé. À enregistrer **avant** `orm.connect()` (le modèle est
+ * compilé au connect). `module: "security"` → regroupé sous @nodefony/security
+ * dans l'ERD Studio.
+ *
+ * @param connector - clé de l'ORM cible dans le `ormRegistry`.
+ */
+export declare function createTotpSecretEntity(connector: string): IEntity;
+/**
+ * Enregistre l'entité du store de secrets TOTP dans le `entityRegistry` pour un
+ * ORM donné. À appeler **avant** `orm.connect()`.
+ *
+ * @param connector - nom de la connexion cible (clé du registre).
+ */
+export declare function registerTotpSecretEntity(connector: string): void;
+export {};

package/dist/types/nodefony/registerStores.d.ts

@@ -7,9 +7,12 @@
  * modèles sont compilés à la connexion). Pas de dialecte (NoSQL) : les schémas
  * sont portables par construction.
  *
- * Couverture PARTIELLE assumée : session (auto via `@entity`), tokens, webauthn,
- * webhooks. PAS d'implémentation mongoose pour l'audit ni l'idempotence — les
- * sélectionner sur mongoose échoue franc (« store inconnu »), jamais en silence.
+ * Couverture : session (auto via `@entity`), utilisateurs, tokens, webauthn,
+ * webhooks, audit, TOTP et idempotence — soit **la totalité des briques
+ * durables**. C'est la propriété que Mongo doit tenir : une application doit
+ * pouvoir tourner SANS aucun backend SQL, et un backend durable est un chemin
+ * complet ou n'en est pas un. Une brique qui manquerait se sélectionnerait en
+ * échec franc (« store inconnu »), jamais en silence.
  *
  * Mêmes garde-fous que Drizzle : entité `has`-guarded (l'app garde la main),
  * fabrique `get`-guarded (premier-arrivé-premier-servi).

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

@@ -28,7 +28,7 @@ declare class MongooseService extends Service {
      */
     connectAll(connect?: boolean): Promise<void>;
     /** Assemble l'URI de connexion à partir de la config (`uri` ou composants). */
-    static buildUri(cfg: IMongooseConnectorConfig): string;
+    static buildUri(cfg: Partial<IMongooseConnectorConfig>): string;
     /**
      * Options de connexion Mongoose d'un connecteur.
      *
@@ -45,7 +45,7 @@ declare class MongooseService extends Service {
      * @param cfg - configuration validée du connecteur.
      * @returns les options à passer à la connexion, ou `undefined` s'il n'y en a aucune.
      */
-    static buildConnectOptions(cfg: IMongooseConnectorConfig): ConnectOptions | undefined;
+    static buildConnectOptions(cfg: Partial<IMongooseConnectorConfig>): ConnectOptions | undefined;
     /** Ferme toutes les connexions. */
     disconnectAll(): Promise<void>;
     /** Retourne l'ORM Mongoose d'un connecteur (défaut : `"nodefony"`). */