@nodefony/security 10.0.0-alpha.1

package/dist/nodefony/src/token/tokenCriteria.js

@@ -0,0 +1,35 @@
+//#region nodefony/src/token/tokenCriteria.ts
+/**
+* Fragment de critère **portable** exprimant l'état de vie d'un jeton — la
+* traduction que les adapters SQL et Mongo partagent au lieu de la réécrire.
+*
+* Elle tient dans le `Criteria` d'orm-core depuis que celui-ci porte `$or` :
+* « utilisable » signifie *sans échéance* **ou** *échéance à venir*, ce qu'aucune
+* conjonction ne dit. Avant ça, chaque backend serait descendu à son SQL natif —
+* trois écritures de la même règle, et la divergence pour seule perspective.
+*
+* Révoqué l'emporte sur expiré : les deux autres branches exigent donc
+* explicitement `revokedAt IS NULL`. Sans cette précision, une clé révoquée
+* **puis** échue compterait dans deux facettes, et la somme dépasserait le total.
+*
+* @param status - l'état demandé, ou `undefined` pour ne pas filtrer.
+* @param now - instant de référence (injecté : un compteur ne doit pas dépendre
+*   du moment où le test tourne).
+* @returns le fragment à fusionner dans le critère, vide si aucun filtre.
+*/
+function tokenStatusCriteria(status, now) {
+	switch (status) {
+		case "revoked": return { revokedAt: { $null: false } };
+		case "expired": return {
+			revokedAt: { $null: true },
+			expiresAt: { $lte: now }
+		};
+		case "active": return {
+			revokedAt: { $null: true },
+			$or: [{ expiresAt: { $null: true } }, { expiresAt: { $gt: now } }]
+		};
+		default: return {};
+	}
+}
+//#endregion
+export { tokenStatusCriteria };

package/dist/nodefony/src/token/tokenFilters.js

@@ -0,0 +1,72 @@
+//#region nodefony/src/token/tokenFilters.ts
+/**
+* **Le vocabulaire de filtre des jetons**, en noms PUBLICS — ceux qu'un client
+* écrit dans l'URL (`?status=revoked`), jamais des noms de colonne.
+*
+* Frère de `TOKEN_SORTABLE_FIELDS`, et posé pour la même raison : le vocabulaire
+* appartient au propriétaire du contrat (`@nodefony/security`), la mécanique de
+* lecture au cœur (`parseFilters`).
+*
+* **La différence avec le tri est structurelle.** Un tri est une CAPACITÉ de
+* backend — Redis ne sait pas trier, donc `sortableFields` se déclare par store.
+* Un filtre listé ici est une OBLIGATION de tous les backends de jetons : il est
+* inscrit dans {@link ITokenListQuery}, et le store mémoire, SQL, Mongo comme
+* Redis l'honorent chacun à sa façon (`WHERE` indexé, prédicat, filtre inline de
+* batch `SCAN`). Le déclarer par store laisserait croire qu'il est facultatif.
+*
+* **Ce qui n'y est PAS, et pourquoi** : `kind`. Il existe bien au contrat, mais
+* l'endpoint d'administration des clés d'API passe par `listPagePat`, qui impose
+* `kind: "pat"` (`service/apiKeys.ts:210`). L'exposer donnerait un filtre que le
+* service écrase en silence — la faute même que ce chantier corrige.
+*/
+const TOKEN_FILTERS = {
+	/** Restreint à un porteur (colonne indexée dans tous les backends SQL). */
+	subjectId: "string",
+	/**
+	* État de vie de la clé — la liste fermée vaut allowlist.
+	*
+	* Remplace l'ancien `revoked: "boolean"`, qui ne distinguait pas une clé
+	* ACTIVE d'une clé ARRIVÉE À ÉCHÉANCE : les deux étaient « non révoquées »,
+	* alors que la première ouvre l'accès et la seconde ne l'ouvre plus. La
+	* console affichait ces deux populations dans des cartes séparées sans
+	* pouvoir les demander au serveur.
+	*/
+	status: [
+		"active",
+		"expired",
+		"revoked"
+	]
+};
+/**
+* **Les facettes des jetons** — les questions fermées posées à la collection
+* ENTIÈRE pour les cartes de tête.
+*
+* Contrairement aux webhooks, les trois états **partitionnent** : un jeton est
+* dans exactement une case. On les compte tout de même une par une, sans jamais
+* soustraire — une partition est une propriété du domaine d'aujourd'hui, pas une
+* garantie du code, et un quatrième état la briserait en silence.
+*/
+const TOKEN_FACETS = {
+	/** Toutes les clés, quel que soit leur état. */
+	total: {},
+	/** Utilisables : ni révoquées, ni arrivées à échéance. */
+	active: { status: "active" },
+	/** Arrivées à échéance sans avoir été révoquées. */
+	expired: { status: "expired" },
+	/** Révoquées par un administrateur. */
+	revoked: { status: "revoked" }
+};
+/**
+* Ce que l'endpoint de COMPTEURS accepte de filtrer — `TOKEN_FILTERS` **moins**
+* les champs que les facettes décomposent.
+*
+* `status` en est retiré : le demander à un endpoint dont les cartes SONT les
+* états produirait une réponse qui se contredit — un total suivant le filtre, et
+* chaque facette l'écrasant par le sien. Le refuser dit au client ce qui se
+* passe ; l'accepter lui montrerait « 5 clés, dont 538 révoquées ».
+*
+* Un test verrouille l'accord entre cette liste et {@link TOKEN_FACETS}.
+*/
+const TOKEN_STATS_FILTERS = { subjectId: "string" };
+//#endregion
+export { TOKEN_FACETS, TOKEN_FILTERS, TOKEN_STATS_FILTERS };

