@johnhenry/wsh 0.2.0 → 0.4.0

package/package.json

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

@@ -357,11 +357,13 @@ export class WshClient {
             return this.#sessionId;
           }
 
-          // Sign the challenge.
+          // Sign the challenge. Challenge.session_id (not the one from
+          // ServerHello) is authoritative for the transcript — see the
+          // comment in the CHALLENGE-first branch below for why.
           const { signature, publicKeyRaw } = await signChallenge(
             keyPair.privateKey,
             keyPair.publicKey,
-            tempSessionId,
+            challengeMsg.session_id,
             challengeMsg.nonce,
             { username }
           );
@@ -388,17 +390,18 @@ export class WshClient {
           throw new Error('Server sent CHALLENGE but no key pair was provided');
         }
 
-        // We need a session ID for the transcript. Use the nonce-derived ID
-        // 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();
-
+        // Challenge carries session_id directly (protocol requirement as
+        // of wsh-v1's Challenge.session_id field), so the transcript's
+        // session-id component is always the server's real, authoritative
+        // value regardless of whether ServerHello was sent, dropped, or
+        // arrived out of order. No synthesizing a placeholder here. Keep
+        // tempSessionId as a fallback for this.#sessionId below in case
+        // AUTH_OK's own session_id is ever absent.
+        tempSessionId = firstResponse.session_id;
         const { signature, publicKeyRaw } = await signChallenge(
           keyPair.privateKey,
           keyPair.publicKey,
-          tempSessionId,
+          firstResponse.session_id,
           firstResponse.nonce,
           { username }
         );
@@ -1436,7 +1439,7 @@ export class WshClient {
           }
 
           const { signature, publicKeyRaw } = await signChallenge(
-            keyPair.privateKey, keyPair.publicKey, tempSessionId, challengeMsg.nonce, { username }
+            keyPair.privateKey, keyPair.publicKey, challengeMsg.session_id, challengeMsg.nonce, { username }
           );
 
           await this.#transport.sendControl(authMsg({
@@ -1450,11 +1453,13 @@ export class WshClient {
       } else if (firstResponse.type === MSG.CHALLENGE) {
         if (!keyPair) throw new Error('Server sent CHALLENGE but no key pair provided');
 
-        // See connect()'s CHALLENGE branch for why this must be random
-        // rather than a fixed literal.
-        tempSessionId = tempSessionId || crypto.randomUUID();
+        // Challenge carries session_id directly — see connect()'s
+        // CHALLENGE branch for why. Keep tempSessionId as a fallback for
+        // this.#sessionId below in case AUTH_OK's own session_id is ever
+        // absent.
+        tempSessionId = firstResponse.session_id;
         const { signature, publicKeyRaw } = await signChallenge(
-          keyPair.privateKey, keyPair.publicKey, tempSessionId, firstResponse.nonce, { username }
+          keyPair.privateKey, keyPair.publicKey, firstResponse.session_id, firstResponse.nonce, { username }
         );
 
         await this.#transport.sendControl(authMsg({

package/src/messages.gen.mjs

@@ -200,10 +200,11 @@ export function serverHello({ sessionId, features = [], fingerprints = [] } = {}
   };
 }
 
-export function challenge({ nonce } = {}) {
+export function challenge({ nonce, sessionId } = {}) {
   return {
     type: MSG.CHALLENGE,
     nonce,
+    session_id: sessionId,
   };
 }
 

package/src/transport-ws.mjs

@@ -206,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 */
@@ -215,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://.
@@ -242,7 +265,8 @@ export class WebSocketTransport extends WshTransport {
       });
 
       ws.addEventListener('message', (ev) => {
-        this.#handleMessage(ev.data);
+        this.#messageQueue.push(ev.data);
+        this.#drainMessageQueue();
       });
     });
   }
@@ -295,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

package/src/transport.mjs

@@ -281,6 +281,19 @@ 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) {