@johnhenry/wsh 0.19.1 → 0.21.0

package/README.md

@@ -186,7 +186,139 @@ 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, MCP.
+mode.
+
+### 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
+
+`createWshServer({ mcp })` answers `McpDiscover` and `McpCall`, so the stock
+`client.discoverTools()` / `client.callTool()` and `WshMcpBridge` work against
+it. Off unless you pass it.
+
+```js
+const server = createWshServer({
+  auth,
+  mcp: {
+    tools: [{
+      name: 'read_note',
+      description: 'Read a note by id',
+      inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'], additionalProperties: false },
+      call: async ({ id }, { user, signal }) => ({ success: true, output: await readNote(id, { signal }) }),
+    }],
+    authorize: (user, tool) => tool.name !== 'admin_only' || user === 'root',   // optional
+    // client: mcpSdkClient,   // optional: proxy an @modelcontextprotocol/sdk Client's tools too
+    // maxConcurrent: 8, timeoutMs: 30_000,
+  },
+});
+```
+
+- **Tool shape:** `tools` is an array of `{ name, description, inputSchema,
+  call(args, { user, fingerprint, signal }) }` or a `{ name: { ... } }` map.
+  `inputSchema` is advertised to clients as `parameters` (the `McpToolSpec`
+  field).
+- **Arguments are untrusted.** They are validated against `inputSchema` before
+  `call()` runs; invalid arguments never reach the tool. The package has no
+  runtime dependencies, so the validator covers the keywords tool schemas use
+  (`type`, `enum`, `const`, `properties`, `required`, `additionalProperties`,
+  `items`, length/range/`pattern`/`multipleOf` bounds, `allOf`/`anyOf`/`oneOf`/
+  `not`, local `$ref`); a schema using any other keyword (`if`,
+  `patternProperties`, ...) is **refused when the server is created** rather than
+  silently enforced less strictly. Only tools you list are reachable.
+- **Results:** whatever `call()` returns is `McpResult.result` verbatim (the
+  stock `WshMcpBridge` normalizes the `{ success, output, error }` shape, and
+  wraps anything else as `{ success: true, output }`). A tool that throws, an
+  unknown tool, invalid arguments, a timeout or the concurrency cap all answer
+  `{ success: false, error }` -- the error text is the thrown `message`, so
+  throw messages you are happy for the caller to read.
+- **Correlation:** every `McpResult` echoes the call's `call_id`, and the
+  server advertises `mcp-call-id` (when `mcp` is configured), so concurrent
+  calls from one client get their own results, and a slow tool does not hold up
+  the calls behind it.
+- **Limits:** `maxConcurrent` in-flight calls per connection (default 8) and a
+  `timeoutMs` per call (default 30000). On timeout or disconnect the tool's
+  `signal` aborts; a tool that ignores it keeps running but its reply is dropped.
+- **Access:** discovery and calls are answered after authentication only.
+  `authorize(user, tool, { username, fingerprint })` filters both, and a tool
+  hidden from a caller is indistinguishable from one that does not exist.
+- **Proxying:** `client` takes anything with `listTools()` / `callTool()` (an
+  `@modelcontextprotocol/sdk` `Client`; this package does not import the SDK).
+  Its tools are re-listed on every discovery, validated against their own
+  `inputSchema`s here, and `isError` results become `{ success: false, error }`,
+  else the result is `structuredContent` or the `content` array. A proxied tool
+  whose schema uses an unsupported keyword is not exposed.
+- Without `mcp`, `McpDiscover` answers an empty list and `McpCall` an
+  `{ success: false, error: 'mcp is not enabled on this server' }` result.
 
 ### Host key (fingerprint / TOFU)
 
@@ -301,8 +433,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:
@@ -314,6 +447,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
@@ -456,6 +594,7 @@ 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 |
+| 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 |
 | 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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnhenry/wsh",
-  "version": "0.19.1",
+  "version": "0.21.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.