wire-mesh 3.2.1 → 3.4.0

package/dist/server.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { createNodeWebSocketTransport } from "./adapters/node-websocket-transport.mjs";
-import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { dirname, extname, join, normalize, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createRelayHub } from "wire-mesh-core/domain/relay-hub";
@@ -12,8 +12,15 @@ import { randomBytes } from "node:crypto";
 import { networkInterfaces } from "node:os";
 import { connectionFromByteStream } from "wire-mesh-core/adapters/byte-stream-connection";
 import { formatPinnedAddress } from "wire-mesh-core/domain/pinned-address";
+import { createMemoryStorage } from "wire-mesh-core/adapters/memory-storage";
 import "reflect-metadata";
 import { BasicConstraintsExtension, ExtendedKeyUsage, ExtendedKeyUsageExtension, KeyUsageFlags, KeyUsagesExtension, X509CertificateGenerator } from "@peculiar/x509";
+//#region src/adapters/certificate-limits.ts
+const MILLISECONDS_PER_SECOND = 1e3;
+const MILLISECONDS_PER_DAY = 86400 * MILLISECONDS_PER_SECOND;
+/** Slack under the maximum, so clock skew between the node and a browser cannot push the certificate over the limit. */
+const PINNED_CERTIFICATE_LIFETIME_MS = 14 * MILLISECONDS_PER_DAY - 1 * MILLISECONDS_PER_DAY;
+//#endregion
 //#region src/cli-options.ts
 /** The address the server binds when --bind is not given. */
 const DEFAULT_BIND_ADDRESS = "0.0.0.0:8787";
@@ -46,6 +53,16 @@ const FLAGS = {
 		valueName: "host:port",
 		description: "Also serve WebTransport on this UDP address, with a self-signed certificate renewed on a schedule that a browser accepts by pinning its hash, and print the address to give a console. Needs the optional @fails-components/webtransport dependency. Off unless given."
 	},
+	"state-dir": {
+		type: "string",
+		valueName: "path",
+		description: "Directory to keep the WebTransport certificates in, private keys included, so a restart serves the same certificates and the addresses already handed out stay valid. Created readable by this user only. Without it the certificates live in memory and a restart starts a new set. Needs --webtransport."
+	},
+	"certificate-lifetime": {
+		type: "string",
+		valueName: "seconds",
+		description: "How long each WebTransport certificate is valid, in seconds. The node rotates to the next certificate every half lifetime, ending the sessions open on the server it replaces, so a shorter lifetime rotates more often. At most the WebTransport limit for a pinned certificate, which is also the default. Needs --webtransport."
+	},
 	help: {
 		type: "boolean",
 		short: "h",
@@ -79,6 +96,12 @@ function helpText() {
 		...rows.map((row) => `  ${row.label.padEnd(labelWidth)}  ${row.description}`)
 	].join("\n");
 }
