@johnhenry/wsh 0.21.0 → 0.22.0

package/README.md

@@ -185,8 +185,85 @@ 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.
+Not implemented (tracking issue): WebTransport.
+
+### 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 +672,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.22.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/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,37 @@ 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 WshServerOptions {
   /** Bind address (default `127.0.0.1`). */
   host?: string;
@@ -196,6 +227,12 @@ 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;
   /** 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 +252,8 @@ export interface WshServer {
   close(): Promise<void>;
   /** The bound address, or `null` when not listening. */
   address(): WshServerAddress | 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 +265,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;

package/src/server/index.mjs

@@ -10,14 +10,13 @@
 
 import { buildAuthorizer, parseAuthorizedKeys, authMethods, FailureLimiter } from './auth.mjs';
 import { loadHostKey } from './host-key.mjs';
-import { spawnRunner } from './exec.mjs';
-import { normalizePty } from './pty.mjs';
-import { createFileAccess } from './fs.mjs';
-import { createMcpHost } from './mcp.mjs';
+import { buildBackends } from './backends.mjs';
 import { SessionRegistry } from './sessions.mjs';
+import { RelayHub } from './relay.mjs';
 import { createConnectionFactory, STREAM_ANNOUNCE } from './connection.mjs';
 
 export { parseAuthorizedKeys, STREAM_ANNOUNCE };