package/dist/nodefony/src/token/tokenSort.js

@@ -0,0 +1,40 @@
+//#region nodefony/src/token/tokenSort.ts
+/**
+* **Le vocabulaire de tri des jetons**, en noms PUBLICS — ceux qu'un client écrit
+* dans l'URL (`?order=createdAt:DESC`), jamais des noms de colonne.
+*
+* Il vit ici, chez le propriétaire du contrat (`@nodefony/security`), et non dans
+* chaque backend : c'est ce qui garantit qu'une console de clés d'API offre le
+* même tri, que l'application tourne sur mémoire, SQL ou Mongo. Un store dont le
+* schéma nomme un champ autrement traduit **chez lui** — cf
+* {@link translateTokenOrderMongo}.
+*
+* - `createdAt` — date d'émission, l'axe naturel d'une console de clés ;
+* - `name` — le libellé humain, ce qu'on lit dans la colonne de gauche ;
+* - `subjectId` — regroupe les clés d'un même porteur (vue d'administration) ;
+* - `id` — identifiant public, utile surtout en départage.
+*
+* **Ce qui n'y est PAS, et pourquoi** : `lastUsedAt`, `expiresAt` et `revokedAt`
+* sont *nullables*, et le placement des valeurs absentes n'est pas le même d'un
+* moteur à l'autre — PostgreSQL range les `NULL` en tête d'un tri `DESC`, SQLite
+* et MySQL en queue, et le tri en mémoire (`compareByOrder`) les met en queue
+* dans les deux sens. Les déclarer offrirait donc un tri dont l'ordre
+* dépendrait de la base configurée, ce qui est exactement ce que ce vocabulaire
+* existe pour empêcher. Ils s'ouvriront quand la normalisation « absents en
+* queue » sera portée dans le helper de pagination, pas avant.
+*/
+const TOKEN_SORTABLE_FIELDS = [
+	"createdAt",
+	"name",
+	"subjectId",
+	"id"
+];
+/**
+* Ordre contractuel appliqué quand le client n'en demande aucun : les clés les
+* plus récentes d'abord, départagées par identifiant pour rester **déterministe**
+* à horodatage égal (sans quoi une pagination offset peut sauter ou répéter une
+* ligne entre deux pages).
+*/
+const TOKEN_DEFAULT_ORDER = [["createdAt", "DESC"], ["id", "DESC"]];
+//#endregion
+export { TOKEN_DEFAULT_ORDER, TOKEN_SORTABLE_FIELDS };

package/dist/nodefony/src/token/tokenStatus.js

