wire-mesh 3.2.1 → 3.4.0

package/README.md

@@ -34,13 +34,15 @@ Every flag the CLI accepts, exactly as `wire-mesh --help` prints it. An unknown
 Usage: wire-mesh [options]
 
 Options:
-      --bind <host:port>          Address to listen on. Port 0 asks the OS for a free port. Use 127.0.0.1:8787 to accept local connections only. (default: 0.0.0.0:8787)
-      --tls-cert <path>           PEM certificate file, to serve wss:// and https://. Requires --tls-key.
-      --tls-key <path>            PEM private key file for --tls-cert. Requires --tls-cert.
-      --mailbox-dir <path>        Directory to hold other devices' logs in while they are offline, which makes this node an announcer as well as a relay. Bounded by fixed limits. Off unless given.
-      --webtransport <host:port>  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.
-  -h, --help                      Print this help and exit.
-  -v, --version                   Print the version and exit.
+      --bind <host:port>                Address to listen on. Port 0 asks the OS for a free port. Use 127.0.0.1:8787 to accept local connections only. (default: 0.0.0.0:8787)
+      --tls-cert <path>                 PEM certificate file, to serve wss:// and https://. Requires --tls-key.
+      --tls-key <path>                  PEM private key file for --tls-cert. Requires --tls-cert.
+      --mailbox-dir <path>              Directory to hold other devices' logs in while they are offline, which makes this node an announcer as well as a relay. Bounded by fixed limits. Off unless given.
+      --webtransport <host:port>        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 <path>                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 <seconds>  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.
+  -h, --help                            Print this help and exit.
+  -v, --version                         Print the version and exit.
 ```
 
 **Default bind address is `0.0.0.0:8787`, not loopback.** Unlike a typical dev-server tool, whose loopback-only default assumes only the machine itself needs to reach it, this package's whole purpose is LAN reachability — a phone on the same network, a laptop in the next room. `--bind` overrides the address if you want to restrict it (loopback-only, a specific interface, a different port).
@@ -52,7 +54,9 @@ curl http://<host>:8787/health
 # {"ok":true,"node":"wire-mesh","roles":["relay"]}
 ```
 
-With `--webtransport <host:port>` the node also serves WebTransport on a UDP port, for a browser that has no way to trust a certificate for this node's LAN address. The node mints a self-signed ECDSA certificate valid for under two weeks, renews it on a schedule, and prints an address of the form `https://<host>:<port>#sha256=<hash>` for each address of this machine a client can reach (when bound to a wildcard, one per non-internal IPv4 address). Give one of them to a console (the Node field takes it as typed): a browser accepts the certificate by that hash with no certificate authority and no internet. The server is the optional `@fails-components/webtransport` dependency with its native binary; where it is not installed the flag fails at startup rather than serving without it. The prebuilt binary needs glibc 2.38 or newer on Linux. The certificate is renewed before it expires, and the new address is printed when its hash changes.
+With `--webtransport <host:port>` the node also serves WebTransport on a UDP port, for a browser that has no way to trust a certificate for this node's LAN address. The node mints self-signed ECDSA certificates, each valid for under two weeks, and prints an address of the form `https://<host>:<port>#sha256=<hash>[,<hash>...]` for each address of this machine a client can reach (when bound to a wildcard, one per non-internal IPv4 address). Give one of them to a console (the Node field takes it as typed): a browser accepts the certificate whose hash matches any in the list, with no certificate authority and no internet.
+
+The list holds the certificate served now and the ones that will replace it. The node rotates to the next certificate every half lifetime, by replacing its WebTransport server, so open sessions on that server end and a console reconnects, and an address stays usable for about three of those periods after it was copied. Without `--state-dir` the certificates live in memory, so a restart starts a new set and every address already handed out stops working; with it the certificates, private keys included, are kept in that directory (created readable by this user only) and a restart resumes them. The server is the optional `@fails-components/webtransport` dependency with its native binary; where it is not installed the flag fails at startup rather than serving without it. The prebuilt binary needs glibc 2.38 or newer on Linux.
 
 With `--mailbox-dir` the node also serves the announcer role and `/health` says so (`"roles":["relay","announcer"]`). It then holds other devices' `core/data` logs in that directory while those devices are offline, so a peer that reconnects catches up from the node. Only the device that owns a log can write to it: the node takes a log's entries from the connection whose verified advert names that device and from no one else. Any client that has gossiped an advert can read a log. Entries are opaque bytes to the node, and the applications that write them sign and encrypt their own. The number of logs, the bytes in each and the size of an entry are bounded (`src/mailbox-limits.ts`), and a frame that would exceed a bound is refused whole; nothing is evicted, so a full log stays full until the directory is cleared.
 

package/dist/server.cjs

@@ -13,8 +13,15 @@ let node_crypto = require("node:crypto");
 let node_os = require("node:os");
 let wire_mesh_core_adapters_byte_stream_connection = require("wire-mesh-core/adapters/byte-stream-connection");
 let wire_mesh_core_domain_pinned_address = require("wire-mesh-core/domain/pinned-address");
+let wire_mesh_core_adapters_memory_storage = require("wire-mesh-core/adapters/memory-storage");
 require("reflect-metadata");
 let _peculiar_x509 = require("@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";
@@ -47,6 +54,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",
@@ -80,6 +97,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);
@@ -106,6 +129,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),
@@ -114,7 +139,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
@@ -128,13 +155,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",
@@ -147,15 +169,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 _peculiar_x509.X509CertificateGenerator.createSelfSigned({
 		serialNumber: toHex(crypto.getRandomValues(new Uint8Array(SERIAL_NUMBER_BYTES))),
 		name: "CN=wire-mesh",
-		notBefore: now,
+		notBefore,
 		notAfter,
 		signingAlgorithm: SIGNING_ALGORITHM,
 		keys,
@@ -170,15 +192,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) {
@@ -203,7 +288,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.
@@ -221,53 +306,99 @@ function createWebTransportTransport(options = {}) {
 		},
 		async listen(address, onConnection) {
 			const Http3ServerClass = await loadHttp3Server();
+			const storage = options.storage ?? (0, wire_mesh_core_adapters_memory_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: (0, node_crypto.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) => (0, wire_mesh_core_domain_pinned_address.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((0, wire_mesh_core_adapters_byte_stream_connection.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: (0, node_crypto.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((0, wire_mesh_core_adapters_byte_stream_connection.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) => (0, wire_mesh_core_domain_pinned_address.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();
 				}
 			};
 		}
@@ -326,6 +457,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;
@@ -401,7 +534,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) (0, node_fs.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: (0, wire_mesh_core_adapters_node_fs_storage.createNodeFsStorage)({ dir: command.stateDir }) } : {},
 			onError: (error) => {
 				logError(`wire-mesh: WebTransport: ${String(error)}`);
 			},