@johnhenry/wsh 0.25.1 → 0.26.0

package/README.md

@@ -287,27 +287,56 @@ const s = await client.openSession({ type: 'exec', command: 'echo hello' });
   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.
+- **One operator per peer at a time**, by design: a `RelayForward` names its
+  sender but not its recipient, and nothing on the wire tells a peer that one
+  of several operators left, so replies could not be addressed and a departed
+  operator's work could not be cleaned up. A second `ReverseConnect` to a peer
+  that already has an operator (or a request awaiting its answer) is rejected
+  with `ReverseReject.reason` `busy: this peer already has an operator ...`
+  (exported as `BUSY_PEER` from `src/server/relay.mjs`), and an operator that
+  already has a bridge or a request in flight is rejected with `busy: you
+  already have a bridge ...` (`BUSY_OPERATOR`); a request the peer does not
+  answer within `connectTimeoutMs` (default 8 s) is `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. Lifting the limit needs a spec addition (a recipient on
+  `RelayForward`, a bridge-ended notice) shared with the Rust side; it is
+  tracked rather than built.
 - **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.
+- **End-to-end encryption through the bridge.** `KeyExchange` and `EncryptedFrame`
+  are on the spec's `forwardable` list, so an operator and a peer can run
+  `initiateE2E()` / `enableE2E()` with each other through the relay: it carries
+  the CBOR of each as opaque bytes and holds no key, so it sees only public
+  values and ciphertext (`test/server-relay-bridge.test.mjs` checks the relay
+  never holds the plaintext). **`KeyExchange` is unauthenticated**: this
+  protects against a relay that only observes, not against one that substitutes
+  the exchanged keys, so if the relay operator is not trusted, authenticate the
+  derived key yourself (compare it out of band, or sign it with the keys the
+  bridge already names). Only a stock-client peer (a browser tab, `connectReverse`)
+  speaks E2E: **`createReverseHost` does not answer `KeyExchange` or open
+  `EncryptedFrame`s** (the Node host has no E2E layer at all), so against it traffic
+  is in the clear to the relay -- serve the relay over `wss://` and treat its
+  operator as trusted. Key exchange from a connection that is not bridged is
+  never carried.
+- **Feature gates follow the host behind the bridge.** The host's own features
+  (`file-write`, `file-rename`, `mcp-call-id`) are stated in the optional
+  `ReverseAccept.features`; the relay forwards the list (bounded: at most 64
+  strings of 128 characters, otherwise it is dropped) and, once
+  `reverseConnect()` resolves, `client.hasFeature()` / `client.features` answer
+  from it instead of the relay's `ServerHello`. `client.bridgedFeatures` is that
+  list (`null` before a bridge, or when the peer did not say, in which case the
+  gates fall back to `client.serverFeatures`, the relay's, as before).
+  `createReverseHost` always states its features (`reportFeatures: false` leaves
+  them out). A **Rust `wsh-server` / `wsh` older than `rust-v0.3.0` rejects a
+  `ReverseAccept` that carries `features`** (the message is `deny_unknown_fields`
+  there): against such a relay or operator, set `reportFeatures: false` on the
+  host (and use `ReverseAccept` without the field in your own peers).
 
 ### Sessions: attach / resume / detach
 
@@ -828,7 +857,7 @@ than left to be found.
 | Typed RPC channels (`openRpc`, `rpc` sessions; `wsh-host`, `wsh-fs`, `mcp`) | `WshClient.openRpc()`, `RpcChannel` | none yet (a Rust `wsh-server` does not advertise `rpc`; a JS client falls back to `FileOp` for files) | **JS server only, no wire change**: `Open { kind: 'rpc', command: <protocol> }` plus `rpc*` `ServerHello` features, negotiated so it fails fast elsewhere |
 | 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` does the same (`rust-v0.2.0`+; fixed 256 KiB ring) |
-| 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 |
+| 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 (`busy:` reasons say so); E2E and bridged feature gates need `rust-v0.3.0`+ on the Rust side |
 | 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 |
@@ -900,6 +929,11 @@ out explicitly below rather than left to be discovered.
   `SHA-256("wsh-v1\0" || lp(username) || lp(session_id) || nonce || channel_binding)`,
   so a signature can't be replayed against a different session or relabeled
   to a different username.
+- **E2E through a relay is opt-in and unauthenticated key agreement.** The relay
+  carries `KeyExchange` / `EncryptedFrame` between a bridged operator and peer
+  without being able to read the sealed frames, but `KeyExchange` carries no
+  signature: a relay that substitutes keys is not detected (see the [relay
+  section](#relay--reverse-mode)).
 - **Signed peer records.** Reverse-mode registration is self-signed by the
   peer's identity key (the libp2p RFC 0002/0003 pattern), in a signing
   domain separate from the auth challenge. `listPeers()` verifies every

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnhenry/wsh",
-  "version": "0.25.1",
+  "version": "0.26.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/client.mjs

@@ -313,6 +313,11 @@ export class WshClient {
 
   /** @type {string[]} Server-advertised features from SERVER_HELLO. */
   #serverFeatures = [];
+  /**
+   * @type {string[]|null} Features of the host behind an accepted relay bridge, from
+   * `ReverseAccept.features`; `null` when no bridge is up or the peer stated none.
+   */
+  #bridgedFeatures = null;
 
   /** @type {number|null} Ping interval handle. */
   #pingTimer = null;
@@ -437,11 +442,29 @@ export class WshClient {
     return new Map(this.#sessions);
   }
 
-  /** Server-advertised features from SERVER_HELLO. */
+  /**
+   * The features this connection's operations can rely on: those of the host
+   * behind an accepted relay bridge when it stated them (`ReverseAccept.features`,
+   * see `reverseConnect()`), otherwise the server's `SERVER_HELLO` features.
+   */
   get features() {
+    return [...(this.#bridgedFeatures ?? this.#serverFeatures)];
+  }
+
+  /** The `SERVER_HELLO` features of the server this connection is to (the relay, over a bridge). */
+  get serverFeatures() {
     return [...this.#serverFeatures];
   }
 
+  /**
+   * Features of the host behind an accepted relay bridge, as it stated them in
+   * `ReverseAccept.features`; `null` when there is no bridge, or the peer did
+   * not say (then `hasFeature()` falls back to the server's own).
+   */
+  get bridgedFeatures() {
+    return this.#bridgedFeatures ? [...this.#bridgedFeatures] : null;
+  }
+
   /**
    * Low-level transport reference.
    * Exposed for relay message replies (IncomingSession._sendReply).
@@ -458,7 +481,7 @@ export class WshClient {
    * @returns {boolean}
    */
   hasFeature(name) {
-    return this.#serverFeatures.includes(name);
+    return (this.#bridgedFeatures ?? this.#serverFeatures).includes(name);
   }
 
   /**
@@ -980,6 +1003,7 @@ export class WshClient {
 
     this.#stopPing();
     this.#state = STATE_CLOSED;
+    this.#bridgedFeatures = null;
 
     // Close all sessions concurrently.
     const closePromises = [];
@@ -1217,6 +1241,12 @@ export class WshClient {
 
     if (response.type === MSG.REVERSE_ACCEPT) {
       this.trustRelayPeer(response.target_fingerprint);
+      // The relay's SERVER_HELLO describes the relay, not the host behind the
+      // bridge: when that host says what it supports, feature gates
+      // (file-write, file-rename, mcp-call-id) follow it instead.
+      this.#bridgedFeatures = Array.isArray(response.features) && response.features.every((f) => typeof f === 'string')
+        ? [...response.features]
+        : null;
     }
 
     return response;
@@ -2747,6 +2777,7 @@ export class WshClient {
     if (this.#state === STATE_CLOSED) return;
 
     this.#state = STATE_CLOSED;
+    this.#bridgedFeatures = null;
     this.#stopPing();
     this.#rejectAllWaiters(new Error('Transport closed'));
 

package/src/index.d.ts

@@ -603,6 +603,8 @@ export function reverseAccept(opts?: {
   supportsReplay?: boolean;
   supportsEcho?: boolean;
   supportsTermSync?: boolean;
+  /** Features of this (bridged) host, in the vocabulary of `ServerHello.features`; omit rather than send `[]`. */
+  features?: string[];
 }): WshMessage;
 
 export function reverseReject(opts?: {
@@ -1970,8 +1972,15 @@ export class WshClient {
   /** Read-only view of active sessions. */
   readonly sessions: Map<number, WshSession>;
 
-  /** Server-advertised features from SERVER_HELLO. */
+  /**
+   * The features this connection can rely on: those of the host behind an accepted relay bridge when it
+   * stated them (`ReverseAccept.features`), otherwise the server's `SERVER_HELLO` features.
+   */
   readonly features: string[];
+  /** The `SERVER_HELLO` features of the server connected to (the relay, over a bridge). */
+  readonly serverFeatures: string[];
+  /** Features of the host behind an accepted relay bridge as it stated them; `null` when there is no bridge or it did not say. */
+  readonly bridgedFeatures: string[] | null;
 
   /**
    * Low-level transport reference.
@@ -2004,7 +2013,7 @@ export class WshClient {
   onGatewayMessage: ((msg: WshMessage) => void) | null;
 
   /**
-   * Check if the server advertised a specific feature.
+   * Check if a feature is available: advertised by the server, or by the bridged host (see `features`).
    */
   hasFeature(name: string): boolean;
 

package/src/messages.gen.mjs

@@ -495,19 +495,10 @@ export function reverseConnect({ targetFingerprint, username, fromFingerprint }
   };
 }
 
-export function reverseAccept({ targetFingerprint, username, capabilities = [], peerType = "host", shellBackend = "pty", supportsAttach = false, supportsReplay = false, supportsEcho = false, supportsTermSync = false } = {}) {
-  return {
-    type: MSG.REVERSE_ACCEPT,
-    target_fingerprint: targetFingerprint,
-    username,
-    capabilities,
-    peer_type: peerType,
-    shell_backend: shellBackend,
-    supports_attach: supportsAttach,
-    supports_replay: supportsReplay,
-    supports_echo: supportsEcho,
-    supports_term_sync: supportsTermSync,
-  };
+export function reverseAccept({ targetFingerprint, username, capabilities = [], peerType = "host", shellBackend = "pty", supportsAttach = false, supportsReplay = false, supportsEcho = false, supportsTermSync = false, features } = {}) {
+  const msg = { type: MSG.REVERSE_ACCEPT, target_fingerprint: targetFingerprint, username, capabilities, peer_type: peerType, shell_backend: shellBackend, supports_attach: supportsAttach, supports_replay: supportsReplay, supports_echo: supportsEcho, supports_term_sync: supportsTermSync };
+  if (features !== undefined) msg.features = features;
+  return msg;
 }
 
 export function reverseReject({ targetFingerprint, username, reason } = {}) {
@@ -962,6 +953,8 @@ export const RELAY_FORWARDABLE = new Set([
   MSG.ECHO_STATE,
   MSG.TERM_SYNC,
   MSG.TERM_DIFF,
+  MSG.KEY_EXCHANGE,
+  MSG.ENCRYPTED_FRAME,
 ]);
 
 /**

package/src/server/connection.mjs

@@ -31,6 +31,22 @@ import { RpcChannel, RPC_FEATURE, RPC_MAX_MESSAGE_PREFIX, rpcProtocolFeature } f
 import { HOST_KEY_PREFIX, HOST_KEY_SIG_PREFIX, findClientNonce, hostKeyProofMessage, toHex } from '../host-key.mjs';
 
 export const STREAM_ANNOUNCE = 'stream-announce';
+
+/**
+ * The features a host built from `cfg` advertises (`ServerHello.features`, minus the host-key proof).
+ * Over a relay bridge (`dataStreams: false`) there are no client-opened streams, so the
+ * stream-based ones (`stream-announce`, `rpc`) are not offered; a reverse host reports this
+ * list to the operator in `ReverseAccept.features`.
+ */
+export function hostFeatures(cfg, { dataStreams = true } = {}) {
+  const features = dataStreams ? [STREAM_ANNOUNCE] : [];
+  if (cfg.mcp) features.push(MCP_CALL_ID_FEATURE);
+  if (cfg.files) features.push('file-transfer', 'file-write', 'file-rename');
+  if (cfg.rpc && dataStreams && cfg.rpc.protocols.size) {
+    features.push(RPC_FEATURE, ...[...cfg.rpc.protocols.keys()].map(rpcProtocolFeature), RPC_MAX_MESSAGE_PREFIX + cfg.rpc.maxMessageBytes);
+  }
+  return features;
+}
 const MAX_PENDING_WRITES = 8;
 const MAX_RENAME_PATH_BYTES = 4096;
 const WRITE_IDLE_MS = 30_000;
@@ -201,12 +217,7 @@ export function createConnectionFactory(cfg) {
         }
         state.username = user;
         state.method = method;
-        const features = [STREAM_ANNOUNCE];
-        if (cfg.mcp) features.push(MCP_CALL_ID_FEATURE);
-        if (cfg.files) features.push('file-transfer', 'file-write', 'file-rename');
-        if (cfg.rpc && dataStreams && cfg.rpc.protocols.size) {
-          features.push(RPC_FEATURE, ...[...cfg.rpc.protocols.keys()].map(rpcProtocolFeature), RPC_MAX_MESSAGE_PREFIX + cfg.rpc.maxMessageBytes);
-        }
+        const features = hostFeatures(cfg, { dataStreams });
         let hostFingerprint;
         if (cfg.hostKey) {
           hostFingerprint = cfg.hostKey.fingerprint;

package/src/server/relay.mjs

@@ -27,8 +27,15 @@ export const DEFAULT_CONNECT_TIMEOUT_MS = 8000;
 const MAX_FORWARD_BYTES = 8 * 1024 * 1024;
 const MAX_REMEMBERED_SEQS = 4096;
 const MAX_CAPABILITIES = 32;
+const MAX_FEATURES = 64;
+const MAX_FEATURE_LENGTH = 128;
 const SHORT_PREFIX_MIN = 8;
 
+/** `ReverseReject.reason` for a peer that already has an operator (or a request awaiting its answer). */
+export const BUSY_PEER = 'busy: this peer already has an operator (the relay bridges one operator per peer at a time; retry when it leaves)';
+/** `ReverseReject.reason` for an operator that already has a bridge, or a request in flight. */
+export const BUSY_OPERATOR = 'busy: you already have a bridge or a pending connect on this relay (one at a time)';
+
 const isStr = (v, max) => typeof v === 'string' && v.length <= max;
 
 /**
@@ -186,9 +193,13 @@ export class RelayHub {
         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');
+    // One bridge per peer, and one per operator: a RelayForward names its sender but not its recipient, so a
+    // peer's reply could not be addressed to one of several operators (see the README's relay section).
+    if (this.#pairs.has(target.handle) || this.#pending.has(target.handle)) {
+      return reject(BUSY_PEER);
+    }
+    if (this.#pairs.has(operator) || [...this.#pending.values()].some((p) => p.operator === operator)) {
+      return reject(BUSY_OPERATOR);
     }
     const timer = setTimeout(() => {
       if (this.#pending.get(target.handle)?.operator !== operator) return;
@@ -213,8 +224,13 @@ export class RelayHub {
     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 });
+    // The answer names the answering peer, not whatever it wrote; its features claim is bounded.
+    const answer = { ...msg, target_fingerprint: peer.fingerprint };
+    if (msg.type === MSG.REVERSE_ACCEPT) {
+      if (Array.isArray(msg.features) && msg.features.length <= MAX_FEATURES && msg.features.every((f) => isStr(f, MAX_FEATURE_LENGTH))) answer.features = [...msg.features];
+      else delete answer.features;
+    }
+    p.operator.send(answer);
     if (msg.type === MSG.REVERSE_ACCEPT) {
       this.#pairs.set(p.operator, peer);
       this.#pairs.set(peer, p.operator);

package/src/server/reverse-host.mjs

@@ -13,7 +13,7 @@ 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';
+import { createConnectionFactory, hostFeatures } from './connection.mjs';
 
 const BACKOFF_START_MS = 500;
 const BACKOFF_MAX_MS = 30_000;
@@ -32,10 +32,13 @@ const BACKOFF_MAX_MS = 30_000;
  * @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 {boolean} [options.reportFeatures=true] - State this host's features in `ReverseAccept.features`, so the operator's
+ *   feature gates follow this host rather than the relay. Turn off only for a relay (a Rust `wsh-server` older than the field)
+ *   that rejects a `ReverseAccept` carrying it.
  * @param {(line: string) => void} [options.onLog]
  */
 export function createReverseHost({
-  url, username, keyPair, accept, exec, pty, fs, mcp, reconnect = true, connect = {}, peerType = 'host', onLog = () => {},
+  url, username, keyPair, accept, exec, pty, fs, mcp, reconnect = true, connect = {}, peerType = 'host', reportFeatures = true, onLog = () => {},
 } = {}) {
   if (!url) throw new TypeError('createReverseHost: url is required');
   if (!username) throw new TypeError('createReverseHost: username is required');
@@ -46,6 +49,9 @@ export function createReverseHost({
   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';
+  // What this host can do over a bridge, for the operator's feature gates (`ReverseAccept.features`).
+  // `reportFeatures: false` leaves them out (a Rust peer or relay older than the field rejects a ReverseAccept that has it).
+  const bridgeFeatures = hostFeatures({ mcp: backends.mcp, files: backends.files }, { dataStreams: false });
   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,
@@ -74,7 +80,7 @@ export function createReverseHost({
       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; }
+      if (bridge || typeof from !== 'string' || !from) { await refuse('busy: this host is already serving an operator'); 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; }
@@ -89,6 +95,7 @@ export function createReverseHost({
       await answer(reverseAccept({
         targetFingerprint: myFingerprint, username, capabilities, peerType, shellBackend,
         supportsAttach: false, supportsReplay: false, supportsEcho: false, supportsTermSync: false,
+        features: reportFeatures ? bridgeFeatures : undefined,
       }));
     };
     c.onClose = () => {