@nodefony/http 10.0.0-alpha.1

package/dist/nodefony/service/certificates.js

@@ -0,0 +1,545 @@
+import { Service, extend } from "nodefony";
+import { randomBytes } from "node:crypto";
+import fsp from "node:fs/promises";
+import path, { resolve } from "node:path";
+import { promisify } from "node:util";
+import { execFile } from "node:child_process";
+//#region nodefony/service/certificates.ts
+const execFileAsync = promisify(execFile);
+/**
+* Vrai si `host` est une IP littérale (IPv4 `n.n.n.n` ou IPv6 — contient `:`).
+* Une IP doit aller en SAN `iPAddress`, jamais en `dNSName` (RFC 6125).
+*/
+function isIpLiteral(host) {
+	return /^\d{1,3}(\.\d{1,3}){3}$/.test(host) || host.includes(":");
+}
+const defaultOptions = {
+	path: resolve(".", "nodefony", "config", "certificates"),
+	strategy: "auto",
+	privateKeyMode: 384,
+	dev: { useMkcert: true },
+	san: {
+		dns: [],
+		ip: []
+	},
+	openssl: {
+		size: 2048,
+		hash: "sha256",
+		validityDays: 365,
+		backdateMinutes: 5,
+		attrs: []
+	}
+};
+/**
+* Service de fourniture du certificat TLS du serveur HTTPS/WSS.
+*
+* Trois stratégies : `explicit` (certificat fourni en config — le cas de
+* PRODUCTION), `mkcert` (CA locale trustée, confort de dev) et `selfsigned`
+* (auto-signé node-forge, secours). La génération est réservée au
+* DÉVELOPPEMENT : en production sans certificat fourni, le service crie un
+* avertissement (Nodefony n'est pas une autorité de certification).
+*
+* Conformité (génération auto-signée) : signature SHA-256 (jamais SHA-1,
+* RFC 5280 / CA-B Forum), numéro de série aléatoire 128 bits unique
+* (RFC 5280 §4.1.2.2), SAN qui fait foi (RFC 6125), `notBefore` reculé,
+* clé privée écrite en `0600`.
+*/
+var Certificate = class Certificate extends Service {
+	module;
+	files = [];
+	keysPair = null;
+	certForge = null;
+	ca = "";
+	key = "";
+	cert = "";
+	fullchainPem = "";
+	publicKeyPem = "";
+	rootCertPem = "";
+	intermediateCertPem = "";
+	/** CAROOT résolu de mkcert (null tant que non détecté / indisponible). */
+	mkcertCaRoot = null;
+	/**
+	* Backend crypto node-forge, chargé PARESSEUSEMENT. La génération de
+	* certificat est un confort de DÉVELOPPEMENT : en production avec un
+	* certificat fourni (`strategy: "explicit"`), cette grosse dépendance n'est
+	* jamais importée (règle perf-mémoire — pas de dep chargée « au cas où »).
+	*/
+	forge = null;
+	path = resolve(".", "nodefony", "config", "certificates");
+	serverPath = resolve(this.path, "server");
+	caPath = resolve(this.path, "ca", "nodefony-root-ca.crt.pem");
+	publicKeyPath = resolve(this.path, "server", "publickey.pem");
+	privateKeyPath = resolve(this.path, "server", "privkey.pem");
+	certPath = resolve(this.path, "server", "cert.pem");
+	fullchainPath = resolve(this.path, "server", "fullchain.pem");
+	constructor(module) {
+		super("certificates", module.container, module.notificationsCenter, extend(true, {}, defaultOptions, module.options.certificates || {}));
+		this.module = module;
+	}
+	/** Accès typé aux options du service (Service.options est volontairement lâche). */
+	get certOptions() {
+		return this.options;
+	}
+	/** Vrai en environnement de développement (mkcert réservé à ce mode). */
+	isDev() {
+		return this.kernel?.environment === "development";
+	}
+	/**
+	* Charge node-forge à la demande (idempotent) — uniquement sur le chemin de
+	* GÉNÉRATION (selfsigned / mkcert / inspection). Le chemin `explicit` (prod)
+	* ne l'appelle jamais.
+	*/
+	async loadForge() {
+		if (!this.forge) this.forge = (await import("node-forge")).default;
+		return this.forge;
+	}
+	/** Accès au backend forge déjà chargé (lève si `loadForge` n'a pas été appelé). */
+	get forgeLib() {
+		if (!this.forge) throw new Error("node-forge non chargé — appeler loadForge() avant toute génération.");
+		return this.forge;
+	}
+	async init() {
+		this.kernel?.once("onBoot", async () => {
+			this.options = extend(true, this.options, this.module.options.certificates || {});
+			await this.generateServerCertificates();
+		});
+		return this;
+	}
+	/**
+	* Numéro de série X.509 — RFC 5280 §4.1.2.2 : entier positif unique par CA.
+	* 128 bits aléatoires (≥ 64 bits d'entropie exigés par le CA/Browser Forum
+	* contre les attaques par collision) ; bit de poids fort à 0 pour garantir un
+	* entier positif en encodage DER ; ≤ 20 octets.
+	*/
+	static generateSerialHex() {
+		const bytes = randomBytes(16);
+		bytes[0] &= 127;
+		if (bytes[0] === 0) bytes[0] = 1;
+		return bytes.toString("hex");
+	}
+	setFiles() {
+		this.files = [
+			{
+				path: this.privateKeyPath,
+				variable: this.key
+			},
+			{
+				path: this.publicKeyPath,
+				variable: this.publicKeyPem
+			},
+			{
+				path: this.certPath,
+				variable: this.cert
+			},
+			{
+				path: this.fullchainPath,
+				variable: this.fullchainPem
+			}
+		];
+	}
+	async checkCertificates() {
+		try {
+			await Promise.all(this.files.map((file) => fsp.access(file.path)));
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	async ensureDirectoriesExist() {
+		const directories = [
+			this.path,
+			this.serverPath,
+			path.dirname(this.privateKeyPath),
+			path.dirname(this.caPath),
+			path.dirname(this.certPath),
+			path.dirname(this.fullchainPath)
+		];
+		for await (const directory of directories) try {
+			await fsp.access(directory);
+		} catch {
+			await fsp.mkdir(directory, { recursive: true });
+			this.log(`Directory created: ${directory}`, "DEBUG");
+		}
+	}
+	/**
+	* Génère (ou recharge) le certificat serveur selon la stratégie résolue :
+	* `explicit` (fourni en config / prod), `mkcert` (dev, CA trustée) ou
+	* `selfsigned` (auto-signé node-forge, secours). Régénère automatiquement si
+	* le certificat présent sur disque n'est pas adéquat pour la stratégie active
+	* (expiré, SHA-1, SAN incomplet).
+	*
+	* @param force - forcer la régénération même si un certificat valide existe
+	*/
+	async generateServerCertificates(force = false) {
+		this.setFiles();
+		await this.ensureDirectoriesExist();
+		const strategy = await this.resolveStrategy();
+		if (strategy === "explicit") return this.loadExplicitCert();
+		await this.loadForge();
+		if (await this.checkCertificates() && !force && await this.isCertAdequate(strategy)) return this.readCerticates();
+		if (strategy === "mkcert") await this.generateWithMkcert();
+		else {
+			this.keysPair = this.generateKeys();
+			this.certForge = this.createCertificate();
+			this.setExtension();
+			this.sign();
+			this.key = this.generatePrivateKeyPem();
+			this.publicKeyPem = this.generatePublickeyPem();
+			const certPem = this.generateCertPem();
+			this.cert = certPem;
+			this.ca = certPem;
+			this.fullchainPem = this.createFullChain();
+			this.setFiles();
+			await this.writeCertificates(true);
+			await fsp.writeFile(this.caPath, certPem.toString(), "utf8");
+		}
+		return this.readCerticates();
+	}
+	/**
+	* Résout la stratégie effective à partir de `certificates.strategy` :
+	* - `explicit` : `key` + `cert` fournis (prod, Let's Encrypt…). Forcé →
+	*   erreur si absents.
+	* - `mkcert` : dev + binaire mkcert + CA locale présents. Forcé hors dev →
+	*   retombe sur `selfsigned` avec avertissement.
+	* - `selfsigned` : auto-signé node-forge (fallback). En PRODUCTION, crie un
+	*   avertissement : la génération n'est pas le rôle d'un serveur de prod.
+	*/
+	async resolveStrategy() {
+		const requested = this.certOptions.strategy ?? "auto";
+		if (requested === "explicit") {
+			if (!this.hasExplicitCert()) throw new Error("certificates.strategy='explicit' mais key/cert absents de la configuration.");
+			return "explicit";
+		}
+		if (requested === "auto" && this.hasExplicitCert()) return "explicit";
+		if (requested === "mkcert" || requested === "auto") {
+			if (this.isDev() && this.certOptions.dev?.useMkcert !== false) {
+				const caRoot = await this.detectMkcert();
+				if (caRoot) {
+					this.mkcertCaRoot = caRoot;
+					return "mkcert";
+				}
+				this.log((requested === "mkcert" ? "strategy='mkcert' mais mkcert introuvable — " : "mkcert introuvable — ") + "fallback certificat auto-signé node-forge (non trusté). `brew install mkcert nss && mkcert -install` pour un HTTPS dev sans erreur (HMR cross-origin/WSS).", "WARNING");
+			} else if (requested === "mkcert") this.log("strategy='mkcert' ignoré hors development → certificat auto-signé.", "WARNING");
+		}
+		if (!this.isDev()) this.log("Aucun certificat TLS fourni en PRODUCTION : génération d'un auto-signé NON trusté (secours). Nodefony n'est PAS une autorité de certification de production — fournissez un vrai certificat (Let's Encrypt, ingress k8s, reverse-proxy edge) via certificates.{ key, cert, ca } (strategy='explicit').", "WARNING");
+		return "selfsigned";
+	}
+	/** `key` + `cert` présents en config (chemin fichier ou Buffer) → cert fourni. */
+	hasExplicitCert() {
+		const o = this.certOptions;
+		return Boolean(o.key) && Boolean(o.cert);
+	}
+	/**
+	* Détecte mkcert : binaire dans le PATH + CA racine générée (rootCA.pem).
+	* @returns le chemin CAROOT, ou null si indisponible.
+	*/
+	async detectMkcert() {
+		try {
+			const { stdout } = await execFileAsync("mkcert", ["-CAROOT"]);
+			const caRoot = stdout.trim();
+			if (!caRoot) return null;
+			await fsp.access(path.join(caRoot, "rootCA.pem"));
+			return caRoot;
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* SAN effectif : config explicite si fournie, sinon dérivé du kernel
+	* (localhost + domain en DNS ; loopback en IP). Une IP littérale (ex. domain
+	* `127.0.0.1` en dev) est classée en `ip`, pas en `dns` (RFC 6125).
+	*/
+	derivedSan() {
+		const san = this.certOptions.san;
+		if (san && (san.dns.length > 0 || san.ip.length > 0)) return san;
+		const dns = ["localhost"];
+		const ip = ["127.0.0.1", "::1"];
+		const domain = this.kernel?.domain;
+		if (domain && domain !== "localhost" && domain !== "0.0.0.0") {
+			if (isIpLiteral(domain)) {
+				if (!ip.includes(domain)) ip.unshift(domain);
+			} else dns.unshift(domain);
+		}
+		return {
+			dns,
+			ip
+		};
+	}
+	/** Hostnames DNS couverts par le SAN. */
+	sanDnsNames() {
+		return this.derivedSan().dns;
+	}
+	/** Adresses IP couvertes par le SAN. */
+	sanIps() {
+		return this.derivedSan().ip;
+	}
+	/** Hostnames passés à mkcert (DNS + IP du SAN). */
+	certHostnames() {
+		return [...this.sanDnsNames(), ...this.sanIps()];
+	}
+	/**
+	* Génère le certificat de dev via mkcert (signé par la CA locale trustée).
+	* Écrit cert + clé privée (mkcert), puis dérive clé publique, fullchain et CA.
+	*/
+	async generateWithMkcert() {
+		const caRoot = this.mkcertCaRoot ?? await this.detectMkcert();
+		if (!caRoot) throw new Error("mkcert CAROOT introuvable");
+		const names = this.certHostnames();
+		await execFileAsync("mkcert", [
+			"-cert-file",
+			this.certPath,
+			"-key-file",
+			this.privateKeyPath,
+			...names
+		]);
+		await this.restrictPrivateKey();
+		const rootCaPem = await fsp.readFile(path.join(caRoot, "rootCA.pem"), "utf8");
+		const certPem = await fsp.readFile(this.certPath, "utf8");
+		const { pki } = this.forgeLib;
+		const publicKeyPem = pki.publicKeyToPem(pki.certificateFromPem(certPem).publicKey);
+		await fsp.writeFile(this.publicKeyPath, publicKeyPem, "utf8");
+		await fsp.writeFile(this.fullchainPath, `${certPem}${rootCaPem}`, "utf8");
+		await fsp.writeFile(this.caPath, rootCaPem, "utf8");
+		this.log(`Certificat dev généré via mkcert (CA trustée) — ${names.join(", ")}`, "INFO");
+	}
+	/**
+	* Vérifie que le certificat présent sur disque convient à la stratégie :
+	* - expiration (RFC 5280 §4.1.2.5) : un cert expiré est inadéquat.
+	* - **SAN** couvrant les hostnames requis (les DEUX stratégies) : si le SAN
+	*   demandé change (ex. `nodefony.com` ajouté via NF_BIND_ALL), on régénère.
+	* - `mkcert` : émis par la CA mkcert (issuer organisation contient "mkcert").
+	* - `selfsigned` : signature non SHA-1.
+	* @returns false si absent, illisible ou inadéquat → déclenche la régénération.
+	*/
+	async isCertAdequate(strategy) {
+		try {
+			const { pki } = this.forgeLib;
+			const certPem = await fsp.readFile(this.certPath, "utf8");
+			const cert = pki.certificateFromPem(certPem);
+			if (cert.validity.notAfter.getTime() <= Date.now()) return false;
+			const ext = cert.getExtension("subjectAltName");
+			if (!ext || !this.sanCovers(ext.altNames ?? [])) return false;
+			if (strategy === "mkcert") {
+				const org = cert.issuer.getField("O");
+				return Boolean(org && /mkcert/i.test(String(org.value)));
+			}
+			return cert.signatureOid !== pki.oids.sha1WithRSAEncryption;
+		} catch {
+			return false;
+		}
+	}
+	/** Le SAN présent couvre-t-il tous les noms DNS requis (RFC 6125) ? */
+	sanCovers(present) {
+		const presentDns = new Set(present.filter((p) => p.type === 2 && p.value).map((p) => p.value));
+		return this.sanDnsNames().every((name) => presentDns.has(name));
+	}
+	/** Charge un certificat fourni en config (chemin fichier ou Buffer). */
+	async loadExplicitCert() {
+		const o = this.certOptions;
+		this.key = await this.resolveMaterial(o.key);
+		this.cert = await this.resolveMaterial(o.cert);
+		this.fullchainPem = this.cert;
+		if (o.ca) this.ca = await this.resolveMaterial(o.ca);
+		this.setFiles();
+		this.log("Certificat TLS chargé depuis la configuration (fourni).", "INFO");
+		return this;
+	}
+	/** Résout un matériel TLS : Buffer renvoyé tel quel, string lue comme chemin. */
+	async resolveMaterial(value) {
+		if (!value) throw new Error("certificate material is empty");
+		if (Buffer.isBuffer(value)) return value;
+		return Buffer.from(await fsp.readFile(value, "utf8"));
+	}
+	createFullChain() {
+		return [
+			this.cert,
+			this.intermediateCertPem,
+			this.rootCertPem
+		].map((part) => part?.toString().trim()).filter(Boolean).join("\n");
+	}
+	async readCerticates() {
+		for (const file of this.files) try {
+			const buf = Buffer.from(await fsp.readFile(file.path, "utf8"));
+			if (file.path === this.privateKeyPath) this.key = buf;
+			else if (file.path === this.publicKeyPath) this.publicKeyPem = buf;
+			else if (file.path === this.caPath) this.ca = buf;
+			else if (file.path === this.certPath) this.cert = buf;
+			else if (file.path === this.fullchainPath) this.fullchainPem = buf;
+			this.log(`Read Certificat file ${file.path}`, "DEBUG");
+		} catch (err) {
+			this.log(err, "WARNING");
+		}
+		try {
+			this.ca = Buffer.from(await fsp.readFile(this.caPath, "utf8"));
+		} catch {}
+		return this;
+	}
+	async writeCertificates(force = false) {
+		await this.ensureDirectoriesExist();
+		for await (const file of this.files) try {
+			if (file.variable) {
+				const mode = file.path === this.privateKeyPath ? this.certOptions.privateKeyMode ?? 384 : 420;
+				if (force) await fsp.rm(file.path, { force: true });
+				try {
+					await fsp.writeFile(file.path, file.variable.toString(), {
+						encoding: "utf8",
+						flag: "wx",
+						mode
+					});
+				} catch (error) {
+					if (error.code === "EEXIST") {
+						this.log(`File ${file.path} already exists, skipping.`, "DEBUG");
+						continue;
+					}
+					throw error;
+				}
+				this.log(`Certificate file ${file.path} written successfully.`, "INFO");
+			}
+		} catch (err) {
+			this.log(`Error writing to file ${file.path}`, "ERROR");
+			this.log(err, "ERROR");
+			throw err;
+		}
+		await this.restrictPrivateKey();
+		return this;
+	}
+	/**
+	* Durcit les permissions de la clé privée (et de son dossier) après écriture
+	* — garantit `0600` même si l'umask du process était permissif (la clé écrite
+	* par mkcert passe aussi par ici). Échec silencieux hors POSIX.
+	*/
+	async restrictPrivateKey() {
+		const mode = this.certOptions.privateKeyMode ?? 384;
+		try {
+			await fsp.chmod(this.privateKeyPath, mode);
+			await fsp.chmod(this.serverPath, 448);
+		} catch (err) {
+			this.log(err, "DEBUG");
+		}
+	}
+	generateKeys() {
+		return this.forgeLib.pki.rsa.generateKeyPair(this.certOptions.openssl.size);
+	}
+	generatePrivateKeyPem() {
+		if (this.keysPair) return Buffer.from(this.forgeLib.pki.privateKeyToPem(this.keysPair.privateKey));
+		throw new Error(`pki.rsa.KeyPair  not found`);
+	}
+	generatePublickeyPem() {
+		if (this.keysPair) return Buffer.from(this.forgeLib.pki.publicKeyToPem(this.keysPair.publicKey));
+		throw new Error(`pki.rsa.KeyPair  not found`);
+	}
+	generateCertPem() {
+		if (this.certForge) return Buffer.from(this.forgeLib.pki.certificateToPem(this.certForge));
+		throw new Error(`pki.Certificate  not found`);
+	}
+	createCertificate() {
+		if (!this.keysPair) throw new Error(`KeyPair  not found`);
+		const o = this.certOptions.openssl;
+		const cert = this.forgeLib.pki.createCertificate();
+		cert.publicKey = this.keysPair.publicKey;
+		cert.serialNumber = Certificate.generateSerialHex();
+		const backdateMs = o.backdateMinutes * 6e4;
+		const start = Date.now() - backdateMs;
+		cert.validity.notBefore = new Date(start);
+		cert.validity.notAfter = new Date(start + o.validityDays * 864e5);
+		cert.setSubject(o.attrs);
+		cert.setIssuer(o.attrs);
+		return cert;
+	}
+	/** subjectAltName de l'auto-signé : DNS + IP (config explicite sinon dérivé). */
+	altNames() {
+		const out = [];
+		for (const dns of this.sanDnsNames()) out.push({
+			type: 2,
+			value: dns
+		});
+		for (const ip of this.sanIps()) out.push({
+			type: 7,
+			ip
+		});
+		return out;
+	}
+	setExtension() {
+		if (!this.certForge) throw new Error(`pki.Certificate  not found`);
+		this.certForge.setExtensions([
+			{
+				name: "basicConstraints",
+				cA: false
+			},
+			{
+				name: "keyUsage",
+				digitalSignature: true,
+				keyEncipherment: true
+			},
+			{
+				name: "extKeyUsage",
+				serverAuth: true,
+				clientAuth: true
+			},
+			{
+				name: "subjectAltName",
+				altNames: this.altNames()
+			},
+			{ name: "subjectKeyIdentifier" }
+		]);
+	}
+	/**
+	* Signe le certificat avec le hachage configuré (SHA-256 par défaut).
+	* SHA-1 est INTERDIT (collision SHAttered 2017, CA/Browser Forum depuis 2016) :
+	* `node-forge` signe en SHA-1 par défaut si on ne passe pas de digest → on en
+	* passe toujours un.
+	*/
+	sign() {
+		if (!this.certForge || !this.keysPair) throw new Error(`pki.rsa.KeyPair or pki.Certificate  not found`);
+		this.certForge.sign(this.keysPair.privateKey, this.digestFor(this.certOptions.openssl.hash));
+	}
+	/**
+	* Résumé introspectable du certificat serveur courant — réutilisé par la
+	* commande CLI `certificates` et un futur endpoint d'admin Studio (parité
+	* CLI ↔ Web). Parse le certificat chargé (charge node-forge à la demande).
+	*/
+	async describe() {
+		const info = {
+			strategy: this.certOptions.strategy ?? "auto",
+			certPath: this.certPath,
+			keyPath: this.privateKeyPath,
+			fullchainPath: this.fullchainPath
+		};
+		try {
+			await fsp.access(this.caPath);
+			info.caPath = this.caPath;
+		} catch {}
+		if (!this.cert) return info;
+		const { pki } = await this.loadForge();
+		try {
+			const cert = pki.certificateFromPem(this.cert.toString());
+			info.serial = cert.serialNumber;
+			info.validFrom = cert.validity.notBefore.toISOString();
+			info.validTo = cert.validity.notAfter.toISOString();
+			info.signatureAlgorithm = this.oidName(cert.signatureOid, pki);
+			const cn = cert.subject.getField("CN");
+			if (cn) info.commonName = String(cn.value);
+			const ext = cert.getExtension("subjectAltName");
+			if (ext?.altNames) info.san = ext.altNames.map((a) => a.type === 7 ? a.ip ?? "" : a.value ?? "");
+		} catch {}
+		return info;
+	}
+	/** Nom lisible de l'OID d'algorithme de signature. */
+	oidName(oid, pki) {
+		return pki.oids[oid] ?? oid;
+	}
+	/** Digest node-forge correspondant au hachage configuré (jamais SHA-1). */
+	digestFor(hash) {
+		const { md } = this.forgeLib;
+		switch (hash) {
+			case "sha512": return md.sha512.create();
+			case "sha384": return md.sha384.create();
+			case "sha256": return md.sha256.create();
+			default:
+				this.log(`Hachage '${hash}' refusé (SHA-1 interdit) → SHA-256.`, "WARNING");
+				return md.sha256.create();
+		}
+	}
+};
+//#endregion
+export { Certificate as default };