@johnhenry/wsh 0.21.0 → 0.23.0

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,8 +185,128 @@ 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 (each has a tracking issue): WebTransport, relay/reverse
-mode.
+### 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
+
+A host that cannot accept connections (behind NAT, or a browser tab) dials *out*
+and registers; an operator reaches it through a relay. `@johnhenry/wsh/server`
+is both ends:
+
+```js
+// The relay -- anyone who can reach it and authenticate; nothing is permitted by default.
+createWshServer({
+  auth: { authorizedKeys },
+  relay: {
+    canRegister: (who, record) => who.username === 'build-box',          // who may be a peer
+    canConnect: (from, to) => from.username === 'alice',                  // who may list and reach which peer
+  },
+});
+
+// The peer, on the machine behind the NAT: same backends as createWshServer.
+const host = createReverseHost({
+  url: 'wss://relay.example/', username: 'build-box', keyPair,
+  exec: true, fs: { root: '/srv/share' }, mcp: { tools },
+  accept: ({ fingerprint, username }) => fingerprint === aliceFingerprint, // default: nobody
+});
+await host.start();                    // host.fingerprint is what operators connect to
+
+// The operator: stock client.
+const peers = await client.listPeers();                       // each entry's signed record verified client-side
+await client.reverseConnect(peers[0].fingerprint);            // ReverseAccept trusts the peer for RelayForward
+const s = await client.openSession({ type: 'exec', command: 'echo hello' });
+```
+
+- **Default deny, twice.** The relay admits no peer (`canRegister`) and lets no
+  one connect (`canConnect`) unless you say so, and the peer refuses every
+  operator unless `accept` says otherwise -- the client's `trustRelayPeer()` is
+  the third gate. A peer an operator may not connect to is not listed and is
+  indistinguishable from an absent one (`ReverseReject: no such peer`).
+  Relay roles need a **key** login (`from_fingerprint` is a key fingerprint);
+  password logins can still use the relay server as an ordinary host.
+- **Peer table.** Keyed by fingerprint. `ReverseRegister` is checked against the
+  connection's own authenticated key (`public_key` must hash to it) and its
+  self-signed record (`buildPeerRecordTranscript` / `signPeerRecord`) is verified
+  here, not trusted; `ReversePeers` forwards the signed fields so operators verify
+  them again themselves. The record `seq` must increase per fingerprint -- and is
+  remembered across reconnects (the last 4096 fingerprints), so an old record
+  cannot regress a peer. Failures answer an `Error` (the stock client surfaces it
+  through `onError`); there is no acknowledgement of success on the wire, so poll
+  `listPeers()` (or `server.peerFingerprints()`) if you need to know it landed.
+- **Bridge.** `ReverseConnect` is forwarded to the peer with `from_fingerprint`
+  (and `username`) set from the operator's authenticated login, whatever the
+  client wrote; the peer's `ReverseAccept`/`Reject` goes back, attributed to the
+  peer that sent it, and an accept pairs the two connections. From then on every
+  spec-`forwardable` message from either end is wrapped as `RelayForward {
+  from_fingerprint, inner }` with `from_fingerprint` the sender's authenticated
+  key. A `RelayForward` a client writes itself is unwrapped, its inner type
+  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.
+- **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.
 
 ### Sessions: attach / resume / detach
 
