wire-mesh 3.2.0 → 3.3.0

package/README.md

@@ -39,6 +39,7 @@ Options:
       --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.
   -h, --help                      Print this help and exit.
   -v, --version                   Print the version and exit.
 ```
@@ -52,7 +53,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,6 +13,7 @@ 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/cli-options.ts
@@ -47,6 +48,11 @@ 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."
+	},
 	help: {
 		type: "boolean",
 		short: "h",
@@ -106,6 +112,7 @@ 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");
 	return {
 		kind: "serve",
 		bindAddress: validatedBindAddress("bind", values.bind),
@@ -114,7 +121,8 @@ 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"]
 	};
 }
 //#endregion
@@ -147,15 +155,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,14 +178,74 @@ 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;
 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. */
@@ -188,12 +256,13 @@ function reachableHosts(host) {
 /** The optional WebTransport package is not installed, or its native binary was not built for this platform. */
 var WebTransportUnavailableError = class extends Error {
 	constructor(cause) {
-		super("serving WebTransport needs the optional dependency @fails-components/webtransport and its native binary, which is not available on this platform or was not installed", { cause });
+		super("serving WebTransport needs the optional dependency @fails-components/webtransport and its native binary, which is missing: either no binary is published for this platform, or the package manager skipped its install script (an ignore-scripts setting does that)", { cause });
 		this.name = "WebTransportUnavailableError";
 	}
 };
 async function loadHttp3Server() {
 	try {
+		await import("@fails-components/webtransport-transport-http3-quiche");
 		const module = await import("@fails-components/webtransport");
 		await module.quicheLoaded;
 		return module.Http3Server;
@@ -220,53 +289,72 @@ 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;
+				(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;
+						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 started;
+			};
+			let server = 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)));
+			let rotation;
+			let closed = false;
+			const armRotation = () => {
+				rotation = setTimeout(() => {
+					(async () => {
+						schedule = await advanceCertificateSchedule(storage, now(), scheduleOptions);
+						server.stopServer();
+						await server.closed;
+						if (closed) return;
+						server = 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);
+					closed = true;
+					clearTimeout(rotation);
 					server.stopServer();
 					await server.closed;
 				},
 				unref: () => {
-					renewal.unref();
+					rotation?.unref();
 				}
 			};
 		}
@@ -325,6 +413,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 +490,12 @@ 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.stateDir !== void 0 ? { storage: (0, wire_mesh_core_adapters_node_fs_storage.createNodeFsStorage)({ dir: command.stateDir }) } : {},
 			onError: (error) => {
 				logError(`wire-mesh: WebTransport: ${String(error)}`);
 			},

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,6 +12,7 @@ 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/cli-options.ts
@@ -46,6 +47,11 @@ 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."
+	},
 	help: {
 		type: "boolean",
 		short: "h",
@@ -105,6 +111,7 @@ 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");
 	return {
 		kind: "serve",
 		bindAddress: validatedBindAddress("bind", values.bind),
@@ -113,7 +120,8 @@ 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"]
 	};
 }
 //#endregion
@@ -146,15 +154,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,14 +177,74 @@ 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;
 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. */
@@ -187,12 +255,13 @@ function reachableHosts(host) {
 /** The optional WebTransport package is not installed, or its native binary was not built for this platform. */
 var WebTransportUnavailableError = class extends Error {
 	constructor(cause) {
-		super("serving WebTransport needs the optional dependency @fails-components/webtransport and its native binary, which is not available on this platform or was not installed", { cause });
+		super("serving WebTransport needs the optional dependency @fails-components/webtransport and its native binary, which is missing: either no binary is published for this platform, or the package manager skipped its install script (an ignore-scripts setting does that)", { cause });
 		this.name = "WebTransportUnavailableError";
 	}
 };
 async function loadHttp3Server() {
 	try {
+		await import("@fails-components/webtransport-transport-http3-quiche");
 		const module = await import("@fails-components/webtransport");
 		await module.quicheLoaded;
 		return module.Http3Server;
@@ -219,53 +288,72 @@ 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;
+				(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;
+						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 started;
+			};
+			let server = await startServer();
+			const advertise = () => reachableHosts(host).map((reachable) => formatPinnedAddress(`${reachable}:${String(port)}`, schedule.advertised.map((certificate) => certificate.sha256Hex)));
+			let rotation;
+			let closed = false;
+			const armRotation = () => {
+				rotation = setTimeout(() => {
+					(async () => {
+						schedule = await advanceCertificateSchedule(storage, now(), scheduleOptions);
+						server.stopServer();
+						await server.closed;
+						if (closed) return;
+						server = 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);
+					closed = true;
+					clearTimeout(rotation);
 					server.stopServer();
 					await server.closed;
 				},
 				unref: () => {
-					renewal.unref();
+					rotation?.unref();
 				}
 			};
 		}
@@ -324,6 +412,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;
@@ -399,7 +489,12 @@ 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.stateDir !== void 0 ? { storage: createNodeFsStorage({ dir: command.stateDir }) } : {},
 			onError: (error) => {
 				logError(`wire-mesh: WebTransport: ${String(error)}`);
 			},