@nodefony/security 10.0.0-alpha.1

package/dist/nodefony/service/tokenService.js

@@ -0,0 +1,486 @@
+import { AuthenticationError } from "../errors/AuthenticationError.js";
+import { ThrottledError } from "../errors/ThrottledError.js";
+import { defineSecurityConfig } from "../config/defineModuleConfig.js";
+import { resolveJwtRuntime } from "../src/token/jwtRuntime.js";
+import { recordAudit } from "../src/audit/recordAudit.js";
+import { InvalidTargetError } from "../errors/InvalidTargetError.js";
+import { getTokenStoreFactory, listTokenStores } from "../src/token/tokenStoreRegistry.js";
+import { JwtKeystore } from "../src/token/JwtKeystore.js";
+import { AUTO_STORE, EMPTY_INFRA, GcScheduler, Service, canonicalIssuer, readStoreLocation, refusedAdminScopes, resolveAutoStore } from "nodefony";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+//#region nodefony/service/tokenService.ts
+const serviceName = "tokenService";
+/**
+* Orchestrateur des jetons longue durée (P6 J4) — émission/refresh des JWT +
+* **maintenance du store** (le seam `ITokenStore.gc()` n'a pas d'autre appelant).
+*
+* Au boot (si `jwt.enabled`) : résout le store pluggable (`tokenStore.store`),
+* crée le keystore Ed25519, les pose au container (`tokenStore`/`jwtKeystore`,
+* consommés par le `JwtAuthenticator` et les endpoints framework), puis arme un
+* **timer de gc** `unref` (n'empêche pas l'arrêt) avec **jitter** de phase
+* (étale les balayages entre process d'un cluster sur un store partagé). À
+* l'arrêt (`onTerminate`) : `clearInterval`/`clearTimeout`.
+*
+* Émission = « password grant » M2M/CLI : credential vérifié par le service
+* `users` → access (JWT signé, 15 min) + refresh (secret opaque haute entropie,
+* stocké **haché**). Refresh = rotation + détection de rejeu (RFC 9700 §4.14).
+*/
+var TokenService = class extends Service {
+	module;
+	#runtime = null;
+	/** Émetteur publiable, résolu une fois au boot (cf `#resolvePublication`). */
+	#published = null;
+	#store = null;
+	#keystore = null;
+	#jose = null;
+	#users = null;
+	#throttler = null;
+	#throttlerResolved = false;
+	#gc = null;
+	constructor(module) {
+		super(serviceName, module.container, module.notificationsCenter, module.options);
+		this.module = module;
+		this.kernel?.once("onBoot", () => this.#build());
+		this.kernel?.once("onTerminate", () => this.#shutdown());
+	}
+	#build() {
+		let config;
+		try {
+			config = defineSecurityConfig(this.options);
+		} catch {
+			return;
+		}
+		const jwtEnabled = config.jwt.enabled;
+		const apiKeysEnabled = config.apiKeys.enabled;
+		if (!jwtEnabled && !apiKeysEnabled) {
+			this.log("token service idle — JWT et clés API désactivés", "DEBUG");
+			return;
+		}
+		let storeName = config.tokenStore.store;
+		let reason = `store explicitement configuré ("${storeName}")`;
+		if (storeName === AUTO_STORE) {
+			const auto = resolveAutoStore("durable", this.kernel?.infra ?? EMPTY_INFRA, listTokenStores());
+			storeName = auto.store;
+			reason = auto.reason;
+			this.log(`tokenStore "auto" → "${storeName}" (${auto.reason})`, "INFO");
+		}
+		const factory = getTokenStoreFactory(storeName);
+		if (!factory) {
+			const msg = `token store "${storeName}" inconnu (enregistrés : ${listTokenStores().join(", ") || "aucun"})`;
+			if (this.kernel?.environment === "production") throw new Error(`${msg} — JWT/clés API indisponibles : boot avorté.`);
+			this.log(`${msg} — JWT/clés API indisponibles`, "CRITIC");
+			return;
+		}
+		if (storeName === "memory" && this.kernel?.environment === "production") this.log("tokenStore \"memory\" en PRODUCTION — denylist JWT, refresh tokens et clés API per-pod et volatils : révocation non partagée entre pods, tout est perdu au redémarrage. Déclarer une infra durable (NF_DATABASE_URL) ou un store persistant.", "WARNING");
+		this.#store = factory({
+			container: this.container,
+			config
+		});
+		this.kernel?.registerStoreResolution({
+			brick: "tokens",
+			nature: "durable",
+			configured: config.tokenStore.store,
+			resolved: storeName,
+			available: listTokenStores(),
+			reason,
+			configPath: "security.tokenStore.store",
+			location: readStoreLocation(this.#store)
+		});
+		this.container?.set("tokenStore", this.#store);
+		if (jwtEnabled) {
+			this.#runtime = resolveJwtRuntime(config.jwt);
+			this.#keystore = new JwtKeystore(config.jwt.keystore, (m, s) => this.log(m, s));
+			this.container?.set("jwtKeystore", this.#keystore);
+			this.#resolvePublication(config.jwt.jwks, this.#runtime.issuer);
+		}
+		this.#gc = new GcScheduler({
+			intervalS: config.tokenStore.gcIntervalS,
+			jitter: config.tokenStore.gcJitter,
+			run: () => this.runGc(),
+			onError: (e) => this.log(e, "ERROR")
+		});
+		this.#gc.start();
+		this.log(`token service ready — store "${config.tokenStore.store}", jwt=${jwtEnabled}, apiKeys=${apiKeysEnabled}, gc ${config.tokenStore.gcIntervalS}s`, "DEBUG");
+	}
+	#shutdown() {
+		this.#gc?.stop();
+		this.#gc = null;
+	}
+	/** `true` si l'émission JWT (signature + refresh) est opérationnelle. */
+	isEnabled() {
+		return this.#keystore !== null && this.#runtime !== null;
+	}
+	/**
+	* Décide UNE fois, au boot, si cette application peut se déclarer émetteur.
+	*
+	* Trois conditions, et la troisième est celle qui surprend : l'émetteur doit
+	* être une **URL https** (RFC 8414 §2). Le défaut `"nodefony"` de
+	* {@link resolveJwtRuntime} n'en est pas une — parfaitement inoffensif tant
+	* que Nodefony émet ET vérifie ses propres jetons (`iss` n'est alors qu'une
+	* chaîne comparée à elle-même), mais inutilisable comme identifiant public.
+	*
+	* 🔴 **On ne DEVINE pas cette URL.** Derrière un relais (HAProxy, ingress,
+	* CDN), le processus n'a aucun moyen fiable de connaître son adresse
+	* publique : `Host` et `X-Forwarded-*` viennent de la requête, donc du client
+	* en dernière analyse. La dériver ferait servir, par le VRAI serveur, un
+	* document `issuer: https://attaquant.example` — crédible, et empoisonnant
+	* tout cache mutualisé. Un argument non sécuritaire suffirait d'ailleurs :
+	* l'émetteur est gravé dans le `iss` de chaque jeton DÉJÀ émis ; variable
+	* selon l'hôte d'entrée, il ferait rejeter un jeton valide.
+	*
+	* Le refus est donc ANNONCÉ (avertissement au boot) plutôt que masqué
+	* derrière un document qui ne mènerait nulle part.
+	*/
+	#resolvePublication(wanted, issuer) {
+		if (!wanted) return;
+		try {
+			this.#published = canonicalIssuer(issuer);
+		} catch {
+			this.#published = null;
+			this.log(`JWKS non publié : \`security.jwt.issuer\` vaut « ${issuer} », qui n'est pas une URL https. Renseigner l'URL publique de cette application (RFC 8414 §2) — derrière un relais, elle ne peut pas être devinée. Les jetons restent émis et vérifiés normalement.`, "WARNING");
+		}
+	}
+	/**
+	* Émetteur sous lequel cette application accepte d'être DÉCOUVERTE, ou `null`.
+	*
+	* C'est la question que pose `@nodefony/framework` au moment de monter (ou
+	* non) `/.well-known/oauth-authorization-server` et `/.well-known/jwks.json` :
+	* il ne lit pas la configuration de sécurité, il obtient une réponse. `null`
+	* = aucune route, donc `404` — pas de document creux, pas de demi-mesure.
+	*
+	* @returns l'émetteur canonique publiable, ou `null` si rien ne doit l'être
+	*/
+	publishedIssuer() {
+		return this.#published;
+	}
+	/**
+	* Jeu de clés **publiques** de signature, tel qu'il doit être servi.
+	*
+	* Ne contient que des paramètres publics (RFC 8037/7517) — le keystore ne
+	* sérialise jamais `d`. Rien n'est calculé ici : la route est une porte, la
+	* matière vient du keystore.
+	*
+	* @returns le JWKS public
+	* @throws Error si la capacité JWT n'est pas active (garde de programmation :
+	*         les routes ne sont montées que si {@link publishedIssuer} répond)
+	*/
+	async getPublicJWKS() {
+		if (!this.#keystore) throw new Error("JWKS demandé alors que la capacité JWT est inactive (`security.jwt.enabled: false`).");
+		return this.#keystore.getPublicJWKS();
+	}
+	/**
+	* Une passe de purge du store (`ITokenStore.gc()`) — point d'entrée public d'un
+	* ordonnanceur : le {@link GcScheduler} l'appelle, mais le futur worker cron
+	* (`security:token-gc` / k8s CronJob) peut l'appeler à sa place (poser alors
+	* `tokenStore.gcIntervalS: 0`). L'anti-empilement et la capture d'erreur vivent
+	* dans le GcScheduler (via `onError`) — ici, la passe métier nue.
+	*
+	* ⚠️ Un store **local** (`memory`/`file`) est par-process (mémoires disjointes) :
+	* seul SON process peut le purger → le timer in-process reste indispensable. Un
+	* store **partagé** (ORM) peut être délégué au worker cron (un seul balayage).
+	*
+	* @returns nombre d'entrées purgées.
+	*/
+	async runGc() {
+		if (!this.#store) return 0;
+		const t0 = performance.now();
+		const purged = await this.#store.gc();
+		if (purged > 0) this.log(`token gc: ${purged} jeton(s) purgé(s) en ${(performance.now() - t0).toFixed(1)}ms`, "DEBUG");
+		return purged;
+	}
+	/**
+	* Émet un couple access/refresh après vérification d'un credential
+	* identifiant/mot de passe (grant M2M/CLI). Throttling NIST partagé si activé.
+	*
+	* @throws ThrottledError (429) — backoff actif.
+	* @throws AuthenticationError (401, message uniforme) — credential invalide.
+	*/
+	async issueForCredentials(identifier, password, requestedScopes, resource) {
+		if (typeof identifier !== "string" || identifier.length === 0 || typeof password !== "string" || password.length === 0) {
+			this.#auditGrant("login.failure", typeof identifier === "string" && identifier.length > 0 ? identifier : null, "invalid_credentials");
+			throw new AuthenticationError("Invalid credentials");
+		}
+		const throttler = this.#resolveThrottler();
+		if (throttler !== null) {
+			const retryAfterS = throttler.check(identifier);
+			if (retryAfterS > 0) {
+				this.#auditGrant("login.throttled", identifier, "throttled");
+				throw new ThrottledError(retryAfterS);
+			}
+		}
+		const user = await this.#resolveUsers().authenticate(identifier, password);
+		if (user === null) {
+			throttler?.recordFailure(identifier);
+			this.#auditGrant("login.failure", identifier, "invalid_credentials");
+			throw new AuthenticationError("Invalid credentials");
+		}
+		throttler?.recordSuccess(identifier);
+		return this.issueTokens(user, requestedScopes, resource);
+	}
+	#auditGrant(action, actor, reason) {
+		recordAudit(this.container, {
+			category: "auth",
+			action,
+			outcome: "failure",
+			actor,
+			reason
+		});
+	}
+	/**
+	* Résout l'audience (`aud`) d'un jeton à émettre — RFC 8707 §2.
+	*
+	* Le client dit POUR QUI il demande le jeton ; le serveur décide s'il accepte.
+	* La liste `security.jwt.audiences` est donc une **liste blanche de ressources
+	* demandables**, et non une simple valeur par défaut : sans elle, n'importe
+	* quel porteur d'un identifiant valide se ferait délivrer un jeton portant
+	* l'audience de son choix — y compris celle d'une ressource à laquelle il n'a
+	* rien à faire, dont la porte accepterait alors ce jeton sans sourciller.
+	*
+	* **Une seule ressource.** La RFC autorise plusieurs `resource` mais recommande
+	* l'inverse (§3) : « If a bearer token has multiple intended recipients […] the
+	* token is valid at more than one protected resource and can be used by any one
+	* of those resources to access any of the others », d'où « a high degree of
+	* trust between the involved parties is needed » — et elle prévoit qu'un
+	* serveur soit « unwilling or unable » de le faire. Nous le sommes : la portée
+	* minimale est le seul réglage qui ne se retourne pas contre l'application.
+	*
+	* @param requested - valeur `resource` telle que reçue, ou rien
+	* @returns l'audience à inscrire dans le jeton
+	* @throws InvalidTargetError (400) si la ressource est multiple, malformée ou
+	*         non déclarée
+	*/
+	#resolveAudience(requested) {
+		const fallback = this.#runtime.audiences[0];
+		if (requested === void 0 || requested === null) return fallback;
+		if (Array.isArray(requested)) throw new InvalidTargetError("A single `resource` is accepted — a token valid at several resources lets each of them act at the others (RFC 8707 §3).");
+		if (typeof requested !== "string" || requested.length === 0) throw new InvalidTargetError("`resource` must be an absolute URI.");
+		let url;
+		try {
+			url = new URL(requested);
+		} catch {
+			throw new InvalidTargetError("`resource` must be an absolute URI (RFC 8707 §2).", requested);
+		}
+		if (url.hash) throw new InvalidTargetError("`resource` must not include a fragment (RFC 8707 §2).", requested);
+		if (!this.#runtime.audiences.includes(requested)) throw new InvalidTargetError("The requested resource is not available to this application.", requested);
+		return requested;
+	}
+	/**
+	* Émet un couple access/refresh pour un utilisateur déjà authentifié.
+	*
+	* @param user - porteur, déjà authentifié
+	* @param requestedScopes - scopes demandés (RFC 6749 §3.3)
+	* @param resource - ressource visée (RFC 8707) ; omise = audience par défaut
+	* @throws InvalidTargetError (400) si `resource` ne peut pas être servie
+	*/
+	/**
+	* Borne les scopes demandés à ce que le porteur peut légitimement obtenir.
+	*
+	* 🔴 Un scope se DEMANDE ; il ne s'accorde pas pour autant. Les scopes
+	* d'administration du framework (`admin:read`, `admin:write`) ouvrent le plan
+	* d'administration à un porteur de jeton : les signer sur simple demande
+	* ferait de n'importe quel compte un administrateur — il lui suffirait de le
+	* demander. La règle de ce qui est réservé vit au cœur
+	* ({@link refusedAdminScopes}), à côté de la traduction inverse qui les
+	* consomme ; ici on l'applique et on le DIT.
+	*
+	* Retirer plutôt que refuser tout le grant : RFC 6749 §3.3 prévoit
+	* explicitement qu'un serveur accorde MOINS que demandé, à condition
+	* d'informer le client — c'est ce que fait le champ `scope` de la réponse,
+	* déjà rempli avec les scopes réellement accordés.
+	*
+	* Les scopes d'une APPLICATION ne sont pas jugés ici : c'est à elle de dire
+	* qui peut obtenir `shop:read`.
+	*
+	* @param user - le porteur, déjà authentifié.
+	* @param requested - ce qu'il demande.
+	* @returns ce qui lui est accordé.
+	*/
+	#grantableScopes(user, requested) {
+		const roles = Array.isArray(user.roles) ? user.roles.filter((r) => typeof r === "string") : [];
+		const refuses = refusedAdminScopes(requested, roles);
+		if (refuses.length === 0) return requested;
+		this.log(`grant : scope(s) « ${refuses.join(" ")} » NON accordé(s) à « ${user.identifier} » — réservé(s) au rôle d'administration. Le jeton est émis avec les scopes restants (RFC 6749 §3.3).`, "WARNING");
+		return requested.filter((scope) => !refuses.includes(scope));
+	}
+	async issueTokens(user, requestedScopes, resource, accessTtlS) {
+		this.#ensureReady();
+		const scopes = this.#grantableScopes(user, requestedScopes && requestedScopes.length > 0 ? [...requestedScopes] : []);
+		const audience = this.#resolveAudience(resource);
+		const access = await this.#signAccess(user.identifier, scopes, audience, accessTtlS);
+		const { record, raw } = this.#buildRefresh(user.identifier, scopes, this.#randomId(), audience);
+		await this.#store.put(record);
+		recordAudit(this.container, {
+			category: "token",
+			action: "token.issued",
+			outcome: "success",
+			actor: user.identifier,
+			metadata: {
+				tokenId: record.id,
+				scopes
+			}
+		});
+		return {
+			access_token: access,
+			refresh_token: raw,
+			token_type: "Bearer",
+			expires_in: accessTtlS ?? this.#runtime.accessTtlS,
+			scope: scopes.join(" ")
+		};
+	}
+	/**
+	* Rotation d'un refresh token (RFC 9700 §4.14) : valide le refresh présenté,
+	* émet un nouveau couple, révoque l'ancien. Un refresh **déjà révoqué**
+	* re-présenté = rejeu → toute la famille est coupée.
+	*
+	* @param rawRefresh - le refresh token présenté, en clair
+	* @param resource - ressource visée (RFC 8707 §2.2). Sur un `refresh_token`,
+	*          la politique « may limit the acceptable resources to those that
+	*          were originally granted […] or a subset thereof » : un jeton ne
+	*          portant qu'une seule audience, le seul sous-ensemble possible est
+	*          elle-même. Demander autre chose est donc refusé, jamais ignoré —
+	*          sinon la rotation devient le chemin par lequel on obtient une
+	*          audience qu'on n'a pas su demander à l'émission.
+	* @throws AuthenticationError (401) — refresh inconnu/expiré/révoqué, sujet banni.
+	* @throws InvalidTargetError (400) — `resource` demandée ≠ celle accordée
+	*/
+	async refresh(rawRefresh, resource) {
+		this.#ensureReady();
+		if (typeof rawRefresh !== "string" || rawRefresh.length === 0) throw new AuthenticationError("Invalid token");
+		const store = this.#store;
+		const record = await store.findByHash(this.#hash(rawRefresh));
+		if (!record || record.kind !== "refresh") throw new AuthenticationError("Invalid token");
+		if (record.revokedAt !== null) {
+			if (record.family) await store.revokeFamily(record.family, "reuse_detected");
+			recordAudit(this.container, {
+				category: "token",
+				action: "token.reuse_detected",
+				outcome: "denied",
+				actor: record.subjectId,
+				reason: "reuse_detected",
+				metadata: {
+					tokenId: record.id,
+					family: record.family
+				}
+			});
+			throw new AuthenticationError("Invalid token");
+		}
+		const now = Date.now();
+		if (record.expiresAt !== null && record.expiresAt <= now) throw new AuthenticationError("Invalid token");
+		const user = await this.#resolveUserForRefresh(record.subjectId);
+		const scopes = [...record.scopes];
+		const audience = record.audience?.[0] ?? this.#runtime.audiences[0];
+		if (resource !== void 0 && resource !== null && resource !== audience) throw new InvalidTargetError("The requested resource does not match the one granted to this token (RFC 8707 §2.2).", typeof resource === "string" ? resource : void 0);
+		const access = await this.#signAccess(user.identifier, scopes, audience);
+		if (!this.#runtime.rotateRefresh) return {
+			access_token: access,
+			refresh_token: rawRefresh,
+			token_type: "Bearer",
+			expires_in: this.#runtime.accessTtlS,
+			scope: scopes.join(" ")
+		};
+		const family = record.family ?? this.#randomId();
+		const next = this.#buildRefresh(user.identifier, scopes, family, audience);
+		await store.put(next.record);
+		record.replacedBy = next.record.id;
+		record.revokedAt = now;
+		record.revokedReason = "rotated";
+		await store.put(record);
+		return {
+			access_token: access,
+			refresh_token: next.raw,
+			token_type: "Bearer",
+			expires_in: this.#runtime.accessTtlS,
+			scope: scopes.join(" ")
+		};
+	}
+	async #signAccess(subject, scopes, audience, ttlS) {
+		const jose = await this.#ensureJose();
+		const { key, kid } = await this.#keystore.getSigningKey();
+		const rt = this.#runtime;
+		return new jose.SignJWT({ scope: scopes.join(" ") }).setProtectedHeader({
+			alg: "EdDSA",
+			kid,
+			typ: "at+jwt"
+		}).setIssuedAt().setIssuer(rt.issuer).setSubject(subject).setAudience(audience).setExpirationTime(`${ttlS ?? rt.accessTtlS}s`).setJti(randomUUID()).sign(key);
+	}
+	/**
+	* Construit (sans persister) un record refresh + son secret opaque en clair.
+	*
+	* @param audience - ressource ACCORDÉE, mémorisée pour que la rotation rende
+	*          un jeton de même portée. Sans elle, le renouvellement élargirait
+	*          silencieusement l'accès à l'audience par défaut — un downscoping
+	*          qui s'annule au bout de quelques minutes n'en est pas un.
+	*/
+	#buildRefresh(subject, scopes, family, audience) {
+		const raw = `nfr_${randomBytes(32).toString("base64url")}`;
+		const now = Date.now();
+		return {
+			record: {
+				id: randomUUID(),
+				kind: "refresh",
+				name: "refresh token",
+				prefix: null,
+				subjectId: subject,
+				subjectType: "user",
+				tenantId: null,
+				scopes: [...scopes],
+				audience: [audience],
+				resources: null,
+				secretHash: this.#hash(raw),
+				hashAlg: "sha256",
+				clientId: null,
+				cnf: null,
+				family,
+				replacedBy: null,
+				createdAt: now,
+				expiresAt: now + this.#runtime.refreshTtlS * 1e3,
+				lastUsedAt: null,
+				lastUsedIp: null,
+				lastUsedUserAgent: null,
+				revokedAt: null,
+				revokedReason: null,
+				metadata: {}
+			},
+			raw
+		};
+	}
+	#ensureReady() {
+		if (!this.#store || !this.#keystore || !this.#runtime) throw new Error("TokenService: non initialisé (JWT désactivé ou store indisponible)");
+	}
+	async #ensureJose() {
+		return this.#jose ??= await import("jose");
+	}
+	#hash(secret) {
+		return createHash("sha256").update(secret).digest("hex");
+	}
+	#randomId() {
+		return randomBytes(16).toString("base64url");
+	}
+	#resolveUsers() {
+		if (this.#users === null) {
+			const users = this.get("users");
+			if (!users) throw new Error("TokenService: aucun service 'users' (IPasswordVerifier & IUserProvider) dans le container — enregistrer un UserService au boot.");
+			this.#users = users;
+		}
+		return this.#users;
+	}
+	async #resolveUserForRefresh(subjectId) {
+		let user;
+		try {
+			user = await this.#resolveUsers().loadUserByIdentifier(subjectId);
+		} catch {
+			throw new AuthenticationError("Invalid token");
+		}
+		if (!user.isActive() || user.isLocked()) throw new AuthenticationError("Invalid token");
+		return user;
+	}
+	#resolveThrottler() {
+		if (!this.#throttlerResolved) {
+			this.#throttler = this.get("loginThrottler") ?? null;
+			this.#throttlerResolved = true;
+		}
+		return this.#throttler;
+	}
+};
+//#endregion
+export { TokenService, TokenService as default };