+export { createReverseHost } from './reverse-host.mjs';
 
 /**
  * @param {object} [options]
@@ -31,6 +30,10 @@ export { parseAuthorizedKeys, STREAM_ANNOUNCE };
  * @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 {{ 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:
+ *   `canRegister(who, record)` and `canConnect(from, to)` must both be given and return true. See `createReverseHost`.
  * @param {true | { detachTtlMs?: number, maxDetached?: number, ringBytes?: number, sessionSecret?: string | Uint8Array }} [options.sessions]
  *   Keep pty/exec sessions alive across disconnects so a client can `resumeSession()` / `attachSession()`
  *   them: a per-server registry, a ring buffer of the newest `ringBytes` (default 1 MiB) of output, and
@@ -45,22 +48,12 @@ export { parseAuthorizedKeys, STREAM_ANNOUNCE };
  * @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, bindTimeoutMs = 3000, onLog = () => {},
+  host = '127.0.0.1', port = 0, auth, exec, pty, fs, hostKey, mcp, sessions, sessionSecret, relay, bindTimeoutMs = 3000, onLog = () => {},
 } = {}) {
   let wss = null;
   let bound = null;
 
-  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);
-  }
-  const ptyConfig = pty ? normalizePty(pty) : null;
-  const files = fs ? createFileAccess(fs) : null;
-  const mcpHost = mcp ? createMcpHost(mcp) : null;
+  const { execRunner, execOptions, pty: ptyConfig, files, mcp: mcpHost } = buildBackends({ exec, pty, fs, mcp });
   const methods = authMethods(auth);
   const rl = auth?.rateLimit ?? {};
   const rateLimit = {
@@ -70,6 +63,7 @@ export function createWshServer({
   };
   let host_ = null;
   let registry = null;
+  let hub = null;
   const sessionOptions = sessions ? (sessions === true ? {} : sessions) : null;
 
   return {
@@ -93,9 +87,10 @@ export function createWshServer({
           log: onLog,
         });
       }
+      if (relay) hub = new RelayHub({ ...relay, log: onLog });
       const attach = createConnectionFactory({
         authorize, execRunner, execOptions, pty: ptyConfig, files, bindTimeoutMs, log: onLog,
-        methods, hostKey: host_, rateLimit, mcp: mcpHost, sessions: registry,
+        methods, hostKey: host_, rateLimit, mcp: mcpHost, sessions: registry, relay: hub,
       });
 
       wss = new WebSocketServer({ host, port });
@@ -103,6 +98,7 @@ export function createWshServer({
         const conn = attach({
           send: (b) => { if (ws.readyState === 1) ws.send(b); },
           remote: { address: req?.socket?.remoteAddress, headers: req?.headers ?? {} },
+          closeTransport: () => ws.close(1000),
         });
         ws.on('message', (d) => {
           const buf = Array.isArray(d) ? Buffer.concat(d) : Buffer.isBuffer(d) ? d : Buffer.from(d);
@@ -129,12 +125,19 @@ export function createWshServer({
       await new Promise((resolve) => server.close(resolve));
       registry?.closeAll();
       registry = null;
+      hub?.closeAll();
+      hub = null;
     },
 
     address() {
       return bound;
     },
 
+    /** Fingerprints of the peers currently registered with this relay (`[]` when it is not one). */
+    peerFingerprints() {
+      return hub ? hub.peerFingerprints() : [];
+    },
+
     /** The advertised host identity (`null` until `listen()` resolves, or with no `hostKey`). */
     hostKey() {
       return host_ ? { fingerprint: host_.fingerprint, publicKey: host_.publicKey, openssh: host_.openssh } : null;

package/src/server/relay.mjs

@@ -0,0 +1,281 @@
+/**
+ * Relay (reverse-mode) hub for `@johnhenry/wsh/server`: what lets a host that
+ * cannot accept connections (behind NAT, or a browser tab) register with this
+ * server, and an operator reach it through it.
+ *
+ *   peer      --ReverseRegister-->  hub   (a signed peer record, verified here)
+ *   operator  --ReverseList----->   hub   (peers it may connect to)
+ *   operator  --ReverseConnect-->   hub  --ReverseConnect(from_fingerprint)--> peer
+ *   peer      --ReverseAccept---->  hub  --ReverseAccept------------------>  operator
+ *   operator <==RelayForward{from_fingerprint, inner}==> peer     (bridged)
+ *
+ * Nothing is open by default: `canRegister` and `canConnect` both default to
+ * "no". `from_fingerprint` is always the sender's own authenticated key, set
+ * here and never taken from a payload; only the spec's `forwardable` message
+ * types cross a bridge. One bridge per peer at a time, and it lasts as long as
+ * both connections: when either ends the hub closes the other, so no
+ * half-bridged state (and no processes belonging to a departed operator)
+ * outlives it.
+ */
+
+import { cborEncode, cborDecode } from '../cbor.mjs';
+import { fingerprint as fingerprintOf, importPublicKeyRaw, verifyPeerRecord } from '../auth.mjs';
+import { MSG, isRelayForwardable, relayForward, reversePeers, reverseReject } from '../messages.gen.mjs';
+
+export const DEFAULT_MAX_PEERS = 1024;
+export const DEFAULT_CONNECT_TIMEOUT_MS = 8000;
+const MAX_FORWARD_BYTES = 8 * 1024 * 1024;
+const MAX_REMEMBERED_SEQS = 4096;
+const MAX_CAPABILITIES = 32;
+const SHORT_PREFIX_MIN = 8;
+
+const isStr = (v, max) => typeof v === 'string' && v.length <= max;
+
+/**
+ * A connection as the hub sees it.
+ * @typedef {object} RelayHandle
+ * @property {(msg: object) => unknown} send - deliver a message to that connection
+ * @property {() => void} close - end that connection
+ * @property {string} fingerprint - its authenticated key
+ * @property {string} username
+ */
+
+export class RelayHub {
+  /** @type {Map<string, { handle: RelayHandle, meta: object }>} */
+  #peers = new Map();
+  /** @type {Map<RelayHandle, RelayHandle>} */
+  #pairs = new Map();
+  /** target handle -> { operator, timer } while a ReverseConnect awaits its answer */
+  #pending = new Map();
+  /** fingerprint -> the highest record seq ever accepted (survives disconnects, bounded). */
+  #lastSeq = new Map();
+
+  constructor({ canRegister, canConnect, maxPeers = DEFAULT_MAX_PEERS, connectTimeoutMs = DEFAULT_CONNECT_TIMEOUT_MS, log = () => {} } = {}) {
+    for (const [name, fn] of [['canRegister', canRegister], ['canConnect', canConnect]]) {
+      if (fn !== undefined && typeof fn !== 'function') throw new TypeError(`createWshServer: relay.${name} must be a function`);
+    }
+    this.canRegister = canRegister ?? (() => false);
+    this.canConnect = canConnect ?? (() => false);
+    this.maxPeers = maxPeers;
+    this.connectTimeoutMs = connectTimeoutMs;
+    this.log = log;
+  }
+
+  get peerCount() { return this.#peers.size; }
+
+  /** Fingerprints currently registered. */
+  peerFingerprints() { return [...this.#peers.keys()]; }
+
+  async #allowed(fn, ...args) {
+    try { return (await fn(...args)) === true; } catch (e) { this.log(`relay policy threw: ${e.message}`); return false; }
+  }
+
+  /**
+   * Verify and record a `ReverseRegister`. Resolves to `null` on success or a reason.
+   * @param {RelayHandle} handle
+   * @param {object} msg
+   * @param {{ username: string, fingerprint: string }} who - the authenticated connection
+   */
+  async register(handle, msg, who) {
+    // Cheap structural checks first, then policy, then the signature (the expensive part).
+    if (!(msg.public_key instanceof Uint8Array) || !(msg.record_signature instanceof Uint8Array)) return 'missing signed-record fields';
+    const seq = typeof msg.seq === 'bigint' ? Number(msg.seq) : msg.seq;
+    if (!Number.isSafeInteger(seq) || seq < 0) return 'missing or invalid record seq';
+    if (!isStr(msg.username, 64) || !isStr(msg.peer_type ?? 'host', 64) || !isStr(msg.shell_backend ?? 'pty', 64)) return 'malformed record';
+    const caps = msg.capabilities ?? [];
+    if (!Array.isArray(caps) || caps.length > MAX_CAPABILITIES || !caps.every((c) => isStr(c, 64))) return 'malformed capabilities';
+    if ((await fingerprintOf(msg.public_key)) !== who.fingerprint) return 'public_key does not match the authenticated identity';
+
+    if (!(await this.#allowed(this.canRegister, { username: who.username, fingerprint: who.fingerprint }, {
+      username: msg.username, capabilities: caps, peerType: msg.peer_type ?? 'host', shellBackend: msg.shell_backend ?? 'pty',
+    }))) return 'registration not permitted';
+
+    const previous = this.#lastSeq.get(who.fingerprint);
+    if (previous !== undefined && seq <= previous) return `stale record (seq ${seq} <= ${previous})`;
+
+    let key;
+    try { key = await importPublicKeyRaw(msg.public_key); } catch { return 'malformed public_key'; }
+    let ok = false;
+    try {
+      ok = await verifyPeerRecord(key, msg.record_signature, {
+        username: msg.username,
+        peerType: msg.peer_type,
+        shellBackend: msg.shell_backend,
+        capabilities: msg.capabilities,
+        supportsAttach: msg.supports_attach,
+        supportsReplay: msg.supports_replay,
+        supportsEcho: msg.supports_echo,
+        supportsTermSync: msg.supports_term_sync,
+        seq,
+      });
+    } catch { ok = false; }
+    if (!ok) return 'record signature does not verify';
+
+    // Re-check after the awaits: a concurrent registration may have moved the counter.
+    const latest = this.#lastSeq.get(who.fingerprint);
+    if (latest !== undefined && seq <= latest) return `stale record (seq ${seq} <= ${latest})`;
+    const existing = this.#peers.get(who.fingerprint);
+    if (!existing && this.#peers.size >= this.maxPeers) return 'relay is full';
+
+    this.#lastSeq.delete(who.fingerprint);
+    this.#lastSeq.set(who.fingerprint, seq);
+    while (this.#lastSeq.size > MAX_REMEMBERED_SEQS) this.#lastSeq.delete(this.#lastSeq.keys().next().value);
+
+    if (existing && existing.handle !== handle) {
+      // The same key came back on a new connection: the old one is dead or superseded.
+      this.#peers.delete(who.fingerprint);
+      this.drop(existing.handle);
+      existing.handle.close();
+    }
+    this.#peers.set(who.fingerprint, {
+      handle,
+      meta: {
+        fingerprint: who.fingerprint,
+        fingerprint_short: who.fingerprint.slice(0, 12),
+        username: msg.username,
+        capabilities: [...caps],
+        peer_type: msg.peer_type ?? 'host',
+        shell_backend: msg.shell_backend ?? 'pty',
+        source: 'wsh-relay',
+        supports_attach: !!msg.supports_attach,
+        supports_replay: !!msg.supports_replay,
+        supports_echo: !!msg.supports_echo,
+        supports_term_sync: !!msg.supports_term_sync,
+        last_seen: Date.now(),
+        public_key: msg.public_key,
+        seq,
+        record_signature: msg.record_signature,
+      },
+    });
+    this.log(`relay: peer registered ${who.fingerprint.slice(0, 12)} (${msg.username})`);
+    return null;
+  }
+
+  /** Is this connection a registered peer? Refreshes its `last_seen` when it is. */
+  touch(handle) {
+    const e = this.#peers.get(handle.fingerprint);
+    if (e && e.handle === handle) e.meta.last_seen = Date.now();
+  }
+
+  /** The peers `who` is allowed to connect to -- an operator sees only what it could reach. */
+  async list(who) {
+    const out = [];
+    for (const { meta, handle } of this.#peers.values()) {
+      if (handle.fingerprint === who.fingerprint) continue;
+      if (await this.#allowed(this.canConnect, who, { fingerprint: meta.fingerprint, username: meta.username, capabilities: meta.capabilities })) out.push({ ...meta });
+    }
+    return reversePeers({ peers: out });
+  }
+
+  #find(target) {
+    if (typeof target !== 'string') return undefined;
+    const exact = this.#peers.get(target);
+    if (exact) return exact;
+    if (target.length < SHORT_PREFIX_MIN) return undefined;
+    const hits = [...this.#peers.values()].filter((p) => p.meta.fingerprint.startsWith(target));
+    return hits.length === 1 ? hits[0] : undefined;
+  }
+
+  /** `ReverseConnect` from `operator`: forward it to the target, with the identity the hub knows. */
+  async connect(operator, msg) {
+    const reject = (reason) => operator.send(reverseReject({ targetFingerprint: String(msg.target_fingerprint ?? ''), username: msg.username ?? '', reason }));
+    const target = this.#find(msg.target_fingerprint);
+    // Unknown, unreachable-by-policy and self look the same to the caller.
+    if (!target || target.handle === operator
+      || !(await this.#allowed(this.canConnect, { username: operator.username, fingerprint: operator.fingerprint }, {
+        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');
+    }
+    const timer = setTimeout(() => {
+      if (this.#pending.get(target.handle)?.operator !== operator) return;
+      this.#pending.delete(target.handle);
+      reject('peer did not respond');
+    }, this.connectTimeoutMs);
+    timer.unref?.();
+    this.#pending.set(target.handle, { operator, timer });
+    // The relay speaks for the operator's identity; whatever the client wrote in these fields is discarded.
+    target.handle.send({
+      type: MSG.REVERSE_CONNECT,
+      target_fingerprint: target.meta.fingerprint,
+      username: operator.username,
+      from_fingerprint: operator.fingerprint,
+    });
+    this.log(`relay: ${operator.fingerprint.slice(0, 12)} -> ${target.meta.fingerprint.slice(0, 12)} requested`);
+  }
+
+  /** `ReverseAccept` / `ReverseReject` from a peer, answering a pending `connect`. */
+  answer(peer, msg) {
+    const p = this.#pending.get(peer);
+    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 });
+    if (msg.type === MSG.REVERSE_ACCEPT) {
+      this.#pairs.set(p.operator, peer);
+      this.#pairs.set(peer, p.operator);
+      this.log(`relay: bridged ${p.operator.fingerprint.slice(0, 12)} <-> ${peer.fingerprint.slice(0, 12)}`);
+    }
+  }
+
+  /** Is `handle` one end of a bridge? */
+  bridged(handle) {
+    return this.#pairs.has(handle);
+  }
+
+  /**
+   * Carry a message across `handle`'s bridge. A plain forwardable message is
+   * wrapped; a `RelayForward` the client wrote itself is unwrapped, its inner
+   * checked, and re-wrapped -- either way `from_fingerprint` is the sender's
+   * authenticated key. Returns false when there is no bridge.
+   */
+  forward(handle, msg) {
+    const partner = this.#pairs.get(handle);
+    if (!partner) return false;
+    let inner;
+    if (msg.type === MSG.RELAY_FORWARD) {
+      if (!(msg.inner instanceof Uint8Array) || msg.inner.byteLength > MAX_FORWARD_BYTES) { this.log('relay: dropped an oversized or malformed RelayForward'); return true; }
+      let decoded;
+      try { decoded = cborDecode(msg.inner); } catch { this.log('relay: dropped a RelayForward with an undecodable inner'); return true; }
+      if (!decoded || typeof decoded.type !== 'number' || !isRelayForwardable(decoded.type)) {
+        this.log(`relay: dropped a RelayForward wrapping a non-forwardable type ${decoded?.type}`);
+        return true;
+      }
+      inner = msg.inner;
+    } else {
+      if (!isRelayForwardable(msg.type)) return false;
+      inner = cborEncode(msg);
+    }
+    partner.send(relayForward({ fromFingerprint: handle.fingerprint, inner }));
+    return true;
+  }
+
+  /** A connection ended: forget it, and end the bridge it was part of. */
+  drop(handle) {
+    const entry = this.#peers.get(handle.fingerprint);
+    if (entry && entry.handle === handle) this.#peers.delete(handle.fingerprint);
+    const p = this.#pending.get(handle);
+    if (p) { clearTimeout(p.timer); this.#pending.delete(handle); p.operator.send(reverseReject({ targetFingerprint: handle.fingerprint, username: '', reason: 'peer went away' })); }
+    for (const [target, pend] of this.#pending) {
+      if (pend.operator === handle) { clearTimeout(pend.timer); this.#pending.delete(target); }
+    }
+    const partner = this.#pairs.get(handle);
+    if (partner) {
+      this.#pairs.delete(handle);
+      this.#pairs.delete(partner);
+      partner.close();
+    }
+  }
+
+  /** Server shutdown. */
+  closeAll() {
+    for (const p of this.#pending.values()) clearTimeout(p.timer);
+    this.#pending.clear();
+    this.#pairs.clear();
+    this.#peers.clear();
+  }
+}

package/src/server/reverse-host.mjs

@@ -0,0 +1,147 @@
+/**
+ * A reverse host: this process dials OUT to a relay (`createWshServer({ relay })`),
+ * registers itself as a peer, and serves whichever operator the relay bridges to
+ * it -- with the same exec / pty / fs / mcp backends `createWshServer` serves
+ * direct clients with. Use it for a machine that cannot accept connections.
+ *
+ * The relay has already authenticated the operator (its key), so the bridged
+ * connection is pre-authenticated; what a relay-asserted identity is worth is
+ * yours to decide in `accept`, which defaults to refusing everyone.
+ */
+
+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';
+
+const BACKOFF_START_MS = 500;
+const BACKOFF_MAX_MS = 30_000;
+
+/**
+ * @param {object} options
+ * @param {string} options.url - The relay (`ws://` or `wss://`).
+ * @param {string} options.username
+ * @param {CryptoKeyPair} options.keyPair - This host's identity; its fingerprint is what operators connect to.
+ * @param {(operator: { fingerprint: string, username: string }) => boolean | Promise<boolean>} [options.accept]
+ *   Who may be bridged to this host. Default: nobody.
+ * @param {true | object | Function} [options.exec]
+ * @param {object} [options.pty]
+ * @param {object} [options.fs]
+ * @param {object} [options.mcp]
+ * @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 {(line: string) => void} [options.onLog]
+ */
+export function createReverseHost({
+  url, username, keyPair, accept, exec, pty, fs, mcp, reconnect = true, connect = {}, peerType = 'host', onLog = () => {},
+} = {}) {
+  if (!url) throw new TypeError('createReverseHost: url is required');
+  if (!username) throw new TypeError('createReverseHost: username is required');
+  if (!keyPair) throw new TypeError('createReverseHost: keyPair is required (the relay keys peers by fingerprint)');
+  if (accept !== undefined && typeof accept !== 'function') throw new TypeError('createReverseHost: accept must be a function');
+
+  const backends = buildBackends({ exec, pty, fs, mcp });
+  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';
+  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,
+    sessions: null, relay: null, bindTimeoutMs: 3000, log: (l) => onLog(`[reverse] ${l}`),
+  });
+
+  let client = null;
+  let myFingerprint = null;
+  let closed = false;
+  let timer = null;
+  let backoff = BACKOFF_START_MS;
+
+  async function dial() {
+    const c = new WshClient();
+    let bridge = null;
+    let operator = null;
+
+    const endBridge = () => {
+      if (operator) c.untrustRelayPeer(operator);
+      bridge?.close();
+      bridge = null;
+      operator = null;
+    };
+    c.onRelayMessage = (msg) => bridge?.receiveMessage(msg);
+    c.onReverseConnect = async (req) => {
+      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; }
+      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; }
+      c.trustRelayPeer(from);
+      operator = from;
+      bridge = factory({
+        sendMessage: (m) => c.sendRelayControl(m),
+        authenticated: { username: String(req.username ?? 'operator'), fingerprint: from },
+        dataStreams: false,
+      });
+      onLog(`[reverse] bridged to ${from.slice(0, 12)}`);
+      await answer(reverseAccept({
+        targetFingerprint: myFingerprint, username, capabilities, peerType, shellBackend,
+        supportsAttach: false, supportsReplay: false, supportsEcho: false, supportsTermSync: false,
+      }));
+    };
+    c.onClose = () => {
+      endBridge();
+      if (client === c) client = null;
+      if (closed || !reconnect) return;
+      onLog(`[reverse] relay connection ended; redialling in ${backoff}ms`);
+      timer = setTimeout(() => { redial().catch(() => {}); }, backoff);
+      timer.unref?.();
+      backoff = Math.min(backoff * 2, BACKOFF_MAX_MS);
+    };
+
+    await c.connectReverse(url, {
+      username, keyPair, expose, peerType, shellBackend,
+      supportsAttach: false, supportsReplay: false, supportsEcho: false, supportsTermSync: false,
+      ...connect,
+    });
+    client = c;
+    backoff = BACKOFF_START_MS;
+    onLog(`[reverse] registered ${myFingerprint.slice(0, 12)} on ${url}`);
+  }
+
+  async function redial() {
+    if (closed) return;
+    try { await dial(); } catch (e) {
+      onLog(`[reverse] redial failed: ${e.message}`);
+      if (closed || !reconnect) return;
+      timer = setTimeout(() => { redial().catch(() => {}); }, backoff);
+      timer.unref?.();
+      backoff = Math.min(backoff * 2, BACKOFF_MAX_MS);
+    }
+  }
+
+  return {
+    /** Dial the relay and register. Rejects if the first attempt fails; later drops are retried. */
+    async start() {
+      if (client) throw new Error('createReverseHost: already started');
+      closed = false;
+      myFingerprint = await fingerprint(await exportPublicKeyRaw(keyPair.publicKey));
+      await dial();
+      return { fingerprint: myFingerprint };
+    },
+    /** Leave the relay and end any bridged session. */
+    async close() {
+      closed = true;
+      clearTimeout(timer);
+      const c = client;
+      client = null;
+      await c?.disconnect().catch(() => {});
+    },
+    /** This host's fingerprint (what operators `reverseConnect()` to); `null` before `start()`. */
+    get fingerprint() { return myFingerprint; },
+    /** Is the relay connection up right now? */
+    get connected() { return client !== null; },
+  };
+}