@johnhenry/wsh 0.20.0 → 0.22.0

package/src/server/index.mjs

@@ -10,13 +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]
@@ -30,6 +30,15 @@ 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
+ *   `detachTtlMs` (default 300000; 0 = kill on disconnect) / `maxDetached` (default 16) bounds. Off unless given.
+ * @param {string | Uint8Array} [options.sessionSecret] - Alias for `sessions.sessionSecret`.
  * @param {true | { file: string } | CryptoKeyPair} [options.hostKey] - The server's own Ed25519
  *   identity, advertised (with proof of possession) so clients can pin it. See `src/host-key.mjs`.
  * @param {object} [options.auth.rateLimit] - Password-failure throttle: `{ maxFailures=5, windowMs=60000,
@@ -39,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, 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 = {
@@ -63,6 +62,9 @@ export function createWshServer({
     failureDelayMs: rl.failureDelayMs ?? 250,
   };
   let host_ = null;
+  let registry = null;
+  let hub = null;
+  const sessionOptions = sessions ? (sessions === true ? {} : sessions) : null;
 
   return {
     async listen() {
@@ -75,9 +77,20 @@ export function createWshServer({
       }
       const authorize = await buildAuthorizer(auth);
       host_ = hostKey ? await loadHostKey(hostKey) : null;
+      if (sessionOptions) {
+        const secret = sessionOptions.sessionSecret ?? sessionSecret;
+        registry = new SessionRegistry({
+          secret: secret === undefined ? undefined : Buffer.from(secret),
+          detachTtlMs: sessionOptions.detachTtlMs,
+          maxDetached: sessionOptions.maxDetached,
+          ringBytes: sessionOptions.ringBytes,
+          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,
+        methods, hostKey: host_, rateLimit, mcp: mcpHost, sessions: registry, relay: hub,
       });
 
       wss = new WebSocketServer({ host, port });
@@ -85,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);
@@ -109,12 +123,21 @@ export function createWshServer({
       bound = null;
       for (const client of server.clients) client.terminate();
       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; },
+  };
+}