@johnhenry/wsh 0.22.0 → 0.23.1

package/README.md

@@ -155,7 +155,7 @@ hosts do). Pass `primer: false` to never send it.
 ## Node Server
 
 `@johnhenry/wsh/server` is a Node host for the same protocol, over WebSocket
-(QMux). It is a separate subpath -- the package root stays browser-safe and
+(QMux) and, optionally, [WebTransport](#webtransport-listener). It is a separate subpath -- the package root stays browser-safe and
 never imports it -- and needs the optional peer dependency `ws`
 (`npm install ws`).
 
@@ -185,7 +185,50 @@ restricted host with no shell. `fs.root` confines every path: `..`, absolute
 paths and symlinks pointing out of it are refused -- for `write` and `rename`
 (both paths) exactly as for `read`.
 
-Not implemented (tracking issue): WebTransport.
+### WebTransport listener
+
+The client's ladder prefers WebTransport (`https://`) and falls back to `wss://`;
+`webTransport` gives the Node host the first rung, with real independent QUIC
+streams (no head-of-line blocking across channels):
+
+```js
+const server = createWshServer({
+  auth, exec: true, fs: { root: '/srv/share' },
+  webTransport: { port: 4433, selfSigned: true },        // or { cert, privKey } PEM
+});
+await server.listen();                                    // the WebSocket listener still runs
+const { url, certificateHash } = server.webTransport();  // https://127.0.0.1:4433/wsh, sha-256 of the cert
+
+// client (a browser, or Node with a WebTransport implementation)
+await client.connect(url, {
+  username, keyPair, transport: 'wt',
+  webTransport: { serverCertificateHashes: [{ algorithm: 'sha-256', value: certificateHash }] },
+});
+```
+
+- **Optional peers**, imported only when `webTransport` is set:
+  `npm install @fails-components/webtransport @fails-components/webtransport-transport-http3-quiche`
+  (a native HTTP/3 build, prebuilt for Linux/macOS/Windows on x64 and arm).
+  Without them `listen()` rejects with that instruction, and a server with no `webTransport`
+  never loads them.
+- **Same host, other wire.** Auth (keys, password, host key), `exec`, `pty`, `fs`, `mcp`,
+  `sessions` and `relay` behave identically; only the transport differs. The control stream is the
+  session's first bidirectional stream (length-prefixed CBOR frames); every bidirectional stream the client
+  opens afterwards is a data stream, bound to the next exec channel in `OpenOk` order. A client-created
+  stream is visible to the host as soon as it exists, so the host advertises `stream-announce` and the
+  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)).
+- 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**.
 
 ### Relay / reverse mode
 
@@ -500,7 +543,7 @@ the host to find it:
 | Current stock client | `@johnhenry/wsh/server` (advertises `stream-announce`) | The client's transport announces the stream with an empty STREAM frame. **No primer is written.** |
 | Current stock client | Host without `stream-announce` (e.g. the Rust `wsh-server`, older vendored hosts) | The client writes a one-byte primer (`0x00`) on the new stream so the host sees it; that host strips it. `primer: false` disables this (then such a host never binds the stream and the output is lost). |
 | A client that primes anyway (older stock client, `primer` forced, other implementations) | `@johnhenry/wsh/server` | **The leading `0x00` is dropped:** if the first data on an exec stream is exactly one `0x00` byte it is discarded, never forwarded to the process's stdin. Only that first chunk is inspected; a later `0x00`, or a first chunk that is longer than one byte, is delivered untouched. The cost: a client whose genuine first stdin chunk is a lone NUL loses it. |
-| A client that neither announces nor primes | `@johnhenry/wsh/server` | The host waits `bindTimeoutMs` (default 3000) for the stream, then drops the output and logs it. |
+| A client that neither announces nor primes (a third-party QMux client; the stock client always does one or the other) | `@johnhenry/wsh/server` | The host waits `bindTimeoutMs` (default 3000) for the stream, then drops the output and logs it. This cannot be fixed host-side: nothing about the stream has been sent, so there is nothing to bind. Such a client must send `QMuxStream.announce()` (an empty STREAM frame) or any first write -- a zero-length `write()` now does the same. |
 
 ## Attach and Resume
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnhenry/wsh",
-  "version": "0.22.0",
+  "version": "0.23.1",
   "description": "Web Shell \u2014 browser-native remote command execution over WebTransport and WebSocket with Ed25519 authentication",
   "type": "module",
   "main": "./src/index.mjs",
