@johnhenry/wsh 0.26.0 → 0.27.1

package/README.md

@@ -220,11 +220,66 @@ await client.connect(url, {
   client writes no primer.
 - **`selfSigned: true`** generates (no dependency) an ECDSA P-256 certificate valid for 13 days -- a browser refuses a
   pinned certificate valid for more than 14 -- and exposes the SHA-256 for `serverCertificateHashes`
-  (`{ selfSigned: { hosts, validityDays } }` to change the SANs or the lifetime). **It is not renewed:**
-  restart before `notAfter`, and re-pin. A certificate you pass as `cert`/`privKey` is used as is
-  (`certificateHash` is then `null`). `generateSelfSignedCertificate()` is exported for the same
-  certificate without a server. The web platform's other pinning rules apply (`https:` URL, HTTP/3 only; see
-  [Pinning a Self-Signed Certificate](#pinning-a-self-signed-certificate)).
+  (`{ selfSigned: { hosts, validityDays } }` to change the SANs or the lifetime). A certificate you pass as
+  `cert`/`privKey` is used as is (`certificateHash` is then `null`, and nothing rotates).
+  `generateSelfSignedCertificate()` is exported for the same certificate without a server. The web platform's other
+  pinning rules apply (`https:` URL, HTTP/3 only; see
+  [Pinning a Self-Signed Certificate](#pinning-a-self-signed-certificate)). **It is rotated, see below.**
+- Node has no `WebTransport` global: a Node *client* needs `globalThis.WebTransport = (await import(
+  '@fails-components/webtransport')).WebTransport` first. UDP, so a firewall must allow `port`, and there
+  is no `wss://`-style TLS terminator in front: the certificate is the one this process serves.
+- Tests (`test/server-webtransport.test.mjs`) run the stock client against it over a real HTTP/3
+  connection and are **skipped, with the reason, where the native binary cannot load**.
+
+#### Certificate rotation
+
+A pinned certificate cannot just be renewed in place: clients hold its hash, and the platform
+takes none valid for more than 14 days. So a `selfSigned` certificate is rotated **ahead of its expiry, with an
+overlap in which both hashes are published**:
+
+```js
+server.certificateHashes();       // [{ algorithm: 'sha-256', value }, ...]: what a client should pin right now
+await server.rotateCertificate(); // make the next certificate now and publish its hash too -> [current, next]
+await server.rotateCertificate({ activate: true });   // ... and switch the listener to it immediately
+```
+
+- **Automatically**: `prepareBeforeMs` before `notAfter` (default 3 days, at most a third of the validity) the next
+  certificate is generated and `certificateHashes()` becomes `[current, next]`; `activateBeforeMs` before `notAfter`
+  (default 1 hour, at most a sixth) the listener switches to it and the list drops the old hash. Then the next rotation
+  is scheduled from the new certificate. `selfSigned: { rotate: false }` turns this off (restart before `notAfter`,
+  as before); `{ prepareBeforeMs, activateBeforeMs, validityDays }` tune it (tests use a seconds-long validity).
+  The same list is on `server.webTransport().certificateHashes()`, with validity and which one is active in
+  `.certificates()`; `certificateHash`/`notAfter` there always describe the certificate being presented.
+- **The switch restarts the HTTP/3 listener on the same port.** The native transport has no way to swap a certificate
+  in place and presents one certificate at a time, so live WebTransport sessions end at the switch (the WebSocket
+  listener is untouched) and clients reconnect. A client that pinned the overlap list `[current, next]` before the
+  switch connects after it; one that only has the old hash does not, so it must **re-pin**.
+- **Client re-pin flow.** `serverCertificateHashes` takes several values, and `connect()` / `WebTransportTransport` pass the
+  whole array. Publish `server.certificateHashes()` over something the client already trusts (your page's
+  HTTPS, an API call, a config endpoint) and have the client fetch it (a) before connecting and (b) again whenever
+  the WebTransport handshake fails, then retry once:
+
+  ```js
+  // server: GET /wsh-pins -> hex strings (parseCertificateHash() on the client accepts hex)
+  app.get('/wsh-pins', (req, res) => res.json(server.certificateHashes().map((h) => Buffer.from(h.value).toString('hex'))));
+
+  // client
+  async function connectPinned(url, opts) {
+    for (let attempt = 0; ; attempt++) {
+      const pins = (await (await fetch('/wsh-pins')).json()).map((hex) => ({ algorithm: 'sha-256', value: hexToBytes(hex) }));
+      try { return await client.connect(url, { ...opts, transport: 'wt', webTransport: { serverCertificateHashes: pins } }); }
+      catch (err) { if (attempt === 1) throw err; }   // stale pins: fetch the list again and retry once
+    }
+  }
+  ```
+
+  Because the next hash is published `prepareBeforeMs` (3 days) before the switch, a client that refreshes at least that
+  often (or on any failure) never sees a certificate it has not pinned. A client that stays up for longer than a certificate
+  lives and never refetches needs this retry; `transport: 'wt'` makes the failure explicit instead of falling back to
+  `wss://`.
+- Not covered: a certificate you supply (`cert`/`privKey`) is yours to renew; restart the server (or run it behind a
+  CA-issued certificate, which needs no pinning).
+
 - Node has no `WebTransport` global: a Node *client* needs `globalThis.WebTransport = (await import(
   '@fails-components/webtransport')).WebTransport` first. UDP, so a firewall must allow `port`, and there
   is no `wss://`-style TLS terminator in front: the certificate is the one this process serves.
@@ -668,9 +723,9 @@ whoever supplies the `Server`/`Client`, and the package root stays
 dependency-free and browser-safe.
 
 **Compatibility.** Purely additive. Old clients never open `rpc` sessions; an old
-host (or the Rust `wsh-server`, which has no `rpc` kind yet) does not advertise
-`rpc`, so a new client fails fast with `UNSUPPORTED_PROTOCOL` instead of waiting
-on an `OpenFail`. Only `@johnhenry/wsh/server` serves `rpc` today. Not goals: a
+host does not advertise `rpc`, so a new client fails fast with
+`UNSUPPORTED_PROTOCOL` instead of waiting on an `OpenFail`. `@johnhenry/wsh/server`
+and the Rust `wsh-server` (see below) serve `rpc` today. Not goals: a
 replacement for byte streams (exec/pty are unchanged), a new transport (`rpc`
 rides WebSocket/QMux and WebTransport streams), or an auth change -- an `rpc`
 session is opened on an authenticated connection and per-method authorization is
@@ -678,6 +733,33 @@ the handler's job (`-32003`; `ctx.user` / `ctx.fingerprint` identify the caller)
 Handlers run per channel, so register methods synchronously (or before the
 returned promise settles: inbound messages are held until it does).
 
+**The Rust `wsh-server`** (since `rust-v0.4.0`) serves `wsh-host` and `wsh-fs`
+exactly as the JS server does -- same features, methods, parameters, results,
+error codes and messages, same CBOR-sequence decoder and size bound, same
+`$/cancel` / `$/progress` -- over a WebSocket (QMux) connection. It does not
+serve `mcp` (hosting an MCP server is an embedding concern) and does not offer
+`rpc` on the native WebTransport listener, whose single control stream has no
+client-opened data streams to carry a channel. `wsh-host` is on by default;
+`wsh-fs` is **off until you give it a root** (file access is opt-in), and is
+confined to it the way the JS `fs` option is. In `~/.wsh/config.toml`:
+
+```toml
+[rpc]
+enabled = true            # default; false turns rpc off entirely
+max_message_bytes = 1048576   # advertised as rpc-max-message:<n>; at least 256
+max_inflight = 64         # concurrent requests per channel before -32002
+fs_root = "/srv/files"    # unset (the default): wsh-fs is not offered
+fs_read_only = false
+fs_max_file_bytes = 67108864
+```
+
+Key options apply as they do to other channels: a key restricted to a forced
+command opens no rpc channel, and `wsh-fs` needs the `file-transfer` scope
+(`permit-file-transfer` under `restrict`). `host.info` reports the crate version
+and `hostFingerprint: null` (the Rust server has no host key). The JS client
+needs nothing new: it reads `rpc` from `ServerHello`, and its file helpers prefer
+`wsh-fs` automatically once the server offers it.
+
 ## Attach and Resume
 
 Opening a PTY/exec session returns a session-scoped credential alongside the channel:
@@ -756,7 +838,10 @@ The constraints are the platform's, not wsh's:
 
 - The URL must be `https:`; pinning is HTTP/3 only, with no HTTP/2 fallback.
 - The certificate must use an **ECDSA P-256** key and be valid for **at most
-  14 days**, so it has to be reissued on a schedule.
+  14 days**, so it has to be reissued on a schedule. `serverCertificateHashes`
+  takes several digests: pin the current and the next one across a rotation
+  (the Node host's `certificateHashes()` publishes both; see
+  [Certificate rotation](#certificate-rotation)).
 - Connection pooling is disabled for a pinned connection.
 - Only `sha-256` is accepted as the algorithm.
 
@@ -854,7 +939,7 @@ than left to be found.
 | Remove a remote file | `WshClient.fileRemove()` | `file_transfer::remove()`, `wsh sftp`'s `rm` | **Wire-unified**: `FileOp`/`FileResult` (`op: "remove"`) -- refused today by every `wsh-server` release ("not yet implemented"), the same refusal on both sides |
 | Install an authorized key | `WshClient.addAuthorizedKey()` | `wsh_client::WshClient::add_authorized_key()`, `wsh copy-id` | **Wire-unified** (wsh #59): `AuthorizedKeyAdd`/`AuthorizedKeyResult`, replacing a Rust-CLI-only shell command with a message every implementation can send |
 | Host identity / TOFU | `WshKnownHosts` (localStorage-backed) | `KnownHosts`/`HostStatus` (`~/.wsh/known_hosts`-backed) | **Record unified, policy is not** (wsh #59): both pin `ServerHello.host_fingerprint`, which `@johnhenry/wsh/server` populates (with a proof of possession, [Host key](#host-key-fingerprint--tofu)) but no Rust `wsh-server` release does yet (see [Security](#security-model)). *When* to trust, prompt, or persist is deliberately left per-implementation -- a browser and a CLI have different UX for "first time seeing this host" |
-| Typed RPC channels (`openRpc`, `rpc` sessions; `wsh-host`, `wsh-fs`, `mcp`) | `WshClient.openRpc()`, `RpcChannel` | none yet (a Rust `wsh-server` does not advertise `rpc`; a JS client falls back to `FileOp` for files) | **JS server only, no wire change**: `Open { kind: 'rpc', command: <protocol> }` plus `rpc*` `ServerHello` features, negotiated so it fails fast elsewhere |
+| Typed RPC channels (`openRpc`, `rpc` sessions; `wsh-host`, `wsh-fs`, `mcp`) | `WshClient.openRpc()`, `RpcChannel` | Rust `wsh-server` (`rust-v0.4.0`+): `wsh-host`, and `wsh-fs` when `[rpc] fs_root` is set; no client yet in `wsh-client` | **No wire change**: `Open { kind: 'rpc', command: <protocol> }` plus `rpc*` `ServerHello` features, negotiated so it fails fast elsewhere; the Rust server serves it on WebSocket/QMux only |
 | Interactive shell UI | none -- this SDK is a protocol client, not a terminal emulator; pair with xterm.js/ghostty-web | `wsh connect`, `wsh sftp` (line-oriented REPL) | **Deliberately not unified** -- a browser embeds a terminal widget the host page owns; a CLI process owns its own TTY |
 | Attach / resume | `attachSession()`, `resumeSession()`, `WshSession.seq` | `attach_session()`, `resume_session()` | **Wire-unified** (`Attach`/`Resume`/`Presence`); `seq` = cumulative output bytes. `@johnhenry/wsh/server` honours `last_seq` (bounded ring, gap errors) and answers Presence with `channel_id`/`seq`; the Rust `wsh-server` does the same (`rust-v0.2.0`+; fixed 256 KiB ring) |
 | Reverse-connect / relay peer | `connectReverse()`, `trustRelayPeer()`; `@johnhenry/wsh/server`: `relay` option and `createReverseHost()` | `wsh reverse`, `wsh agent` (persistent, with startup-unit install) | **Wire-unified** (registration, discovery, signed peer records); **daemonization is CLI-only** -- a browser tab cannot be a background OS service. The Node relay is default-deny and bridges one operator per peer (`busy:` reasons say so); E2E and bridged feature gates need `rust-v0.3.0`+ on the Rust side |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnhenry/wsh",
-  "version": "0.26.0",
+  "version": "0.27.1",
   "description": "Web Shell \u2014 browser-native remote command execution over WebTransport and WebSocket with Ed25519 authentication",
   "type": "module",
   "main": "./src/index.mjs",

package/src/server/index.d.ts

@@ -215,10 +215,22 @@ export interface WshServerWebTransportOptions {
   privKey?: string;
   /**
    * Generate a short-lived ECDSA P-256 certificate (13 days; browsers refuse a pinned one valid for more than 14) and
-   * expose its SHA-256 as `webTransport().certificateHash`, for the client's `serverCertificateHashes`. It is not
-   * renewed: restart the server before `notAfter`. An object takes `{ hosts, validityDays }`.
+   * expose its SHA-256 as `webTransport().certificateHash`, for the client's `serverCertificateHashes`.
+   *
+   * It is rotated before it expires: `prepareBeforeMs` ahead of `notAfter` (default: 3 days, at most a third of the
+   * validity) the next certificate is generated and its hash published next to the current one
+   * (`server.certificateHashes()` returns both: a client that re-reads the list pins both), and `activateBeforeMs` ahead
+   * (default: 1 hour, at most a sixth of the validity) the listener switches to it. The switch restarts the HTTP/3
+   * listener on the same port, so live WebTransport sessions end and clients reconnect. `rotate: false` turns
+   * all of this off (restart before `notAfter`). An object takes `{ hosts, validityDays }` for the certificates too.
    */
-  selfSigned?: boolean | { hosts?: string[]; validityDays?: number };
+  selfSigned?: boolean | {
+    hosts?: string[];
+    validityDays?: number;
+    rotate?: boolean;
+    prepareBeforeMs?: number;
+    activateBeforeMs?: number;
+  };
   /** QUIC stateless-reset secret (default: random). */
   secret?: string;
 }
@@ -234,6 +246,27 @@ export interface WshServerWebTransport {
   certificateHashHex: string | null;
   /** When the `selfSigned` certificate expires; `null` otherwise. */
   notAfter: Date | null;
+  /** The `serverCertificateHashes` to pin now: the certificate being presented and, during a rotation's overlap, the next. */
+  certificateHashes(): WshPinnedCertificateHash[];
+  /** The same certificates with their validity and which one is being presented. */
+  certificates(): WshServerCertificateInfo[];
+  /** See `WshServer.rotateCertificate()`. */
+  rotateCertificate(options?: { activate?: boolean }): Promise<{ current: WshServerCertificateInfo; next: WshServerCertificateInfo | null }>;
+}
+
+/** A `serverCertificateHashes` entry, ready to pass to `new WebTransport(url, { serverCertificateHashes })`. */
+export interface WshPinnedCertificateHash {
+  algorithm: 'sha-256';
+  value: Uint8Array;
+}
+
+export interface WshServerCertificateInfo {
+  hash: Uint8Array;
+  hashHex: string;
+  notBefore: Date;
+  notAfter: Date;
+  /** Is it the one the listener presents right now? */
+  active: boolean;
 }
 
 export interface WshSelfSignedCertificate {
@@ -344,6 +377,19 @@ export interface WshServer {
   address(): WshServerAddress | null;
   /** The WebTransport listener; `null` when not configured or before `listen()` resolves. */
   webTransport(): WshServerWebTransport | null;
+  /**
+   * The `serverCertificateHashes` a WebTransport client should pin right now: the `selfSigned` certificate being
+   * presented and, during a rotation's overlap window, the next one. `[]` without a WebTransport listener or with a
+   * certificate you supplied. Serve it to your clients out of band (see the README's re-pin flow).
+   */
+  certificateHashes(): WshPinnedCertificateHash[];
+  /**
+   * Start rotating the `selfSigned` certificate: generate the next one and publish it in `certificateHashes()` now; the
+   * listener switches to it shortly before the current one expires (automatically, unless `selfSigned.rotate` is
+   * `false`). `{ activate: true }` switches immediately: live WebTransport sessions end. Rejects for a certificate
+   * you supplied, or before `listen()`.
+   */
+  rotateCertificate(options?: { activate?: boolean }): Promise<{ current: WshServerCertificateInfo; next: WshServerCertificateInfo | null }>;
   /** Fingerprints of the peers currently registered with this relay (`[]` when it is not one). */
   peerFingerprints(): string[];
   /** The advertised host identity; `null` before `listen()` resolves or without a `hostKey`. */

package/src/server/index.mjs

@@ -36,7 +36,8 @@ export { generateSelfSignedCertificate } from './self-signed.mjs';
  * @param {{ port?: number, host?: string, path?: string, cert?: string, privKey?: string, selfSigned?: boolean | object, secret?: string }} [options.webTransport]
  *   Also listen for WebTransport (HTTP/3 over UDP) clients, with the same auth and features as the WebSocket
  *   listener. `cert` / `privKey` are PEM; `selfSigned: true` makes a 13-day ECDSA P-256 certificate and exposes its
- *   SHA-256 through `webTransport()` for the client's `serverCertificateHashes`. Needs the optional peers
+ *   SHA-256 through `webTransport()` / `certificateHashes()` for the client's `serverCertificateHashes`, and rotates it
+ *   before it expires (`rotateCertificate()`). Needs the optional peers
  *   `@fails-components/webtransport` and `@fails-components/webtransport-transport-http3-quiche`. Off unless given.
  * @param {{ canRegister?: Function, canConnect?: Function, maxPeers?: number, connectTimeoutMs?: number }} [options.relay]
  *   Act as a relay: peers register (`ReverseRegister`, a signed record), operators list and connect to them
@@ -168,9 +169,29 @@ export function createWshServer({
       return {
         port: wt.port, host: wt.host, path: wt.path, url: `https://${wt.host.includes(':') ? `[${wt.host}]` : wt.host}:${wt.port}${wt.path}`,
         certificateHash: wt.certificateHash, certificateHashHex: wt.certificateHashHex, notAfter: wt.notAfter,
+        certificateHashes: () => wt.certificateHashes(), certificates: () => wt.certificates(), rotateCertificate: (o) => wt.rotateCertificate(o),
       };
     },
 
+    /**
+     * The `serverCertificateHashes` a WebTransport client should pin right now: the `selfSigned` certificate being
+     * presented and, during a rotation's overlap window, the next one too. `[]` with no WebTransport listener or
+     * with a certificate you supplied.
+     */
+    certificateHashes() {
+      return wt ? wt.certificateHashes() : [];
+    },
+
+    /**
+     * Start rotating the `selfSigned` WebTransport certificate: generate the next one and publish its hash in
+     * `certificateHashes()` now; it is switched to shortly before the current one expires (this happens by itself
+     * unless `selfSigned: { rotate: false }`). `{ activate: true }` switches immediately, ending live sessions.
+     */
+    rotateCertificate(options) {
+      if (!wt) return Promise.reject(new Error('rotateCertificate: there is no WebTransport listener (configure `webTransport` and `listen()`)'));
+      return wt.rotateCertificate(options);
+    },
+
     /** Fingerprints of the peers currently registered with this relay (`[]` when it is not one). */
     peerFingerprints() {
       return hub ? hub.peerFingerprints() : [];

package/src/server/self-signed.mjs

@@ -82,9 +82,11 @@ export function generateSelfSignedCertificate({ hosts = ['localhost', '127.0.0.1
   }
   const { publicKey, privateKey } = generateKeyPairSync('ec', { namedCurve: 'P-256' });
   // An hour of back-dating tolerates clock skew; the whole window stays under 14 days for validityDays <= 13.
-  const skewMs = Math.min(60 * 60 * 1000, (MAX_PINNED_CERT_DAYS - validityDays) * DAY_MS);
+  // (A very short validity, as rotation tests use, gets a proportionally smaller back-dating.)
+  const validityMs = validityDays * DAY_MS;
+  const skewMs = Math.min(60 * 60 * 1000, validityMs / 2, (MAX_PINNED_CERT_DAYS - validityDays) * DAY_MS);
   const notBefore = new Date(Math.floor((now.getTime() - skewMs) / 1000) * 1000);
-  const notAfter = new Date(Math.floor((now.getTime() + validityDays * DAY_MS - skewMs) / 1000) * 1000);
+  const notAfter = new Date(Math.ceil((now.getTime() + validityMs - skewMs) / 1000) * 1000);
 
   const name = seq(set(seq(oid(OID.commonName), utf8('wsh self-signed'))));
   const san = seq(...hosts.map((h) => (net.isIP(h) ? der(0x87, ipBytes(h)) : der(0x82, Buffer.from(h, 'ascii')))));

package/src/server/webtransport.mjs

@@ -13,6 +13,10 @@
  * host's `stream-announce` feature holds here as it does over QMux: the
  * client writes no primer.
  *
+ * A `selfSigned` certificate is rotated (see `startWebTransport`): the next one
+ * is generated and published (`certificateHashes()`) ahead of time, and the
+ * listener is switched to it shortly before the current one expires.
+ *
  * `@fails-components/webtransport` (and its native HTTP/3 transport package)
  * are optional peers, imported only when `webTransport` is given.
  */
@@ -22,6 +26,10 @@ import { FrameDecoder, frameEncode } from '../cbor.mjs';
 import { generateSelfSignedCertificate } from './self-signed.mjs';
 
 const DEFAULT_PATH = '/wsh';
+const DAY_MS = 24 * 60 * 60 * 1000;
+const HOUR_MS = 60 * 60 * 1000;
+/** setTimeout cannot wait longer than this (a 32-bit signed millisecond count). */
+const MAX_TIMER_MS = 2 ** 31 - 1;
 
 /** What a QMux stream looks like to the connection code, over a WebTransport bidirectional stream. */
 function adaptStream({ readable, writable }, onGone) {
@@ -59,19 +67,27 @@ function adaptStream({ readable, writable }, onGone) {
  * @param {string} opts.host
  * @param {(opts: object) => { receiveMessage: Function, bindStream: Function, close: Function }} opts.attach
  * @param {(line: string) => void} opts.log
- * @returns {Promise<{ port: number, host: string, path: string, certificateHash: Uint8Array | null, certificateHashHex: string | null, notAfter: Date | null, close(): Promise<void> }>}
+ * @returns {Promise<{ port: number, host: string, path: string, certificateHash: Uint8Array | null, certificateHashHex: string | null, notAfter: Date | null,
+ *   certificateHashes(): object[], certificates(): object[], rotateCertificate(opts?: { activate?: boolean }): Promise<object>, close(): Promise<void> }>}
  */
 export async function startWebTransport({ options, host, attach, log }) {
   const { port = 0, path = DEFAULT_PATH, selfSigned = false } = options;
   let { cert, privKey } = options;
-  let generated = null;
+  const certOpts = typeof selfSigned === 'object' ? selfSigned : {};
+  const { rotate = true, prepareBeforeMs: prepareOpt, activateBeforeMs: activateOpt, ...generateOpts } = certOpts;
+  /** The certificate being presented, and the next one once it has been generated (both only for `selfSigned`). */
+  let current = null;
+  let next = null;
   if (selfSigned) {
     if (cert || privKey) throw new TypeError('createWshServer: webTransport takes either selfSigned or cert/privKey, not both');
-    generated = generateSelfSignedCertificate(typeof selfSigned === 'object' ? selfSigned : {});
-    ({ cert, privKey } = generated);
+    current = generateSelfSignedCertificate(generateOpts);
+    ({ cert, privKey } = current);
   }
   if (!cert || !privKey) throw new TypeError('createWshServer: webTransport needs cert and privKey (PEM), or selfSigned: true');
   if (typeof path !== 'string' || !path.startsWith('/')) throw new TypeError('createWshServer: webTransport.path must start with "/"');
+  for (const [name, v] of [['prepareBeforeMs', prepareOpt], ['activateBeforeMs', activateOpt]]) {
+    if (v !== undefined && !(Number.isFinite(v) && v >= 0)) throw new TypeError(`createWshServer: webTransport.selfSigned.${name} must be a non-negative number`);
+  }
 
   let wtLib;
   try {
@@ -85,19 +101,7 @@ export async function startWebTransport({ options, host, attach, log }) {
     );
   }
 
-  const server = new wtLib.Http3Server({
-    port, host: options.host ?? host, secret: options.secret ?? randomBytes(16).toString('hex'), cert, privKey,
-  });
-  const sessions = server.sessionStream(path);
-  server.startServer();
-  try {
-    await server.ready;
-  } catch (err) {
-    try { server.stopServer(); } catch { /* never started */ }
-    throw err;
-  }
-  const addr = server.address();
-
+  const secret = options.secret ?? randomBytes(16).toString('hex');
   const live = new Set();
   let closing = false;
 
@@ -151,38 +155,154 @@ export async function startWebTransport({ options, host, attach, log }) {
     end();
   }
 
-  (async () => {
-    const reader = sessions.getReader();
+  /** Start an HTTP/3 listener presenting `pem` on `onPort` and feed its sessions to `serve`. */
+  async function launch(pem, onPort) {
+    const server = new wtLib.Http3Server({
+      port: onPort, host: options.host ?? host, secret, cert: pem.cert, privKey: pem.privKey,
+    });
+    const sessions = server.sessionStream(path);
+    server.startServer();
     try {
-      for (;;) {
-        const { done, value: session } = await reader.read();
-        if (done || closing) break;
-        serve(session).catch((e) => log(`webtransport session error: ${e.message}`));
+      await server.ready;
+    } catch (err) {
+      try { server.stopServer(); } catch { /* never started */ }
+      throw err;
+    }
+    (async () => {
+      const reader = sessions.getReader();
+      try {
+        for (;;) {
+          const { done, value: session } = await reader.read();
+          if (done || closing) break;
+          serve(session).catch((e) => log(`webtransport session error: ${e.message}`));
+        }
+      } catch { /* server stopped */ }
+    })();
+    return { server, addr: server.address() };
+  }
+
+  /** End every live session, giving the close a moment to reach the peers. */
+  async function closeLive() {
+    const open = [...live];
+    for (const s of open) { try { s.close(); } catch { /* gone */ } }
+    // Bounded: a peer that never acks cannot hold shutdown.
+    await Promise.race([
+      Promise.allSettled(open.map((s) => s.closed)),
+      new Promise((r) => { const t = setTimeout(r, 500); t.unref?.(); }),
+    ]);
+    live.clear();
+  }
+
+  let listener = await launch({ cert, privKey }, port);
+  const boundPort = listener.addr.port;
+
+  // ── Rotation (selfSigned only) ─────────────────────────────────────
+  //
+  // A pinned certificate cannot simply be renewed: clients pin its hash, and a
+  // browser takes no certificate valid for more than 14 days, so a long-running
+  // server would stop being reachable at `notAfter`. Instead the next
+  // certificate is generated AHEAD of time and its hash is published next to the
+  // current one (`certificateHashes()`), so a client that re-reads the list
+  // during the overlap window pins both and survives the switch. The listener
+  // presents one certificate at a time (the native transport cannot swap one in
+  // place, so the switch restarts it on the same port: sessions end, clients
+  // reconnect).
+  let prepareTimer = null;
+  let activateTimer = null;
+  let chain = Promise.resolve();
+  const serial = (fn) => { const run = chain.then(fn); chain = run.catch(() => {}); return run; };
+
+  const validityOf = (c) => c.notAfter.getTime() - c.notBefore.getTime();
+  const prepareBeforeMs = () => prepareOpt ?? Math.min(3 * DAY_MS, validityOf(current) / 3);
+  const activateBeforeMs = () => activateOpt ?? Math.min(HOUR_MS, validityOf(current) / 6);
+  const clearTimers = () => { clearTimeout(prepareTimer); clearTimeout(activateTimer); prepareTimer = activateTimer = null; };
+  const later = (fn, at) => {
+    // Long waits are re-armed: a timer cannot exceed ~24.8 days, and a sleeping machine fires late, so re-check on wake.
+    const wait = Math.max(0, at - Date.now());
+    const t = setTimeout(() => (wait > MAX_TIMER_MS ? later(fn, at) : fn()), Math.min(wait, MAX_TIMER_MS));
+    t.unref?.();
+    return t;
+  };
+
+  function schedule() {
+    clearTimers();
+    if (!current || !rotate || closing) return;
+    if (!next) {
+      prepareTimer = later(() => { rotateCertificate().catch((e) => log(`webtransport: preparing the next certificate failed: ${e.message}`)); }, current.notAfter.getTime() - prepareBeforeMs());
+    } else {
+      activateTimer = later(() => { rotateCertificate({ activate: true }).catch((e) => log(`webtransport: certificate rotation failed: ${e.message}`)); }, current.notAfter.getTime() - activateBeforeMs());
+    }
+  }
+
+  function prepare() {
+    if (next) return;
+    next = generateSelfSignedCertificate(generateOpts);
+    log(`webtransport: next certificate ready, sha-256 ${next.hashHex} (current ${current.hashHex} until ${current.notAfter.toISOString()})`);
+  }
+
+  async function activate() {
+    prepare();
+    const incoming = next;
+    await closeLive();
+    try { listener.server.stopServer(); } catch { /* already stopped */ }
+    // The UDP port may take a moment to come free.
+    let lastErr;
+    for (let attempt = 0; attempt < 20; attempt++) {
+      try {
+        listener = await launch(incoming, boundPort);
+        lastErr = null;
+        break;
+      } catch (err) {
+        lastErr = err;
+        await new Promise((r) => setTimeout(r, 100));
       }
-    } catch { /* server stopped */ }
-  })();
+    }
+    if (lastErr) throw new Error(`could not restart the WebTransport listener on port ${boundPort} with the new certificate: ${lastErr.message}`, { cause: lastErr });
+    const old = current;
+    current = incoming;
+    next = null;
+    log(`webtransport: now presenting certificate sha-256 ${current.hashHex} until ${current.notAfter.toISOString()} (replaced ${old.hashHex})`);
+  }
+
+  /**
+   * Start a rotation: generate the next certificate if there is none yet and publish its hash
+   * (`certificateHashes()` = [current, next]). With `activate`, also switch to it now (live sessions
+   * end); otherwise it is switched to shortly before the current one expires.
+   */
+  function rotateCertificate({ activate: now = false } = {}) {
+    if (!current) return Promise.reject(new Error('rotateCertificate: only a selfSigned certificate is rotated (supply a new cert by restarting the server)'));
+    return serial(async () => {
+      if (closing) throw new Error('rotateCertificate: the listener is closed');
+      if (now) await activate(); else prepare();
+      schedule();
+      return { current: describe(current, true), next: next ? describe(next, false) : null };
+    });
+  }
+
+  const describe = (c, active) => ({ hash: c.hash, hashHex: c.hashHex, notBefore: c.notBefore, notAfter: c.notAfter, active });
+  schedule();
 
   const bound = {
-    port: addr.port,
-    host: addr.host,
+    port: boundPort,
+    host: listener.addr.host,
     path,
-    certificateHash: generated?.hash ?? null,
-    certificateHashHex: generated?.hashHex ?? null,
-    notAfter: generated?.notAfter ?? null,
+    get certificateHash() { return current?.hash ?? null; },
+    get certificateHashHex() { return current?.hashHex ?? null; },
+    get notAfter() { return current?.notAfter ?? null; },
+    /** `serverCertificateHashes` for a client: the current certificate and, during an overlap, the next. */
+    certificateHashes() { return [current, next].filter(Boolean).map((c) => ({ algorithm: 'sha-256', value: c.hash })); },
+    /** The same, with validity and which one is being presented. */
+    certificates() { return [current && describe(current, true), next && describe(next, false)].filter(Boolean); },
+    rotateCertificate,
     async close() {
       closing = true;
-      const open = [...live];
-      for (const s of open) { try { s.close(); } catch { /* gone */ } }
-      // Let the close reach the peers before the socket is torn down (bounded: a peer that never acks cannot hold shutdown).
-      await Promise.race([
-        Promise.allSettled(open.map((s) => s.closed)),
-        new Promise((r) => { const t = setTimeout(r, 500); t.unref?.(); }),
-      ]);
-      live.clear();
-      try { server.stopServer(); } catch { /* already stopped */ }
+      clearTimers();
+      await chain.catch(() => {});
+      await closeLive();
+      try { listener.server.stopServer(); } catch { /* already stopped */ }
     },
   };
-  log(`webtransport listening on https://${addr.host}:${addr.port}${path}`
-    + (generated ? ` (self-signed, sha-256 ${generated.hashHex}, until ${generated.notAfter.toISOString()})` : ''));
+  log(`webtransport listening on https://${listener.addr.host}:${boundPort}${path}`
+    + (current ? ` (self-signed, sha-256 ${current.hashHex}, until ${current.notAfter.toISOString()}${rotate ? '' : ', not rotated'})` : ''));
   return bound;
 }