@johnhenry/wsh 0.25.1 → 0.27.0

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.
@@ -287,27 +342,56 @@ const s = await client.openSession({ type: 'exec', command: 'echo hello' });
   checked against the allowlist (a non-forwardable or undecodable inner is
   dropped, logged), and re-wrapped with the real sender; traffic from a connection
   that is not bridged is never forwarded.
-- **One operator per peer at a time**; a second `ReverseConnect` is rejected as
-  `busy`, and one the peer does not answer within `connectTimeoutMs` (default
-  8 s) as `peer did not respond`. A bridge lasts as long as both connections:
-  when either ends, the relay closes the other, so nothing an operator started
-  outlives it (the reverse host kills its processes). `createReverseHost`
-  redials with backoff by default (`reconnect: false` to turn it off), so it is
-  registered again for the next operator.
+- **One operator per peer at a time**, by design: a `RelayForward` names its
+  sender but not its recipient, and nothing on the wire tells a peer that one
+  of several operators left, so replies could not be addressed and a departed
+  operator's work could not be cleaned up. A second `ReverseConnect` to a peer
+  that already has an operator (or a request awaiting its answer) is rejected
+  with `ReverseReject.reason` `busy: this peer already has an operator ...`
+  (exported as `BUSY_PEER` from `src/server/relay.mjs`), and an operator that
+  already has a bridge or a request in flight is rejected with `busy: you
+  already have a bridge ...` (`BUSY_OPERATOR`); a request the peer does not
+  answer within `connectTimeoutMs` (default 8 s) is `peer did not respond`.
+  A bridge lasts as long as both connections: when either ends, the relay
+  closes the other, so nothing an operator started outlives it (the reverse
+  host kills its processes). `createReverseHost` redials with backoff by
+  default (`reconnect: false` to turn it off), so it is registered again for
+  the next operator. Lifting the limit needs a spec addition (a recipient on
+  `RelayForward`, a bridge-ended notice) shared with the Rust side; it is
+  tracked rather than built.
 - **On the peer**, the bridged operator is served by the same connection code as
   a direct client, over an in-memory message pipe instead of a socket. Nothing a
   client opens can cross the relay but control messages, so exec sessions are
   `data_mode: 'virtual'` there (stdin and output ride `SessionData`; there is no
   stdin EOF).
