@johnhenry/wsh 0.7.0 → 0.13.0

package/src/client.mjs

@@ -28,10 +28,17 @@ import {
   copilotDetach as copilotDetachMsg,
   keyExchange as keyExchangeMsg,
   fileOp as fileOpMsg,
+  fileChunk as fileChunkMsg,
   policyEval as policyEvalMsg, policyUpdate as policyUpdateMsg,
+  detach as detachMsg,
+  sessionListRequest as sessionListRequestMsg,
+  sessionGrant as sessionGrantMsg, sessionRevoke as sessionRevokeMsg,
+  isRelayForwardable,
 } from './messages.mjs';
-import { signChallenge, exportPublicKeyRaw } from './auth.mjs';
+import { signChallenge, exportPublicKeyRaw, signPeerRecord, verifyPeerRecord, importPublicKeyRaw, fingerprint as computeFingerprint } from './auth.mjs';
+import { generateMlKemKeyPair, mlKemEncapsulate, mlKemDecapsulate } from './mlkem.mjs';
 import { WshSession } from './session.mjs';
+import { cborDecode } from './cbor.mjs';
 
 // ── Client states ─────────────────────────────────────────────────────
 
@@ -49,71 +56,72 @@ const DEFAULT_PING_INTERVAL  = 30_000;  // ms
 const DEFAULT_EXEC_TIMEOUT   = 60_000;  // ms
 const FILE_CHUNK_SIZE        = 65_536;
 