+function validatedCertificateLifetimeMs(seconds) {
+	if (seconds === void 0) return;
+	const lifetimeMs = Number(seconds) * MILLISECONDS_PER_SECOND;
+	if (!/^\d+$/.test(seconds) || lifetimeMs === 0 || lifetimeMs > 11232e5) throw new CliUsageError(`--certificate-lifetime expects a whole number of seconds from 1 to ${String(PINNED_CERTIFICATE_LIFETIME_MS / MILLISECONDS_PER_SECOND)}, got "${seconds}"`);
+	return lifetimeMs;
+}
 function validatedBindAddress(flag, address) {
 	const separator = address.lastIndexOf(":");
 	const host = address.slice(0, separator);
@@ -105,6 +128,8 @@ function parseCliArguments(argv) {
 	const certPath = values["tls-cert"];
 	const keyPath = values["tls-key"];
 	if (certPath === void 0 !== (keyPath === void 0)) throw new CliUsageError("--tls-cert and --tls-key must be given together");
+	if (values["state-dir"] !== void 0 && values.webtransport === void 0) throw new CliUsageError("--state-dir needs --webtransport");
+	if (values["certificate-lifetime"] !== void 0 && values.webtransport === void 0) throw new CliUsageError("--certificate-lifetime needs --webtransport");
 	return {
 		kind: "serve",
 		bindAddress: validatedBindAddress("bind", values.bind),
@@ -113,7 +138,9 @@ function parseCliArguments(argv) {
 			keyPath
 		},
 		mailboxDir: values["mailbox-dir"],
-		webTransportAddress: values.webtransport === void 0 ? void 0 : validatedBindAddress("webtransport", values.webtransport)
+		webTransportAddress: values.webtransport === void 0 ? void 0 : validatedBindAddress("webtransport", values.webtransport),
+		stateDir: values["state-dir"],
+		certificateLifetimeMs: validatedCertificateLifetimeMs(values["certificate-lifetime"])
 	};
 }
 //#endregion
@@ -127,13 +154,8 @@ const nodeMailboxLimits = {
 };
 //#endregion
 //#region src/adapters/pinned-certificate.ts
-const MILLISECONDS_PER_DAY = 864e5;
-const MAX_PINNED_CERTIFICATE_LIFETIME_DAYS = 14;
-const CLOCK_SKEW_ALLOWANCE_DAYS = 1;
 const SERIAL_NUMBER_BYTES = 16;
 const PEM_LINE_LENGTH = 64;
-/** Slack under the maximum, so clock skew between the node and a browser cannot push the certificate over the limit. */
-const PINNED_CERTIFICATE_LIFETIME_MS = MAX_PINNED_CERTIFICATE_LIFETIME_DAYS * MILLISECONDS_PER_DAY - CLOCK_SKEW_ALLOWANCE_DAYS * MILLISECONDS_PER_DAY;
 const SIGNING_ALGORITHM = {
 	name: "ECDSA",
 	namedCurve: "P-256",
@@ -146,15 +168,15 @@ function toPem(label, der) {
 	return `-----BEGIN ${label}-----\n${(Buffer.from(der).toString("base64").match(new RegExp(`.{1,${String(PEM_LINE_LENGTH)}}`, "g")) ?? []).join("\n")}\n-----END ${label}-----\n`;
 }
 /**
-* Mints an ECDSA P-256 certificate valid from `now` for PINNED_CERTIFICATE_LIFETIME_MS. Clients pin it by hash rather than by name, so it carries only a common name.
+* Mints an ECDSA P-256 certificate valid from `notBefore` for `lifetimeMs` (PINNED_CERTIFICATE_LIFETIME_MS unless a test asks for less). Clients pin it by hash rather than by name, so it carries only a common name.
 */
-async function mintPinnedCertificate(now) {
+async function mintPinnedCertificate(notBefore, lifetimeMs = PINNED_CERTIFICATE_LIFETIME_MS) {
 	const keys = await crypto.subtle.generateKey(SIGNING_ALGORITHM, true, ["sign", "verify"]);
-	const notAfter = new Date(now.getTime() + PINNED_CERTIFICATE_LIFETIME_MS);
+	const notAfter = new Date(notBefore.getTime() + lifetimeMs);
 	const certificate = await X509CertificateGenerator.createSelfSigned({
 		serialNumber: toHex(crypto.getRandomValues(new Uint8Array(SERIAL_NUMBER_BYTES))),
 		name: "CN=wire-mesh",
-		notBefore: now,
+		notBefore,
 		notAfter,
 		signingAlgorithm: SIGNING_ALGORITHM,
 		keys,
@@ -169,15 +191,78 @@ async function mintPinnedCertificate(now) {
 		certificatePem: certificate.toString("pem"),
 		privateKeyPem: toPem("PRIVATE KEY", await crypto.subtle.exportKey("pkcs8", keys.privateKey)),
 		sha256Hex: toHex(new Uint8Array(digest)),
+		notBefore,
 		notAfter
 	};
 }
+/** A certificate is served for half its lifetime, so each successor is already valid, and its hash already listed, well before it takes over. */
+const SERVING_FRACTION = .5;
+const STORAGE_KEY = "webtransport-certificates";
+function isStoredCertificate(value) {
+	if (typeof value !== "object" || value === null) return false;
+	return "certificatePem" in value && typeof value.certificatePem === "string" && "privateKeyPem" in value && typeof value.privateKeyPem === "string" && "sha256Hex" in value && typeof value.sha256Hex === "string" && "notBefore" in value && typeof value.notBefore === "string" && "notAfter" in value && typeof value.notAfter === "string";
+}
+function fromStored(stored) {
+	return {
+		certificatePem: stored.certificatePem,
+		privateKeyPem: stored.privateKeyPem,
+		sha256Hex: stored.sha256Hex,
+		notBefore: new Date(stored.notBefore),
+		notAfter: new Date(stored.notAfter)
+	};
+}
+function toStored(certificate) {
+	return {
+		certificatePem: certificate.certificatePem,
+		privateKeyPem: certificate.privateKeyPem,
+		sha256Hex: certificate.sha256Hex,
+		notBefore: certificate.notBefore.toISOString(),
+		notAfter: certificate.notAfter.toISOString()
+	};
+}
+async function readStored(storage) {
+	const bytes = await storage.get(STORAGE_KEY);
+	if (bytes === void 0) return [];
+	const parsed = JSON.parse(new TextDecoder().decode(bytes));
+	if (!Array.isArray(parsed) || !parsed.every(isStoredCertificate)) throw new Error(`the stored ${STORAGE_KEY} are not in the expected shape`);
+	return parsed.map(fromStored);
+}
+async function writeStored(storage, certificates) {
+	await storage.set(STORAGE_KEY, new TextEncoder().encode(JSON.stringify(certificates.map(toStored))));
+}
+/**
+* Keeps a rolling schedule of pinned certificates in `storage`: the one serving now and enough successors that an address lists ADVERTISED_CERTIFICATES of them. Each successor starts one serving period after its predecessor, so it is valid, and pinned, before it takes over.
+*
+* `advance` brings the schedule up to `now`: certificates that have finished serving are dropped, missing successors are minted, and if nothing stored is serving (a first run, or a node that was down past every stored certificate) a certificate valid from `now` starts a new schedule. What it returns is written back, so a restart resumes the same certificates and the addresses already handed out stay valid.
+*/
+async function advanceCertificateSchedule(storage, now, options = {}) {
+	const lifetimeMs = options.lifetimeMs ?? 11232e5;
+	const servingMs = lifetimeMs * SERVING_FRACTION;
+	const stillValid = (await readStored(storage)).filter((certificate) => certificate.notAfter.getTime() > now.getTime());
+	const startedIndex = stillValid.findLastIndex((certificate) => certificate.notBefore.getTime() <= now.getTime());
+	const certificates = startedIndex === -1 ? [await mintPinnedCertificate(now, lifetimeMs)] : stillValid.slice(startedIndex);
+	while (certificates.length < 4) {
+		const last = certificates[certificates.length - 1];
+		if (last === void 0) throw new Error("the certificate schedule is empty");
+		certificates.push(await mintPinnedCertificate(new Date(last.notBefore.getTime() + servingMs), lifetimeMs));
+	}
+	await writeStored(storage, certificates);
+	const [serving, next] = certificates;
+	if (serving === void 0 || next === void 0) throw new Error("the certificate schedule is empty");
+	return {
+		serving,
+		advertised: certificates.slice(0, 3),
+		rotatesAt: next.notBefore
+	};
+}
 //#endregion
 //#region src/adapters/webtransport-transport.ts
 /** The path a client opens its WebTransport session on. */
 const WEBTRANSPORT_PATH = "/wire-mesh";
-const RENEWAL_DELAY_MS = PINNED_CERTIFICATE_LIFETIME_MS * .5;
 const SECRET_BYTES = 32;
+/** The application close code and reason sent when a certificate rotation ends a session; the code is arbitrary, and 0 is what a normal close carries. */
+const SESSION_CLOSE_CODE = 0;
+const ROTATION_CLOSE_REASON = "certificate rotated";
 const WILDCARD_HOSTS = ["0.0.0.0", "::"];
 /** The hosts a client can dial for a listener bound to `host`: the host itself, or for a wildcard every non-internal IPv4 address of this machine. */
 function reachableHosts(host) {
@@ -202,7 +287,7 @@ async function loadHttp3Server() {
 	}
 }
 function isIncomingSession(value) {
-	return typeof value === "object" && value !== null && "ready" in value && value.ready instanceof Promise && "incomingBidirectionalStreams" in value && value.incomingBidirectionalStreams instanceof ReadableStream;
+	return typeof value === "object" && value !== null && "ready" in value && value.ready instanceof Promise && "closed" in value && value.closed instanceof Promise && "close" in value && typeof value.close === "function" && "incomingBidirectionalStreams" in value && value.incomingBidirectionalStreams instanceof ReadableStream;
 }
 /**
 * A WebTransport Transport: each session carries one connection, on the first bidirectional stream the client opens, framed as length-prefixed CBOR (core's byte-stream-connection). A server binds a UDP port and serves a self-signed ECDSA certificate it renews on a schedule, which a browser accepts by pinning its hash (`serverCertificateHashes`) with no certificate authority involved.
@@ -220,53 +305,99 @@ function createWebTransportTransport(options = {}) {
 		},
 		async listen(address, onConnection) {
 			const Http3ServerClass = await loadHttp3Server();
+			const storage = options.storage ?? createMemoryStorage();
+			const scheduleOptions = options.certificateLifetimeMs === void 0 ? {} : { lifetimeMs: options.certificateLifetimeMs };
 			const lastColon = address.lastIndexOf(":");
 			const host = address.slice(0, lastColon);
-			const port = Number(address.slice(lastColon + 1));
-			let certificate = await mintPinnedCertificate(now());
-			const server = new Http3ServerClass({
-				host,
-				port,
-				secret: randomBytes(SECRET_BYTES).toString("hex"),
-				cert: certificate.certificatePem,
-				privKey: certificate.privateKeyPem
-			});
-			server.startServer();
-			await server.ready;
-			const bound = server.address();
-			if (bound === null) throw new Error("the WebTransport server bound no address");
-			const boundAddress = `${host}:${String(bound.port)}`;
-			const advertise = () => reachableHosts(host).map((reachable) => formatPinnedAddress(`${reachable}:${String(bound.port)}`, certificate.sha256Hex));
-			(async () => {
-				for await (const session of server.sessionStream(WEBTRANSPORT_PATH)) (async () => {
-					if (!isIncomingSession(session)) throw new Error("the WebTransport server yielded a malformed session");
-					await session.ready;
-					const reader = session.incomingBidirectionalStreams.getReader();
-					const first = await reader.read();
-					reader.releaseLock();
-					if (!first.done) onConnection(connectionFromByteStream(first.value));
+			let port = Number(address.slice(lastColon + 1));
+			let schedule = await advanceCertificateSchedule(storage, now(), scheduleOptions);
+			/** Starts a server presenting the schedule's serving certificate. The package cannot change the certificate of a running HTTP/3 server (`updateCert` only reaches the HTTP/2 side), so a rotation replaces the server. */
+			const startServer = async () => {
+				const started = new Http3ServerClass({
+					host,
+					port,
+					secret: randomBytes(SECRET_BYTES).toString("hex"),
+					cert: schedule.serving.certificatePem,
+					privKey: schedule.serving.privateKeyPem
+				});
+				started.startServer();
+				await started.ready;
+				const bound = started.address();
+				if (bound === null) throw new Error("the WebTransport server bound no address");
+				port = bound.port;
+				const liveSessions = /* @__PURE__ */ new Set();
+				const drainState = { draining: false };
+				const endSession = (session) => {
+					session.close({
+						closeCode: SESSION_CLOSE_CODE,
+						reason: ROTATION_CLOSE_REASON
+					});
+				};
+				(async () => {
+					for await (const session of started.sessionStream(WEBTRANSPORT_PATH)) (async () => {
+						if (!isIncomingSession(session)) throw new Error("the WebTransport server yielded a malformed session");
+						await session.ready;
+						if (drainState.draining) {
+							endSession(session);
+							return;
+						}
+						liveSessions.add(session);
+						session.closed.catch(() => void 0).finally(() => {
+							liveSessions.delete(session);
+						});
+						const reader = session.incomingBidirectionalStreams.getReader();
+						const first = await reader.read();
+						reader.releaseLock();
+						if (!first.done) onConnection(connectionFromByteStream(first.value));
+					})().catch(reportError);
 				})().catch(reportError);
-			})().catch(reportError);
-			const renewal = setInterval(() => {
-				mintPinnedCertificate(now()).then((renewed) => {
-					certificate = renewed;
-					server.updateCert(renewed.certificatePem, renewed.privateKeyPem, false);
-					options.onCertificateRenewed?.(advertise());
-				}).catch(reportError);
-			}, RENEWAL_DELAY_MS);
-			renewal.unref();
+				return {
+					server: started,
+					drain: async () => {
+						drainState.draining = true;
+						const open = [...liveSessions];
+						for (const session of open) endSession(session);
+						await Promise.allSettled(open.map(async (session) => session.closed));
+					}
+				};
+			};
+			let running = await startServer();
+			const advertise = () => reachableHosts(host).map((reachable) => formatPinnedAddress(`${reachable}:${String(port)}`, schedule.advertised.map((certificate) => certificate.sha256Hex)));
+			const retire = async () => {
+				await running.drain();
+				running.server.stopServer();
+				await running.server.closed;
+			};
+			let rotation;
+			let closed = false;
+			const armRotation = () => {
+				rotation = setTimeout(() => {
+					(async () => {
+						schedule = await advanceCertificateSchedule(storage, now(), scheduleOptions);
+						await retire();
+						if (closed) return;
+						running = await startServer();
+						options.onCertificateRenewed?.(advertise());
+						armRotation();
+					})().catch(reportError);
+				}, Math.max(schedule.rotatesAt.getTime() - now().getTime(), 0));
+				rotation.unref();
+			};
+			armRotation();
 			return {
-				address: boundAddress,
+				get address() {
+					return `${host}:${String(port)}`;
+				},
 				get advertisedAddresses() {
 					return advertise();
 				},
 				close: async () => {
-					clearInterval(renewal);
-					server.stopServer();
-					await server.closed;
+					closed = true;
+					clearTimeout(rotation);
+					await retire();
 				},
 				unref: () => {
-					renewal.unref();
+					rotation?.unref();
 				}
 			};
 		}
@@ -325,6 +456,8 @@ function healthResponse(announcer) {
 }
 const HTTP_OK = 200;
 const HTTP_NOT_FOUND = 404;
+/** Owner read, write and search only: the state directory holds private keys. */
+const STATE_DIR_MODE = 448;
 const HEALTH_PATH = "/health";
 const EXIT_FAILURE = 1;
 const EXIT_USAGE = 2;
@@ -400,7 +533,13 @@ async function main(argv) {
 	});
 	logOutput(`wire-mesh listening on ${tls ? "wss" : "ws"}://${listener.address}`);
 	if (command.webTransportAddress !== void 0) {
+		if (command.stateDir !== void 0) mkdirSync(command.stateDir, {
+			recursive: true,
+			mode: STATE_DIR_MODE
+		});
 		const webTransport = await createWebTransportTransport({
+			...command.certificateLifetimeMs !== void 0 ? { certificateLifetimeMs: command.certificateLifetimeMs } : {},
+			...command.stateDir !== void 0 ? { storage: createNodeFsStorage({ dir: command.stateDir }) } : {},
 			onError: (error) => {
 				logError(`wire-mesh: WebTransport: ${String(error)}`);
 			},