-- **Not provided:** end-to-end encryption between operator and peer -- `KeyExchange` /
-  `EncryptedFrame` are not on the spec's `forwardable` list, so the relay sees the
-  traffic in clear (serve it over `wss://`, and treat the relay operator as trusted).
-  Client-side feature gates (`fileWrite`/`fileRename` need `file-write`/`file-rename`,
-  `callTool` correlates on `mcp-call-id`) read the **relay's** `ServerHello`, which
-  says nothing about the peer behind it: against a relay without `fs`, `fileWrite()`
-  refuses locally (reads, listing, stat and exec are unaffected). Multiplexing
-  several operators onto one peer needs a way to address replies, which `RelayForward`
-  does not have.
+- **End-to-end encryption through the bridge.** `KeyExchange` and `EncryptedFrame`
+  are on the spec's `forwardable` list, so an operator and a peer can run
+  `initiateE2E()` / `enableE2E()` with each other through the relay: it carries
+  the CBOR of each as opaque bytes and holds no key, so it sees only public
+  values and ciphertext (`test/server-relay-bridge.test.mjs` checks the relay
+  never holds the plaintext). **`KeyExchange` is unauthenticated**: this
+  protects against a relay that only observes, not against one that substitutes
+  the exchanged keys, so if the relay operator is not trusted, authenticate the
+  derived key yourself (compare it out of band, or sign it with the keys the
+  bridge already names). Only a stock-client peer (a browser tab, `connectReverse`)
+  speaks E2E: **`createReverseHost` does not answer `KeyExchange` or open
+  `EncryptedFrame`s** (the Node host has no E2E layer at all), so against it traffic
+  is in the clear to the relay -- serve the relay over `wss://` and treat its
+  operator as trusted. Key exchange from a connection that is not bridged is
+  never carried.
+- **Feature gates follow the host behind the bridge.** The host's own features
+  (`file-write`, `file-rename`, `mcp-call-id`) are stated in the optional
+  `ReverseAccept.features`; the relay forwards the list (bounded: at most 64
+  strings of 128 characters, otherwise it is dropped) and, once
+  `reverseConnect()` resolves, `client.hasFeature()` / `client.features` answer
+  from it instead of the relay's `ServerHello`. `client.bridgedFeatures` is that
+  list (`null` before a bridge, or when the peer did not say, in which case the
+  gates fall back to `client.serverFeatures`, the relay's, as before).
+  `createReverseHost` always states its features (`reportFeatures: false` leaves
+  them out). A **Rust `wsh-server` / `wsh` older than `rust-v0.3.0` rejects a
+  `ReverseAccept` that carries `features`** (the message is `deny_unknown_fields`
+  there): against such a relay or operator, set `reportFeatures: false` on the
+  host (and use `ReverseAccept` without the field in your own peers).
 
 ### Sessions: attach / resume / detach
 
@@ -727,7 +811,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.
 
@@ -828,7 +915,7 @@ than left to be found.
 | 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 |
 | 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 |
+| 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 |
 | Post-quantum E2E (experimental) | `initiateE2E()` (WebCrypto ML-KEM-768 or `@noble/post-quantum` fallback) | `E2eKeyExchange` (`ml-kem` crate) | **Wire-unified** algorithm and transcript; key material backends differ by platform necessity |
 | Session recording/replay | `SessionRecorder`/`SessionPlayer` (asciicast v2) | none | **JS-only** -- no current Rust consumer needs playback; the format itself (asciicast v2) is not proprietary if one is added later |
 | Self-signed cert pinning | `serverCertificateHashes` (WebTransport option) | N/A -- Rust dials a cert its own TLS stack already trusts, or `--generate-cert`'s self-signed cert out of band | **Deliberately not unified** -- this is a browser-specific WebTransport API shape, not a wire-protocol concept |
@@ -900,6 +987,11 @@ out explicitly below rather than left to be discovered.
   `SHA-256("wsh-v1\0" || lp(username) || lp(session_id) || nonce || channel_binding)`,
   so a signature can't be replayed against a different session or relabeled
   to a different username.
+- **E2E through a relay is opt-in and unauthenticated key agreement.** The relay
+  carries `KeyExchange` / `EncryptedFrame` between a bridged operator and peer
+  without being able to read the sealed frames, but `KeyExchange` carries no
+  signature: a relay that substitutes keys is not detected (see the [relay
+  section](#relay--reverse-mode)).
 - **Signed peer records.** Reverse-mode registration is self-signed by the
   peer's identity key (the libp2p RFC 0002/0003 pattern), in a signing
   domain separate from the auth challenge. `listPeers()` verifies every

package/package.json

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

package/src/client.mjs

@@ -313,6 +313,11 @@ export class WshClient {
 
   /** @type {string[]} Server-advertised features from SERVER_HELLO. */
   #serverFeatures = [];
+  /**
+   * @type {string[]|null} Features of the host behind an accepted relay bridge, from
+   * `ReverseAccept.features`; `null` when no bridge is up or the peer stated none.
+   */
+  #bridgedFeatures = null;
 
   /** @type {number|null} Ping interval handle. */
   #pingTimer = null;
@@ -437,11 +442,29 @@ export class WshClient {
     return new Map(this.#sessions);
   }
 
-  /** Server-advertised features from SERVER_HELLO. */
+  /**
+   * The features this connection's operations can rely on: those of the host
+   * behind an accepted relay bridge when it stated them (`ReverseAccept.features`,
+   * see `reverseConnect()`), otherwise the server's `SERVER_HELLO` features.
+   */
   get features() {
+    return [...(this.#bridgedFeatures ?? this.#serverFeatures)];
+  }
+
+  /** The `SERVER_HELLO` features of the server this connection is to (the relay, over a bridge). */
+  get serverFeatures() {
     return [...this.#serverFeatures];
   }
 
+  /**
+   * Features of the host behind an accepted relay bridge, as it stated them in
+   * `ReverseAccept.features`; `null` when there is no bridge, or the peer did
+   * not say (then `hasFeature()` falls back to the server's own).
+   */
+  get bridgedFeatures() {
+    return this.#bridgedFeatures ? [...this.#bridgedFeatures] : null;
+  }
+
   /**
    * Low-level transport reference.
    * Exposed for relay message replies (IncomingSession._sendReply).
@@ -458,7 +481,7 @@ export class WshClient {
    * @returns {boolean}
    */
   hasFeature(name) {
-    return this.#serverFeatures.includes(name);
+    return (this.#bridgedFeatures ?? this.#serverFeatures).includes(name);
   }
 
   /**
@@ -980,6 +1003,7 @@ export class WshClient {
 
     this.#stopPing();
     this.#state = STATE_CLOSED;
+    this.#bridgedFeatures = null;
 
     // Close all sessions concurrently.
     const closePromises = [];
@@ -1217,6 +1241,12 @@ export class WshClient {
 
     if (response.type === MSG.REVERSE_ACCEPT) {
       this.trustRelayPeer(response.target_fingerprint);
+      // The relay's SERVER_HELLO describes the relay, not the host behind the
+      // bridge: when that host says what it supports, feature gates
+      // (file-write, file-rename, mcp-call-id) follow it instead.
+      this.#bridgedFeatures = Array.isArray(response.features) && response.features.every((f) => typeof f === 'string')
+        ? [...response.features]
+        : null;
     }
 
     return response;
@@ -2747,6 +2777,7 @@ export class WshClient {
     if (this.#state === STATE_CLOSED) return;
 
     this.#state = STATE_CLOSED;
+    this.#bridgedFeatures = null;
     this.#stopPing();
     this.#rejectAllWaiters(new Error('Transport closed'));
 

package/src/index.d.ts

@@ -603,6 +603,8 @@ export function reverseAccept(opts?: {
   supportsReplay?: boolean;
   supportsEcho?: boolean;
   supportsTermSync?: boolean;
+  /** Features of this (bridged) host, in the vocabulary of `ServerHello.features`; omit rather than send `[]`. */
+  features?: string[];
 }): WshMessage;
 
 export function reverseReject(opts?: {
@@ -1970,8 +1972,15 @@ export class WshClient {
   /** Read-only view of active sessions. */
   readonly sessions: Map<number, WshSession>;
 
-  /** Server-advertised features from SERVER_HELLO. */
+  /**
+   * The features this connection can rely on: those of the host behind an accepted relay bridge when it
+   * stated them (`ReverseAccept.features`), otherwise the server's `SERVER_HELLO` features.
+   */
   readonly features: string[];
+  /** The `SERVER_HELLO` features of the server connected to (the relay, over a bridge). */
+  readonly serverFeatures: string[];
+  /** Features of the host behind an accepted relay bridge as it stated them; `null` when there is no bridge or it did not say. */
+  readonly bridgedFeatures: string[] | null;
 
   /**
    * Low-level transport reference.
@@ -2004,7 +2013,7 @@ export class WshClient {
   onGatewayMessage: ((msg: WshMessage) => void) | null;
 
   /**
-   * Check if the server advertised a specific feature.
+   * Check if a feature is available: advertised by the server, or by the bridged host (see `features`).
    */
   hasFeature(name: string): boolean;
 

package/src/messages.gen.mjs

@@ -495,19 +495,10 @@ export function reverseConnect({ targetFingerprint, username, fromFingerprint }
   };
 }
 
-export function reverseAccept({ targetFingerprint, username, capabilities = [], peerType = "host", shellBackend = "pty", supportsAttach = false, supportsReplay = false, supportsEcho = false, supportsTermSync = false } = {}) {
-  return {
-    type: MSG.REVERSE_ACCEPT,
-    target_fingerprint: targetFingerprint,
-    username,
-    capabilities,
-    peer_type: peerType,
-    shell_backend: shellBackend,
-    supports_attach: supportsAttach,
-    supports_replay: supportsReplay,
-    supports_echo: supportsEcho,
-    supports_term_sync: supportsTermSync,
-  };
+export function reverseAccept({ targetFingerprint, username, capabilities = [], peerType = "host", shellBackend = "pty", supportsAttach = false, supportsReplay = false, supportsEcho = false, supportsTermSync = false, features } = {}) {
+  const msg = { type: MSG.REVERSE_ACCEPT, target_fingerprint: targetFingerprint, username, capabilities, peer_type: peerType, shell_backend: shellBackend, supports_attach: supportsAttach, supports_replay: supportsReplay, supports_echo: supportsEcho, supports_term_sync: supportsTermSync };
+  if (features !== undefined) msg.features = features;
+  return msg;
 }
 
 export function reverseReject({ targetFingerprint, username, reason } = {}) {
@@ -962,6 +953,8 @@ export const RELAY_FORWARDABLE = new Set([
   MSG.ECHO_STATE,
   MSG.TERM_SYNC,
   MSG.TERM_DIFF,
+  MSG.KEY_EXCHANGE,
+  MSG.ENCRYPTED_FRAME,
 ]);
 
 /**

package/src/server/connection.mjs

@@ -31,6 +31,22 @@ import { RpcChannel, RPC_FEATURE, RPC_MAX_MESSAGE_PREFIX, rpcProtocolFeature } f
 import { HOST_KEY_PREFIX, HOST_KEY_SIG_PREFIX, findClientNonce, hostKeyProofMessage, toHex } from '../host-key.mjs';
 
 export const STREAM_ANNOUNCE = 'stream-announce';
+
+/**
+ * The features a host built from `cfg` advertises (`ServerHello.features`, minus the host-key proof).
+ * Over a relay bridge (`dataStreams: false`) there are no client-opened streams, so the
+ * stream-based ones (`stream-announce`, `rpc`) are not offered; a reverse host reports this
+ * list to the operator in `ReverseAccept.features`.
+ */
+export function hostFeatures(cfg, { dataStreams = true } = {}) {
+  const features = dataStreams ? [STREAM_ANNOUNCE] : [];
+  if (cfg.mcp) features.push(MCP_CALL_ID_FEATURE);
+  if (cfg.files) features.push('file-transfer', 'file-write', 'file-rename');
+  if (cfg.rpc && dataStreams && cfg.rpc.protocols.size) {
+    features.push(RPC_FEATURE, ...[...cfg.rpc.protocols.keys()].map(rpcProtocolFeature), RPC_MAX_MESSAGE_PREFIX + cfg.rpc.maxMessageBytes);
+  }
+  return features;
+}
 const MAX_PENDING_WRITES = 8;
 const MAX_RENAME_PATH_BYTES = 4096;
 const WRITE_IDLE_MS = 30_000;
@@ -201,12 +217,7 @@ export function createConnectionFactory(cfg) {
         }
         state.username = user;
         state.method = method;
-        const features = [STREAM_ANNOUNCE];
-        if (cfg.mcp) features.push(MCP_CALL_ID_FEATURE);
-        if (cfg.files) features.push('file-transfer', 'file-write', 'file-rename');
-        if (cfg.rpc && dataStreams && cfg.rpc.protocols.size) {
-          features.push(RPC_FEATURE, ...[...cfg.rpc.protocols.keys()].map(rpcProtocolFeature), RPC_MAX_MESSAGE_PREFIX + cfg.rpc.maxMessageBytes);
-        }
+        const features = hostFeatures(cfg, { dataStreams });
         let hostFingerprint;
         if (cfg.hostKey) {
           hostFingerprint = cfg.hostKey.fingerprint;

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/relay.mjs

@@ -27,8 +27,15 @@ export const DEFAULT_CONNECT_TIMEOUT_MS = 8000;
 const MAX_FORWARD_BYTES = 8 * 1024 * 1024;
 const MAX_REMEMBERED_SEQS = 4096;
 const MAX_CAPABILITIES = 32;
+const MAX_FEATURES = 64;
+const MAX_FEATURE_LENGTH = 128;
 const SHORT_PREFIX_MIN = 8;
 
+/** `ReverseReject.reason` for a peer that already has an operator (or a request awaiting its answer). */
+export const BUSY_PEER = 'busy: this peer already has an operator (the relay bridges one operator per peer at a time; retry when it leaves)';
+/** `ReverseReject.reason` for an operator that already has a bridge, or a request in flight. */
+export const BUSY_OPERATOR = 'busy: you already have a bridge or a pending connect on this relay (one at a time)';
+
 const isStr = (v, max) => typeof v === 'string' && v.length <= max;
 
 /**
@@ -186,9 +193,13 @@ export class RelayHub {
         fingerprint: target.meta.fingerprint, username: target.meta.username, capabilities: target.meta.capabilities,
       }))) return reject('no such peer');
     if (this.#peers.get(target.meta.fingerprint) !== target) return reject('no such peer');
-    if (this.#pairs.has(operator) || this.#pairs.has(target.handle)
-      || [...this.#pending.values()].some((p) => p.operator === operator) || this.#pending.has(target.handle)) {
-      return reject('busy');
+    // One bridge per peer, and one per operator: a RelayForward names its sender but not its recipient, so a
+    // peer's reply could not be addressed to one of several operators (see the README's relay section).
+    if (this.#pairs.has(target.handle) || this.#pending.has(target.handle)) {
+      return reject(BUSY_PEER);
+    }
+    if (this.#pairs.has(operator) || [...this.#pending.values()].some((p) => p.operator === operator)) {
+      return reject(BUSY_OPERATOR);
     }
     const timer = setTimeout(() => {
       if (this.#pending.get(target.handle)?.operator !== operator) return;
@@ -213,8 +224,13 @@ export class RelayHub {
     if (!p) return;
     clearTimeout(p.timer);
     this.#pending.delete(peer);
-    // The answer names the answering peer, not whatever it wrote.
-    p.operator.send({ ...msg, target_fingerprint: peer.fingerprint });
+    // The answer names the answering peer, not whatever it wrote; its features claim is bounded.
+    const answer = { ...msg, target_fingerprint: peer.fingerprint };
+    if (msg.type === MSG.REVERSE_ACCEPT) {
+      if (Array.isArray(msg.features) && msg.features.length <= MAX_FEATURES && msg.features.every((f) => isStr(f, MAX_FEATURE_LENGTH))) answer.features = [...msg.features];
+      else delete answer.features;
+    }
+    p.operator.send(answer);
     if (msg.type === MSG.REVERSE_ACCEPT) {
       this.#pairs.set(p.operator, peer);
       this.#pairs.set(peer, p.operator);

package/src/server/reverse-host.mjs

@@ -13,7 +13,7 @@ import { WshClient } from '../client.mjs';
 import { exportPublicKeyRaw, fingerprint } from '../auth.mjs';
 import { reverseAccept, reverseReject } from '../messages.gen.mjs';
 import { buildBackends } from './backends.mjs';
-import { createConnectionFactory } from './connection.mjs';
+import { createConnectionFactory, hostFeatures } from './connection.mjs';
 
 const BACKOFF_START_MS = 500;
 const BACKOFF_MAX_MS = 30_000;
@@ -32,10 +32,13 @@ const BACKOFF_MAX_MS = 30_000;
  * @param {boolean} [options.reconnect=true] - Dial again (with backoff) after the relay connection ends. A relay ends it when a bridge does.
  * @param {object} [options.connect] - Extra options for the relay connection (`expectHostKey`, `knownHosts`, ...).
  * @param {string} [options.peerType='host']
+ * @param {boolean} [options.reportFeatures=true] - State this host's features in `ReverseAccept.features`, so the operator's
+ *   feature gates follow this host rather than the relay. Turn off only for a relay (a Rust `wsh-server` older than the field)
+ *   that rejects a `ReverseAccept` carrying it.
  * @param {(line: string) => void} [options.onLog]
  */
 export function createReverseHost({
-  url, username, keyPair, accept, exec, pty, fs, mcp, reconnect = true, connect = {}, peerType = 'host', onLog = () => {},
+  url, username, keyPair, accept, exec, pty, fs, mcp, reconnect = true, connect = {}, peerType = 'host', reportFeatures = true, onLog = () => {},
 } = {}) {
   if (!url) throw new TypeError('createReverseHost: url is required');
   if (!username) throw new TypeError('createReverseHost: username is required');
@@ -46,6 +49,9 @@ export function createReverseHost({
   const expose = { shell: !!backends.pty, exec: !!backends.execRunner, fs: !!backends.files, tools: !!backends.mcp };
   const capabilities = Object.entries(expose).filter(([, on]) => on).map(([k]) => k);
   const shellBackend = backends.pty ? 'pty' : 'exec-only';
+  // What this host can do over a bridge, for the operator's feature gates (`ReverseAccept.features`).
+  // `reportFeatures: false` leaves them out (a Rust peer or relay older than the field rejects a ReverseAccept that has it).
+  const bridgeFeatures = hostFeatures({ mcp: backends.mcp, files: backends.files }, { dataStreams: false });
   const factory = createConnectionFactory({
     authorize: async () => false, methods: { pubkey: false, password: null }, hostKey: null, rateLimit: null,
     execRunner: backends.execRunner, execOptions: backends.execOptions, pty: backends.pty, files: backends.files, mcp: backends.mcp,
@@ -74,7 +80,7 @@ export function createReverseHost({
       const from = req.from_fingerprint;
       const answer = (m) => c.sendRelayControl(m).catch(() => {});
       const refuse = (reason) => answer(reverseReject({ targetFingerprint: myFingerprint, username, reason }));
-      if (bridge || typeof from !== 'string' || !from) { await refuse('busy'); return; }
+      if (bridge || typeof from !== 'string' || !from) { await refuse('busy: this host is already serving an operator'); return; }
       let ok = false;
       try { ok = (await accept?.({ fingerprint: from, username: String(req.username ?? '') })) === true; } catch (e) { onLog(`[reverse] accept threw: ${e.message}`); }
       if (!ok || bridge) { await refuse('not accepted'); return; }
@@ -89,6 +95,7 @@ export function createReverseHost({
       await answer(reverseAccept({
         targetFingerprint: myFingerprint, username, capabilities, peerType, shellBackend,
         supportsAttach: false, supportsReplay: false, supportsEcho: false, supportsTermSync: false,
+        features: reportFeatures ? bridgeFeatures : undefined,
       }));
     };
     c.onClose = () => {

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;
 }