@johnhenry/wsh 0.7.0 → 0.14.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 ──────────────────────────────────────────────────────
@@ -126,8 +134,18 @@ export class WshClient {
   /** @type {string|null} Session ID assigned by the server after authentication. */
   #sessionId = null;
 
-  /** @type {string|null} Resume token from AUTH_OK. */
-  #resumeToken = null;
+  /**
+   * @type {string|null} Connection-level token from AUTH_OK, bound to
+   * this connection's own auth session_id (from CHALLENGE/SERVER_HELLO) --
+   * NOT a PTY/exec session's token. Renamed from `#resumeToken` (clawser
+   * #48): the old name invited exactly the bug this fix addresses --
+   * attachSession() used to send this as if it were a valid token for the
+   * *target* session_id, which it can never be (it's scoped to a
+   * different session_id entirely). Not used for anything else currently;
+   * kept and exposed via `authToken` for potential future connection-level
+   * resume use, mirroring the Rust client's `WshClient::token()`.
+   */
+  #authToken = null;
 
   /** @type {import('./transport.mjs').WshTransport|null} Active transport. */
   #transport = null;
@@ -138,6 +156,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;
 
@@ -249,6 +292,16 @@ export class WshClient {
     return this.#sessionId;
   }
 
+  /**
+   * This connection's own AUTH-level token (from AUTH_OK), scoped to this
+   * connection's auth session_id -- NOT a PTY/exec session token. See
+   * `WshSession.resumeToken` for the per-session credential used by
+   * `resumeSession`.
+   */
+  get authToken() {
+    return this.#authToken;
+  }
+
   /** Read-only view of active sessions. */
   get sessions() {
     return new Map(this.#sessions);
@@ -308,7 +361,7 @@ export class WshClient {
     this.#channelCounter = 0;
     this.#waiters.clear();
     this.#sessionId = null;
-    this.#resumeToken = null;
+    this.#authToken = null;
 
     try {
       // ── Select and connect transport ──────────────────────────────
@@ -351,7 +404,7 @@ export class WshClient {
           if (challengeMsg.type === MSG.AUTH_OK) {
             // Server accepted without challenge (e.g. trusted key).
             this.#sessionId = challengeMsg.session_id || tempSessionId;
-            this.#resumeToken = challengeMsg.token || null;
+            this.#authToken = challengeMsg.token || null;
             this.#state = STATE_AUTHENTICATED;
             this.#startPing();
             return this.#sessionId;
@@ -427,7 +480,7 @@ export class WshClient {
       }
 
       this.#sessionId = authResult.session_id || tempSessionId;
-      this.#resumeToken = authResult.token || null;
+      this.#authToken = authResult.token || null;
       this.#state = STATE_AUTHENTICATED;
       this.#startPing();
 
@@ -465,42 +518,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);
+    });
   }
 
   /**
@@ -522,28 +558,48 @@ export class WshClient {
   /**
    * Attach to an existing remote session (collaborative or read-only).
    *
+   * Authorization is satisfied by EITHER `token` OR the caller already
+   * owning/being ACL-granted access to `targetSessionId` server-side (see
+   * wsh-server's `check_session_access`) -- `token` is optional and, for
+   * the common case of attaching via ownership or a `grantSessionAccess`
+   * grant, should simply be omitted (a granted principal never receives
+   * the session's token to begin with -- only the opener does, via
+   * `WshSession.resumeToken`). Pass one explicitly only if you have it
+   * (e.g. this same process opened the session earlier, or the owner
+   * shared it with you out of band).
+   *
+   * Previously (clawser #48) this always sent this connection's own
+   * AUTH-level token, which can never verify against a *different*
+   * session_id -- making attachSession() unreachable for everyone,
+   * including the session's own owner from a fresh connection. Also fixed
+   * alongside that: the server actually replies with PRESENCE (success)
+   * or ERROR (failure), not OPEN_OK/OPEN_FAIL -- this used to wait on the
+   * wrong response stream entirely and would have hung even once the
+   * token bug was fixed.
+   *
    * @param {string} targetSessionId - Remote session ID to attach to
    * @param {object} [opts]
    * @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 response
+   * @returns {Promise<object>} Server's PRESENCE response
    */
-  async attachSession(targetSessionId, { readOnly = false, timeout = DEFAULT_OPEN_TIMEOUT } = {}) {
+  async attachSession(targetSessionId, { readOnly = false, token, 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, mode: attachMode })
     );
 
     const response = await this.#waitForMessage(
-      [MSG.OPEN_OK, MSG.OPEN_FAIL],
+      [MSG.PRESENCE, MSG.ERROR],
       timeout,
       'Timed out waiting for attach response'
     );
 
-    if (response.type === MSG.OPEN_FAIL) {
-      throw new Error(`Failed to attach: ${response.reason || 'rejected'}`);
+    if (response.type === MSG.ERROR) {
+      throw new Error(`Failed to attach: ${response.message || 'rejected'}`);
     }
 
     return response;
@@ -552,31 +608,120 @@ export class WshClient {
   /**
    * Resume a previously disconnected session.
    *
+   * Unlike attachSession(), `token` is required and verified
+   * unconditionally server-side -- Resume is specifically for the
+   * connection that was handed this exact token (via
+   * `WshSession.resumeToken`, when it originally opened the session)
+   * coming back. A principal who only has ACL/ownership access but never
+   * held the token should use attachSession() instead.
+   *
    * @param {string} targetSessionId - Session ID to resume
-   * @param {string} token - Resume token from original AUTH_OK
-   * @param {number} [opts.timeout] - Timeout in ms
-   * @returns {Promise<object>} Server's response
+   * @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.timeout=10000] - Timeout in ms
+   * @returns {Promise<object>} Server's PRESENCE response
    */
-  async resumeSession(targetSessionId, token, { timeout = DEFAULT_OPEN_TIMEOUT } = {}) {
+  async resumeSession(targetSessionId, token, { lastSeq = 0, timeout = DEFAULT_OPEN_TIMEOUT } = {}) {
     this.#assertAuthenticated('resumeSession');
 
     await this.#transport.sendControl(
-      resumeMsg({ sessionId: targetSessionId, token })
+      resumeMsg({ sessionId: targetSessionId, token, lastSeq })
     );
 
     const response = await this.#waitForMessage(
-      [MSG.AUTH_OK, MSG.AUTH_FAIL],
+      [MSG.PRESENCE, MSG.ERROR],
       timeout,
       'Timed out waiting for resume response'
     );
 
-    if (response.type === MSG.AUTH_FAIL) {
-      throw new Error(`Failed to resume: ${response.reason || 'rejected'}`);
+    if (response.type === MSG.ERROR) {
+      throw new Error(`Failed to resume: ${response.message || 'rejected'}`);
     }
 
     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 +859,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 +899,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 +924,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 +953,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 +985,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 +1032,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 +1066,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 +1371,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 +1423,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 +1431,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 ───────────────────────────────────────
@@ -1432,7 +1707,7 @@ export class WshClient {
 
           if (challengeMsg.type === MSG.AUTH_OK) {
             this.#sessionId = challengeMsg.session_id || tempSessionId;
-            this.#resumeToken = challengeMsg.token || null;
+            this.#authToken = challengeMsg.token || null;
             this.#state = STATE_AUTHENTICATED;
             this.#startPing();
             return this.#sessionId;
@@ -1478,7 +1753,7 @@ export class WshClient {
       }
 
       this.#sessionId = authResult.session_id || tempSessionId;
-      this.#resumeToken = authResult.token || null;
+      this.#authToken = authResult.token || null;
       this.#state = STATE_AUTHENTICATED;
       this.#startPing();
 
@@ -1502,6 +1777,92 @@ 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);
+
+      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,
+          // clawser #48: OpenOk now carries the session_id/token this
+          // channel belongs to (pty/exec only -- undefined for e.g. file
+          // channels, which have no Attach/Resume-able session). Exposed
+          // via WshSession.sessionId/resumeToken for a later
+          // attachSession()/resumeSession() call, possibly from a
+          // different connection.
+          sessionId: msg.session_id,
+          resumeToken: msg.token,
+        }
+      );
+      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 +2114,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 +2169,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);
   }
 
   /**