package/dist/nodefony/service/totp.js

@@ -0,0 +1,209 @@
+import { defineSecurityConfig } from "../config/defineModuleConfig.js";
+import { getTotpStoreFactory, listTotpStores } from "../src/totp/totpSecretStoreRegistry.js";
+import { generateEphemeralKey } from "../src/crypto/secretCipher.js";
+import { deriveTotpKey } from "../src/totp/totpCipher.js";
+import { beginTotpEnrollment, confirmTotpEnrollment, disableTotp, totpStatus, verifyTotpLogin } from "../src/totp/totpOperations.js";
+import { AUTO_STORE, EMPTY_INFRA, Service, deriveStoreBackend, readStoreLocation, resolveAutoStore } from "nodefony";
+//#region nodefony/service/totp.ts
+const serviceName = "totp";
+function isFlushable(s) {
+	return s !== null && typeof s.flushNow === "function";
+}
+/**
+* **2FA TOTP** (P6.17, RFC 6238) — service d'orchestration du second facteur.
+*
+* Coquille fine : au boot (si `totp.enabled`) il résout le **store** de secrets
+* pluggable + la **clé de chiffrement** AES-256-GCM, puis délègue toute la logique
+* aux opérations pures `totpOperations` (testées sans serveur). Le TOTP est un
+* facteur de **login step-up** (le code n'est présenté qu'à la connexion, calque
+* WebAuthn/OAuth), pas un authenticator du firewall — `session.user` n'est posé
+* qu'une fois le second facteur validé (Zero Trust 401 protège tout le reste).
+*
+* **Clé de chiffrement** : le secret TOTP est réversible (le serveur le relit pour
+* calculer le code) → chiffré, jamais haché. La clé vient de `totp.encryptionKey`
+* (dérivée HKDF). Absente : en dev une clé **éphémère** est générée + WARNING (les
+* secrets ne survivent pas au redémarrage) ; en **production** c'est fatal — 2FA
+* désactivé (une clé éphémère rendrait les secrets illisibles après redémarrage /
+* sur les autres pods). Politique calquée sur RedisIdempotencyStore.
+*/
+var TotpService = class extends Service {
+	module;
+	#deps = null;
+	#store = null;
+	#ready = false;
+	constructor(module) {
+		super(serviceName, module.container, module.notificationsCenter, module.options);
+		this.module = module;
+		this.kernel?.once("onBoot", () => this.#build());
+		this.kernel?.once("onTerminate", () => void this.#shutdown());
+	}
+	#build() {
+		let config;
+		try {
+			config = defineSecurityConfig(this.options);
+		} catch {
+			return;
+		}
+		if (!config.totp.enabled) {
+			this.log("totp idle — 2FA désactivé en config", "DEBUG");
+			return;
+		}
+		const store = this.#resolveStore(config);
+		if (!store) return;
+		const key = this.#resolveKey(config);
+		if (!key) return;
+		this.#store = store;
+		this.#deps = {
+			store,
+			key,
+			now: () => Date.now(),
+			issuer: config.totp.issuer ?? this.#defaultIssuer(),
+			algorithm: config.totp.algorithm,
+			digits: config.totp.digits,
+			period: config.totp.period,
+			window: config.totp.window,
+			recoveryCodesCount: config.totp.recoveryCodes
+		};
+		this.#ready = true;
+		this.log(`totp ready — store "${config.totp.store}", ${config.totp.digits} chiffres / ${config.totp.period}s`, "DEBUG");
+	}
+	/**
+	* Résout le store de secrets : adapter posé au container (ORM/Redis) en priorité,
+	* sinon le driver configuré. `auto` (défaut) suit l'infra database déclarée puis
+	* un backend local persistant (sqlite/drizzle chargé), repli `memory` ANNONCÉ.
+	*/
+	#resolveStore(config) {
+		const existing = this.get("totpSecretStore");
+		if (existing) {
+			this.kernel?.registerStoreResolution({
+				brick: "totp",
+				nature: "durable",
+				configured: config.totp.store,
+				resolved: deriveStoreBackend(existing),
+				available: listTotpStores(),
+				reason: "adapter posé au container (infra database déclarée)",
+				configPath: "security.totp.store",
+				location: readStoreLocation(existing)
+			});
+			return existing;
+		}
+		let driver = config.totp.store;
+		let reason = `store explicitement configuré ("${driver}")`;
+		if (driver === AUTO_STORE) {
+			const auto = resolveAutoStore("durable", this.kernel?.infra ?? EMPTY_INFRA, listTotpStores());
+			driver = auto.store;
+			reason = auto.reason;
+			this.log(`totp.store "auto" → "${driver}" (${auto.reason})`, "INFO");
+		}
+		const factory = getTotpStoreFactory(driver);
+		if (!factory) {
+			const msg = `totp store "${driver}" inconnu (enregistrés : ${listTotpStores().join(", ") || "aucun"})`;
+			if (this.kernel?.environment === "production") throw new Error(`${msg} — 2FA indisponible : boot avorté.`);
+			this.log(`${msg} — 2FA indisponible`, "CRITIC");
+			return null;
+		}
+		if (driver === "memory" && this.kernel?.environment === "production") this.log("totp.store \"memory\" en PRODUCTION — secrets 2FA volatils : perdus au redémarrage (utilisateurs verrouillés). Déclarer une infra durable (NF_DATABASE_URL) ou charger @nodefony/drizzle.", "WARNING");
+		const store = factory({
+			container: this.container,
+			config
+		});
+		this.container?.set("totpSecretStore", store);
+		this.kernel?.registerStoreResolution({
+			brick: "totp",
+			nature: "durable",
+			configured: config.totp.store,
+			resolved: driver,
+			available: listTotpStores(),
+			reason,
+			configPath: "security.totp.store",
+			location: readStoreLocation(store)
+		});
+		return store;
+	}
+	/**
+	* Résout la clé de chiffrement AES-256 du secret au repos. Clé de config →
+	* dérivée HKDF. Absente : dev = clé éphémère + WARNING ; prod = fatal (null →
+	* 2FA désactivé), pour ne jamais chiffrer un secret avec une clé non
+	* reproductible (illisible après redémarrage ou sur un autre pod).
+	*/
+	#resolveKey(config) {
+		const material = config.totp.encryptionKey;
+		if (material && material.length > 0) return deriveTotpKey(material);
+		if (this.kernel?.environment === "production") {
+			this.log("totp: AUCUNE clé de chiffrement (`security.totp.encryptionKey`) en PRODUCTION — 2FA désactivé (un secret chiffré par une clé éphémère serait illisible après redémarrage / sur les autres pods). Fournir une clé ≥ 32 octets depuis l'environnement.", "CRITIC");
+			return null;
+		}
+		this.log("totp: aucune clé de chiffrement configurée — clé ÉPHÉMÈRE générée (dev). Les secrets 2FA ne survivront pas au redémarrage. Définir `totp.encryptionKey` — générer la clé et le câblage : `npx nodefony security:secrets`.", "WARNING");
+		return generateEphemeralKey();
+	}
+	/**
+	* Arrêt propre : flush immédiat du store s'il est persistant (driver `file`) →
+	* aucune écriture en attente n'est perdue. No-op pour un store mémoire/adapter.
+	*/
+	async #shutdown() {
+		if (isFlushable(this.#store)) try {
+			await this.#store.flushNow();
+		} catch (e) {
+			this.log(e, "ERROR");
+		}
+	}
+	/** `true` si le 2FA est opérationnel (activé en config, boot OK). */
+	isEnabled() {
+		return this.#ready;
+	}
+	/** Démarre l'enrôlement (secret + QR affichés 1×). */
+	beginEnrollment(userId, account) {
+		return beginTotpEnrollment(this.#ensureReady(), userId, account);
+	}
+	/** Confirme l'enrôlement par un 1ᵉʳ code → active + codes de récupération clairs. */
+	confirmEnrollment(userId, code) {
+		return confirmTotpEnrollment(this.#ensureReady(), userId, code);
+	}
+	/** Vérifie un second facteur au login (code TOTP ou code de récupération). */
+	verifyLogin(userId, code) {
+		return verifyTotpLogin(this.#ensureReady(), userId, code);
+	}
+	/** Désactive le 2FA d'un utilisateur. */
+	disable(userId) {
+		return disableTotp(this.#ensureReady(), userId);
+	}
+	/** État 2FA d'un utilisateur (absent / pending / activé + codes restants). */
+	status(userId) {
+		return totpStatus(this.#ensureReady(), userId);
+	}
+	/**
+	* Page d'enrôlements 2FA — pagination **native au store** (jamais un parcours
+	* complet). Vue sans secret ni condensats, garantie par le contrat du store.
+	*
+	* @param query - fenêtre + filtres ({@link ITotpListQuery}).
+	* @returns la page d'enrôlements.
+	*/
+	listPage(query) {
+		return this.#ensureReady().store.listPage(query);
+	}
+	/**
+	* Nombre d'enrôlements correspondant aux filtres — le KPI « couverture 2FA »
+	* sans énumérer.
+	*
+	* @param query - filtres ({@link ITotpListQuery}) ; `limit` ignoré.
+	* @returns le compte exact.
+	*/
+	countEnrollments(query) {
+		return this.#ensureReady().store.countEnrollments(query);
+	}
+	/** 2FA activé pour cet utilisateur ? (raccourci pour le flow de login). */
+	async isEnabledFor(userId) {
+		if (!this.#ready || !this.#deps) return false;
+		return (await totpStatus(this.#deps, userId)).enabled;
+	}
+	#defaultIssuer() {
+		const name = this.kernel?.projectName;
+		return name && name !== "NODEFONY" ? name : "Nodefony";
+	}
+	#ensureReady() {
+		if (!this.#ready || !this.#deps) throw new Error("TotpService: non initialisé (2FA désactivé ou boot échoué)");
+		return this.#deps;
+	}
+};
+//#endregion
+export { TotpService, TotpService as default };