@johnhenry/wsh 0.16.1 → 0.17.1

package/src/control-listener.mjs

@@ -0,0 +1,130 @@
+/**
+ * Control-message subscription for the helper classes that compose their
+ * own wire messages — `WshMcpBridge` and `WshFileTransfer`.
+ *
+ * Both accept "a WshClient, or any object exposing sendControl() plus a
+ * way to observe inbound control messages", and both used to inline the
+ * same three-way registration. The third branch of it — the fallback for
+ * an object whose only hook is a settable `onControl` property, which is
+ * what a bare `WshTransport` is — wrapped that property and **never
+ * unwrapped it**:
+ *
+ * ```js
+ * const prev = client.onControl;
+ * client.onControl = (msg) => { prev?.(msg); listener(msg); };
+ * ```
+ *
+ * The matching `cleanup()` handled `removeControlListener` and
+ * `_controlListeners` and did nothing at all for this branch. So every
+ * `discover()` / `call()` / `list()` left another wrapper permanently in
+ * the chain. Measured against a real `WshTransport`, the number of frames
+ * an inbound control message traverses to reach the connection's own
+ * handler grew one-for-one with the number of operations — 1, 5, 20 and
+ * 50 operations gave 5, 9, 24 and 54 frames — with no ceiling.
+ *
+ * Attaching once per subscriber and detaching on cleanup keeps that flat.
+ */
+
+/**
+ * Subscribe `listener` to a client's inbound control messages.
+ *
+ * Supports, in order of preference:
+ *  1. `addControlListener()` / `removeControlListener()` — what `WshClient`
+ *     exposes, and the only shape that can deregister cleanly.
+ *  2. A `_controlListeners` array.
+ *  3. A settable `onControl` property (a bare `WshTransport`), wrapped
+ *     once and restored on detach.
+ *
+ * @param {object} client
+ * @param {function(object): void} listener
+ * @returns {function(): void} detach — idempotent; safe to call twice.
+ */
+export function attachControlListener(client, listener) {
+  if (typeof client.addControlListener === 'function') {
+    client.addControlListener(listener);
+    let detached = false;
+    return () => {
+      if (detached) return;
+      detached = true;
+      client.removeControlListener?.(listener);
+    };
+  }
+
+  if (Array.isArray(client._controlListeners)) {
+    client._controlListeners.push(listener);
+    let detached = false;
+    return () => {
+      if (detached) return;
+      detached = true;
+      const idx = client._controlListeners.indexOf(listener);
+      if (idx !== -1) client._controlListeners.splice(idx, 1);
+    };
+  }
+
+  // Fallback: wrap `onControl`. Restoring `prev` is only correct while our
+  // wrapper is still the installed handler — if something else has wrapped
+  // it since, putting `prev` back would drop that handler. In that case the
+  // wrapper stays but is made inert, so the chain stops growing per
+  // operation even though this one link cannot be spliced out.
+  const prev = client.onControl;
+  let live = true;
+  const wrapper = (msg) => {
+    prev?.(msg);
+    if (live) listener(msg);
+  };
+  client.onControl = wrapper;
+
+  let detached = false;
+  return () => {
+    if (detached) return;
+    detached = true;
+    live = false;
+    if (client.onControl === wrapper) client.onControl = prev;
+  };
+}
+
+/**
+ * Wait for the first inbound control message matching `predicate`.
+ *
+ * @param {object} client
+ * @param {function(object): boolean} predicate
+ * @param {number} timeoutMs
+ * @param {string} label - Used in the timeout message.
+ * @returns {Promise<object>}
+ */
+export function waitForControlMessage(client, predicate, timeoutMs, label) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let detach = () => {};
+    let timer = null;
+
+    const cleanup = () => {
+      settled = true;
+      if (timer !== null) clearTimeout(timer);
+      detach();
+    };
+
+    // `detach` is assigned after attach() returns, but a client that
+    // dispatches synchronously from inside attach() would fire the
+    // listener first — hence the `settled` guard rather than relying on
+    // detach() having been wired up.
+    detach = attachControlListener(client, (msg) => {
+      if (settled) return;
+      let matches = false;
+      try {
+        matches = predicate(msg);
+      } catch {
+        matches = false;
+      }
+      if (!matches) return;
+      cleanup();
+      resolve(msg);
+    });
+
+    timer = setTimeout(() => {
+      if (settled) return;
+      cleanup();
+      reject(new Error(`${label} timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+  });
+}

package/src/e2e-frame.mjs

@@ -138,13 +138,44 @@ export async function sealFrame(key, sessionId, roleTag, counter, plaintext) {
  * @param {{nonce: Uint8Array, ciphertext: Uint8Array}} frame
  * @returns {Promise<Uint8Array>} plaintext
  */
-export async function openFrame(key, sessionId, expectedCounter, { nonce, ciphertext }) {
+export async function openFrame(key, sessionId, expectedCounter, { nonce, ciphertext, expectedRoleTag }) {
   if (!key || typeof key !== 'object') {
     throw new Error('e2e-frame: openFrame requires a CryptoKey');
   }
   if (!(nonce instanceof Uint8Array) || nonce.length !== NONCE_LENGTH) {
     throw new Error(`e2e-frame: nonce must be a ${NONCE_LENGTH}-byte Uint8Array`);
   }
+  /*
+   * The role tag is REQUIRED, and a caller that omits it gets an error rather
+   * than a skipped check.
+   *
+   * The tag exists so the two directions of one session are structurally
+   * distinguishable -- it is the reason a colliding nonce is impossible when
+   * both directions share one AES-GCM key. WshSession computed the peer's
+   * expected tag and stored it, and nothing ever read it: `grep -rn
+   * e2eRecvRoleTag` returned the declaration and the assignment and no third
+   * line. So the receiver accepted a frame sealed with its OWN tag, and the
+   * relay this layer exists to distrust could echo a peer's sealed frame
+   * straight back at it. Both counters start at zero, so the first frame of a
+   * session reflects cleanly.
+   *
+   * Optional would have reproduced the defect: a security check nobody is
+   * forced to pass is the same as no check, and this file already had one --
+   * see TimestampProof.verify's ignored verifyFn for the same shape.
+   */
+  if (!(expectedRoleTag instanceof Uint8Array) || expectedRoleTag.length !== ROLE_TAG_LENGTH) {
+    throw new Error(
+      `e2e-frame: openFrame requires expectedRoleTag, a ${ROLE_TAG_LENGTH}-byte Uint8Array`
+    );
+  }
+  const actualRoleTag = nonce.subarray(COUNTER_LENGTH);
+  for (let i = 0; i < ROLE_TAG_LENGTH; i += 1) {
+    if (actualRoleTag[i] !== expectedRoleTag[i]) {
+      throw new Error(
+        'e2e-frame: role tag mismatch -- this frame was sealed by the wrong side of the session'
+      );
+    }
+  }
   const actualCounter = Number(new DataView(nonce.buffer, nonce.byteOffset, nonce.byteLength).getBigUint64(0, false));
   if (actualCounter !== expectedCounter) {
     throw new Error(

package/src/file-transfer.mjs

@@ -3,33 +3,36 @@
  *
  * Uploads and downloads delegate to the underlying client's upload()/
  * download() (FileChunk control messages over a 'file'-kind channel —
- * see client.mjs). list() is a separate helper that runs `ls -la` over
- * a plain exec channel.
+ * see client.mjs). list() (wsh #59) delegates to the client's fileList(),
+ * which sends a structured FileOp{op:"list"} and reads the typed
+ * FileResult.entries -- the same wire path upload/download already use
+ * for moving bytes, now extended to directory listings.
+ *
+ * Before wsh #59, list() ran `ls -la` over a plain exec channel and
+ * parsed the text output client-side -- a private, JS-only convention
+ * the Rust client had no equivalent of at all (see wsh #58/#59, and the
+ * FileEntry nested type in spec/wsh-v1.yaml this now shares with Rust).
  */
 
-import { MSG, open, CHANNEL_KIND } from './messages.mjs';
-
 /** Default timeout for waiting on control messages (30 seconds). */
 const RESPONSE_TIMEOUT_MS = 30_000;
 
 export class WshFileTransfer {
   /**
    * @type {{
-   *   upload: function, download: function,
-   *   sendControl: function, openStream: function, onControl: function,
+   *   upload: function, download: function, fileList: function,
    * }}
    */
   #client;
 
   /**
-   * @param {object} client - A WshClient (or any object exposing upload()/
-   *   download() with the same signatures — those are used directly for
-   *   upload/download). list() additionally needs, for the underlying exec
-   *   channel it runs `ls -la` over:
-   *   - sendControl(msg): send a control message
-   *   - openStream(): open a new bidirectional stream
-   *   - onControl: settable callback for incoming control messages
-   *     (or a method to add a listener — see _waitForMessage)
+   * @param {object} client - A WshClient (or any object exposing the same
+   *   methods used below). `upload()`/`download()` are used directly for
+   *   file transfer; `list()` uses `fileList()` (the structured
+   *   FileOp/FileResult request-response helper already on WshClient).
+   *   Each method checks for the members it specifically needs, so a
+   *   client exposing only `upload()`/`download()` (and nothing else)
+   *   stays valid for those two calls.
    */
   constructor(client) {
     if (!client) throw new Error('WshFileTransfer requires a client');
@@ -92,195 +95,47 @@ export class WshFileTransfer {
   }
 
   /**
-   * List files at a remote path by executing `ls -la` via the client.
+   * List files at a remote path over the structured file channel (wsh #59):
+   * sends `FileOp{op:"list"}` via the client's `fileList()` and reads the
+   * typed `FileResult.entries` -- the same `FileEntry` shape
+   * `crates/wsh-core`'s Rust client is generated from, so a symlink can't
+   * be reported as a plain file here and correctly here-and-there.
    *
-   * This uses a standard exec channel rather than the file transfer protocol,
-   * parsing the output of `ls -la` into structured entries.
+   * A refusal (unimplemented op, unauthorized fs capability, no such
+   * directory) throws -- it is never coerced into an empty array, so a
+   * caller can't mistake "refused" for "empty directory" (wsh #58).
    *
    * @param {string} remotePath - Directory path on the remote host
-   * @returns {Promise<Array<{ name: string, size: number, modified: string, type: string }>>}
+   * @param {object} [opts]
+   * @param {number} [opts.timeout] - Timeout in ms for the server response
+   * @returns {Promise<Array<{
+   *   name: string, size: number, modified: Date,
+   *   type: 'file'|'directory'|'symlink'|'device'|'pipe'|'socket',
+   *   symlinkTarget?: string,
+   * }>>}
    */
-  async list(remotePath) {
+  async list(remotePath, { timeout = RESPONSE_TIMEOUT_MS } = {}) {
     if (!remotePath || typeof remotePath !== 'string') {
       throw new Error('remotePath is required');
     }
-
-    // Use an exec channel to run ls
-    const openMsg = open({
-      kind: CHANNEL_KIND.EXEC,
-      command: `ls -la ${this._shellEscape(remotePath)}`,
-    });
-
-    await this.#client.sendControl(openMsg);
-
-    const response = await this._waitForMessage(
-      (msg) => msg.type === MSG.OPEN_OK || msg.type === MSG.OPEN_FAIL,
-      RESPONSE_TIMEOUT_MS
-    );
-
-    if (response.type === MSG.OPEN_FAIL) {
-      throw new Error(`List failed: ${response.reason || 'unknown reason'}`);
-    }
-
-    // Read the output stream
-    const stream = await this.#client.openStream();
-    const reader = stream.readable.getReader();
-    const chunks = [];
-
-    try {
-      while (true) {
-        const { done, value } = await reader.read();
-        if (done) break;
-        chunks.push(value);
-      }
-    } finally {
-      reader.releaseLock();
-    }
-
-    const output = new TextDecoder().decode(this._concatChunks(chunks));
-    return this._parseLsOutput(output);
-  }
-
-  // ── Internal helpers ──────────────────────────────────────────────
-
-  /**
-   * Wait for a control message matching a predicate.
-   *
-   * Temporarily hooks into the client's control message flow and resolves
-   * when a matching message arrives (or rejects on timeout).
-   *
-   * @param {function(object): boolean} predicate
-   * @param {number} timeoutMs
-   * @returns {Promise<object>}
-   */
-  _waitForMessage(predicate, timeoutMs) {
-    return new Promise((resolve, reject) => {
-      let timer = null;
-      let settled = false;
-
-      const cleanup = () => {
-        settled = true;
-        if (timer !== null) clearTimeout(timer);
-        // Remove listener
-        if (this.#client.removeControlListener) {
-          this.#client.removeControlListener(listener);
-        } else if (this.#client._controlListeners) {
-          const idx = this.#client._controlListeners.indexOf(listener);
-          if (idx !== -1) this.#client._controlListeners.splice(idx, 1);
-        }
-      };
-
-      const listener = (msg) => {
-        if (settled) return;
-        if (predicate(msg)) {
-          cleanup();
-          resolve(msg);
-        }
-      };
-
-      // Register listener on the client
-      if (this.#client.addControlListener) {
-        this.#client.addControlListener(listener);
-      } else if (this.#client._controlListeners) {
-        this.#client._controlListeners.push(listener);
-      } else {
-        // Fallback: wrap existing onControl
-        const prev = this.#client.onControl;
-        this.#client.onControl = (msg) => {
-          prev?.(msg);
-          listener(msg);
-        };
-      }
-
-      timer = setTimeout(() => {
-        if (!settled) {
-          cleanup();
-          reject(new Error(`Timeout waiting for response (${timeoutMs}ms)`));
-        }
-      }, timeoutMs);
-    });
-  }
-
-  /**
-   * Concatenate an array of Uint8Arrays into one.
-   *
-   * @param {Uint8Array[]} chunks
-   * @param {number} [totalLength] - Pre-computed total, avoids re-summing
-   * @returns {Uint8Array}
-   */
-  _concatChunks(chunks, totalLength) {
-    if (chunks.length === 0) return new Uint8Array(0);
-    if (chunks.length === 1) return chunks[0];
-
-    const total = totalLength ?? chunks.reduce((sum, c) => sum + c.length, 0);
-    const result = new Uint8Array(total);
-    let offset = 0;
-    for (const chunk of chunks) {
-      result.set(chunk, offset);
-      offset += chunk.length;
+    if (typeof this.#client.fileList !== 'function') {
+      throw new TypeError(
+        'WshFileTransfer.list() requires a client exposing fileList() (e.g. WshClient)'
+      );
     }
-    return result;
-  }
-
-  /**
-   * Parse the output of `ls -la` into structured entries.
-   *
-   * Expected format per line:
-   *   drwxr-xr-x 2 user group  4096 Jan 15 12:00 dirname
-   *   -rw-r--r-- 1 user group 12345 Jan 15 12:00 filename.txt
-   *
-   * @param {string} output
-   * @returns {Array<{ name: string, size: number, modified: string, type: string }>}
-   */
-  _parseLsOutput(output) {
-    const lines = output.split('\n').filter((l) => l.trim());
-    const entries = [];
-
-    for (const line of lines) {
-      // Skip the "total" header line
-      if (line.startsWith('total ')) continue;
-
-      // ls -la columns: perms links owner group size month day time name
-      const parts = line.split(/\s+/);
-      if (parts.length < 9) continue;
 
-      const perms = parts[0];
-      const size = parseInt(parts[4], 10) || 0;
-      const month = parts[5];
-      const day = parts[6];
-      const time = parts[7];
-      // Name may contain spaces — rejoin everything from column 8 onward
-      const name = parts.slice(8).join(' ');
+    const result = await this.#client.fileList(remotePath, timeout);
 
-      // Skip . and .. entries
-      if (name === '.' || name === '..') continue;
-
-      // Determine type from permission string first character
-      let type = 'file';
-      if (perms.startsWith('d')) type = 'directory';
-      else if (perms.startsWith('l')) type = 'symlink';
-      else if (perms.startsWith('c') || perms.startsWith('b')) type = 'device';
-      else if (perms.startsWith('p')) type = 'pipe';
-      else if (perms.startsWith('s')) type = 'socket';
-
-      entries.push({
-        name,
-        size,
-        modified: `${month} ${day} ${time}`,
-        type,
-      });
+    if (!result.success) {
+      throw new Error(result.error_message || `List failed: refused for ${remotePath}`);
     }
 
-    return entries;
-  }
-
-  /**
-   * Basic shell escaping for a path argument.
-   * @param {string} str
-   * @returns {string}
-   */
-  _shellEscape(str) {
-    // Wrap in single quotes, escaping any embedded single quotes
-    return "'" + str.replace(/'/g, "'\\''") + "'";
+    return (result.entries || []).map((entry) => ({
+      name: entry.name,
+      size: entry.size,
+      modified: new Date(entry.modified * 1000),
+      type: entry.type,
+      ...(entry.symlink_target !== undefined ? { symlinkTarget: entry.symlink_target } : {}),
+    }));
   }
 }