@@ -0,0 +1,35 @@
+//#region nodefony/src/token/tokenStatus.ts
+/**
+* **La** définition de l'état d'un jeton — un seul exemplaire, pour les backends
+* qui évaluent en mémoire (store mémoire, filtrage inline d'un batch `SCAN`).
+*
+* L'ordre d'évaluation est significatif : **révoqué l'emporte sur expiré**. Une
+* clé révoquée puis arrivée à échéance reste « révoquée » — c'est l'acte
+* d'administration qui décrit ce qui s'est passé, pas l'écoulement du temps.
+*
+* Les backends SQL et Mongo n'appellent pas cette fonction (ils traduisent la
+* condition dans leur langage, sinon il faudrait rapatrier la collection pour la
+* filtrer) : c'est le banc de contrat partagé qui garantit qu'ils disent la même
+* chose qu'elle.
+*
+* @param token - les deux horodatages du jeton.
+* @param now - l'instant de référence (injecté : les tests ne dépendent pas de
+*   l'horloge réelle, et un store porte déjà la sienne).
+*/
+function tokenStatusOf(token, now) {
+	if (token.revokedAt !== null) return "revoked";
+	if (token.expiresAt !== null && token.expiresAt <= now) return "expired";
+	return "active";
+}
+/**
+* `true` si le jeton correspond au filtre d'état demandé (`undefined` = tous).
+*
+* @param token - les deux horodatages du jeton.
+* @param status - l'état demandé, ou `undefined` pour ne pas filtrer.
+* @param now - l'instant de référence.
+*/
+function matchesTokenStatus(token, status, now) {
+	return status === void 0 || tokenStatusOf(token, now) === status;
+}
+//#endregion
+export { matchesTokenStatus, tokenStatusOf };

package/dist/nodefony/src/token/tokenStoreRegistry.js

@@ -0,0 +1,25 @@
+import { MemoryTokenStore } from "./MemoryTokenStore.js";
+//#region nodefony/src/token/tokenStoreRegistry.ts
+const factories = /* @__PURE__ */ new Map();
+/**
+* Enregistre (ou remplace) la fabrique d'un store de jetons. Appelée par le
+* builtin `memory` au chargement, et par les adapters (drizzle/mongoose/redis)
+* pour les leurs.
+*/
+function registerTokenStore(name, factory) {
+	factories.set(name, factory);
+}
+/** Fabrique d'un store par nom, ou `undefined` si inconnu. */
+function getTokenStoreFactory(name) {
+	return factories.get(name);
+}
+/** Noms enregistrés (validation boot, introspection Studio, tests). */
+function listTokenStores() {
+	return [...factories.keys()];
+}
+registerTokenStore("memory", (ctx) => {
+	const days = ctx?.config?.tokenStore?.retentionRevokedDays;
+	return typeof days === "number" ? new MemoryTokenStore(Date.now, days * 864e5) : new MemoryTokenStore();
+});
+//#endregion
+export { getTokenStoreFactory, listTokenStores, registerTokenStore };

package/dist/nodefony/src/totp/MemoryTotpSecretStore.js