-const textEncoder = new TextEncoder();
-
-function buildUploadHeader(path, totalSize) {
-  const pathBytes = textEncoder.encode(path);
-  const header = new Uint8Array(4 + pathBytes.length + 8);
-  const view = new DataView(header.buffer);
-  view.setUint32(0, pathBytes.length);
-  header.set(pathBytes, 4);
-  writeU64(header, 4 + pathBytes.length, totalSize);
-  return header;
-}
-
-function buildDownloadHeader(path) {
-  const pathBytes = textEncoder.encode(path);
-  const header = new Uint8Array(4 + pathBytes.length);
-  const view = new DataView(header.buffer);
-  view.setUint32(0, pathBytes.length);
-  header.set(pathBytes, 4);
-  return header;
-}
-
-function writeU64(buffer, offset, value) {
-  const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
-  const big = BigInt(value);
-  view.setBigUint64(offset, big);
+/**
+ * Verify a `PeerInfo` entry's self-signed record (see `listPeers`).
+ * Defensive by design: any missing field, malformed key, or fingerprint
+ * mismatch resolves to `false` rather than throwing, so one bad entry
+ * from an untrusted relay can't break the whole `listPeers()` call.
+ * @param {object} peer - a raw `PeerInfo` wire entry
+ * @returns {Promise<boolean>}
+ */
+async function verifyPeerInfoRecord(peer) {
+  if (!peer.public_key || !peer.record_signature || peer.seq === undefined || peer.seq === null) return false;
+  try {
+    const claimedFingerprint = await computeFingerprint(peer.public_key);
+    if (claimedFingerprint !== peer.fingerprint) return false;
+    const publicKey = await importPublicKeyRaw(peer.public_key);
+    return await verifyPeerRecord(publicKey, peer.record_signature, {
+      username: peer.username,
+      peerType: peer.peer_type,
+      shellBackend: peer.shell_backend,
+      capabilities: peer.capabilities,
+      supportsAttach: peer.supports_attach,
+      supportsReplay: peer.supports_replay,
+      supportsEcho: peer.supports_echo,
+      supportsTermSync: peer.supports_term_sync,
+      seq: peer.seq,
+    });
+  } catch {
+    return false;
+  }
 }
 
-function decodeU64(bytes) {
-  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
-  return Number(view.getBigUint64(0));
+/**
+ * Lexicographic byte comparison, used by `initiateE2E`'s hybrid mode to
+ * deterministically assign the ML-KEM "encapsulator" role without an
+ * extra round trip: both sides already have both ephemeral X25519
+ * public keys after round 1, so whichever side's own key sorts lower
+ * encapsulates.
+ * @returns {number} <0 if a<b, >0 if a>b, 0 if equal
+ */
+function compareBytes(a, b) {
+  const len = Math.min(a.length, b.length);
+  for (let i = 0; i < len; i++) {
+    if (a[i] !== b[i]) return a[i] - b[i];
+  }
+  return a.length - b.length;
 }
 
-function createSessionReader(session) {
-  let remainder = new Uint8Array();
-  return {
-    async readExact(totalBytes) {
-      const output = new Uint8Array(totalBytes);
-      let offset = 0;
-
-      while (offset < totalBytes) {
-        if (remainder.byteLength === 0) {
-          const chunk = await session.read();
-          if (chunk === null) {
-            return null;
-          }
-          remainder = chunk;
-        }
-
-        const take = Math.min(totalBytes - offset, remainder.byteLength);
-        output.set(remainder.subarray(0, take), offset);
-        offset += take;
-        remainder = remainder.subarray(take);
-      }
-
-      return output;
-    },
-    async readChunk() {
-      if (remainder.byteLength > 0) {
-        const chunk = remainder;
-        remainder = new Uint8Array();
-        return chunk;
-      }
-      return await session.read();
-    },
-  };
+/**
+ * Combine the classical (X25519 ECDH) and post-quantum (ML-KEM-768) key
+ * exchange outputs into one AES-256-GCM key via HKDF-SHA256, so the
+ * final key is only as weak as the *stronger* of the two if either
+ * primitive is ever broken.
+ * @param {Uint8Array} x25519Bits - 32-byte ECDH shared secret
+ * @param {Uint8Array} kemSharedSecret - 32-byte ML-KEM-768 shared secret
+ * @returns {Promise<Uint8Array>} 32 bytes of combined key material
+ */
+async function combineHybridSecret(x25519Bits, kemSharedSecret) {
+  const ikm = new Uint8Array(x25519Bits.length + kemSharedSecret.length);
+  ikm.set(x25519Bits, 0);
+  ikm.set(kemSharedSecret, x25519Bits.length);
+  const hkdfKey = await crypto.subtle.importKey('raw', ikm, 'HKDF', false, ['deriveBits']);
+  const bits = await crypto.subtle.deriveBits(
+    { name: 'HKDF', hash: 'SHA-256', salt: new Uint8Array(0), info: new TextEncoder().encode('wsh-hybrid-e2e-v1') },
+    hkdfKey,
+    256
+  );
+  return new Uint8Array(bits);
 }
 
 // ── Client class ──────────────────────────────────────────────────────
@@ -138,6 +146,31 @@ export class WshClient {
   /** @type {Map<number, WshSession>} Active sessions keyed by channel ID. */
   #sessions = new Map();
 
+  /**
+   * FIFO queue of in-flight openSession() calls awaiting the next
+   * OPEN_OK/OPEN_FAIL. Handled as a dedicated synchronous case in
+   * #handleControl (not the generic #waitForMessage machinery) so that
+   * #sessions.set() happens in the same synchronous dispatch step as
+   * OPEN_OK itself, with no microtask hop in between. That matters
+   * because a server can legitimately push channel-scoped data (e.g. the
+   * first FileChunk of a download) immediately after OPEN_OK, landing in
+   * the same message batch -- dispatchSerially only guarantees one
+   * microtask tick of separation between batch items, and registering the
+   * session via a promise continuation takes more hops than that, so the
+   * next item in the batch could still find #sessions.has(channelId)
+   * false and be misrouted/dropped.
+   * @type {Array<{kind: string, resolve: function, reject: function, timer: number}>}
+   */
+  #pendingOpens = [];
+
+  /**
+   * Fingerprints of reverse-connect peers this client has accepted a relay
+   * bridge with. RelayForward-wrapped messages are only unwrapped and
+   * delivered if their from_fingerprint is in this set — see trustRelayPeer.
+   * @type {Set<string>}
+   */
+  #acceptedRelayPeers = new Set();
+
   /** @type {number} Monotonically increasing channel ID counter. */
   #channelCounter = 0;
 
@@ -465,42 +498,25 @@ export class WshClient {
       openMsg({ kind: type, command, cols, rows, env })
     );
 
-    // Wait for OPEN_OK or OPEN_FAIL.
-    const response = await this.#waitForMessage(
-      [MSG.OPEN_OK, MSG.OPEN_FAIL],
-      timeout,
-      'Timed out waiting for session open response'
-    );
-
-    if (response.type === MSG.OPEN_FAIL) {
-      throw new Error(`Failed to open session: ${response.reason || 'rejected'}`);
-    }
-
-    const serverChannelId = response.channel_id ?? requestedChannelId;
-    const streamIds = response.stream_ids ?? {};
-    const dataMode = response.data_mode === 'virtual' ? 'virtual' : 'stream';
-    const capabilities = Array.isArray(response.capabilities) ? response.capabilities : [];
-
-    // Create the session object.
-    const session = new WshSession(
-      this.#transport,
-      serverChannelId,
-      streamIds,
-      type,
-      { dataMode, capabilities }
-    );
-    this.#sessions.set(serverChannelId, session);
-
-    if (dataMode === 'virtual') {
-      session._activateVirtual((msg) => this.sendRelayControl(msg));
-      return session;
-    }
-
-    // Open the data stream and bind it to the session.
-    const stream = await this.#transport.openStream();
-    session._bind(stream.readable, stream.writable);
-
-    return session;
+    // Registered as a dedicated pending-open (not the generic
+    // #waitForMessage waiter) so #handleControl can construct and
+    // register the WshSession synchronously the instant OPEN_OK arrives
+    // — see #pendingOpens's doc comment for why that matters.
+    return new Promise((resolve, reject) => {
+      const entry = {
+        mode: 'session',
+        kind: type,
+        requestedChannelId,
+        resolve,
+        reject,
+      };
+      entry.timer = setTimeout(() => {
+        const idx = this.#pendingOpens.indexOf(entry);
+        if (idx !== -1) this.#pendingOpens.splice(idx, 1);
+        reject(new Error('Timed out waiting for session open response'));
+      }, timeout);
+      this.#pendingOpens.push(entry);
+    });
   }
 
   /**
@@ -531,16 +547,25 @@ export class WshClient {
   async attachSession(targetSessionId, { readOnly = false, timeout = DEFAULT_OPEN_TIMEOUT } = {}) {
     this.#assertAuthenticated('attachSession');
 
-    const mode = readOnly ? 'readonly' : 'control';
+    const attachMode = readOnly ? 'readonly' : 'control';
     await this.#transport.sendControl(
-      attachMsg({ sessionId: targetSessionId, token: this.#resumeToken, mode })
+      attachMsg({ sessionId: targetSessionId, token: this.#resumeToken, mode: attachMode })
     );
 
-    const response = await this.#waitForMessage(
-      [MSG.OPEN_OK, MSG.OPEN_FAIL],
-      timeout,
-      'Timed out waiting for attach response'
-    );
+    // Shares #pendingOpens with openSession() -- both wait on the same
+    // OPEN_OK/OPEN_FAIL response stream, in the order their requests were
+    // sent (see #pendingOpens's doc comment). Unlike openSession(),
+    // attachSession() doesn't construct a WshSession, so it just wants
+    // the raw response either way.
+    const response = await new Promise((resolve, reject) => {
+      const entry = { mode: 'raw', resolve, reject };
+      entry.timer = setTimeout(() => {
+        const idx = this.#pendingOpens.indexOf(entry);
+        if (idx !== -1) this.#pendingOpens.splice(idx, 1);
+        reject(new Error('Timed out waiting for attach response'));
+      }, timeout);
+      this.#pendingOpens.push(entry);
+    });
 
     if (response.type === MSG.OPEN_FAIL) {
       throw new Error(`Failed to attach: ${response.reason || 'rejected'}`);
@@ -577,6 +602,86 @@ export class WshClient {
     return response;
   }
 
+  /**
+   * Detach from a remote session: release control (stop receiving its
+   * output) while leaving it running server-side, so it can be resumed
+   * later via resumeSession(). Mirrors the Rust client/CLI's `wsh detach`.
+   *
+   * @param {string} sessionId - Remote session ID to detach from
+   * @param {number} [timeout=10000]
+   */
+  async detach(sessionId, timeout = DEFAULT_OPEN_TIMEOUT) {
+    this.#assertAuthenticated('detach');
+
+    await this.#transport.sendControl(detachMsg({ sessionId }));
+
+    const response = await this.#waitForMessage(
+      [MSG.DETACH_OK, MSG.DETACH_FAIL],
+      timeout,
+      'Timed out waiting for detach response'
+    );
+
+    if (response.type === MSG.DETACH_FAIL) {
+      throw new Error(`Failed to detach: ${response.reason || 'rejected'}`);
+    }
+  }
+
+  /**
+   * List sessions on the server that this connection's key owns or has
+   * been granted access to (a server round trip — distinct from the
+   * purely local listSessions(), which only reports channels open on
+   * this connection). Mirrors the Rust client's list_remote_sessions().
+   *
+   * @param {number} [timeout=10000]
+   * @returns {Promise<Array<object>>} Server-reported session summaries
+   */
+  async listRemoteSessions(timeout = DEFAULT_OPEN_TIMEOUT) {
+    this.#assertAuthenticated('listRemoteSessions');
+
+    await this.#transport.sendControl(sessionListRequestMsg());
+
+    const response = await this.#waitForMessage(
+      [MSG.SESSION_LIST],
+      timeout,
+      'Timed out waiting for session list response'
+    );
+
+    return response.sessions || [];
+  }
+
+  /**
+   * Grant another authenticated principal (username or fingerprint)
+   * access to a session this connection owns. Server-enforced (only the
+   * session owner may grant); fire-and-forget like updatePolicy() — the
+   * server sends no response on success, only an Error envelope on
+   * rejection (surfaced via onError, not this call).
+   *
+   * @param {string} sessionId
+   * @param {string} principal - Username or fingerprint of the grantee
+   * @param {string[]} [permissions=['read']]
+   */
+  async grantSessionAccess(sessionId, principal, permissions = ['read']) {
+    this.#assertAuthenticated('grantSessionAccess');
+    await this.#transport.sendControl(
+      sessionGrantMsg({ sessionId, principal, permissions })
+    );
+  }
+
+  /**
+   * Revoke a previously granted principal's access to a session this
+   * connection owns. Same fire-and-forget shape as grantSessionAccess().
+   *
+   * @param {string} sessionId
+   * @param {string} principal
+   * @param {string} [reason]
+   */
+  async revokeSessionAccess(sessionId, principal, reason) {
+    this.#assertAuthenticated('revokeSessionAccess');
+    await this.#transport.sendControl(
+      sessionRevokeMsg({ sessionId, principal, reason })
+    );
+  }
+
   // ── Disconnect ──────────────────────────────────────────────────────
 
   /**
@@ -714,19 +819,37 @@ export class WshClient {
     }
 
     const effectiveShellBackend = shellBackend || (expose.shell ? 'virtual-shell' : 'exec-only');
+    const record = {
+      username,
+      capabilities,
+      peerType,
+      shellBackend: effectiveShellBackend,
+      supportsAttach: supportsAttach ?? effectiveShellBackend !== 'exec-only',
+      supportsReplay: supportsReplay ?? effectiveShellBackend !== 'exec-only',
+      supportsEcho: supportsEcho ?? effectiveShellBackend === 'virtual-shell',
+      supportsTermSync: supportsTermSync ?? effectiveShellBackend === 'virtual-shell',
+      // The peer's own monotonic counter for this signed record --
+      // current-time-millis in practice (see buildPeerRecordTranscript).
+      // A server/operator must reject a record whose seq doesn't exceed
+      // the last one accepted for this fingerprint.
+      seq: Date.now(),
+    };
+
+    // Self-sign the registration so ReversePeers entries built from it
+    // are verifiable by an operator independent of trusting the relay
+    // (see auth.mjs's "Signed peer records" section). Only possible with
+    // a real identity key, same precondition `publicKey` already had.
+    let recordSignature;
+    if (keyPair) {
+      ({ signature: recordSignature } = await signPeerRecord(keyPair.privateKey, keyPair.publicKey, record));
+    }
 
     // Register as a reverse peer.
     await this.#transport.sendControl(
       reverseRegisterMsg({
-        username,
-        capabilities,
-        peerType,
-        shellBackend: effectiveShellBackend,
-        supportsAttach: supportsAttach ?? effectiveShellBackend !== 'exec-only',
-        supportsReplay: supportsReplay ?? effectiveShellBackend !== 'exec-only',
-        supportsEcho: supportsEcho ?? effectiveShellBackend === 'virtual-shell',
-        supportsTermSync: supportsTermSync ?? effectiveShellBackend === 'virtual-shell',
+        ...record,
         publicKey,
+        recordSignature,
       })
     );
 
@@ -736,8 +859,19 @@ export class WshClient {
   /**
    * List peers registered on the relay server.
    *
+   * Each entry's `verified` field is computed here, client-side, from
+   * the peer's own signed record (`public_key`/`seq`/`record_signature`,
+   * present when the relay honestly forwards what the peer sent) --
+   * `true` only if the signature actually verifies against `public_key`
+   * AND that key's fingerprint matches the claimed `fingerprint` field.
+   * This is deliberately NOT trust-on-first-use of the relay's own
+   * claims: a relay that omits or tampers with these fields, or that
+   * substitutes a different key, produces `verified: false` rather than
+   * silently passing. `verified` is additive to the wire response, not
+   * a wire field itself.
+   *
    * @param {number} [timeout=10000] - Timeout in ms
-   * @returns {Promise<Array<{fingerprint_short: string, username: string, capabilities: string[], last_seen: number|null}>>}
+   * @returns {Promise<Array<{fingerprint_short: string, username: string, capabilities: string[], last_seen: number|null, verified: boolean}>>}
    */
   async listPeers(timeout = DEFAULT_OPEN_TIMEOUT) {
     this.#assertAuthenticated('listPeers');
@@ -750,7 +884,8 @@ export class WshClient {
       'Timed out waiting for peer list'
     );
 
-    return response.peers || [];
+    const peers = response.peers || [];
+    return Promise.all(peers.map(async (peer) => ({ ...peer, verified: await verifyPeerInfoRecord(peer) })));
   }
 
   /**
@@ -778,14 +913,22 @@ export class WshClient {
     this.#assertAuthenticated('reverseConnect');
 
     await this.#transport.sendControl(
-      reverseConnectMsg({ targetFingerprint, username: '' })
+      // fromFingerprint is ignored by the server -- it overwrites it with
+      // this connection's own authenticated fingerprint before forwarding.
+      reverseConnectMsg({ targetFingerprint, username: '', fromFingerprint: '' })
     );
 
-    return this.#waitForMessage(
+    const response = await this.#waitForMessage(
       [MSG.REVERSE_ACCEPT, MSG.REVERSE_REJECT],
       timeout,
       'Timed out waiting for reverse-connect response'
     );
+
+    if (response.type === MSG.REVERSE_ACCEPT) {
+      this.trustRelayPeer(response.target_fingerprint);
+    }
+
+    return response;
   }
 
   /**
@@ -802,12 +945,40 @@ export class WshClient {
     await this.#transport.sendControl(msg);
   }
 
+  /**
+   * Mark a peer fingerprint as an accepted reverse-connect bridge partner.
+   *
+   * Call this once a ReverseConnect has been accepted (either side): the
+   * target after sending ReverseAccept in response to an incoming request
+   * (using the request's from_fingerprint), or the operator after receiving
+   * ReverseAccept for a request it sent (handled automatically by
+   * reverseConnect()). Only RelayForward-wrapped messages whose
+   * from_fingerprint is trusted this way are unwrapped and delivered.
+   *
+   * @param {string} fingerprint
+   */
+  trustRelayPeer(fingerprint) {
+    this.#acceptedRelayPeers.add(fingerprint);
+  }
+
+  /**
+   * Stop trusting a peer as a relay-forward bridge partner (e.g. on session end).
+   * @param {string} fingerprint
+   */
+  untrustRelayPeer(fingerprint) {
+    this.#acceptedRelayPeers.delete(fingerprint);
+  }
+
   // ── File transfer ───────────────────────────────────────────────────
 
   /**
    * Upload a blob to a remote path.
    *
-   * Opens a file channel, writes the data, and waits for acknowledgment.
+   * Opens a file channel, then sends the data as a sequence of FileChunk
+   * control messages (offset-addressed, the last one marked is_final) and
+   * waits for the server to confirm completion. Works the same whether the
+   * channel's data plane is stream- or virtual-backed, since FileChunk is
+   * an ordinary control message rather than raw stream bytes.
    *
    * @param {Blob|Uint8Array} blob - Data to upload
    * @param {string} remotePath - Destination path on the server
@@ -821,21 +992,31 @@ export class WshClient {
       ? new Uint8Array(await blob.arrayBuffer())
       : blob;
     const total = data.byteLength;
-    const header = buildUploadHeader(remotePath, total);
-    let sent = 0;
 
     try {
-      await session.write(header);
-      for (let i = 0; i < total; i += FILE_CHUNK_SIZE) {
-        const end = Math.min(i + FILE_CHUNK_SIZE, total);
-        await session.write(data.subarray(i, end));
+      let sent = 0;
+      do {
+        const end = Math.min(sent + FILE_CHUNK_SIZE, total);
+        await this.#transport.sendControl(fileChunkMsg({
+          channelId: session.channelId,
+          offset: sent,
+          data: data.subarray(sent, end),
+          isFinal: end >= total,
+          totalSize: total,
+        }));
         sent = end;
         onProgress?.(sent);
-      }
-
-      const ack = await session.read();
-      if (ack === null) {
-        throw new Error('Upload failed: unexpected EOF waiting for server acknowledgement');
+      } while (sent < total);
+
+      // The server confirms completion the same way an exec session
+      // signals it finished: Exit with a code, then Close. Resolve on
+      // whichever arrives first.
+      const code = await new Promise((resolve) => {
+        session.onExit = (c) => { session.onExit = null; resolve(c); };
+        session.onClose = () => resolve(null);
+      });
+      if (code !== 0) {
+        throw new Error(`Upload failed with exit code ${code ?? 'unknown'}`);
       }
     } finally {
       await session.close().catch(() => {});
@@ -845,36 +1026,45 @@ export class WshClient {
   /**
    * Download a file from a remote path.
    *
+   * Opens a file channel and reads the file as a sequence of FileChunk
+   * control messages until the final chunk arrives. offset/total_size are
+   * checked so a truncated transfer (channel closes before is_final, or
+   * the final chunk doesn't actually reach total_size) is detected rather
+   * than silently returned as a short file.
+   *
    * @param {string} remotePath - Source path on the server
+   * @param {object} [opts]
+   * @param {function({received: number, total: number}): void} [opts.onProgress]
+   * @param {number} [opts.timeout=10000] - Timeout in ms waiting for the channel to open
    * @returns {Promise<Uint8Array>} File contents
    */
