@johnhenry/wsh 0.26.0 → 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.
@@ -756,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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnhenry/wsh",
-  "version": "0.26.0",
+  "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/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;
 }