@nodefony/mongoose 10.0.0-alpha.8 → 10.0.0-alpha.9

package/dist/nodefony/src/MongooseAuditStore.js

@@ -0,0 +1,213 @@
+import { AUDIT_ENTITY_NAMES } from "../entity/auditEventEntity.js";
+import { assertPageQuery } from "nodefony";
+//#region nodefony/src/MongooseAuditStore.ts
+/** Rétention par défaut d'un événement : 365 jours (aligné `MemoryAuditStore`). */
+const DEFAULT_RETENTION_MS = 31536e6;
+/** Taille de page par défaut / plafond (alignés `MemoryAuditStore`). */
+const DEFAULT_LIMIT = 100;
+const MAX_LIMIT = 500;
+/** Séparateur du curseur composite `<ts>:<id>` (cf `#parseCursor`). */
+const CURSOR_SEPARATOR = ":";
+/**
+* Journal d'audit **Mongoose** (NoSQL) — implémentation documentaire d'
+* {@link IAuditStore} (append-only, tamper-evident) pour la **rétention longue**
+* et le **partage cross-pod**, là où le store mémoire par défaut reste affine à
+* un pod et volatile. Pendant documentaire de `DrizzleAuditStore`.
+*
+* **Append-only** : `append` est la seule écriture ; aucune mutation ni
+* suppression ciblée d'un événement — seul {@link MongooseAuditStore.gc}
+* (rétention) retire des documents. L'immuabilité EST la garantie d'audit.
+*
+* **Pagination curseur EXACTE (`listPage`)** — l'ordre total est `(ts DESC, _id
+* DESC)` : `ts` porte l'ordre chronologique, `_id` (= l'id d'événement) casse
+* les collisions à la milliseconde (rafales de login). Le curseur transporte
+* **les deux** (`<ts>:<id>`) et se compare en **composite** — en Mongo, un `$or`
+* de deux clauses, qui sort du `Criteria` AND-only d'`IRepository`, d'où la
+* query native (même trappe que le frère SQL). Une ligne de garde (`limit + 1`)
+* détermine `hasNext` sans page vide parasite.
+*
+* ⚠️ **Le tri se fait sur `_id`, jamais sur un champ `id`** : au repos un
+* document Mongo n'a PAS de champ `id` (c'est un virtuel de lecture), et Mongo
+* ne se plaint pas d'un tri sur un champ absent — il rend un ordre arbitraire.
+* Un ordre total qui n'ordonne rien casserait le curseur en silence.
+*
+* **Résolution LAZY + dégradation gracieuse** (calqué sur le frère SQL) : le
+* modèle est résolu à CHAQUE appel, pas capturé à la construction — l'ORM se
+* déconnecte au shutdown avant le drain des serveurs, et un `connect()` rejoué
+* recrée la connexion. Si l'ORM n'est pas connecté : `append` est un no-op
+* **best-effort** (l'audit ne bloque ni ne fait échouer le flux métier — un
+* événement au shutdown est perdu plutôt que de crasher un login), `listPage`
+* rend une page vide et `gc` rend 0.
+*
+* Horloge injectable (`now`) pour des tests déterministes.
+*/
+var MongooseAuditStore = class MongooseAuditStore {
+	#resolveModel;
+	#now;
+	#retentionMs;
+	/**
+	* @param resolveModel - résolveur **lazy** du modèle Mongoose (`null` = ORM non
+	*   connecté → dégradation gracieuse).
+	* @param now - horloge (epoch ms) injectable pour des tests déterministes.
+	* @param retentionMs - fenêtre de rétention (ms) avant purge par `gc`.
+	*/
+	constructor(resolveModel, now = Date.now, retentionMs = DEFAULT_RETENTION_MS) {
+		this.#resolveModel = resolveModel;
+		this.#now = now;
+		this.#retentionMs = retentionMs;
+	}
+	/** Connecteur ORM qui porte ce store — posé par {@link MongooseAuditStore.from}. */
+	#connector;
+	/**
+	* Connecteur ORM qui porte ce store, lu par `readStoreConnector` pour le
+	* registre des stores : la console rattache la brique à SON connecteur au
+	* lieu de le déduire. `undefined` pour un store construit sans ORM (bancs).
+	*/
+	get connector() {
+		return this.#connector;
+	}
+	/**
+	* Construit le store depuis un {@link MongooseOrm}. Le modèle est résolu
+	* **lazy** (gardé par `isConnected()` → `null` tant que l'ORM n'est pas/plus
+	* connecté). L'entité (`registerAuditEntities`) doit avoir été enregistrée
+	* **avant** `orm.connect()` (le modèle est compilé au connect).
+	*
+	* @param orm - ORM Mongoose hébergeant la collection `audit_event`.
+	* @param now - horloge injectable (tests).
+	* @param retentionMs - fenêtre de rétention (ms).
+	*/
+	static from(orm, now, retentionMs) {
+		const store = new MongooseAuditStore(() => {
+			if (!orm.isConnected()) return null;
+			return orm.getNativeConnection().model(AUDIT_ENTITY_NAMES.events);
+		}, now, retentionMs);
+		store.#connector = orm.name;
+		return store;
+	}
+	async append(event) {
+		const model = this.#resolveModel();
+		if (!model) return;
+		await model.create({
+			_id: event.id,
+			ts: event.ts,
+			category: event.category,
+			action: event.action,
+			outcome: event.outcome,
+			actor: event.actor ?? null,
+			resource: event.resource ?? null,
+			reason: event.reason ?? null,
+			ip: event.ip ?? null,
+			userAgent: event.userAgent ?? null,
+			requestId: event.requestId ?? null,
+			flags: event.flags ?? null,
+			metadata: event.metadata ?? null
+		});
+	}
+	async listPage(query) {
+		assertPageQuery(query, "cursor");
+		const limit = Math.min(Math.max(1, query.limit ?? DEFAULT_LIMIT), MAX_LIMIT);
+		const model = this.#resolveModel();
+		if (!model) return {
+			items: [],
+			limit,
+			hasNext: false,
+			nextCursor: null,
+			total: 0
+		};
+		const filter = this.#buildFilter(query);
+		let total;
+		if (query.withTotal !== false) total = await model.countDocuments(filter).exec();
+		let where = filter;
+		const cursor = this.#parseCursor(query.cursor);
+		if (cursor) {
+			const after = { $or: [{ ts: { $lt: cursor.ts } }, {
+				ts: cursor.ts,
+				_id: { $lt: cursor.id }
+			}] };
+			where = Object.keys(filter).length > 0 ? { $and: [filter, after] } : after;
+		}
+		const docs = await model.find(where).sort({
+			ts: -1,
+			_id: -1
+		}).limit(limit + 1).exec();
+		const hasNext = docs.length > limit;
+		const rows = (hasNext ? docs.slice(0, limit) : docs).map((doc) => doc.toObject({ virtuals: true }));
+		const items = rows.map((row) => this.#toEvent(row));
+		const last = rows[rows.length - 1];
+		return {
+			items,
+			limit,
+			hasNext,
+			nextCursor: hasNext && last ? `${last.ts}${CURSOR_SEPARATOR}${this.#idOf(last)}` : null,
+			...total !== void 0 ? { total } : {}
+		};
+	}
+	/**
+	* Décode le curseur composite `<ts>:<id>` (format privé au store, comme ses
+	* pendants mémoire et SQL). Jeton absent ou malformé → `null` : la lecture
+	* repart de la page la plus récente plutôt que d'échouer sur une consultation.
+	*/
+	#parseCursor(cursor) {
+		if (cursor === void 0) return null;
+		const sep = cursor.indexOf(CURSOR_SEPARATOR);
+		if (sep <= 0) return null;
+		const ts = Number(cursor.slice(0, sep));
+		return Number.isFinite(ts) ? {
+			ts,
+			id: cursor.slice(sep + 1)
+		} : null;
+	}
+	async gc(now = this.#now()) {
+		const model = this.#resolveModel();
+		if (!model) return 0;
+		const threshold = now - this.#retentionMs;
+		return (await model.deleteMany({ ts: { $lt: threshold } }).exec()).deletedCount ?? 0;
+	}
+	/** Compose le filtre Mongo des critères AND ; `{}` si aucun (= tout). */
+	#buildFilter(filter) {
+		const where = {};
+		if (filter.category !== void 0) where.category = filter.category;
+		if (filter.outcome !== void 0) where.outcome = filter.outcome;
+		if (filter.actor !== void 0) where.actor = filter.actor;
+		if (filter.action !== void 0) where.action = filter.action;
+		if (filter.requestId !== void 0) where.requestId = filter.requestId;
+		if (filter.since !== void 0 || filter.until !== void 0) {
+			const ts = {};
+			if (filter.since !== void 0) ts.$gte = filter.since;
+			if (filter.until !== void 0) ts.$lte = filter.until;
+			where.ts = ts;
+		}
+		return where;
+	}
+	/** Identité réelle d'un événement : `_id` fait foi, le virtuel `id` en repli. */
+	#idOf(row) {
+		return row._id ?? row.id;
+	}
+	/**
+	* Mappe un document vers un événement du contrat.
+	*
+	* Les champs optionnels (`flags`, `metadata`) ne sont posés que s'ils portent
+	* une valeur : `IAuditEvent` les déclare **absents**, pas `null`, et un banc de
+	* parité compare les événements relus à ceux qui ont été écrits.
+	*/
+	#toEvent(row) {
+		const event = {
+			id: this.#idOf(row),
+			ts: row.ts,
+			category: row.category,
+			action: row.action,
+			outcome: row.outcome,
+			actor: row.actor,
+			resource: row.resource,
+			reason: row.reason,
+			ip: row.ip,
+			userAgent: row.userAgent,
+			requestId: row.requestId
+		};
+		if (row.flags) event.flags = row.flags;
+		if (row.metadata) event.metadata = row.metadata;
+		return event;
+	}
+};
+//#endregion
+export { MongooseAuditStore };