@@ -0,0 +1,97 @@
+import { assertPageQuery } from "nodefony";
+//#region nodefony/src/totp/MemoryTotpSecretStore.ts
+/**
+* Projette un secret en vue d'introspection — **le seul endroit** où l'on
+* décide ce qui sort d'un store TOTP en mémoire. `secretEnc` et les condensats
+* des codes de récupération n'y figurent pas : seul leur NOMBRE est exposé.
+*
+* @param secret - le secret stocké.
+* @returns la vue publique de l'enrôlement.
+*/
+function toTotpEnrollment(secret) {
+	return {
+		userId: secret.userId,
+		algorithm: secret.algorithm,
+		digits: secret.digits,
+		period: secret.period,
+		confirmedAt: secret.confirmedAt,
+		createdAt: secret.createdAt,
+		lastUsedAt: secret.lastUsedAt,
+		recoveryCodesLeft: secret.recoveryCodes.length
+	};
+}
+/** Applique les filtres d'{@link ITotpListQuery} — sémantique de RÉFÉRENCE. */
+function matchesTotpQuery(secret, query) {
+	if (query.confirmed !== void 0 && secret.confirmedAt !== null !== query.confirmed) return false;
+	if (query.q !== void 0 && query.q.length > 0) {
+		if (!secret.userId.startsWith(query.q)) return false;
+	}
+	return true;
+}
+/**
+* Store de secrets TOTP **en mémoire** — implémentation de référence
+* d'{@link ITotpSecretStore}. Clé = `userId` (un secret par utilisateur).
+*
+* 0 dépendance, idéale pour le développement mono-process et les **tests**. NON
+* partagée entre process et **volatile** → en production multi-process, utiliser
+* un adapter ORM ou Redis. Perf : la `Map` n'existe que si le store est instancié
+* (2FA activé), jamais sur le hot path par requête.
+*/
+var MemoryTotpSecretStore = class {
+	/** userId → secret (source de vérité). */
+	#byUser = /* @__PURE__ */ new Map();
+	findByUser(userId) {
+		return Promise.resolve(this.#byUser.get(userId) ?? null);
+	}
+	save(secret) {
+		this.#byUser.set(secret.userId, secret);
+		return Promise.resolve();
+	}
+	update(userId, patch) {
+		const secret = this.#byUser.get(userId);
+		if (secret) {
+			if (patch.confirmedAt !== void 0) secret.confirmedAt = patch.confirmedAt;
+			if (patch.recoveryCodes !== void 0) secret.recoveryCodes = patch.recoveryCodes;
+			if (patch.lastUsedStep !== void 0) secret.lastUsedStep = patch.lastUsedStep;
+			if (patch.lastUsedAt !== void 0) secret.lastUsedAt = patch.lastUsedAt;
+		}
+		return Promise.resolve();
+	}
+	delete(userId) {
+		this.#byUser.delete(userId);
+		return Promise.resolve();
+	}
+	/** {@inheritDoc ITotpSecretStore.listPage} */
+	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 matched = [...this.#byUser.values()].filter((s) => matchesTotpQuery(s, query));
+		matched.sort((a, b) => b.createdAt - a.createdAt || (a.userId < b.userId ? -1 : a.userId > b.userId ? 1 : 0));
+		const items = matched.slice(offset, offset + limit).map(toTotpEnrollment);
+		return Promise.resolve({
+			items,
+			total: query.withTotal === false ? void 0 : matched.length,
+			limit,
+			offset,
+			hasNext: offset + items.length < matched.length
+		});
+	}
+	/** {@inheritDoc ITotpSecretStore.countEnrollments} */
+	countEnrollments(query) {
+		let n = 0;
+		for (const secret of this.#byUser.values()) if (matchesTotpQuery(secret, query)) n += 1;
+		return Promise.resolve(n);
+	}
+	/** Instantané sérialisable de l'état courant (pour la persistance fichier). */
+	snapshot() {
+		return { secrets: [...this.#byUser.values()] };
+	}
+	/** Remplace l'état par celui d'un instantané. */
+	restore(snapshot) {
+		this.#byUser.clear();
+		for (const secret of snapshot.secrets) this.#byUser.set(secret.userId, secret);
+	}
+};
+//#endregion
+export { MemoryTotpSecretStore, MemoryTotpSecretStore as default, matchesTotpQuery, toTotpEnrollment };

package/dist/nodefony/src/totp/totpCipher.js

@@ -0,0 +1,30 @@
+import { decryptSecret, deriveKey, encryptSecret, generateEphemeralKey } from "../crypto/secretCipher.js";
+import { Buffer } from "node:buffer";
+//#region nodefony/src/totp/totpCipher.ts
+/**
+* Chiffrement réversible du secret TOTP au repos — façade de domaine au-dessus
+* de la brique générique {@link ../crypto/secretCipher}.
+*
+* Le secret TOTP `K` doit être **relu en clair** par le serveur à chaque
+* vérification de code → il est *chiffré* (AES-256-GCM), jamais haché. Ce module
+* fige le contexte de dérivation HKDF **propre au domaine TOTP** : ne JAMAIS
+* modifier {@link TOTP_DERIVATION} (sel/info), sous peine de rendre illisibles
+* tous les secrets TOTP déjà stockés.
+*/
+/**
+* Contexte HKDF figé du domaine TOTP. **Constantes historiques — ne pas changer.**
+*/
+const TOTP_DERIVATION = {
+	salt: Buffer.from("nodefony.totp.hkdf.v1"),
+	info: Buffer.from("totp-secret-encryption")
+};
+/**
+* Dérive la clé AES-256 du domaine TOTP via HKDF-SHA256 (RFC 5869).
+* Déterministe (clé lisible cross-pod). Délègue à {@link deriveKey} avec le
+* contexte figé du domaine TOTP.
+*/
+function deriveTotpKey(material) {
+	return deriveKey(material, TOTP_DERIVATION);
+}
+//#endregion
+export { decryptSecret, deriveTotpKey, encryptSecret, generateEphemeralKey };

package/dist/nodefony/src/totp/totpCrypto.js

@@ -0,0 +1,226 @@
+import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+//#region nodefony/src/totp/totpCrypto.ts
+/** Paramètres TOTP — défauts interopérables (Google Authenticator). */
+const TOTP_DEFAULTS = {
+	/** Taille du secret en octets (RFC 4226 R6 : 160 bits recommandés). */
+	secretBytes: 20,
+	/** Période d'un code en secondes (RFC 6238 §5.2 : 30 s recommandé). */
+	step: 30,
+	/** Nombre de chiffres du code (RFC 4226 §5.3 : 6 minimum). */
+	digits: 6,
+	/** Fonction de hachage HMAC (compat maximale = SHA1). */
+	algorithm: "SHA1",
+	/** Origine du décompte des tranches (RFC 6238 : T0 = 0 = epoch Unix). */
+	t0: 0,
+	/**
+	* Tolérance de dérive d'horloge, en nombre de pas de part et d'autre.
+	* RFC 6238 §5.2 : « at most one time step » → ±1 (1 pas = 30 s avant/après).
+	*/
+	window: 1
+};
+const BASE32_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+/**
+* Encode des octets en base32 RFC 4648 **sans padding** (`=`) — forme attendue
+* par les applications d'authentification dans l'URI `otpauth://`.
+*/
+function base32Encode(buf) {
+	let bits = 0;
+	let value = 0;
+	let out = "";
+	for (let i = 0; i < buf.length; i++) {
+		value = value << 8 | buf[i];
+		bits += 8;
+		while (bits >= 5) {
+			out += BASE32_ALPHABET[value >>> bits - 5 & 31];
+			bits -= 5;
+		}
+	}
+	if (bits > 0) out += BASE32_ALPHABET[value << 5 - bits & 31];
+	return out;
+}
+/**
+* Décode une chaîne base32 RFC 4648 → octets. Tolérant : ignore espaces,
+* tirets et padding `=`, insensible à la casse (un secret peut être saisi à la
+* main par l'utilisateur). Lève si un caractère hors alphabet est rencontré.
+*/
+function base32Decode(input) {
+	const clean = input.replace(/[\s=-]/g, "").toUpperCase();
+	let bits = 0;
+	let value = 0;
+	const out = [];
+	for (let i = 0; i < clean.length; i++) {
+		const idx = BASE32_ALPHABET.indexOf(clean[i]);
+		if (idx === -1) throw new Error(`base32: caractère invalide « ${clean[i]} »`);
+		value = value << 5 | idx;
+		bits += 5;
+		if (bits >= 8) {
+			out.push(value >>> bits - 8 & 255);
+			bits -= 8;
+		}
+	}
+	return Buffer.from(out);
+}
+/** Génère un secret TOTP cryptographiquement aléatoire (défaut 160 bits). */
+function generateTotpSecret(bytes = TOTP_DEFAULTS.secretBytes) {
+	return randomBytes(bytes);
+}
+/** Map nom RFC → identifiant `node:crypto`. */
+function hmacName(algo) {
+	return algo === "SHA1" ? "sha1" : algo === "SHA256" ? "sha256" : "sha512";
+}
+/** Encode un compteur 64 bits big-endian (RFC 4226 §5.1 : C sur 8 octets). */
+function counterBuffer(counter) {
+	const buf = Buffer.alloc(8);
+	buf.writeBigUInt64BE(BigInt(counter));
+	return buf;
+}
+/**
+* HOTP (RFC 4226 §5.3) — `Truncate(HMAC(K, counter))` → code à `digits` chiffres,
+* complété à gauche par des zéros.
+*
+* @param secret - secret partagé `K` (octets bruts).
+* @param counter - compteur `C` (≥ 0).
+* @param digits - longueur du code (défaut 6).
+* @param algorithm - fonction HMAC (défaut SHA1).
+*/
+function hotp(secret, counter, digits = TOTP_DEFAULTS.digits, algorithm = TOTP_DEFAULTS.algorithm) {
+	const hs = createHmac(hmacName(algorithm), secret).update(counterBuffer(counter)).digest();
+	const offset = hs[hs.length - 1] & 15;
+	return (((hs[offset] & 127) << 24 | (hs[offset + 1] & 255) << 16 | (hs[offset + 2] & 255) << 8 | hs[offset + 3] & 255) % 10 ** digits).toString().padStart(digits, "0");
+}
+/** Numéro de tranche temporelle `T` (RFC 6238 §4.2) pour un instant donné. */
+function totpCounter(epochSec, step = TOTP_DEFAULTS.step, t0 = TOTP_DEFAULTS.t0) {
+	return Math.floor((epochSec - t0) / step);
+}
+/**
+* Calcule le code TOTP courant (RFC 6238 §4) pour un secret donné.
+*
+* @param secret - secret partagé `K`.
+* @returns le code à `digits` chiffres pour la tranche temporelle courante.
+*/
+function totpCode(secret, opts = {}) {
+	const step = opts.step ?? TOTP_DEFAULTS.step;
+	return hotp(secret, totpCounter(Math.floor((opts.epochMs ?? Date.now()) / 1e3), step, opts.t0 ?? TOTP_DEFAULTS.t0), opts.digits ?? TOTP_DEFAULTS.digits, opts.algorithm ?? TOTP_DEFAULTS.algorithm);
+}
+/**
+* Vérifie un code TOTP présenté contre une fenêtre de tolérance `±window` pas
+* (RFC 6238 §5.2). Comparaison en **temps constant** (anti-timing). Retourne la
+* tranche `T` validée pour permettre à l'appelant d'appliquer l'anti-rejeu.
+*
+* @param code - code présenté par l'utilisateur (les espaces sont ignorés).
+* @param secret - secret partagé `K`.
+* @param window - nombre de pas de tolérance de part et d'autre (défaut ±1).
+*/
+function verifyTotp(code, secret, opts = {}) {
+	const digits = opts.digits ?? TOTP_DEFAULTS.digits;
+	const normalized = code.replace(/\s/g, "");
+	if (!/^\d+$/.test(normalized) || normalized.length !== digits) return { valid: false };
+	const step = opts.step ?? TOTP_DEFAULTS.step;
+	const current = totpCounter(Math.floor((opts.epochMs ?? Date.now()) / 1e3), step, opts.t0 ?? TOTP_DEFAULTS.t0);
+	const window = opts.window ?? TOTP_DEFAULTS.window;
+	const algorithm = opts.algorithm ?? TOTP_DEFAULTS.algorithm;
+	const presented = Buffer.from(normalized);
+	for (let i = -window; i <= window; i++) {
+		const candidate = Buffer.from(hotp(secret, current + i, digits, algorithm));
+		if (candidate.length === presented.length && timingSafeEqual(candidate, presented)) return {
+			valid: true,
+			step: current + i
+		};
+	}
+	return { valid: false };
+}
+/**
+* Construit l'URI `otpauth://totp/{issuer}:{account}?...` encodé dans le QR code
+* d'enrôlement. Le label `issuer:account` et le paramètre `issuer` sont tous deux
+* renseignés (recommandation Key Uri Format pour la compat des lecteurs).
+*/
+function buildOtpauthUri(params) {
+	return `otpauth://totp/${encodeURIComponent(params.issuer)}:${encodeURIComponent(params.account)}?${new URLSearchParams({
+		secret: params.secretBase32,
+		issuer: params.issuer,
+		algorithm: params.algorithm ?? TOTP_DEFAULTS.algorithm,
+		digits: String(params.digits ?? TOTP_DEFAULTS.digits),
+		period: String(params.period ?? TOTP_DEFAULTS.step)
+	}).toString()}`;
+}
+/** Alphabet des codes de récupération (Crockford-ish, sans I/L/O/U ambigus). */
+const RECOVERY_ALPHABET = "ABCDEFGHJKMNPQRSTVWXYZ23456789";
+/**
+* Tire `count` indices UNIFORMES dans `[0, size)` à partir d'octets aléatoires.
+*
+* Le repli direct (`octet % size`) n'est uniforme que si `size` divise 256. Ici
+* `256 % 30 = 16` : les seize premiers symboles de l'alphabet sortaient une fois
+* sur neuf-deux-cent-cinquante-sixièmes, les quatorze autres une fois sur huit —
+* environ 12 % plus souvent pour les premiers.
+*
+* L'enjeu réel est modeste (l'entropie tombe de 4,9069 à 4,9044 bit par
+* caractère, soit 0,025 bit perdu sur les ~49 d'un code) et n'ouvre aucune
+* attaque praticable. Ce n'est pas la raison de corriger : un tirage biaisé dans
+* du code cryptographique est une dette qui ne se voit plus une fois écrite, et
+* dont le coût explose si l'alphabet change un jour pour une taille moins
+* clémente. Le refus d'échantillon coûte ici quelques octets de plus, une fois
+* par activation de second facteur.
+*
+* @param count - nombre d'indices voulus.
+* @param size - taille de l'alphabet (2 à 256).
+* @param source - fournisseur d'octets aléatoires — paramétrable pour que le
+*          refus d'échantillon soit OBSERVABLE en test, faute de quoi on ne
+*          prouverait jamais que la garde mord.
+* @returns exactement `count` indices, uniformément distribués.
+*/
+function unbiasedIndices(count, size, source = randomBytes) {
+	if (size < 2 || size > 256) throw new RangeError(`taille d'alphabet hors bornes : ${size}`);
+	const limit = 256 - 256 % size;
+	const out = [];
+	while (out.length < count) {
+		const bytes = source(count - out.length + 8);
+		for (const b of bytes) {
+			if (b >= limit) continue;
+			out.push(b % size);
+			if (out.length === count) break;
+		}
+	}
+	return out;
+}
+/** Normalise un code de récupération présenté (casse + séparateurs ignorés). */
+function normalizeRecoveryCode(code) {
+	return code.replace(/[\s-]/g, "").toUpperCase();
+}
+/**
+* Génère `count` codes de récupération à usage unique, lisibles
+* (`XXXXX-XXXXX`, ~50 bits chacun). À présenter **une seule fois** à
+* l'utilisateur ; seul leur condensat est persisté ({@link hashRecoveryCode}).
+*/
+function generateRecoveryCodes(count = 10) {
+	const codes = [];
+	for (let c = 0; c < count; c++) {
+		let raw = "";
+		for (const idx of unbiasedIndices(10, 30)) raw += RECOVERY_ALPHABET[idx];
+		codes.push(`${raw.slice(0, 5)}-${raw.slice(5)}`);
+	}
+	return codes;
+}
+/**
+* Condensat au repos d'un code de récupération (`sha256` hex). `sha256` suffit
+* (≈ 50 bits aléatoires non brute-forçables, comme une clé API — pas un mot de
+* passe humain) ; la normalisation rend la vérification insensible casse/tirets.
+*/
+function hashRecoveryCode(code) {
+	return createHash("sha256").update(normalizeRecoveryCode(code)).digest("hex");
+}
+/**
+* Cherche un code de récupération présenté parmi des condensats stockés, en
+* **temps constant par entrée**. Retourne l'index consommé (à retirer du stock),
+* ou `-1` si aucun ne correspond.
+*/
+function matchRecoveryCode(presented, hashes) {
+	const target = Buffer.from(hashRecoveryCode(presented));
+	let found = -1;
+	for (let i = 0; i < hashes.length; i++) {
+		const candidate = Buffer.from(hashes[i]);
+		if (candidate.length === target.length && timingSafeEqual(candidate, target)) found = i;
+	}
+	return found;
+}
+//#endregion
+export { TOTP_DEFAULTS, base32Decode, base32Encode, buildOtpauthUri, generateRecoveryCodes, generateTotpSecret, hashRecoveryCode, hotp, matchRecoveryCode, totpCode, totpCounter, unbiasedIndices, verifyTotp };