@johnhenry/wsh 0.0.0 → 0.3.0

package/README.md

@@ -1,5 +1,7 @@
 # wsh-upon-star
 
+Full documentation: [opensource.johnhenry.me/wsh](https://opensource.johnhenry.me/wsh/)
+
 > Previously published as `wsh-upon-star` (last release: 0.1.1, now deprecated).
 > Renamed to `@johnhenry/wsh` and restarted at 0.0.0 on import into the
 > @johnhenry family — a new name and era, not a maturity signal.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnhenry/wsh",
-  "version": "0.0.0",
+  "version": "0.3.0",
   "description": "Web Shell \u2014 browser-native remote command execution over WebTransport and WebSocket with Ed25519 authentication",
   "type": "module",
   "main": "./src/index.mjs",
@@ -14,7 +14,13 @@
     "README.md"
   ],
   "scripts": {
-    "test": "node --test test/*.test.mjs"
+    "test": "node --test test/*.test.mjs",
+    "examples": "for f in examples/0*.mjs; do echo \"== $f\" && node \"$f\" || exit 1; done",
+    "example:01": "node examples/01-frames-survive-fragmented-transport.mjs",
+    "example:02": "node examples/02-tampered-challenge-fails-authentication.mjs",
+    "example:03": "node examples/03-handshake-to-exec-over-in-process-pipe.mjs",
+    "example:04": "node examples/04-recording-replays-with-original-timing.mjs",
+    "example:05": "node examples/05-remote-mcp-tools-called-through-bridge.mjs"
   },
   "keywords": [
     "wsh",

package/src/auth.mjs

@@ -110,27 +110,62 @@ export async function verify(publicKey, signature, data) {
 
 // ── Authentication Transcript ─────────────────────────────────────────
 
+/**
+ * Length-prefix a byte string with a 4-byte big-endian length, so two
+ * variable-length fields concatenated in sequence can't collide (e.g.
+ * username="ab", session="c" must hash differently from username="a",
+ * session="bc").
+ * @param {Uint8Array} bytes
+ * @returns {Uint8Array}
+ */
+function lengthPrefixed(bytes) {
+  const out = new Uint8Array(4 + bytes.length);
+  new DataView(out.buffer).setUint32(0, bytes.length);
+  out.set(bytes, 4);
+  return out;
+}
+
 /**
  * Build the authentication transcript hash for challenge-response signing.
  *
- * transcript = SHA-256("wsh-v1\0" || session_id || nonce || channel_binding)
+ * transcript = SHA-256(
+ *   "wsh-v1\0" || lp(username) || lp(session_id) || nonce || channel_binding
+ * )
+ *
+ * `username` is bound so a signature produced for one username can't be
+ * replayed/relabeled as another. `session_id` and `username` are each
+ * length-prefixed (lp) since both are variable-length.
+ *
+ * `channelBinding` is reserved for a transport-layer identity binding (e.g.
+ * a TLS exporter value) — no caller currently populates it. Note this is
+ * NOT currently a binding to the *server's* identity: the protocol has no
+ * server host-identity concept today (SERVER_HELLO.fingerprints lists
+ * client keys the server authorizes, not the server's own key), and TLS
+ * exporter values aren't obtainable from a browser WebSocket/WebTransport
+ * client at all. See the wsh-modernization tracking issue for the
+ * follow-up covering server host-identity + TOFU pinning.
  *
  * @param {string} sessionId
  * @param {Uint8Array} nonce - 32-byte server nonce
- * @param {Uint8Array} [channelBinding] - Optional TLS channel binding
+ * @param {object} [opts]
+ * @param {string} [opts.username] - Username this transcript is bound to
+ * @param {Uint8Array} [opts.channelBinding] - Optional transport-layer binding
  * @returns {Promise<Uint8Array>} 32-byte SHA-256 hash
  */
-export async function buildTranscript(sessionId, nonce, channelBinding = new Uint8Array(0)) {
+export async function buildTranscript(sessionId, nonce, { username = '', channelBinding = new Uint8Array(0) } = {}) {
   const enc = new TextEncoder();
   const versionBytes = enc.encode(PROTOCOL_VERSION + '\0');
-  const sessionBytes = enc.encode(sessionId);
+  const usernameField = lengthPrefixed(enc.encode(username));
+  const sessionField = lengthPrefixed(enc.encode(sessionId));
 
-  const total = versionBytes.length + sessionBytes.length + nonce.length + channelBinding.length;
+  const total = versionBytes.length + usernameField.length + sessionField.length
+    + nonce.length + channelBinding.length;
   const data = new Uint8Array(total);
   let offset = 0;
 
   data.set(versionBytes, offset); offset += versionBytes.length;
-  data.set(sessionBytes, offset); offset += sessionBytes.length;
+  data.set(usernameField, offset); offset += usernameField.length;
+  data.set(sessionField, offset); offset += sessionField.length;
   data.set(nonce, offset); offset += nonce.length;
   data.set(channelBinding, offset);
 
@@ -148,11 +183,13 @@ export async function buildTranscript(sessionId, nonce, channelBinding = new Uin
  * @param {CryptoKey} publicKey
  * @param {string} sessionId
  * @param {Uint8Array} nonce
- * @param {Uint8Array} [channelBinding]
+ * @param {object} [opts]
+ * @param {string} [opts.username]
+ * @param {Uint8Array} [opts.channelBinding]
  * @returns {Promise<{ signature: Uint8Array, publicKeyRaw: Uint8Array }>}
  */
-export async function signChallenge(privateKey, publicKey, sessionId, nonce, channelBinding) {
-  const transcript = await buildTranscript(sessionId, nonce, channelBinding);
+export async function signChallenge(privateKey, publicKey, sessionId, nonce, opts) {
+  const transcript = await buildTranscript(sessionId, nonce, opts);
   const [signature, publicKeyRaw] = await Promise.all([
     sign(privateKey, transcript),
     exportPublicKeyRaw(publicKey),
@@ -167,11 +204,13 @@ export async function signChallenge(privateKey, publicKey, sessionId, nonce, cha
  * @param {Uint8Array} signature
  * @param {string} sessionId
  * @param {Uint8Array} nonce
- * @param {Uint8Array} [channelBinding]
+ * @param {object} [opts]
+ * @param {string} [opts.username]
+ * @param {Uint8Array} [opts.channelBinding]
  * @returns {Promise<boolean>}
  */
-export async function verifyChallenge(publicKey, signature, sessionId, nonce, channelBinding) {
-  const transcript = await buildTranscript(sessionId, nonce, channelBinding);
+export async function verifyChallenge(publicKey, signature, sessionId, nonce, opts) {
+  const transcript = await buildTranscript(sessionId, nonce, opts);
   return verify(publicKey, signature, transcript);
 }
 

package/src/cbor.mjs

@@ -330,16 +330,57 @@ export function frameEncode(value) {
   return frame;
 }
 
+/**
+ * Default cap on a single frame's claimed payload length (16 MiB).
+ *
+ * This channel only ever carries CBOR control-message metadata (session
+ * lists, MCP tool results, recording-export/command-journal entries,
+ * etc.) — bulk data such as file transfers and PTY output travel over
+ * separate raw data streams with their own small chunking, not through
+ * this decoder. 16 MiB is generous headroom for legitimate control
+ * payloads while still bounding memory far below the 4 GiB a hostile or
+ * buggy peer could otherwise claim via the 32-bit length prefix.
+ */
+export const DEFAULT_MAX_FRAME_SIZE = 16 * 1024 * 1024;
+
+/**
+ * Thrown by {@link FrameDecoder#feed} when a frame's claimed length
+ * exceeds the decoder's configured maximum.
+ */
+export class FrameSizeError extends Error {
+  constructor(len, maxFrameSize) {
+    super(`Frame claims length ${len}, which exceeds the maximum of ${maxFrameSize} bytes`);
+    this.name = 'FrameSizeError';
+    this.len = len;
+    this.maxFrameSize = maxFrameSize;
+  }
+}
+
 /**
  * Streaming frame decoder. Feed it chunks and it yields complete messages.
  */
 export class FrameDecoder {
   #buffer = new Uint8Array(0);
+  #maxFrameSize;
+
+  /**
+   * @param {object} [opts]
+   * @param {number} [opts.maxFrameSize] - Maximum allowed claimed frame
+   *   length, in bytes. Frames claiming more than this are rejected as
+   *   soon as their length prefix is parsed, before any payload bytes
+   *   are buffered. Defaults to {@link DEFAULT_MAX_FRAME_SIZE}.
+   */
+  constructor({ maxFrameSize = DEFAULT_MAX_FRAME_SIZE } = {}) {
+    this.#maxFrameSize = maxFrameSize;
+  }
 
   /**
    * Feed bytes and return decoded messages.
    * @param {Uint8Array} chunk
    * @returns {Array} decoded JS values
+   * @throws {FrameSizeError} if a frame's claimed length exceeds the
+   *   configured maximum. The decoder's buffer is cleared before
+   *   throwing; callers should treat this as fatal for the connection.
    */
   feed(chunk) {
     this.#buffer = appendBuffer(this.#buffer, chunk);
@@ -347,6 +388,12 @@ export class FrameDecoder {
     while (this.#buffer.length >= 4) {
       const view = new DataView(this.#buffer.buffer, this.#buffer.byteOffset, 4);
       const len = view.getUint32(0);
+      if (len > this.#maxFrameSize) {
+        // Reject before accumulating toward the (possibly huge) claimed
+        // length — do not wait for the payload to arrive.
+        this.#buffer = new Uint8Array(0);
+        throw new FrameSizeError(len, this.#maxFrameSize);
+      }
       if (this.#buffer.length < 4 + len) break;
       const payload = this.#buffer.slice(4, 4 + len);
       this.#buffer = this.#buffer.slice(4 + len);

package/src/client.mjs

@@ -362,7 +362,8 @@ export class WshClient {
             keyPair.privateKey,
             keyPair.publicKey,
             tempSessionId,
-            challengeMsg.nonce
+            challengeMsg.nonce,
+            { username }
           );
 
           await transport.sendControl(
@@ -388,14 +389,18 @@ export class WshClient {
         }
 
         // We need a session ID for the transcript. Use the nonce-derived ID
-        // or a placeholder if the server hasn't provided one.
-        tempSessionId = tempSessionId || 'pending';
+        // or a fresh random placeholder if the server hasn't provided one.
+        // (A fixed literal here would make the transcript's session-id
+        // component identical across every connection taking this path,
+        // leaving only the nonce to bind the signature to this connection.)
+        tempSessionId = tempSessionId || crypto.randomUUID();
 
         const { signature, publicKeyRaw } = await signChallenge(
           keyPair.privateKey,
           keyPair.publicKey,
           tempSessionId,
-          firstResponse.nonce
+          firstResponse.nonce,
+          { username }
         );
 
         await transport.sendControl(
@@ -1431,7 +1436,7 @@ export class WshClient {
           }
 
           const { signature, publicKeyRaw } = await signChallenge(
-            keyPair.privateKey, keyPair.publicKey, tempSessionId, challengeMsg.nonce
+            keyPair.privateKey, keyPair.publicKey, tempSessionId, challengeMsg.nonce, { username }
           );
 
           await this.#transport.sendControl(authMsg({
@@ -1445,9 +1450,11 @@ export class WshClient {
       } else if (firstResponse.type === MSG.CHALLENGE) {
         if (!keyPair) throw new Error('Server sent CHALLENGE but no key pair provided');
 
-        tempSessionId = tempSessionId || 'pending';
+        // See connect()'s CHALLENGE branch for why this must be random
+        // rather than a fixed literal.
+        tempSessionId = tempSessionId || crypto.randomUUID();
         const { signature, publicKeyRaw } = await signChallenge(
-          keyPair.privateKey, keyPair.publicKey, tempSessionId, firstResponse.nonce
+          keyPair.privateKey, keyPair.publicKey, tempSessionId, firstResponse.nonce, { username }
         );
 
         await this.#transport.sendControl(authMsg({

package/src/index.d.ts

@@ -27,12 +27,35 @@ export function cborDecode(data: Uint8Array): unknown;
  */
 export function frameEncode(value: unknown): Uint8Array;
 
+/**
+ * Default cap on a single frame's claimed payload length (16 MiB).
+ */
+export const DEFAULT_MAX_FRAME_SIZE: number;
+
+/**
+ * Thrown by FrameDecoder#feed when a frame's claimed length exceeds the
+ * decoder's configured maximum.
+ */
+export class FrameSizeError extends Error {
+  constructor(len: number, maxFrameSize: number);
+  readonly len: number;
+  readonly maxFrameSize: number;
+}
+
 /**
  * Streaming frame decoder. Feed it chunks and it yields complete messages.
  */
 export class FrameDecoder {
+  /**
+   * @param opts.maxFrameSize Maximum allowed claimed frame length in bytes.
+   *   Defaults to DEFAULT_MAX_FRAME_SIZE.
+   */
+  constructor(opts?: { maxFrameSize?: number });
+
   /**
    * Feed bytes and return decoded messages.
+   * @throws {FrameSizeError} if a frame's claimed length exceeds the
+   *   configured maximum.
    */
   feed(chunk: Uint8Array): unknown[];
 

package/src/index.mjs

@@ -6,7 +6,7 @@
  */
 
 // CBOR codec + framing
-export { cborEncode, cborDecode, frameEncode, FrameDecoder } from './cbor.mjs';
+export { cborEncode, cborDecode, frameEncode, FrameDecoder, FrameSizeError, DEFAULT_MAX_FRAME_SIZE } from './cbor.mjs';
 
 // Protocol messages
 export {

package/src/messages.gen.mjs

@@ -1,7 +1,7 @@
 /**
  * wsh protocol control message types and constructors.
  * AUTO-GENERATED from wsh-v1.yaml — do not edit.
- * Run: node web/packages/wsh/spec/codegen.mjs
+ * Run: node spec/codegen.mjs (from the @johnhenry/wsh repo root)
  */
 
 // ── Message type constants ────────────────────────────────────────────

package/src/transport-ws.mjs

@@ -15,10 +15,18 @@
  * Data streams carry raw bytes with no additional framing.
  */
 
-import { frameEncode, FrameDecoder } from './cbor.mjs';
+import { frameEncode, FrameDecoder, FrameSizeError } from './cbor.mjs';
 import { WshTransport } from './transport.mjs';
 
 // ── Frame type constants ─────────────────────────────────────────────
+//
+// NOTE: these are unrelated to MSG.WS_DATA (0x60) in messages.gen.mjs.
+// WS_DATA is a JS-only, CBOR-layer bookkeeping marker (it shares its
+// opcode with MSG.DETACH and is explicitly excluded from the Rust
+// message enum by spec/codegen.mjs) — it is never sent as the outer
+// envelope's frame-type byte below. See spec/wsh-v1.yaml's
+// `transport.websocket` section for the authoritative outer-envelope
+// framing docs.
 
 const FRAME_CONTROL      = 0x01;
 const FRAME_DATA         = 0x02;
@@ -198,6 +206,27 @@ export class WebSocketTransport extends WshTransport {
   /** Tracks whether we initiated the close. */
   #closedByUs = false;
 
+  /**
+   * Queue of raw inbound messages awaiting dispatch, plus a drain-in-progress
+   * flag. Needed because some `WebSocket` implementations (notably Node's
+   * `ws` package parsing several frames out of one TCP read) can fire
+   * multiple synchronous `message` events within a single JS task, all
+   * before any microtask gets to run. If we dispatched each message inline,
+   * a handler that resolves a pending waiter (e.g. SERVER_HELLO resolving
+   * the "wait for SERVER_HELLO or CHALLENGE" promise) wouldn't get a chance
+   * to run its `await`'d continuation — which registers the *next* waiter
+   * (e.g. for CHALLENGE) — before the next queued message arrives. That
+   * continuation is a microtask; a same-task, no-yield dispatch loop starves
+   * it, so the next message's waiter isn't registered yet and gets dropped.
+   * Draining the queue with an `await Promise.resolve()` between each
+   * message yields to the microtask queue after every dispatch, and since
+   * microtasks run FIFO, any continuation queued by handling message N
+   * (which runs first) completes before message N+1 is dispatched.
+   * @type {ArrayBuffer[]}
+   */
+  #messageQueue = [];
+  #draining = false;
+
   // ── Lifecycle ──────────────────────────────────────────────────────
 
   /** @override */
@@ -207,6 +236,8 @@ export class WebSocketTransport extends WshTransport {
     this.#nextLocalId = 1;
     this.#openResolvers.clear();
     this.#closedByUs = false;
+    this.#messageQueue.length = 0;
+    this.#draining = false;
 
     return new Promise((resolve, reject) => {
       // Normalize URL scheme: wsh:// → wss://, http:// → ws://.
@@ -234,7 +265,8 @@ export class WebSocketTransport extends WshTransport {
       });
 
       ws.addEventListener('message', (ev) => {
-        this.#handleMessage(ev.data);
+        this.#messageQueue.push(ev.data);
+        this.#drainMessageQueue();
       });
     });
   }
@@ -287,6 +319,29 @@ export class WebSocketTransport extends WshTransport {
 
   // ── Inbound message dispatch ───────────────────────────────────────
 
+  /**
+   * Drain `#messageQueue` one message at a time, yielding to the microtask
+   * queue between each dispatch. See the `#messageQueue` field doc for why:
+   * this is what lets a waiter registered by an earlier message's `await`
+   * continuation (e.g. registering the CHALLENGE waiter after SERVER_HELLO
+   * resolves) actually be in place before the next queued message arrives,
+   * even when the underlying WebSocket implementation delivered several
+   * messages synchronously in one task.
+   */
+  async #drainMessageQueue() {
+    if (this.#draining) return;
+    this.#draining = true;
+    try {
+      while (this.#messageQueue.length > 0) {
+        const raw = this.#messageQueue.shift();
+        this.#handleMessage(raw);
+        await Promise.resolve();
+      }
+    } finally {
+      this.#draining = false;
+    }
+  }
+
   /**
    * Handle a raw WebSocket message (ArrayBuffer).
    * @param {ArrayBuffer} raw
@@ -329,7 +384,18 @@ export class WebSocketTransport extends WshTransport {
    * @param {Uint8Array} payload
    */
   #handleControlFrame(payload) {
-    const messages = this.#decoder.feed(payload);
+    let messages;
+    try {
+      messages = this.#decoder.feed(payload);
+    } catch (err) {
+      this._emitError(err);
+      if (err instanceof FrameSizeError) {
+        // Oversized claimed frame length — treat as a hostile or badly
+        // broken peer and tear down the connection rather than continue.
+        this.close().catch(() => {});
+      }
+      return;
+    }
     for (const msg of messages) {
       this._emitControl(msg);
     }

package/src/transport.mjs

@@ -5,7 +5,7 @@
  * Data streams carry raw bytes with no framing overhead.
  */
 
-import { frameEncode, FrameDecoder, cborEncode } from './cbor.mjs';
+import { frameEncode, FrameDecoder, cborEncode, FrameSizeError } from './cbor.mjs';
 
 // ── Transport states ─────────────────────────────────────────────────
 
@@ -281,11 +281,29 @@ export class WebTransportTransport extends WshTransport {
         const messages = this.#decoder.feed(value);
         for (const msg of messages) {
           this._emitControl(msg);
+          // Yield to the microtask queue between messages. A QUIC stream
+          // has no per-message framing at the transport layer, so a single
+          // read() can return bytes for several messages at once (e.g.
+          // SERVER_HELLO immediately followed by CHALLENGE). Emitting them
+          // in a tight synchronous loop starves any `await`'d continuation
+          // triggered by handling an earlier message (e.g. registering the
+          // CHALLENGE waiter after SERVER_HELLO resolves) — that
+          // continuation is a microtask, and without a yield here it never
+          // gets to run before the next message is dispatched. Since
+          // microtasks run FIFO, a continuation queued while handling msg
+          // N always completes before this yield's own continuation
+          // resumes to dispatch msg N+1.
+          await Promise.resolve();
         }
       }
     } catch (err) {
       if (!this.#abort.signal.aborted) {
         this._emitError(new Error(`Control stream read error: ${err.message}`));
+        if (err instanceof FrameSizeError) {
+          // Oversized claimed frame length — treat as a hostile or badly
+          // broken peer and tear down the connection rather than continue.
+          this.close().catch(() => {});
+        }
       }
     } finally {
       reader.releaseLock();