@@ -595,7 +715,7 @@ than left to be found.
 | Host identity / TOFU | `WshKnownHosts` (localStorage-backed) | `KnownHosts`/`HostStatus` (`~/.wsh/known_hosts`-backed) | **Record unified, policy is not** (wsh #59): both pin `ServerHello.host_fingerprint`, which `@johnhenry/wsh/server` populates (with a proof of possession, [Host key](#host-key-fingerprint--tofu)) but no Rust `wsh-server` release does yet (see [Security](#security-model)). *When* to trust, prompt, or persist is deliberately left per-implementation -- a browser and a CLI have different UX for "first time seeing this host" |
 | 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` replays its whole ring and leaves them unset |
-| Reverse-connect / relay peer | `connectReverse()`, `trustRelayPeer()` | `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 |
+| 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 |
 | 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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnhenry/wsh",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "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/server/backends.mjs

@@ -0,0 +1,32 @@
+/**
+ * What a host can do for the client on the other end: shared by
+ * `createWshServer` (clients that connect to it) and `createReverseHost`
+ * (operators bridged to it by a relay), so the two cannot drift.
+ */
+
+import { spawnRunner } from './exec.mjs';
+import { normalizePty } from './pty.mjs';
+import { createFileAccess } from './fs.mjs';
+import { createMcpHost } from './mcp.mjs';
+
+/**
+ * @param {{ exec?: true | object | Function, pty?: object, fs?: object, mcp?: object }} options
+ * @returns {{ execRunner: Function | null, execOptions: object, pty: object | null, files: object | null, mcp: object | null }}
+ */
+export function buildBackends({ exec, pty, fs, mcp } = {}) {
+  let execRunner = null;
+  let execOptions = {};
+  if (typeof exec === 'function') {
+    execRunner = exec;
+  } else if (exec) {
+    execOptions = exec === true ? {} : exec;
+    execRunner = typeof execOptions.run === 'function' ? execOptions.run : spawnRunner(execOptions);
+  }
+  return {
+    execRunner,
+    execOptions,
+    pty: pty ? normalizePty(pty) : null,
+    files: fs ? createFileAccess(fs) : null,
+    mcp: mcp ? createMcpHost(mcp) : null,
+  };
+}

package/src/server/connection.mjs

@@ -19,7 +19,7 @@ import { FrameDecoder, frameEncode } from '../cbor.mjs';
 import {
   MSG, serverHello, challenge, authOk, authFail, openOk, openFail, sessionData,
   exit as exitMsg, close as closeMsg, pong, fileResult, fileChunk, mcpTools, mcpResult,
-  presence as presenceMsg, error as errorMsg, sessionList, detachOk, detachFail,
+  presence as presenceMsg, error as errorMsg, sessionList, detachOk, detachFail, reversePeers, reverseReject,
 } from '../messages.gen.mjs';
 import {
   generateNonce, verifyChallenge, fingerprint, importPublicKeyRaw,
@@ -52,6 +52,7 @@ const toBytes = (d) => (typeof d === 'string' ? enc.encode(d) : d);
  * @param {{ pubkey: boolean, password: Function | null }} cfg.methods - which auth methods are on
  * @param {object | null} cfg.hostKey - from loadHostKey
  * @param {object | null} cfg.mcp - from createMcpHost
+ * @param {object | null} cfg.relay - a RelayHub (see relay.mjs); null = not a relay
  * @param {object | null} cfg.sessions - a SessionRegistry (see sessions.mjs); null = sessions die with their connection
  * @param {{ limiter: object, key: Function, failureDelayMs: number } | null} cfg.rateLimit - password throttle
  * @param {number} cfg.bindTimeoutMs - how long exec output waits for the data stream
@@ -60,12 +61,20 @@ const toBytes = (d) => (typeof d === 'string' ? enc.encode(d) : d);
 export function createConnectionFactory(cfg) {
   let counter = 0;
 
-  return function attach({ send: sendBytes, remote = {} }) {
+  /**
+   * Attach one connection. Two shapes:
+   *  - bytes (the normal one): `{ send(bytes), remote, closeTransport() }` -> `{ receive(bytes), close() }`, speaking QMux.
+   *  - messages: `{ sendMessage(msg), authenticated, dataStreams }` -> `{ receiveMessage(msg), bindStream(s), close() }`,
+   *    for a transport that already frames messages itself (a relay bridge, WebTransport). `authenticated`
+   *    (`{ username, fingerprint }`) skips the handshake for a peer something else has already authenticated;
+   *    `dataStreams: false` means there are no client-opened streams to bind, so exec output rides SessionData.
+   */
+  return function attach({ send: sendBytes, sendMessage = null, remote = {}, authenticated = null, dataStreams = true, closeTransport = null }) {
     const cid = ++counter;
     const log = (m) => cfg.log(`[conn ${cid}] ${m}`);
     const state = {
-      sessionId: randomUUID(), nonce: null, username: null, authed: false,
-      closed: false, nextChannel: 0, fingerprint: null,
+      sessionId: randomUUID(), nonce: null, username: authenticated?.username ?? null, authed: !!authenticated,
+      closed: false, nextChannel: 0, fingerprint: authenticated?.fingerprint ?? null,
     };
     /** @type {Map<number, any>} */
     const channels = new Map();
@@ -79,11 +88,16 @@ export function createConnectionFactory(cfg) {
     const pendingSends = [];
     let control = null;
     let chain = Promise.resolve();
+    /** This connection as the relay hub sees it (created on first need). */
+    let relayHandle = null;
 
-    const qmux = new QMuxConnection({ isClient: false, send: (b) => { if (!state.closed) sendBytes(b); } });
+    const qmux = sendMessage ? null : new QMuxConnection({ isClient: false, send: (b) => { if (!state.closed) sendBytes(b); } });
 
     const send = (msg) => {
       if (state.closed) return Promise.resolve();
+      if (sendMessage) {
+        try { return Promise.resolve(sendMessage(msg)).catch(() => {}); } catch { return Promise.resolve(); }
+      }
       const bytes = frameEncode(msg);
       if (control) return control.write(bytes).catch(() => {});
       pendingSends.push(bytes);
@@ -101,7 +115,10 @@ export function createConnectionFactory(cfg) {
       mcpCalls.clear();
       for (const w of fileWrites.values()) clearTimeout(w.timer);
       fileWrites.clear();
-      try { qmux.destroy(new Error(why)); } catch { /* already gone */ }
+      try { qmux?.destroy(new Error(why)); } catch { /* already gone */ }
+      // The host ending the connection (a relay bridge ending, a refused login) must end the socket too.
+      try { closeTransport?.(); } catch { /* already gone */ }
+      relayHandle && cfg.relay?.drop(relayHandle);
       log(`closed (${why})`);
     }
 
@@ -110,6 +127,7 @@ export function createConnectionFactory(cfg) {
     // first, then the connection is torn down.
     const shutdownAfterQueue = (why) => { chain = chain.then(() => shutdown(why)); };
 
+    if (qmux) {
     qmux.onError = (e) => log(`qmux error: ${e.message}`);
     qmux.onClose = () => shutdownAfterQueue('peer sent CONNECTION_CLOSE');
     qmux.onStreamOpen = (s) => {
@@ -125,6 +143,7 @@ export function createConnectionFactory(cfg) {
       for (const b of pendingSends.splice(0)) s.write(b).catch(() => {});
     };
     qmux.sendHandshake();
+    }
 
     function bindDataStream(s) {
       const channelId = pendingStreams.shift();
@@ -138,6 +157,7 @@ export function createConnectionFactory(cfg) {
     async function handle(m) {
       if (state.closed) return;
       if (!state.authed) return handleAuth(m);
+      if (await handleRelay(m)) return;
       switch (m.type) {
         case MSG.PING: return send(pong({ id: m.id }));
         case MSG.OPEN: return handleOpen(m);
@@ -255,6 +275,56 @@ export function createConnectionFactory(cfg) {
       log(`authenticated ${state.username} (password)`);
     }
 
+    // ── Relay (createWshServer({ relay })) ────────────────────────────
+
+    const RELAY_TYPES = new Set([MSG.REVERSE_REGISTER, MSG.REVERSE_LIST, MSG.REVERSE_CONNECT, MSG.REVERSE_ACCEPT, MSG.REVERSE_REJECT, MSG.RELAY_FORWARD]);
+
+    function hubHandle() {
+      relayHandle ??= {
+        send, fingerprint: state.fingerprint, username: state.username,
+        close: () => shutdownAfterQueue('relay bridge ended'),
+      };
+      return relayHandle;
+    }
+
+    /** @returns {Promise<boolean>} true when the message was the relay's and has been dealt with */
+    async function handleRelay(m) {
+      const hub = cfg.relay;
+      if (!hub) {
+        // Not a relay: answer instead of leaving the client to time out.
+        if (m.type === MSG.REVERSE_LIST) { await send(reversePeers({ peers: [] })); return true; }
+        if (m.type === MSG.REVERSE_CONNECT) { await send(reverseReject({ targetFingerprint: String(m.target_fingerprint ?? ''), username: '', reason: 'relay is not enabled on this server' })); return true; }
+        if (m.type === MSG.REVERSE_REGISTER) { await send(errorMsg({ code: 3, message: 'relay is not enabled on this server' })); return true; }
+        return false;
+      }
+      if (!RELAY_TYPES.has(m.type)) {
+        // Anything else a bridged connection sends that may cross a bridge, does.
+        if (!relayHandle) return false;
+        hub.touch(relayHandle);
+        return hub.forward(relayHandle, m);
+      }
+      // Relay roles are keyed by an authenticated key: from_fingerprint means nothing for a password login.
+      if (!state.fingerprint) {
+        await send(errorMsg({ code: 2, message: 'relay operations need a key login' }));
+        return true;
+      }
+      const h = hubHandle();
+      switch (m.type) {
+        case MSG.REVERSE_REGISTER: {
+          const reason = await hub.register(h, m, { username: state.username, fingerprint: state.fingerprint });
+          if (reason) {
+            log(`ReverseRegister refused: ${reason}`);
+            await send(errorMsg({ code: 2, message: `registration refused: ${reason}` }));
+          }
+          return true;
+        }
+        case MSG.REVERSE_LIST: await send(await hub.list({ username: state.username, fingerprint: state.fingerprint })); return true;
+        case MSG.REVERSE_CONNECT: await hub.connect(h, m); return true;
+        case MSG.REVERSE_ACCEPT: case MSG.REVERSE_REJECT: hub.answer(h, m); return true;
+        default: hub.forward(h, m); return true; // a RelayForward the client wrote itself
+      }
+    }
+
     // ── MCP ───────────────────────────────────────────────────────────
 
     const principal = () => ({ username: state.username, fingerprint: state.fingerprint });
@@ -486,13 +556,19 @@ export function createConnectionFactory(cfg) {
         },
       };
       channels.set(channelId, ch);
-      pendingStreams.push(channelId);
+      if (dataStreams) pendingStreams.push(channelId);
+      // No client-opened streams on this connection (a relay bridge): stdin arrives as SessionData.
+      else ch.input = (d) => { for (const cb of inputCbs) cb(d); };
 
       let timer = null;
       if (cfg.execOptions.timeoutMs > 0) timer = setTimeout(() => abort.abort(), cfg.execOptions.timeoutMs);
 
       // Output to the opening connection's data stream (held until the client has opened it).
       const toStream = (bytes) => {
+        if (!dataStreams) {
+          wq = wq.then(() => send(sessionData({ channelId, data: bytes })));
+          return wq;
+        }
         if (!stream) { buffered.push(bytes); return Promise.resolve(); }
         const s = stream;
         wq = wq.then(() => s.write(bytes).catch(() => {}));
@@ -502,8 +578,8 @@ export function createConnectionFactory(cfg) {
       // announce support waits for the first byte): give it a bounded chance rather than
       // dropping the output or hanging forever.
       const closeStream = async (code) => {
-        if (!stream) await Promise.race([new Promise((r) => boundWaiters.push(r)), new Promise((r) => setTimeout(r, cfg.bindTimeoutMs))]);
-        if (!stream) log(`exec channel ${channelId}: data stream never appeared; output dropped`);
+        if (dataStreams && !stream) await Promise.race([new Promise((r) => boundWaiters.push(r)), new Promise((r) => setTimeout(r, cfg.bindTimeoutMs))]);
+        if (dataStreams && !stream) log(`exec channel ${channelId}: data stream never appeared; output dropped`);
         await wq;
         try { await stream?.close(); } catch { /* peer gone */ }
         await finishChannel(channelId, Number.isInteger(code) ? code : 0);
@@ -552,7 +628,7 @@ export function createConnectionFactory(cfg) {
       };
 
       await send(openOk({
-        channelId, dataMode: 'stream', capabilities: ['signal'],
+        channelId, dataMode: dataStreams ? 'stream' : 'virtual', capabilities: ['signal'],
         sessionId: hosted?.id ?? randomUUID(), token: hosted?.token ?? randomBytes(16),
       }));
       log(`exec channel ${channelId}: ${command}`);
@@ -740,7 +816,9 @@ export function createConnectionFactory(cfg) {
     }
 
     return {
-      receive(bytes) { if (!state.closed) qmux.receiveBytes(bytes); },
+      receive(bytes) { if (!state.closed) qmux?.receiveBytes(bytes); },
+      receiveMessage(msg) { if (!state.closed) chain = chain.then(() => handle(msg)).catch((e) => log(`handler error: ${e.message}`)); },
+      bindStream: bindDataStream,
       close() { shutdownAfterQueue('transport closed'); },
     };
   };

package/src/server/index.d.ts

@@ -169,6 +169,86 @@ export interface WshServerSessionsOptions {
   sessionSecret?: string | Uint8Array;
 }
 
+/** A peer as the relay's policy callbacks see it. */
+export interface WshRelayPeer {
+  /** Hex SHA-256 of the peer's key. */
+  fingerprint: string;
+  username: string;
+  capabilities: string[];
+}
+
+export interface WshServerRelayOptions {
+  /**
+   * May this authenticated connection register as a peer? `who` is the connection; `record` what it asks to
+   * advertise. Default: no (a relay with no policy admits nobody).
+   */
+  canRegister?: (
+    who: { username: string; fingerprint: string },
+    record: { username: string; capabilities: string[]; peerType: string; shellBackend: string },
+  ) => boolean | Promise<boolean>;
+  /**
+   * May `from` list and connect to `to`? A peer `from` may not connect to is neither listed nor distinguishable
+   * from an absent one. Default: no.
+   */
+  canConnect?: (
+    from: { username: string; fingerprint: string },
+    to: WshRelayPeer,
+  ) => boolean | Promise<boolean>;
+  /** Registered peers at once (default 1024). */
+  maxPeers?: number;
+  /** How long a `ReverseConnect` waits for its peer to answer before the operator is rejected (default 8000). */
+  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;
@@ -196,6 +276,18 @@ export interface WshServerOptions {
   sessions?: true | WshServerSessionsOptions;
   /** Alias for `sessions.sessionSecret`. */
   sessionSecret?: string | Uint8Array;
+  /**
+   * Act as a relay: peers (`createReverseHost`, or any client's `connectReverse()`) register a signed record,
+   * operators list and `reverseConnect()` to them, and traffic is carried between the two as `RelayForward`.
+   * 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). */
@@ -215,6 +307,10 @@ 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`. */
   hostKey(): WshServerHostKey | null;
 }
@@ -226,3 +322,40 @@ export function parseAuthorizedKeys(text: string): Uint8Array[];
 
 /** ServerHello feature: the host discovers client-opened exec data streams itself (no primer byte). */
 export const STREAM_ANNOUNCE: 'stream-announce';
+
+export interface WshReverseHostOptions {
+  /** The relay to register with (`ws://` / `wss://`). */
+  url: string;
+  username: string;
+  /** This host's identity; its fingerprint is what operators connect to. */
+  keyPair: CryptoKeyPair;
+  /** Who may be bridged to this host. Default: nobody. */
+  accept?: (operator: { fingerprint: string; username: string }) => boolean | Promise<boolean>;
+  exec?: true | WshServerExecOptions | WshExecRunner;
+  pty?: WshServerPtyOptions;
+  fs?: WshServerFsOptions;
+  mcp?: WshServerMcpOptions;
+  /** Dial again, with backoff, after the relay connection ends -- which a relay does when a bridge does (default true). */
+  reconnect?: boolean;
+  /** Extra options for the relay connection (`expectHostKey`, `knownHosts`, `trustOnFirstUse`, ...). */
+  connect?: Record<string, unknown>;
+  peerType?: string;
+  onLog?: (line: string) => void;
+}
+
+export interface WshReverseHost {
+  /** Dial the relay and register (rejects if the first attempt fails). Registration is not acknowledged on the wire. */
+  start(): Promise<{ fingerprint: string }>;
+  /** Leave the relay and end any bridged session. */
+  close(): Promise<void>;
+  /** What operators connect to; `null` before `start()`. */
+  readonly fingerprint: string | null;
+  /** Is the relay connection up right now? */
+  readonly connected: boolean;
+}
+
+/**
+ * A host that dials OUT to a relay and serves the operator it bridges to it, with the same exec / pty / fs / mcp
+ * backends `createWshServer` serves direct clients with. For a machine that cannot accept connections.
+ */
+export function createReverseHost(options: WshReverseHostOptions): WshReverseHost;