@johnhenry/wsh 0.20.0 → 0.22.0

package/README.md

@@ -185,8 +185,157 @@ 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, attach/resume of server-side sessions.
+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
+
+By default a pty/exec session dies with the connection that opened it. Pass
+`sessions` and it outlives it, so a dropped socket (a flaky link, a closed
+tab) can be picked up again:
+
+```js
+createWshServer({
+  auth, exec: true, pty: { spawn: nodePty.spawn },
+  sessions: {
+    detachTtlMs: 300_000,   // how long a session nobody is attached to keeps running (0 = kill at once)
+    maxDetached: 16,        // unattended sessions kept at once; the longest-detached is killed beyond that
+    ringBytes: 1 << 20,     // output history kept per session: what a resume can replay
+    // sessionSecret: process.env.WSH_SESSION_SECRET,  // fixes the token key (default: random per process)
+  },
+});
+```
+
+```js
+// original connection
+const s = await client.openSession({ type: 'pty' });
+s.onData = (d) => term.write(d);            // s.seq counts the output bytes received so far
+const { sessionId, resumeToken } = s;       // keep these
+const lastSeq = s.seq;                      // ... the socket drops ...
+
+// fresh connection, same key
+const { session } = await client2.resumeSession(sessionId, resumeToken, { lastSeq });
+session.onData = (d) => term.write(d);      // only the bytes after lastSeq, then live output
+await session.write('ls\n');                // and it is the same process
+```
+
+- **`seq` is the cumulative count of output bytes** the host has produced for
+  a session (stream data or `SessionData` alike). The client counts what it
+  received -- `WshSession.seq` -- so no per-frame field exists, and
+  `Resume.last_seq` is exactly that number. The host keeps the newest
+  `ringBytes` of output and replays `ring[last_seq - ringStart ..]`. A
+  `last_seq` older than the ring still holds is refused with an
+  `output gap` error naming where the history starts (fall back to
+  `attachSession()` for the retained tail); one newer than the session has
+  produced is refused too. While nobody is attached the process keeps running
+  and keeps filling the ring (it is never paused), so a chatty process loses its
+  oldest output rather than blocking.
+- **Token:** `HMAC-SHA256(secret, session_id || expiry)` in the spec's
+  40-byte token format, minted at open, returned as `OpenOk.token` and checked
+  in constant time. **`Resume` needs the token AND ownership** (the same key, or
+  for a password login the same username) -- it is the credentialed connection
+  coming back. **`Attach` accepts the token OR ownership**, so the owner can
+  re-attach with nothing but the session id, and a token holder can join as a
+  guest. Refusals do not say whether the session exists.
+- **What arrives:** the Presence reply names a new channel (`channel_id`) and the
+  `seq` of its first byte; the replay and live output follow as `SessionData` on
+  it. That channel is always message-backed, even for an `exec` session that was
+  opened on a data stream -- neither stock client opens a stream for attach/resume
+  -- so `resumeSession()`/`attachSession()` return the Presence with a
+  non-enumerable `session` (a `WshSession`) to read and write it. A client that
+  ignores that can read the same frames with `addControlListener()`.
+- **Several connections** may attach to one session (up to 16): output fans out
+  to all of them, `attachSession(id, { readOnly: true })` attaches a viewer whose
+  input is dropped, and every change in who is attached is broadcast as `Presence`
+  (the roster, without channel ids).
+- **Ending vs leaving:** `Close` on a channel (which `session.close()` and a
+  graceful `client.disconnect()` send) *ends* the session when its owner sends it,
+  and merely leaves it for anyone else. To walk away from a session and keep it
+  running, `client.detach(sessionId)` first; losing the connection also detaches.
+  `client.listRemoteSessions()` lists the sessions your key owns, attached or not.
+- Exit: when the process ends, everyone attached gets `Exit` + `Close`; the
+  record then lingers for `detachTtlMs` so a late resume still collects the tail
+  and the exit code.
+- Not built: ACL grants (`SessionGrant`/`SessionRevoke`) and `ControlChanged` --
+  only the owner re-attaches as a controller; everyone else needs the token.
+  Sessions are in-memory: a server restart ends them all.
 
 ### MCP tools
 
@@ -361,8 +510,9 @@ Opening a PTY/exec session returns a session-scoped credential alongside the cha
 session.sessionId;   // server-assigned session id (undefined for e.g. file channels)
 session.resumeToken; // token minted at open time; only the opener receives it
 
-// The original opener, reclaiming its session from a fresh connection:
-await client.resumeSession(session.sessionId, session.resumeToken);
+// The original opener, reclaiming its session from a fresh connection,
+// replaying only the output it has not yet seen (`session.seq` counts it):
+await client.resumeSession(session.sessionId, session.resumeToken, { lastSeq });
 
 // Any other authorized principal attaches without a token -- ownership
 // or an ACL grant is enough:
@@ -374,6 +524,11 @@ await client.detach(session.sessionId);   // leave it running server-side
 await client.listRemoteSessions();        // sessions this key can see
 ```
 
+`@johnhenry/wsh/server` implements all of it with its [`sessions`
+option](#sessions-attach--resume--detach). The Rust `wsh-server` replays its whole
+ring on `Resume` regardless of `last_seq` (the position is defined in
+[spec/wsh-v1.md](spec/wsh-v1.md)).
+
 ## Pinning a Self-Signed Certificate
 
 Both transports normally need a certificate a public certificate authority
@@ -516,7 +671,8 @@ than left to be found.
 | Install an authorized key | `WshClient.addAuthorizedKey()` | `wsh_client::WshClient::add_authorized_key()`, `wsh copy-id` | **Wire-unified** (wsh #59): `AuthorizedKeyAdd`/`AuthorizedKeyResult`, replacing a Rust-CLI-only shell command with a message every implementation can send |
 | 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 |
-| 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 |
+| 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()`; `@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.20.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/client.mjs

@@ -244,6 +244,15 @@ export class WshClient {
   /** @type {Map<number, WshSession>} Active sessions keyed by channel ID. */
   #sessions = new Map();
 
+  /**
+   * In-flight attachSession()/resumeSession() calls awaiting the Presence
+   * that answers them. Like #pendingOpens, matched synchronously in
+   * #handleControl so the WshSession exists before the replay (which the
+   * host sends right behind the Presence) is dispatched.
+   * @type {Array<{sessionId: string, token?: Uint8Array}>}
+   */
+  #pendingAttaches = [];
+
   /**
    * FIFO queue of in-flight openSession() calls awaiting the next
    * OPEN_OK/OPEN_FAIL. Handled as a dedicated synchronous case in
@@ -743,27 +752,50 @@ export class WshClient {
    * @param {boolean} [opts.readOnly=false] - Attach in read-only mode
    * @param {Uint8Array} [opts.token] - Session-scoped token (optional; see above)
    * @param {number} [opts.timeout] - Timeout in ms
-   * @returns {Promise<object>} Server's PRESENCE response
+   * @returns {Promise<object>} Server's PRESENCE response. Against a host that
+   *   assigns the attachment a channel (`@johnhenry/wsh/server` with `sessions`)
+   *   the response also has a non-enumerable `session`: a message-backed
+   *   `WshSession` receiving the replay and live output (`onData`, `write()`,
+   *   `resize()`, `onExit`), whose `seq` is the position to resume from next time.
    */
   async attachSession(targetSessionId, { readOnly = false, token, timeout = DEFAULT_OPEN_TIMEOUT } = {}) {
     this.#assertAuthenticated('attachSession');
 
     const attachMode = readOnly ? 'readonly' : 'control';
-    await this.#transport.sendControl(
-      attachMsg({ sessionId: targetSessionId, token, mode: attachMode })
+    return this.#attachOrResume(
+      targetSessionId, token, attachMsg({ sessionId: targetSessionId, token, mode: attachMode }),
+      timeout, 'attach', 'Failed to attach',
     );
+  }
 
-    const response = await this.#waitForMessage(
-      [MSG.PRESENCE, MSG.ERROR],
-      timeout,
-      'Timed out waiting for attach response'
-    );
+  /**
+   * Send an Attach/Resume and wait for the Presence that answers it.
+   * @private
+   */
+  async #attachOrResume(sessionId, token, msg, timeout, what, failure) {
+    const pending = { sessionId, token };
+    this.#pendingAttaches.push(pending);
+    try {
+      await this.#transport.sendControl(msg);
 
-    if (response.type === MSG.ERROR) {
-      throw new Error(`Failed to attach: ${response.message || 'rejected'}`);
-    }
+      const response = await this.#waitForMessage(
+        [MSG.PRESENCE, MSG.ERROR],
+        timeout,
+        `Timed out waiting for ${what} response`,
+        // A roster Presence about some other session this connection is in is not the answer.
+        (m) => m.type === MSG.ERROR || !Array.isArray(m.attachments) || m.attachments.length === 0
+          || m.attachments.some((a) => a?.session_id === sessionId),
+      );
 
-    return response;
+      if (response.type === MSG.ERROR) {
+        throw new Error(`${failure}: ${response.message || 'rejected'}`);
+      }
+
+      return response;
+    } finally {
+      const i = this.#pendingAttaches.indexOf(pending);
+      if (i !== -1) this.#pendingAttaches.splice(i, 1);
+    }
   }
 
   /**
@@ -779,28 +811,22 @@ export class WshClient {
    * @param {string} targetSessionId - Session ID to resume
    * @param {Uint8Array} token - Session-scoped resume token (see `WshSession.resumeToken`)
    * @param {object} [opts]
-   * @param {number} [opts.lastSeq=0] - Last sequence number this client already has (currently advisory -- the ring buffer replays its full contents regardless)
+   * @param {number} [opts.lastSeq=0] - Cumulative session output bytes this
+   *   client has already received (`WshSession.seq` of the session it lost).
+   *   A host with a bounded history replays only what follows and refuses a
+   *   position older than it still holds (use `attachSession()` then); the Rust
+   *   `wsh-server` ignores it and replays its whole ring.
    * @param {number} [opts.timeout=10000] - Timeout in ms
-   * @returns {Promise<object>} Server's PRESENCE response
+   * @returns {Promise<object>} Server's PRESENCE response, with a non-enumerable
+   *   `session` exactly as for `attachSession()`.
    */
   async resumeSession(targetSessionId, token, { lastSeq = 0, timeout = DEFAULT_OPEN_TIMEOUT } = {}) {
     this.#assertAuthenticated('resumeSession');
 
-    await this.#transport.sendControl(
-      resumeMsg({ sessionId: targetSessionId, token, lastSeq })
-    );
-
-    const response = await this.#waitForMessage(
-      [MSG.PRESENCE, MSG.ERROR],
-      timeout,
-      'Timed out waiting for resume response'
+    return this.#attachOrResume(
+      targetSessionId, token, resumeMsg({ sessionId: targetSessionId, token, lastSeq }),
+      timeout, 'resume', 'Failed to resume',
     );
-
-    if (response.type === MSG.ERROR) {
-      throw new Error(`Failed to resume: ${response.message || 'rejected'}`);
-    }
-
-    return response;
   }
 
   /**
@@ -2390,6 +2416,28 @@ export class WshClient {
       return;
     }
 
+    // The Presence answering this connection's own Attach/Resume names the
+    // channel the host assigned (see AttachmentInfo.channel_id): build the
+    // session now, synchronously, so the replay right behind it finds it.
+    if (type === MSG.PRESENCE && this.#pendingAttaches.length > 0) {
+      const own = Array.isArray(msg.attachments)
+        ? msg.attachments.find((a) => a?.channel_id !== undefined && this.#pendingAttaches.some((p) => p.sessionId === a.session_id))
+        : undefined;
+      if (own) {
+        const pending = this.#pendingAttaches.find((p) => p.sessionId === own.session_id);
+        const session = new WshSession(this.#transport, own.channel_id, {}, 'pty', {
+          dataMode: 'virtual',
+          capabilities: ['resize', 'signal'],
+          sessionId: own.session_id,
+          resumeToken: pending.token,
+        });
+        session._setSeq(Number.isSafeInteger(own.seq) ? own.seq : 0);
+        this.#sessions.set(own.channel_id, session);
+        session._activateVirtual((m) => this.sendRelayControl(m));
+        Object.defineProperty(msg, 'session', { value: session, enumerable: false });
+      }
+    }
+
     // First, check if any waiters are listening for this message type.
     // A waiter carrying a `match` predicate only takes messages it claims,
     // so the queue is scanned rather than shifted blindly.

package/src/index.d.ts

@@ -1416,6 +1416,13 @@ export class WshSession {
    */
   readonly resumeToken: Uint8Array | undefined;
 
+  /**
+   * Cumulative session output bytes received so far -- the host's `seq` for
+   * the next byte. Pass it as `lastSeq` to `WshClient.resumeSession()`.
+   * Absolute for a session obtained from `attachSession()`/`resumeSession()`.
+   */
+  readonly seq: number;
+
   /** Called when stdout/stderr data arrives. */
   onData: ((data: Uint8Array) => void) | null;
 
@@ -1621,6 +1628,14 @@ export interface WshOpenSessionOptions {
   primer?: boolean;
 }
 
+/**
+ * The Presence answering `attachSession()` / `resumeSession()`. Against a host
+ * that assigns the attachment a channel (`@johnhenry/wsh/server` with `sessions`),
+ * `session` -- non-enumerable -- is the message-backed `WshSession` receiving
+ * the replay and live output.
+ */
+export type WshAttachResponse = WshMessage & { readonly session?: WshSession };
+
 /** Options for WshClient.attachSession(). */
 export interface WshAttachSessionOptions {
   readOnly?: boolean;
@@ -1637,7 +1652,12 @@ export interface WshAttachSessionOptions {
 
 /** Options for WshClient.resumeSession(). */
 export interface WshResumeSessionOptions {
-  /** Last sequence number this client already has (currently advisory). */
+  /**
+   * Cumulative session output bytes this client already has (`WshSession.seq`
+   * of the session it lost). A host with a bounded history replays only what
+   * follows and refuses a position older than it still holds; the Rust
+   * `wsh-server` ignores it and replays its whole ring. Default 0.
+   */
   lastSeq?: number;
   timeout?: number;
 }
@@ -1851,13 +1871,13 @@ export class WshClient {
    * already owning/being ACL-granted access to `targetSessionId`
    * server-side -- see `WshAttachSessionOptions.token`.
    */
-  attachSession(targetSessionId: string, opts?: WshAttachSessionOptions): Promise<WshMessage>;
+  attachSession(targetSessionId: string, opts?: WshAttachSessionOptions): Promise<WshAttachResponse>;
 
   /**
    * Resume a previously disconnected session. Unlike `attachSession()`,
    * `token` is required and verified unconditionally server-side.
    */
-  resumeSession(targetSessionId: string, token: Uint8Array, opts?: WshResumeSessionOptions): Promise<WshMessage>;
+  resumeSession(targetSessionId: string, token: Uint8Array, opts?: WshResumeSessionOptions): Promise<WshAttachResponse>;
 
   /**
    * Detach from a remote session, leaving it running server-side.

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,
+  };
+}