package/dist/nodefony/src/MongooseIdempotencyStore.js

@@ -0,0 +1,260 @@
+import { IDEMPOTENCY_ENTITY_NAME } from "../entity/idempotencyEntity.js";
+import { assertPageQuery, escapeRegExp } from "nodefony";
+//#region nodefony/src/MongooseIdempotencyStore.ts
+/** Bail par défaut d'une entrée *in-flight* : 60 s (au-delà = exécution abandonnée). */
+const DEFAULT_LEASE_MS = 6e4;
+/** Rétention par défaut d'une réponse mémorisée : 10 min (rejeu plausible). */
+const DEFAULT_TTL_MS = 6e5;
+/** Code d'erreur MongoDB d'une violation de contrainte d'unicité. */
+const DUPLICATE_KEY = 11e3;
+/**
+* L'erreur est-elle une violation d'unicité MongoDB (`E11000`) ?
+*
+* C'est le **verdict de la réservation**, pas un incident : sur ce store, une
+* violation d'unicité signifie « la clé était vivante, quelqu'un d'autre la
+* détient ». Toute autre erreur (réseau, autorisation) doit remonter — la
+* confondre avec une contention ferait passer une panne pour une dédup.
+*/
+function isDuplicateKeyError(error) {
+	return typeof error === "object" && error !== null && error.code === DUPLICATE_KEY;
+}
+/**
+* Store d'idempotence **Mongoose** (NoSQL) — implémentation documentaire d'
+* {@link 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. Pendant documentaire de `DrizzleIdempotencyStore`.
+*
+* **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.
+*
+* **Réservation atomique (`begin`)** — clé de voûte. Un `findOneAndUpdate`
+* filtré sur l'entrée MORTE, en `upsert`, est l'équivalent Mongo du `SET … NX
+* PX` Redis et du `INSERT … ON CONFLICT … WHERE expiré` SQL, en **une seule
+* instruction atomique** côté serveur :
+*  - clé absente → le filtre ne matche rien → l'`upsert` insère → `fresh` ;
+*  - clé présente mais **morte** (bail/rétention expirés) → le filtre matche →
+*    l'update la **vole** atomiquement → `fresh` ;
+*  - clé présente et **vivante** → le filtre ne matche pas → l'`upsert` tente
+*    d'insérer → violation d'unicité sur `_id` (`E11000`) → on lit l'état
+*    (`in-flight` / `replayed` / `mismatch`).
+*
+* C'est la **clé primaire** qui porte cette unicité, jamais un index secondaire :
+* 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.
+*
+* Le store ne renvoie JAMAIS `fresh` sur le chemin de contention → anti
+* double-effet garanti (l'invariant capital d'un store d'idempotence).
+*
+* **Pas de TTL natif** (≠ Redis `PX`, et un index TTL Mongo ignorerait la
+* bascule bail → rétention) → un {@link MongooseIdempotencyStore.gc} applicatif
+* purge les entrées expirées, comme la variante SQL.
+*
+* **Empreinte préservée à la complétion** : `complete()` ne touche pas le champ
+* `fingerprint` → un rejeu de la clé avec un AUTRE payload après complétion est
+* toujours détecté (`mismatch` 422, draft §2.7).
+*
+* **Résolution LAZY + dégradation gracieuse** (calqué sur le frère SQL) : le
+* modèle est résolu à CHAQUE appel, jamais capturé à la construction — le
+* framework fabrique ce store à `onKernelBoot`, AVANT le connect de l'ORM
+* (`onBoot`), et l'ORM se déconnecte au shutdown avant le drain des serveurs. Si
+* l'ORM n'est pas connecté, `begin` renvoie `fresh` (la mutation s'exécute SANS
+* dédup) et `complete`/`abort`/`gc` sont des no-op — l'idempotence est
+* temporairement inactive plutôt que de crasher une mutation en vol.
+*/
+var MongooseIdempotencyStore = class MongooseIdempotencyStore {
+	#resolveModel;
+	#now;
+	#leaseMs;
+	#ttlMs;
+	/** Compteur LOCAL best-effort des réservations faites par CE pod (cf {@link size}). */
+	#pending = 0;
+	/**
+	* @param resolveModel - résolveur **lazy** du modèle Mongoose (`null` = ORM non
+	*   connecté → dégradation gracieuse). Lazy car l'ordre de boot/shutdown n'est
+	*   pas garanti à la construction.
+	* @param now - horloge (epoch ms) injectable pour des tests déterministes.
+	* @param leaseMs - bail d'une entrée *in-flight* (ms).
+	* @param ttlMs - rétention d'une réponse mémorisée (ms).
+	* @param connector - connecteur ORM qui porte la collection, publié au registre des stores.
+	*/
+	constructor(resolveModel, now = Date.now, leaseMs = DEFAULT_LEASE_MS, ttlMs = DEFAULT_TTL_MS, connector) {
+		this.#connector = connector;
+		this.#resolveModel = resolveModel;
+		this.#now = now;
+		this.#leaseMs = leaseMs;
+		this.#ttlMs = ttlMs;
+	}
+	/** Connecteur ORM qui porte ce store — reçu du constructeur. */
+	#connector;
+	/**
+	* Connecteur ORM qui porte ce store, lu par `readStoreConnector` pour le
+	* registre des stores : la console rattache la brique à SON connecteur au
+	* lieu de le déduire. `undefined` pour un store construit sans ORM (bancs).
+	*/
+	get connector() {
+		return this.#connector;
+	}
+	/**
+	* Construit le store depuis un {@link MongooseOrm}. Le modèle est résolu
+	* **lazy** (gardé par `isConnected()` → `null` tant que l'ORM n'est pas/plus
+	* connecté). L'entité (`registerIdempotencyEntities`) doit avoir été
+	* enregistrée **avant** `orm.connect()` (le modèle est compilé au connect).
+	*
+	* @param orm - ORM Mongoose hébergeant la collection `idempotency_key`.
+	* @param now - horloge injectable (tests).
+	* @param leaseMs - bail *in-flight* (ms).
+	* @param ttlMs - rétention d'une réponse mémorisée (ms).
+	*/
+	static from(orm, now, leaseMs, ttlMs) {
+		return new MongooseIdempotencyStore(() => {
+			if (!orm.isConnected()) return null;
+			return orm.getNativeConnection().model(IDEMPOTENCY_ENTITY_NAME);
+		}, now, leaseMs, ttlMs, orm.name);
+	}
+	/**
+	* Approximation **per-pod, best-effort** : compteur local des réservations
+	* faites par CE pod (incrémenté au `fresh`, décrémenté au `complete`/`abort`),
+	* non décrémenté si le bail expire sans complétion, et désaligné cross-pod. La
+	* vérité cluster passe par un `countDocuments`, jamais ce getter (sync). Borné à ≥ 0.
+	*/
+	get size() {
+		return this.#pending < 0 ? 0 : this.#pending;
+	}
+	async begin(key, fingerprint) {
+		const model = this.#resolveModel();
+		if (!model) return { state: "fresh" };
+		const now = this.#now();
+		const leaseExpiresAt = now + this.#leaseMs;
+		let reserved;
+		try {
+			await model.findOneAndUpdate({
+				_id: key,
+				expiresAt: { $lt: now }
+			}, { $set: {
+				key,
+				fingerprint,
+				state: "if",
+				response: null,
+				expiresAt: leaseExpiresAt
+			} }, {
+				upsert: true,
+				returnDocument: "after"
+			}).exec();
+			reserved = true;
+		} catch (error) {
+			if (!isDuplicateKeyError(error)) throw error;
+			reserved = false;
+		}
+		if (reserved) {
+			this.#pending++;
+			return { state: "fresh" };
+		}
+		const existing = await model.findById(key).lean().exec();
+		if (existing === null) return { state: "in-flight" };
+		if (existing.fingerprint !== fingerprint) return { state: "mismatch" };
+		if (existing.state === "done" && existing.response !== null) return {
+			state: "replayed",
+			response: existing.response
+		};
+		return { state: "in-flight" };
+	}
+	async complete(key, response) {
+		const model = this.#resolveModel();
+		if (!model) return;
+		if (((await model.updateOne({
+			_id: key,
+			state: "if"
+		}, { $set: {
+			state: "done",
+			response,
+			expiresAt: this.#now() + this.#ttlMs
+		} }).exec()).modifiedCount ?? 0) > 0) this.#dec();
+	}
+	async abort(key) {
+		const model = this.#resolveModel();
+		if (!model) return;
+		if (((await model.deleteOne({
+			_id: key,
+			state: "if"
+		}).exec()).deletedCount ?? 0) > 0) this.#dec();
+	}
+	/**
+	* Purge les entrées mortes (`expiresAt <= now`) — supplée l'absence de TTL
+	* exploitable ici (cf le schéma : l'échéance bascule du bail à la rétention).
+	* À déclencher périodiquement (le framework arme un `GcScheduler` au boot
+	* quand cette méthode existe).
+	*
+	* @param now - horloge de purge (défaut : horloge injectée).
+	* @returns le nombre d'entrées supprimées.
+	*/
+	async gc(now = this.#now()) {
+		const model = this.#resolveModel();
+		if (!model) return 0;
+		return (await model.deleteMany({ expiresAt: { $lte: now } }).exec()).deletedCount ?? 0;
+	}
+	/**
+	* {@inheritDoc IIdempotencyStore.listPage}
+	*
+	* Query native projetée : on ne lit QUE les champs exposés — la réponse
+	* mémorisée (`response`) ne quitte jamais la base par ce chemin, quelle que
+	* soit la taille de la page (anti-IDOR sur le cache).
+	*
+	* Les entrées expirées sont exclues (`expiresAt > now`) : le GC applicatif
+	* passe plus tard, mais une clé échue n'est déjà plus opposable.
+	*
+	* ⚠️ **Le préfixe `q` est ÉCHAPPÉ**, donc littéral. Une chaîne saisie dans une
+	* console n'est pas une expression régulière : laisser passer les
+	* métacaractères ouvrirait un balayage de collection arbitraire — et pire, une
+	* catastrophe de retour sur trace. L'écart avec le frère SQL (où `%` et `_`
+	* restent des jokers) est assumé dans ce sens : ici le contrat — « `q` =
+	* préfixe » — est tenu au pied de la lettre.
+	*/
+	async listPage(query) {
+		assertPageQuery(query, "offset");
+		const limit = Math.max(1, Math.floor(query.limit));
+		const offset = Math.max(0, Math.floor(query.offset ?? 0));
+		const model = this.#resolveModel();
+		if (!model) return {
+			items: [],
+			total: 0,
+			limit,
+			offset,
+			hasNext: false
+		};
+		const filter = { expiresAt: { $gt: this.#now() } };
+		if (query.state !== void 0) filter.state = query.state === "in-flight" ? "if" : "done";
+		if (query.q !== void 0 && query.q.length > 0) filter._id = { $regex: `^${escapeRegExp(query.q)}` };
+		const docs = await model.find(filter, {
+			_id: 1,
+			state: 1,
+			expiresAt: 1
+		}).sort({
+			expiresAt: 1,
+			_id: 1
+		}).skip(offset).limit(limit + 1).lean().exec();
+		const hasNext = docs.length > limit;
+		const page = hasNext ? docs.slice(0, limit) : docs;
+		const total = query.withTotal === false ? void 0 : await model.countDocuments(filter).exec();
+		return {
+			items: page.map((doc) => ({
+				key: doc._id,
+				state: doc.state === "if" ? "in-flight" : "done",
+				expiresAtMs: Number(doc.expiresAt),
+				hasResponse: doc.state !== "if"
+			})),
+			total,
+			limit,
+			offset,
+			hasNext
+		};
+	}
+	/** Décrémente le compteur local borné à 0. */
+	#dec() {
+		if (this.#pending > 0) this.#pending--;
+	}
+};
+//#endregion
+export { MongooseIdempotencyStore };

package/dist/nodefony/src/MongooseTokenStore.js

@@ -1,5 +1,5 @@
-import { TOKEN_ENTITY_NAMES } from "../entity/tokenEntity.js";
 import { mongoOrder } from "./mongoOrder.js";
+import { TOKEN_ENTITY_NAMES } from "../entity/tokenEntity.js";
 import { assertPageQuery } from "nodefony";
 import { paginate } from "@nodefony/orm-core";
 import { TOKEN_DEFAULT_ORDER, TOKEN_SORTABLE_FIELDS, tokenStatusCriteria } from "@nodefony/security";
@@ -64,6 +64,16 @@ var MongooseTokenStore = class MongooseTokenStore {
 		this.#now = now;
 		this.#retentionRevokedMs = retentionRevokedMs;
 	}
+	/** Connecteur ORM qui porte ce store — posé par {@link MongooseTokenStore.from}. */
+	#connector;
+	/**
+	* Connecteur ORM qui porte ce store, lu par `readStoreConnector` pour le
+	* registre des stores : la console rattache la brique à SON connecteur au
+	* lieu de le déduire. `undefined` pour un store construit sans ORM (bancs).
+	*/
+	get connector() {
+		return this.#connector;
+	}
 	/**
 	* Construit le store depuis un {@link MongooseOrm} connecté. Les entités
 	* (`registerTokenEntities`) doivent avoir été enregistrées **avant** `connect()`.
@@ -73,16 +83,50 @@ var MongooseTokenStore = class MongooseTokenStore {
 	* @param retentionRevokedMs - rétention des PAT révoqués sans `exp`.
 	*/
 	static from(orm, now, retentionRevokedMs) {
-		return new MongooseTokenStore(orm.getRepository(TOKEN_ENTITY_NAMES.records), orm.getRepository(TOKEN_ENTITY_NAMES.denied), orm.getRepository(TOKEN_ENTITY_NAMES.revocations), now, retentionRevokedMs);
+		const store = new MongooseTokenStore(orm.getRepository(TOKEN_ENTITY_NAMES.records), orm.getRepository(TOKEN_ENTITY_NAMES.denied), orm.getRepository(TOKEN_ENTITY_NAMES.revocations), now, retentionRevokedMs);
+		store.#connector = orm.name;
+		return store;
 	}
 	/** Identité réelle d'un record (jti) : `_id` fait foi, le virtuel `id` en repli. */
 	#idOf(row) {
 		return row._id ?? row.id;
 	}
-	/** Normalise `id` (← `_id`) sur un record lu, sans dépendre du virtuel Mongoose. */
-	#withId(row) {
-		if (row) row.id = this.#idOf(row);
-		return row;
+	/**
+	* Document lu → record du contrat, champ par champ. Rendre le document tel
+	* quel laisserait fuir `_id` et `__v` — des champs du MOTEUR que Drizzle ne
+	* rend pas, et qui partiraient jusqu'aux vues d'administration.
+	*/
+	#toRecord(row) {
+		return {
+			id: this.#idOf(row),
+			kind: row.kind,
+			name: row.name,
+			prefix: row.prefix,
+			subjectId: row.subjectId,
+			subjectType: row.subjectType,
+			tenantId: row.tenantId,
+			scopes: row.scopes,
+			audience: row.audience,
+			resources: row.resources,
+			secretHash: row.secretHash,
+			hashAlg: row.hashAlg,
+			clientId: row.clientId,
+			cnf: row.cnf,
+			family: row.family,
+			replacedBy: row.replacedBy,
+			createdAt: row.createdAt,
+			expiresAt: row.expiresAt,
+			lastUsedAt: row.lastUsedAt,
+			lastUsedIp: row.lastUsedIp,
+			lastUsedUserAgent: row.lastUsedUserAgent,
+			revokedAt: row.revokedAt,
+			revokedReason: row.revokedReason,
+			metadata: row.metadata
+		};
+	}
+	/** `#toRecord` tolérant à l'absence (lecture unitaire). */
+	#toRecordOrNull(row) {
+		return row ? this.#toRecord(row) : null;
 	}
 	/**
 	* Insère ou remplace un record (PAT / refresh) — 1 round-trip, `upsert`
@@ -102,27 +146,24 @@ var MongooseTokenStore = class MongooseTokenStore {
 		await this.#records.upsert({ id }, rest);
 	}
 	async findById(id) {
-		return this.#withId(await this.#records.findOne({ id }));
+		return this.#toRecordOrNull(await this.#records.findOne({ id }));
 	}
 	async findByHash(secretHash) {
-		return this.#withId(await this.#records.findOne({ secretHash }));
+		return this.#toRecordOrNull(await this.#records.findOne({ secretHash }));
 	}
 	async findBySubject(subjectId) {
-		const rows = await this.#records.find({ subjectId });
-		for (const row of rows) row.id = this.#idOf(row);
-		return rows;
+		return (await this.#records.find({ subjectId })).map((row) => this.#toRecord(row));
 	}
 	/** Tous les jetons (PAT + refresh) — vue d'administration cross-porteur. */
 	async listAll() {
-		const rows = await this.#records.find({});
-		for (const row of rows) row.id = this.#idOf(row);
-		return rows;
+		return (await this.#records.find({})).map((row) => this.#toRecord(row));
 	}
 	/**
 	* {@inheritDoc ITokenStore.listPage}
 	*
 	* `paginate()` d'orm-core (skip/limit + countDocuments) sur un filtre portable ;
-	* les `id` sont re-normalisés (`_id` → `id`) comme dans {@link listAll}.
+	* les documents sont convertis en records (`_id` → `id`, sans `__v`) comme dans
+	* {@link listAll}.
 	*
 	* Le tri demandé est **traduit** avant de descendre : au repos, le jeton n'a
 	* pas de champ `id` (le `jti` EST le `_id`), et Mongo ne se plaint pas d'un tri
@@ -138,8 +179,10 @@ var MongooseTokenStore = class MongooseTokenStore {
 			withTotal: query.withTotal,
 			order: mongoOrder(query.order, this.sortableFields, TOKEN_DEFAULT_ORDER)
 		});
-		for (const row of page.items) row.id = this.#idOf(row);
-		return page;
+		return {
+			...page,
+			items: page.items.map((row) => this.#toRecord(row))
+		};
 	}
 	/** {@inheritDoc ITokenStore.countTokens} */
 	countTokens(query) {