@@ -24,9 +24,17 @@
     "@noble/post-quantum": "^0.7.0"
   },
   "peerDependencies": {
+    "@fails-components/webtransport": "^1.6.4",
+    "@fails-components/webtransport-transport-http3-quiche": "^1.6.4",
     "ws": "^8.0.0"
   },
   "peerDependenciesMeta": {
+    "@fails-components/webtransport": {
+      "optional": true
+    },
+    "@fails-components/webtransport-transport-http3-quiche": {
+      "optional": true
+    },
     "ws": {
       "optional": true
     }

package/src/qmux-connection.mjs

@@ -116,6 +116,12 @@ class QMuxStream {
     if (this.#sendState === SEND_STATE.DATA_SENT) {
       throw new Error(`Cannot write to stream ${this.id}: already closed (FIN sent)`);
     }
+    if (bytes.byteLength === 0) {
+      // Nothing to send, but a first write is still the caller saying "this
+      // stream exists": announce it (a no-op once anything has been sent).
+      this.announce();
+      return;
+    }
     this.#sendState = SEND_STATE.SEND;
 
     let offset = 0;

package/src/server/index.d.ts

@@ -200,6 +200,55 @@ export interface WshServerRelayOptions {
   connectTimeoutMs?: number;
 }
 
+export interface WshServerWebTransportOptions {
+  /** UDP port for HTTP/3 (default 0 = pick a free one; read it back from `webTransport()`). */
+  port?: number;
+  /** Bind address (default: the server's `host`). */
+  host?: string;
+  /** URL path sessions are accepted on (default `/wsh`). */
+  path?: string;
+  /** PEM certificate chain. With `privKey`. Not together with `selfSigned`. */
+  cert?: string;
+  /** PEM private key for `cert`. */
+  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 }`.
+   */
+  selfSigned?: boolean | { hosts?: string[]; validityDays?: number };
+  /** QUIC stateless-reset secret (default: random). */
+  secret?: string;
+}
+
+export interface WshServerWebTransport {
+  port: number;
+  host: string;
+  path: string;
+  /** `https://host:port/path`, what a client connects to. */
+  url: string;
+  /** SHA-256 of the DER certificate, when `selfSigned` made it; `null` for a certificate you supplied. */
+  certificateHash: Uint8Array | null;
+  certificateHashHex: string | null;
+  /** When the `selfSigned` certificate expires; `null` otherwise. */
+  notAfter: Date | null;
+}
+
+export interface WshSelfSignedCertificate {
+  /** PEM certificate. */
+  cert: string;
+  /** PEM (PKCS#8) private key. */
+  privKey: string;
+  /** SHA-256 of the DER certificate: the value to pin. */
+  hash: Uint8Array;
+  hashHex: string;
+  notBefore: Date;
+  notAfter: Date;
+}
+
+/** A dependency-free self-signed ECDSA P-256 certificate fit for WebTransport's `serverCertificateHashes`. */
+export function generateSelfSignedCertificate(opts?: { hosts?: string[]; validityDays?: number; now?: Date }): WshSelfSignedCertificate;
+
 export interface WshServerOptions {
   /** Bind address (default `127.0.0.1`). */
   host?: string;
@@ -233,6 +282,12 @@ export interface WshServerOptions {
    * Default deny -- give both `canRegister` and `canConnect`. Off by default.
    */
   relay?: WshServerRelayOptions;
+  /**
+   * Also listen for WebTransport (HTTP/3 over UDP) clients -- the same auth, exec, pty, fs, mcp, sessions and relay as the
+   * WebSocket listener, with real independent streams. Needs the optional peers `@fails-components/webtransport` and
+   * `@fails-components/webtransport-transport-http3-quiche`, imported only when this is set. Off by default.
+   */
+  webTransport?: WshServerWebTransportOptions;
   /** Serve MCP tools (`McpDiscover` / `McpCall`) and advertise `mcp-call-id`. Off by default. */
   mcp?: WshServerMcpOptions;
   /** How long exec output waits for a client that has not yet opened its data stream (default 3000). */
@@ -252,6 +307,8 @@ export interface WshServer {
   close(): Promise<void>;
   /** The bound address, or `null` when not listening. */
   address(): WshServerAddress | null;
+  /** The WebTransport listener; `null` when not configured or before `listen()` resolves. */
+  webTransport(): WshServerWebTransport | 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

@@ -13,10 +13,12 @@ import { loadHostKey } from './host-key.mjs';
 import { buildBackends } from './backends.mjs';
 import { SessionRegistry } from './sessions.mjs';
 import { RelayHub } from './relay.mjs';
+import { startWebTransport } from './webtransport.mjs';
 import { createConnectionFactory, STREAM_ANNOUNCE } from './connection.mjs';
 
 export { parseAuthorizedKeys, STREAM_ANNOUNCE };
 export { createReverseHost } from './reverse-host.mjs';
+export { generateSelfSignedCertificate } from './self-signed.mjs';
 
 /**
  * @param {object} [options]
@@ -30,6 +32,11 @@ export { createReverseHost } from './reverse-host.mjs';
  * @param {{ tools?: object[] | object, client?: object, authorize?: Function, maxConcurrent?: number, timeoutMs?: number }} [options.mcp]
  *   MCP tools served over `McpDiscover` / `McpCall`: `tools` (`{ name, description, inputSchema, call(args, { user, signal }) }`),
  *   and/or `client` (an `@modelcontextprotocol/sdk` Client to proxy). Off unless given.
+ * @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
+ *   `@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
  *   (`ReverseList` / `ReverseConnect`) and traffic is carried between them as `RelayForward`. Default deny:
@@ -48,7 +55,7 @@ export { createReverseHost } from './reverse-host.mjs';
  * @returns {{ listen(): Promise<{address: string, port: number}>, close(): Promise<void>, address(): ({address: string, port: number} | null) }}
  */
 export function createWshServer({
-  host = '127.0.0.1', port = 0, auth, exec, pty, fs, hostKey, mcp, sessions, sessionSecret, relay, bindTimeoutMs = 3000, onLog = () => {},
+  host = '127.0.0.1', port = 0, auth, exec, pty, fs, hostKey, mcp, sessions, sessionSecret, relay, webTransport, bindTimeoutMs = 3000, onLog = () => {},
 } = {}) {
   let wss = null;
   let bound = null;
@@ -64,6 +71,7 @@ export function createWshServer({
   let host_ = null;
   let registry = null;
   let hub = null;
+  let wt = null;
   const sessionOptions = sessions ? (sessions === true ? {} : sessions) : null;
 
   return {
@@ -113,6 +121,14 @@ export function createWshServer({
       });
       const a = wss.address();
       bound = { address: a.address, port: a.port };
+      if (webTransport) {
+        try {
+          wt = await startWebTransport({ options: webTransport, host, attach, log: onLog });
+        } catch (err) {
+          await this.close();
+          throw err;
+        }
+      }
       return bound;
     },
 
@@ -122,6 +138,8 @@ export function createWshServer({
       wss = null;
       bound = null;
       for (const client of server.clients) client.terminate();
+      await wt?.close();
+      wt = null;
       await new Promise((resolve) => server.close(resolve));
       registry?.closeAll();
       registry = null;
@@ -133,6 +151,18 @@ export function createWshServer({
       return bound;
     },
 
+    /**
+     * The WebTransport listener, or `null` (not configured, or `listen()` has not resolved). `certificateHash` is
+     * the SHA-256 of a `selfSigned` certificate, for the client's `serverCertificateHashes`; `null` for your own.
+     */
+    webTransport() {
+      if (!wt) return null;
+      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,
+      };
+    },
+
     /** 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

@@ -0,0 +1,121 @@
+/**
+ * A short-lived self-signed certificate for WebTransport's
+ * `serverCertificateHashes` pinning, with no dependency: the X.509 structure
+ * is small enough to assemble as DER by hand, and `node:crypto` signs it.
+ *
+ * The web platform's rules for a pinned certificate (what a browser enforces):
+ * an ECDSA P-256 key, a validity period of at most 14 days, and the page pins
+ * the SHA-256 of the DER certificate. Nothing else about it is checked (no
+ * chain, and the name is not matched), but the subject alternative names are
+ * filled in anyway so the same certificate also works for a client that does.
+ */
+
+import { createHash, generateKeyPairSync, randomBytes, sign } from 'node:crypto';
+import net from 'node:net';
+
+/** What a browser allows for `serverCertificateHashes`. */
+export const MAX_PINNED_CERT_DAYS = 14;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+const OID = {
+  ecdsaWithSha256: '2a8648ce3d040302',
+  commonName: '550403',
+  subjectAltName: '551d11',
+  extKeyUsage: '551d25',
+  serverAuth: '2b06010505070301',
+  keyUsage: '551d0f',
+};
+
+// ── DER ──────────────────────────────────────────────────────────────
+
+const concat = (...parts) => Buffer.concat(parts.map((p) => (Buffer.isBuffer(p) ? p : Buffer.from(p))));
+function der(tag, ...content) {
+  const body = concat(...content);
+  const n = body.length;
+  const len = n < 0x80 ? Buffer.from([n]) : n < 0x100 ? Buffer.from([0x81, n]) : Buffer.from([0x82, n >> 8, n & 0xff]);
+  return concat(Buffer.from([tag]), len, body);
+}
+const seq = (...c) => der(0x30, ...c);
+const set = (...c) => der(0x31, ...c);
+const oid = (hex) => der(0x06, Buffer.from(hex, 'hex'));
+const utf8 = (s) => der(0x0c, Buffer.from(s, 'utf8'));
+const octets = (b) => der(0x04, b);
+const bitString = (b) => der(0x03, Buffer.from([0]), b);
+/** Positive INTEGER from big-endian bytes. */
+function integer(bytes) {
+  let b = Buffer.from(bytes);
+  while (b.length > 1 && b[0] === 0) b = b.subarray(1);
+  if (b[0] & 0x80) b = concat(Buffer.from([0]), b);
+  return der(0x02, b);
+}
+function utcTime(date) {
+  const p = (n) => String(n).padStart(2, '0');
+  return der(0x17, Buffer.from(`${p(date.getUTCFullYear() % 100)}${p(date.getUTCMonth() + 1)}${p(date.getUTCDate())}${p(date.getUTCHours())}${p(date.getUTCMinutes())}${p(date.getUTCSeconds())}Z`, 'ascii'));
+}
+
+function ipBytes(addr) {
+  if (net.isIPv4(addr)) return Buffer.from(addr.split('.').map(Number));
+  // IPv6, possibly with "::" compression
+  const [head, tail = ''] = addr.split('::');
+  const h = head ? head.split(':') : [];
+  const t = tail ? tail.split(':') : [];
+  const groups = [...h, ...Array(8 - h.length - t.length).fill('0'), ...t];
+  return Buffer.from(groups.flatMap((g) => { const v = parseInt(g || '0', 16); return [v >> 8, v & 0xff]; }));
+}
+
+function pem(label, derBytes) {
+  const b64 = derBytes.toString('base64').match(/.{1,64}/g).join('\n');
+  return `-----BEGIN ${label}-----\n${b64}\n-----END ${label}-----\n`;
+}
+
+/**
+ * @param {object} [opts]
+ * @param {string[]} [opts.hosts=['localhost', '127.0.0.1', '::1']] - DNS names and IP addresses for the SAN.
+ * @param {number} [opts.validityDays=13] - At most 14 (a browser refuses a pinned certificate valid for longer).
+ * @param {Date} [opts.now]
+ * @returns {{ cert: string, privKey: string, hash: Uint8Array, hashHex: string, notBefore: Date, notAfter: Date }}
+ *   `cert` / `privKey` are PEM; `hash` is the SHA-256 of the DER certificate, the value to pin.
+ */
+export function generateSelfSignedCertificate({ hosts = ['localhost', '127.0.0.1', '::1'], validityDays = 13, now = new Date() } = {}) {
+  if (!(validityDays > 0) || validityDays > MAX_PINNED_CERT_DAYS) {
+    throw new RangeError(`selfSigned: validityDays must be in (0, ${MAX_PINNED_CERT_DAYS}] -- browsers refuse a pinned certificate valid for longer`);
+  }
+  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);
+  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 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')))));
+  const extensions = der(0xa3, seq(
+    seq(oid(OID.keyUsage), der(0x01, Buffer.from([0xff])), octets(bitString(Buffer.from([0x80])))), // digitalSignature
+    seq(oid(OID.extKeyUsage), octets(seq(oid(OID.serverAuth)))),
+    seq(oid(OID.subjectAltName), octets(san)),
+  ));
+  const serial = randomBytes(16);
+  serial[0] &= 0x7f;
+  serial[0] |= 0x01;
+
+  const tbs = seq(
+    der(0xa0, integer([2])),                              // v3
+    integer(serial),
+    seq(oid(OID.ecdsaWithSha256)),
+    name,
+    seq(utcTime(notBefore), utcTime(notAfter)),
+    name,
+    publicKey.export({ type: 'spki', format: 'der' }),
+    extensions,
+  );
+  const signature = sign('sha256', tbs, privateKey);       // DER-encoded ECDSA-Sig-Value
+  const certDer = seq(tbs, seq(oid(OID.ecdsaWithSha256)), bitString(signature));
+  const hash = new Uint8Array(createHash('sha256').update(certDer).digest());
+  return {
+    cert: pem('CERTIFICATE', certDer),
+    privKey: privateKey.export({ type: 'pkcs8', format: 'pem' }),
+    hash,
+    hashHex: Buffer.from(hash).toString('hex'),
+    notBefore,
+    notAfter,
+  };
+}

package/src/server/webtransport.mjs

@@ -0,0 +1,188 @@
+/**
+ * WebTransport listener for `@johnhenry/wsh/server` (`createWshServer({ webTransport })`).
+ *
+ * QUIC already multiplexes, so the QMux layer the WebSocket path needs is not
+ * used. A session's FIRST bidirectional stream is the control stream (the
+ * client's `WebTransportTransport` opens it first): length-prefixed CBOR
+ * frames, exactly what `frameEncode` / `FrameDecoder` speak. Every later
+ * bidirectional stream the client opens is a data stream, bound to the next
+ * exec channel in `OpenOk` order like a QMux one.
+ *
+ * Streams a client creates are visible to the host the moment they are
+ * created (HTTP/3 sends the stream's WebTransport header with it), so the
+ * host's `stream-announce` feature holds here as it does over QMux: the
+ * client writes no primer.
+ *
+ * `@fails-components/webtransport` (and its native HTTP/3 transport package)
+ * are optional peers, imported only when `webTransport` is given.
+ */
+
+import { randomBytes } from 'node:crypto';
+import { FrameDecoder, frameEncode } from '../cbor.mjs';
+import { generateSelfSignedCertificate } from './self-signed.mjs';
+
+const DEFAULT_PATH = '/wsh';
+
+/** What a QMux stream looks like to the connection code, over a WebTransport bidirectional stream. */
+function adaptStream({ readable, writable }, onGone) {
+  const writer = writable.getWriter();
+  const reader = readable.getReader();
+  const stream = {
+    onData: null,
+    onEnd: null,
+    onReset: null,
+    write: (bytes) => writer.write(bytes),
+    close: async () => { try { await writer.close(); } catch { /* peer gone or already closed */ } },
+    /** Start delivering: after the consumer has had the chance to set its handlers. */
+    start() {
+      (async () => {
+        try {
+          for (;;) {
+            const { done, value } = await reader.read();
+            if (done) { stream.onEnd?.(); return; }
+            stream.onData?.(value);
+          }
+        } catch {
+          stream.onReset?.();
+        } finally {
+          onGone?.();
+        }
+      })();
+    },
+  };
+  return stream;
+}
+
+/**
+ * @param {object} opts
+ * @param {object} opts.options - `createWshServer`'s `webTransport` option
+ * @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> }>}
+ */
+export async function startWebTransport({ options, host, attach, log }) {
+  const { port = 0, path = DEFAULT_PATH, selfSigned = false } = options;
+  let { cert, privKey } = options;
+  let generated = 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);
+  }
+  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 "/"');
+
+  let wtLib;
+  try {
+    wtLib = await import('@fails-components/webtransport');
+    await wtLib.quicheLoaded;
+  } catch (err) {
+    throw new Error(
+      'WebTransport needs the optional packages "@fails-components/webtransport" and '
+      + '"@fails-components/webtransport-transport-http3-quiche": npm install @fails-components/webtransport @fails-components/webtransport-transport-http3-quiche',
+      { cause: err },
+    );
+  }
+
+  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 live = new Set();
+  let closing = false;
+
+  async function serve(session) {
+    let conn = null;
+    let closed = false;
+    const end = () => { if (!closed) { closed = true; live.delete(session); conn?.close(); } };
+    live.add(session);
+    session.closed.then(end, end);
+    try {
+      await session.ready;
+    } catch { end(); return; }
+
+    let controlWriter = null;
+    const decoder = new FrameDecoder();
+    conn = attach({
+      sendMessage: (msg) => (controlWriter ? controlWriter.write(frameEncode(msg)) : undefined),
+      remote: { address: session.peerAddress, headers: session.header ?? {} },
+      closeTransport: () => { try { session.close(); } catch { /* already closed */ } },
+    });
+
+    const incoming = session.incomingBidirectionalStreams.getReader();
+    let first = true;
+    try {
+      for (;;) {
+        const { done, value: bidi } = await incoming.read();
+        if (done) break;
+        if (first) {
+          first = false;
+          controlWriter = bidi.writable.getWriter();
+          const reader = bidi.readable.getReader();
+          (async () => {
+            try {
+              for (;;) {
+                const { done: fin, value } = await reader.read();
+                if (fin) break;
+                let msgs;
+                try { msgs = decoder.feed(value); } catch (e) { log(`webtransport frame decode error: ${e.message}`); break; }
+                for (const m of msgs) conn.receiveMessage(m);
+              }
+            } catch { /* session went away */ }
+            end();
+          })();
+        } else {
+          const s = adaptStream(bidi);
+          conn.bindStream(s);
+          s.start();
+        }
+      }
+    } catch { /* session closed under us */ }
+    end();
+  }
+
+  (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 */ }
+  })();
+
+  const bound = {
+    port: addr.port,
+    host: addr.host,
+    path,
+    certificateHash: generated?.hash ?? null,
+    certificateHashHex: generated?.hashHex ?? null,
+    notAfter: generated?.notAfter ?? null,
+    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 */ }
+    },
+  };
+  log(`webtransport listening on https://${addr.host}:${addr.port}${path}`
+    + (generated ? ` (self-signed, sha-256 ${generated.hashHex}, until ${generated.notAfter.toISOString()})` : ''));
+  return bound;
+}

package/src/transport.mjs

@@ -493,6 +493,11 @@ export class WebTransportTransport extends WshTransport {
     const wt = wtOptions ? new WebTransport(url, wtOptions) : new WebTransport(url);
     this.#wt = wt;
 
+    // A session that never becomes ready rejects `closed` as well as `ready`. Nothing
+    // observes `closed` until #monitorClosed (below, after `ready`), so the second
+    // rejection would surface as an unhandled one -- fatal in Node.
+    wt.closed?.catch?.(() => {});
+
     // Wait for the connection to be ready.
     await wt.ready;