@nodefony/security 10.0.0-alpha.1

package/dist/nodefony/service/webAuthn.js

@@ -0,0 +1,343 @@
+import { AuthenticationError } from "../errors/AuthenticationError.js";
+import { defineSecurityConfig } from "../config/defineModuleConfig.js";
+import { WebAuthnError } from "../errors/WebAuthnError.js";
+import { getWebAuthnStoreFactory, listWebAuthnStores } from "../src/webauthn/webAuthnCredentialStoreRegistry.js";
+import { AUTO_STORE, EMPTY_INFRA, Service, deriveStoreBackend, readStoreLocation, resolveAutoStore } from "nodefony";
+import { Buffer } from "node:buffer";
+//#region nodefony/service/webAuthn.ts
+const serviceName = "webauthn";
+function isFlushable(s) {
+	return s !== null && typeof s.flushNow === "function";
+}
+/**
+* **WebAuthn / passkeys** (P6 J9) — orchestrateur des deux cérémonies FIDO2
+* (WebAuthn L3 §7.1 enregistrement, §7.2 authentification).
+*
+* MFA **phishing-resistant** : la clé privée ne quitte jamais l'authenticator
+* (Touch ID, Windows Hello, clé FIDO). Le serveur ne manipule QUE des clés
+* publiques + vérifie des signatures. La vérification cryptographique (parsing
+* CBOR/COSE, signatures ES256/RS256/EdDSA) est déléguée à `@simplewebauthn/server`
+* (lib auditée de l'écosystème), **importée paresseusement** au 1ᵉʳ usage (cold
+* path — l'enregistrement/login n'est pas le hot path par requête).
+*
+* Au boot (si `passkeys.enabled`) : résout le RP (rpID/rpName/origines depuis la
+* config, sinon le domaine de l'app) + le store de credentials pluggable
+* (`webAuthnCredentialStore` du container, sinon le builtin mémoire) et le pose
+* au container — une application peut donc fournir le sien avant le boot.
+*
+* Il n'existe **pas** d'authenticator passkey : `WebAuthnController`
+* (`@nodefony/framework`) mène les deux cérémonies via ce service, puis
+* `AuthFlow.establishSessionFor()` ouvre la session BFF ; les requêtes
+* suivantes sont ré-authentifiées par `SessionAuthenticator`.
+*
+* **Anti-rejeu** : le challenge serveur est porté HORS de ce service (en session
+* BFF par le controller) ; chaque `verify*` reçoit le `expectedChallenge` qu'il
+* a émis — un challenge n'est jamais réutilisable.
+*/
+var WebAuthnService = class extends Service {
+	module;
+	#config = null;
+	#lib = null;
+	#store = null;
+	#rpID = "localhost";
+	#rpName = "Nodefony";
+	#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.passkeys.enabled) {
+			this.log("webauthn idle — passkeys désactivés en config", "DEBUG");
+			return;
+		}
+		this.#config = config;
+		const rawDomain = config.passkeys.rpId ?? (this.kernel?.domain || "localhost");
+		this.#rpID = /^(\d{1,3}\.){3}\d{1,3}$|:/.test(rawDomain) ? "localhost" : rawDomain;
+		this.#rpName = config.passkeys.rpName ?? "Nodefony";
+		const existing = this.get("webAuthnCredentialStore");
+		let resolved;
+		let reason;
+		if (existing) {
+			this.#store = existing;
+			resolved = deriveStoreBackend(existing);
+			reason = "adapter posé au container (infra database déclarée)";
+		} else {
+			let driver = config.passkeys.store;
+			reason = `store explicitement configuré ("${driver}")`;
+			if (driver === AUTO_STORE) {
+				const auto = resolveAutoStore("durable", this.kernel?.infra ?? EMPTY_INFRA, listWebAuthnStores());
+				driver = auto.store;
+				reason = auto.reason;
+				this.log(`passkeys.store "auto" → "${driver}" (${auto.reason})`, "INFO");
+			}
+			const factory = getWebAuthnStoreFactory(driver);
+			if (!factory) {
+				const msg = `webauthn store "${driver}" inconnu (enregistrés : ${listWebAuthnStores().join(", ") || "aucun"})`;
+				if (this.kernel?.environment === "production") throw new Error(`${msg} — passkeys indisponibles : boot avorté.`);
+				this.log(`${msg} — passkeys indisponibles`, "CRITIC");
+				return;
+			}
+			if (driver === "memory" && this.kernel?.environment === "production") this.log("passkeys.store \"memory\" en PRODUCTION — credentials WebAuthn volatils : tous les passkeys enregistrés sont perdus au redémarrage (utilisateurs verrouillés hors de leur compte). Déclarer une infra durable (NF_DATABASE_URL).", "WARNING");
+			this.#store = factory({
+				container: this.container,
+				config
+			});
+			this.container?.set("webAuthnCredentialStore", this.#store);
+			resolved = driver;
+		}
+		this.kernel?.registerStoreResolution({
+			brick: "passkeys",
+			nature: "durable",
+			configured: config.passkeys.store,
+			resolved,
+			available: listWebAuthnStores(),
+			reason,
+			configPath: "security.passkeys.store",
+			location: readStoreLocation(this.#store)
+		});
+		if (config.passkeys.attestation !== "none") this.log(`passkeys.attestation "${config.passkeys.attestation}" — l'attestation est demandée au navigateur mais N'EST PAS VÉRIFIÉE : ni métadonnées FIDO (MDS), ni certificats racines fabricant, et l'AAGUID n'est pas conservé. Ce réglage ne tient donc pas un AAL3 régulé. Repasser à "none" si la garantie n'est pas requise.`, "WARNING");
+		if (config.passkeys.residentKey === "discouraged") this.log("passkeys.residentKey \"discouraged\" — les credentials enrôlés ne sont pas découvrables, or le login par passkey est usernameless (aucun ciblage depuis la requête, anti-énumération). Ces porteurs ne pourront pas se connecter : repasser à \"preferred\" ou \"required\".", "WARNING");
+		this.#ready = true;
+		this.log(`webauthn ready — rpID "${this.#rpID}", store "${config.passkeys.store}"`, "DEBUG");
+	}
+	/**
+	* Arrêt propre : écrit immédiatement le store sur disque s'il est persistant
+	* (driver `file`) → aucune écriture en attente de flush n'est perdue au
+	* redémarrage. No-op pour un store mémoire ou un adapter sans `flushNow`.
+	*/
+	async #shutdown() {
+		if (isFlushable(this.#store)) try {
+			await this.#store.flushNow();
+		} catch (e) {
+			this.log(e, "ERROR");
+		}
+	}
+	/** `true` si les cérémonies sont opérationnelles (passkeys activés, boot OK). */
+	isEnabled() {
+		return this.#ready;
+	}
+	/**
+	* Prépare les options de `navigator.credentials.create()` — le défi à signer +
+	* les contraintes (RP, type d'attestation, sélection d'authenticator). Le
+	* challenge renvoyé doit être stocké côté serveur (session) par l'appelant.
+	*
+	* `excludeCredentials` liste les passkeys déjà enregistrés du même utilisateur
+	* pour empêcher un double enregistrement sur le même authenticator (§7.1).
+	*/
+	async generateRegistrationOptions(user) {
+		this.#ensureReady();
+		const lib = await this.#ensureLib();
+		const pk = this.#config.passkeys;
+		const existing = await this.#store.findByUser(user.id);
+		return lib.generateRegistrationOptions({
+			rpName: this.#rpName,
+			rpID: this.#rpID,
+			userName: user.name,
+			userID: new Uint8Array(Buffer.from(user.id, "utf8")),
+			userDisplayName: user.displayName ?? user.name,
+			attestationType: pk.attestation,
+			timeout: pk.timeoutMs,
+			excludeCredentials: existing.map((c) => ({
+				id: c.id,
+				transports: [...c.transports]
+			})),
+			authenticatorSelection: {
+				residentKey: pk.residentKey,
+				userVerification: pk.userVerification,
+				...pk.authenticatorAttachment !== "any" ? { authenticatorAttachment: pk.authenticatorAttachment } : {}
+			}
+		});
+	}
+	/**
+	* Vérifie la réponse d'enregistrement (challenge, origine, rpIdHash, flags,
+	* format d'attestation) et **persiste** le nouveau credential.
+	*
+	* @param expectedChallenge - le challenge émis par {@link generateRegistrationOptions} (session).
+	* @param userId - propriétaire du credential (utilisateur authentifié/en création).
+	* @param requestOrigin - origine HTTP de la requête (validée si aucune origine n'est configurée).
+	* @throws AuthenticationError (401) — vérification échouée.
+	* @throws WebAuthnError (409) — plafond `passkeys.maxPerUser` atteint.
+	*/
+	async verifyRegistration(response, expectedChallenge, userId, requestOrigin) {
+		this.#ensureReady();
+		const lib = await this.#ensureLib();
+		const pk = this.#config.passkeys;
+		let verification;
+		try {
+			verification = await lib.verifyRegistrationResponse({
+				response,
+				expectedChallenge,
+				expectedOrigin: this.#expectedOrigin(requestOrigin),
+				expectedRPID: this.#rpID,
+				requireUserVerification: pk.userVerification === "required"
+			});
+		} catch {
+			throw new AuthenticationError("WebAuthn registration failed");
+		}
+		if (!verification.verified || !verification.registrationInfo) throw new AuthenticationError("WebAuthn registration failed");
+		if (await this.#store.countByUser(userId) >= pk.maxPerUser) throw new WebAuthnError(`passkey limit reached (${pk.maxPerUser})`, 409);
+		const info = verification.registrationInfo;
+		const credential = {
+			id: info.credential.id,
+			userId,
+			publicKey: Buffer.from(info.credential.publicKey).toString("base64url"),
+			signCount: info.credential.counter,
+			transports: info.credential.transports ?? [],
+			backupEligible: info.credentialDeviceType === "multiDevice",
+			backupState: info.credentialBackedUp,
+			uvInitialized: info.userVerified,
+			createdAt: Date.now(),
+			lastUsedAt: null
+		};
+		await this.#store.save(credential);
+		return credential;
+	}
+	/**
+	* Prépare les options de `navigator.credentials.get()`. Sans `userId`
+	* (usernameless) : `allowCredentials` est omis → l'authenticator propose ses
+	* passkeys découvrables (UX cible). Avec `userId` : ciblage des credentials
+	* connus de cet utilisateur.
+	*
+	* @param userId - identité **déjà prouvée** (session en cours) et jamais un
+	*   identifiant reçu d'un appelant non authentifié : `allowCredentials`
+	*   révélerait alors qu'un compte porte une passkey et **lesquelles**, or un
+	*   `credentialId` est corrélable entre sites (W3C WebAuthn L3, « Privacy leak
+	*   via credential IDs »). Le controller BFF applique cette règle —
+	*   `WebAuthnController.loginOptions()` ne cible que depuis la session.
+	*/
+	async generateAuthenticationOptions(userId) {
+		this.#ensureReady();
+		const lib = await this.#ensureLib();
+		const pk = this.#config.passkeys;
+		let allowCredentials;
+		if (userId) allowCredentials = (await this.#store.findByUser(userId)).map((c) => ({
+			id: c.id,
+			transports: [...c.transports]
+		}));
+		return lib.generateAuthenticationOptions({
+			rpID: this.#rpID,
+			allowCredentials,
+			userVerification: pk.userVerification,
+			timeout: pk.timeoutMs
+		});
+	}
+	/**
+	* Vérifie une assertion (signature sur `authData ‖ SHA-256(clientDataJSON)`
+	* avec la clé publique stockée, §7.2) + applique l'état (compteur anti-clone,
+	* sauvegarde, usage). Résout l'utilisateur propriétaire via le credentialId.
+	*
+	* @param expectedChallenge - le challenge émis par {@link generateAuthenticationOptions} (session).
+	* @throws AuthenticationError (401) — credential inconnu ou vérification échouée.
+	*/
+	async verifyAuthentication(response, expectedChallenge, requestOrigin) {
+		this.#ensureReady();
+		const lib = await this.#ensureLib();
+		const pk = this.#config.passkeys;
+		const stored = await this.#store.findById(response.id);
+		if (!stored) throw new AuthenticationError("WebAuthn authentication failed");
+		let verification;
+		try {
+			verification = await lib.verifyAuthenticationResponse({
+				response,
+				expectedChallenge,
+				expectedOrigin: this.#expectedOrigin(requestOrigin),
+				expectedRPID: this.#rpID,
+				credential: {
+					id: stored.id,
+					publicKey: new Uint8Array(Buffer.from(stored.publicKey, "base64url")),
+					counter: stored.signCount,
+					transports: [...stored.transports]
+				},
+				requireUserVerification: pk.userVerification === "required"
+			});
+		} catch {
+			throw new AuthenticationError("WebAuthn authentication failed");
+		}
+		if (!verification.verified) throw new AuthenticationError("WebAuthn authentication failed");
+		const info = verification.authenticationInfo;
+		await this.#store.update(stored.id, {
+			signCount: info.newCounter,
+			backupState: info.credentialBackedUp,
+			uvInitialized: stored.uvInitialized || info.userVerified,
+			lastUsedAt: Date.now()
+		});
+		return {
+			credential: stored,
+			userId: stored.userId
+		};
+	}
+	/** Liste les credentials d'un utilisateur (UX « mes appareils »). */
+	listUserCredentials(userId) {
+		this.#ensureReady();
+		return this.#store.findByUser(userId);
+	}
+	/**
+	* Page de passkeys pour le data plane admin (vue TRANSVERSE : « quels appareils
+	* portent des passkeys sur toute la plateforme »).
+	*
+	* ≠ {@link listUserCredentials}, qui sert la fiche d'UN utilisateur et le chemin
+	* chaud du login. Ici on ne matérialise jamais plus d'une page, et la projection
+	* du store exclut la clé publique.
+	*/
+	listCredentialsPage(query) {
+		this.#ensureReady();
+		return this.#store.listPage(query);
+	}
+	/**
+	* Nombre de passkeys correspondant aux filtres, ou `-1` si le backend ne sait
+	* pas compter à coût raisonnable (Redis).
+	*/
+	countCredentials(query) {
+		this.#ensureReady();
+		return this.#store.countCredentials(query);
+	}
+	/** Révoque un credential (retrait d'un appareil). */
+	removeCredential(credentialId) {
+		this.#ensureReady();
+		return this.#store.delete(credentialId);
+	}
+	/**
+	* Supprime un credential **du propriétaire** (self-service, anti-IDOR) : la
+	* suppression n'aboutit que si le credential appartient bien à `userId`, sinon
+	* `false` — 404 indiscernable côté client (on ne révèle pas l'existence d'un
+	* credential d'autrui).
+	*/
+	async removeUserCredential(userId, credentialId) {
+		this.#ensureReady();
+		const cred = await this.#store.findById(credentialId);
+		if (!cred || cred.userId !== userId) return false;
+		await this.#store.delete(credentialId);
+		return true;
+	}
+	/**
+	* Origine(s) attendue(s) (anti-phishing, §7.1/§7.2). Liste blanche de config en
+	* priorité (prod). À défaut : l'origine de la requête est acceptée **seulement
+	* si son hostname == rpID** (dev : `localhost:port` quel que soit le port, sans
+	* jamais ouvrir à un domaine tiers). Dernier recours : `https://{rpID}`.
+	*/
+	#expectedOrigin(requestOrigin) {
+		const origins = this.#config.passkeys.origins;
+		if (origins.length > 0) return [...origins];
+		if (requestOrigin) try {
+			if (new URL(requestOrigin).hostname === this.#rpID) return requestOrigin;
+		} catch {}
+		return `https://${this.#rpID}`;
+	}
+	async #ensureLib() {
+		return this.#lib ??= await import("@simplewebauthn/server");
+	}
+	#ensureReady() {
+		if (!this.#ready || !this.#store || !this.#config) throw new Error("WebAuthnService: non initialisé (passkeys désactivés ou boot échoué)");
+	}
+};
+//#endregion
+export { WebAuthnService, WebAuthnService as default };