-  async download(remotePath) {
+  async download(remotePath, { onProgress, timeout = DEFAULT_OPEN_TIMEOUT } = {}) {
     this.#assertAuthenticated('download');
-    const session = await this.openSession({ type: 'file', command: `download:${remotePath}` });
+    const session = await this.openSession({ type: 'file', command: `download:${remotePath}`, timeout });
 
     try {
-      const reader = createSessionReader(session);
-      await session.write(buildDownloadHeader(remotePath));
+      let data = null;
+      let received = 0;
 
-      const sizeChunk = await reader.readExact(8);
-      if (sizeChunk === null) {
-        throw new Error('Download failed: unexpected EOF reading file size');
-      }
-      const totalSize = decodeU64(sizeChunk);
-      const data = new Uint8Array(totalSize);
-      let offset = 0;
-
-      while (offset < totalSize) {
-        const chunk = await reader.readChunk();
+      while (true) {
+        const chunk = await session._readFileChunk();
         if (chunk === null) {
-          throw new Error('Download failed: unexpected EOF reading file payload');
+          throw new Error('Download failed: connection closed before the transfer completed (truncated)');
         }
-        const remaining = totalSize - offset;
-        data.set(chunk.subarray(0, remaining), offset);
-        offset += Math.min(chunk.byteLength, remaining);
-      }
+        if (data === null) {
+          data = new Uint8Array(chunk.total_size ?? 0);
+        }
+        data.set(chunk.data, chunk.offset);
+        received = chunk.offset + chunk.data.byteLength;
+        onProgress?.({ received, total: data.byteLength });
 
-      return data;
+        if (chunk.is_final) {
+          if (received !== data.byteLength) {
+            throw new Error(`Download failed: truncated transfer (received ${received} of ${data.byteLength} bytes)`);
+          }
+          return data;
+        }
+      }
     } finally {
       await session.close().catch(() => {});
     }
@@ -1141,28 +1331,50 @@ export class WshClient {
   // ── E2E Encryption ────────────────────────────────────────────────
 
   /**
-   * Initiate end-to-end encryption for a session using X25519 key exchange.
+   * Initiate end-to-end encryption for a session.
+   *
+   * `algorithm: 'X25519'` (default): classical ECDH only, one round trip
+   * -- both sides send their ephemeral public key, derive the shared
+   * secret directly.
+   *
+   * `algorithm: 'X25519+ML-KEM-768'`: hybrid classical+post-quantum. Round
+   * 1 is the same as classical, plus both sides also send a fresh
+   * ML-KEM-768 public key. Each side then deterministically derives the
+   * same "encapsulator"/"decapsulator" role assignment by comparing the
+   * two exchanged X25519 public keys byte-lexicographically (no extra
+   * round trip needed, since both sides already have both values after
+   * round 1) -- the encapsulator encapsulates against the decapsulator's
+   * ML-KEM-768 key and sends the ciphertext in a second KeyExchange
+   * message; the decapsulator decapsulates it. Both combine the X25519
+   * and ML-KEM-768 outputs via HKDF-SHA256. Falls back to classical
+   * automatically if the peer's round-1 message doesn't include a
+   * kem_public_key (it doesn't support hybrid mode) -- algorithm
+   * agility, not a hard cutover; check the returned `hybrid` flag to see
+   * which actually happened.
+   *
    * @param {string} sessionId - Session ID
-   * @param {string} [algorithm='X25519'] - Key exchange algorithm
+   * @param {string} [algorithm='X25519'] - 'X25519' or 'X25519+ML-KEM-768'
    * @param {number} [timeout=10000]
-   * @returns {Promise<{sharedSecret: CryptoKey, peerPublicKey: Uint8Array}>}
+   * @returns {Promise<{sharedSecret: CryptoKey, peerPublicKey: Uint8Array, hybrid: boolean}>}
    */
   async initiateE2E(sessionId, algorithm = 'X25519', timeout = DEFAULT_OPEN_TIMEOUT) {
     this.#assertAuthenticated('initiateE2E');
+    const wantHybrid = algorithm === 'X25519+ML-KEM-768';
 
-    // Generate ephemeral X25519 key pair
+    // Generate ephemeral X25519 key pair (and, for hybrid, a fresh
+    // ML-KEM-768 key pair too).
     const ephemeral = await crypto.subtle.generateKey(
       { name: 'X25519' },
       false,
       ['deriveBits']
     );
-
     const localPub = new Uint8Array(
       await crypto.subtle.exportKey('raw', ephemeral.publicKey)
     );
+    const localKem = wantHybrid ? await generateMlKemKeyPair() : null;
 
     await this.#transport.sendControl(
-      keyExchangeMsg({ algorithm, publicKey: localPub, sessionId })
+      keyExchangeMsg({ algorithm, publicKey: localPub, sessionId, kemPublicKey: localKem?.publicKey })
     );
 
     const peerMsg = await this.#waitForMessage(
@@ -1171,7 +1383,7 @@ export class WshClient {
       'Timed out waiting for peer key exchange'
     );
 
-    // Import peer's public key and derive shared secret
+    // Import peer's public key and derive the classical shared secret.
     const peerKey = await crypto.subtle.importKey(
       'raw',
       peerMsg.public_key,
@@ -1179,23 +1391,46 @@ export class WshClient {
       false,
       []
     );
-
-    const sharedBits = await crypto.subtle.deriveBits(
+    const sharedBits = new Uint8Array(await crypto.subtle.deriveBits(
       { name: 'X25519', public: peerKey },
       ephemeral.privateKey,
       256
-    );
+    ));
+
+    const hybridActive = wantHybrid && !!localKem && !!peerMsg.kem_public_key;
+    let combinedBits = sharedBits;
+
+    if (hybridActive) {
+      const peerKemPublicKey = new Uint8Array(peerMsg.kem_public_key);
+      const isEncapsulator = compareBytes(localPub, new Uint8Array(peerMsg.public_key)) < 0;
+
+      let kemSharedSecret;
+      if (isEncapsulator) {
+        const { ciphertext, sharedSecret } = await mlKemEncapsulate(peerKemPublicKey);
+        kemSharedSecret = sharedSecret;
+        await this.#transport.sendControl(keyExchangeMsg({ algorithm, sessionId, kemCiphertext: ciphertext }));
+      } else {
+        const ctMsg = await this.#waitForMessage(
+          [MSG.KEY_EXCHANGE],
+          timeout,
+          'Timed out waiting for peer ML-KEM-768 ciphertext'
+        );
+        kemSharedSecret = await mlKemDecapsulate(localKem.secretKeySeed, new Uint8Array(ctMsg.kem_ciphertext));
+      }
 
-    // Derive an AES-GCM key from the shared secret
+      combinedBits = await combineHybridSecret(sharedBits, kemSharedSecret);
+    }
+
+    // Derive an AES-GCM key from the (possibly hybrid-combined) shared secret
     const sharedSecret = await crypto.subtle.importKey(
       'raw',
-      sharedBits,
+      combinedBits,
       { name: 'AES-GCM', length: 256 },
       false,
       ['encrypt', 'decrypt']
     );
 
-    return { sharedSecret, peerPublicKey: new Uint8Array(peerMsg.public_key) };
+    return { sharedSecret, peerPublicKey: new Uint8Array(peerMsg.public_key), hybrid: hybridActive };
   }
 
   // ── Structured File Channel ───────────────────────────────────────
@@ -1502,6 +1737,89 @@ export class WshClient {
   #handleControl(msg) {
     const type = msg.type;
 
+    // Unwrap RelayForward: only deliver the inner message if it came from a
+    // peer this client has actually accepted a bridge with (see
+    // trustRelayPeer), and only if the inner message's own type is on the
+    // shared relay-forwardable allowlist (defense in depth against a
+    // misbehaving or compromised relay server). from_fingerprint is set by
+    // the server from the sender's authenticated identity -- never trust it
+    // beyond checking membership in #acceptedRelayPeers.
+    if (type === MSG.RELAY_FORWARD) {
+      if (!this.#acceptedRelayPeers.has(msg.from_fingerprint)) {
+        console.warn('[wsh:client] dropping RelayForward from untrusted/unaccepted peer:', msg.from_fingerprint);
+        return;
+      }
+      let inner;
+      try {
+        inner = cborDecode(msg.inner);
+      } catch (err) {
+        console.error('[wsh:client] failed to decode RelayForward inner envelope:', err);
+        return;
+      }
+      if (!isRelayForwardable(inner.type)) {
+        console.warn('[wsh:client] dropping RelayForward wrapping a non-forwardable type:', inner.type);
+        return;
+      }
+      this.#handleControl(inner);
+      return;
+    }
+
+    // OPEN_OK/OPEN_FAIL: handled as a dedicated case (not the generic
+    // waiter mechanism below) so the WshSession gets constructed and
+    // registered in #sessions synchronously, in the same dispatch step as
+    // OPEN_OK itself — see #pendingOpens's doc comment for why.
+    if (type === MSG.OPEN_OK || type === MSG.OPEN_FAIL) {
+      const pending = this.#pendingOpens.shift();
+      if (!pending) return;
+      clearTimeout(pending.timer);
+
+      // attachSession() wants the raw response either way and never
+      // constructs a session -- it has no #sessions-registration race to
+      // protect against.
+      if (pending.mode === 'raw') {
+        pending.resolve(msg);
+        return;
+      }
+
+      if (type === MSG.OPEN_FAIL) {
+        pending.reject(new Error(`Failed to open session: ${msg.reason || 'rejected'}`));
+        return;
+      }
+
+      const serverChannelId = msg.channel_id ?? pending.requestedChannelId;
+      const streamIds = msg.stream_ids ?? {};
+      const dataMode = msg.data_mode === 'virtual' ? 'virtual' : 'stream';
+      const capabilities = Array.isArray(msg.capabilities) ? msg.capabilities : [];
+
+      const session = new WshSession(
+        this.#transport,
+        serverChannelId,
+        streamIds,
+        pending.kind,
+        { dataMode, capabilities }
+      );
+      this.#sessions.set(serverChannelId, session);
+
+      if (dataMode === 'virtual') {
+        session._activateVirtual((m) => this.sendRelayControl(m));
+        pending.resolve(session);
+        return;
+      }
+
+      // Stream mode needs a real transport stream, which is inherently
+      // async — but #sessions.set() above already happened synchronously,
+      // so channel-scoped control messages arriving before the stream
+      // finishes binding still route correctly.
+      this.#transport.openStream().then(
+        (stream) => {
+          session._bind(stream.readable, stream.writable);
+          pending.resolve(session);
+        },
+        (err) => pending.reject(err)
+      );
+      return;
+    }
+
     // First, check if any waiters are listening for this message type.
     if (this.#waiters.has(type)) {
       const queue = this.#waiters.get(type);
@@ -1753,6 +2071,12 @@ export class WshClient {
       }
     }
     this.#waiters.clear();
+
+    for (const pending of this.#pendingOpens) {
+      clearTimeout(pending.timer);
+      pending.reject(err);
+    }
+    this.#pendingOpens.length = 0;
   }
 
   // ── Internal: ping/pong keepalive ───────────────────────────────────
@@ -1802,22 +2126,15 @@ export class WshClient {
    * that a client would not normally receive from the server, but that
    * arrives via the relay bridge from a remote CLI peer.
    *
+   * Backed by the generated allowlist (single source of truth: the
+   * `relay.forwardable` list in spec/wsh-v1.yaml) so this can no longer
+   * drift out of sync with the server's own allowlist.
+   *
    * @param {number} type - Message opcode
    * @returns {boolean}
    */
   _isRelayForwardable(type) {
-    return [
-      MSG.OPEN, MSG.MCP_DISCOVER, MSG.MCP_CALL,
-      MSG.CLOSE, MSG.RESIZE, MSG.SIGNAL,
-      MSG.SESSION_DATA,
-      MSG.REVERSE_ACCEPT, MSG.REVERSE_REJECT,
-      MSG.GUEST_JOIN, MSG.GUEST_REVOKE,         // Unit 4
-      MSG.COPILOT_ATTACH, MSG.COPILOT_DETACH,   // Unit 9
-      MSG.FILE_OP,                               // Unit 11
-      MSG.POLICY_EVAL,                           // Unit 12
-      MSG.ECHO_ACK, MSG.ECHO_STATE,
-      MSG.TERM_SYNC, MSG.TERM_DIFF,
-    ].includes(type);
+    return isRelayForwardable(type);
   }
 
   /**