@johnhenry/wsh 0.7.0 → 0.13.0

package/src/file-transfer.mjs

@@ -1,24 +1,31 @@
 /**
- * WshFileTransfer — dedicated stream file transfer (scp-like) over a wsh connection.
+ * WshFileTransfer — scp-like file transfer over a wsh connection.
  *
- * Uploads and downloads files using the wsh channel protocol with 'file' kind
- * channels. Data flows over a dedicated bidirectional stream in 64KB chunks.
+ * Uploads and downloads delegate to the underlying client's upload()/
+ * download() (FileChunk control messages over a 'file'-kind channel —
+ * see client.mjs). list() is a separate helper that runs `ls -la` over
+ * a plain exec channel.
  */
 
 import { MSG, open, CHANNEL_KIND } from './messages.mjs';
 
-/** Transfer chunk size: 64KB. */
-const CHUNK_SIZE = 65536;
-
 /** Default timeout for waiting on control messages (30 seconds). */
 const RESPONSE_TIMEOUT_MS = 30_000;
 
 export class WshFileTransfer {
-  /** @type {{ sendControl: function, openStream: function, onControl: function }} */
+  /**
+   * @type {{
+   *   upload: function, download: function,
+   *   sendControl: function, openStream: function, onControl: function,
+   * }}
+   */
   #client;
 
   /**
-   * @param {object} client - A WshClient or any transport object exposing:
+   * @param {object} client - A WshClient (or any object exposing upload()/
+   *   download() with the same signatures — those are used directly for
+   *   upload/download). list() additionally needs, for the underlying exec
+   *   channel it runs `ls -la` over:
    *   - sendControl(msg): send a control message
    *   - openStream(): open a new bidirectional stream
    *   - onControl: settable callback for incoming control messages
@@ -32,12 +39,10 @@ export class WshFileTransfer {
   /**
    * Upload data to a remote path.
    *
-   * Protocol flow:
-   *   1. Send OPEN { kind: 'file', command: 'upload', path }
-   *   2. Receive OPEN_OK { channel_id, stream_ids }
-   *   3. Write data to dedicated stream in 64KB chunks
-   *   4. Close the write side of the stream
-   *   5. Wait for EXIT message with status code
+   * Delegates to the underlying client's `upload()`, which sends the data
+   * as a sequence of `FileChunk` control messages over a `'file'`-kind
+   * channel — the single wire scheme for file transfer (see
+   * `WshClient.upload` in `client.mjs`).
    *
    * @param {Uint8Array | ArrayBuffer} data - File content to upload
    * @param {string} remotePath - Destination path on the remote host
@@ -47,97 +52,31 @@ export class WshFileTransfer {
    * @returns {Promise<{ success: boolean, bytesTransferred: number }>}
    */
   async upload(data, remotePath, { onProgress, timeout = RESPONSE_TIMEOUT_MS } = {}) {
-    if (typeof this.#client.upload === 'function') {
-      await this.#client.upload(data, remotePath, {
-        onProgress: (value) => {
-          if (typeof value === 'number') {
-            onProgress?.({ sent: value, total: data.byteLength ?? data.length ?? 0 });
-            return;
-          }
-          onProgress?.(value);
-        },
-        timeout,
-      });
-      const bytes = data instanceof Uint8Array ? data.byteLength : data.byteLength ?? data.length ?? 0;
-      return { success: true, bytesTransferred: bytes };
-    }
-
-    const bytes = data instanceof ArrayBuffer ? new Uint8Array(data) : data;
-    if (!(bytes instanceof Uint8Array)) {
-      throw new TypeError('Data must be a Uint8Array or ArrayBuffer');
-    }
-    if (!remotePath || typeof remotePath !== 'string') {
-      throw new Error('remotePath is required');
+    if (typeof this.#client.upload !== 'function') {
+      throw new Error('WshFileTransfer requires a client exposing upload() (e.g. WshClient)');
     }
 
-    // 1. Request a file upload channel
-    const openMsg = open({
-      kind: CHANNEL_KIND.FILE,
-      command: 'upload',
+    await this.#client.upload(data, remotePath, {
+      onProgress: (value) => {
+        if (typeof value === 'number') {
+          onProgress?.({ sent: value, total: data.byteLength ?? data.length ?? 0 });
+          return;
+        }
+        onProgress?.(value);
+      },
+      timeout,
     });
-    openMsg.path = remotePath;
-    openMsg.size = bytes.length;
-
-    await this.#client.sendControl(openMsg);
-
-    // 2. Wait for OPEN_OK or OPEN_FAIL
-    const response = await this._waitForMessage(
-      (msg) => msg.type === MSG.OPEN_OK || msg.type === MSG.OPEN_FAIL,
-      timeout
-    );
-
-    if (response.type === MSG.OPEN_FAIL) {
-      throw new Error(`Upload rejected: ${response.reason || 'unknown reason'}`);
-    }
-
-    const channelId = response.channel_id;
-
-    // 3. Open a dedicated data stream and write in chunks
-    const stream = await this.#client.openStream();
-    const writer = stream.writable.getWriter();
-    let sent = 0;
-
-    try {
-      while (sent < bytes.length) {
-        const end = Math.min(sent + CHUNK_SIZE, bytes.length);
-        const chunk = bytes.subarray(sent, end);
-        await writer.write(chunk);
-        sent = end;
-        try {
-          onProgress?.({ sent, total: bytes.length });
-        } catch { /* ignore callback errors */ }
-      }
-    } finally {
-      // 4. Close the write side to signal end of data
-      try {
-        await writer.close();
-      } catch {
-        // Stream may already be closed on error
-      }
-    }
-
-    // 5. Wait for EXIT confirmation
-    const exitMsg = await this._waitForMessage(
-      (msg) => msg.type === MSG.EXIT && msg.channel_id === channelId,
-      timeout
-    );
-
-    const success = exitMsg.code === 0;
-    if (!success) {
-      throw new Error(`Upload failed with exit code ${exitMsg.code}`);
-    }
-
-    return { success, bytesTransferred: sent };
+    const bytes = data instanceof Uint8Array ? data.byteLength : data.byteLength ?? data.length ?? 0;
+    return { success: true, bytesTransferred: bytes };
   }
 
   /**
    * Download a file from a remote path.
    *
-   * Protocol flow:
-   *   1. Send OPEN { kind: 'file', command: 'download', path }
-   *   2. Receive OPEN_OK { channel_id, stream_ids }
-   *   3. Read from the dedicated stream, accumulating chunks
-   *   4. Return complete file content as Uint8Array
+   * Delegates to the underlying client's `download()`, which reads the
+   * data as a sequence of `FileChunk` control messages over a
+   * `'file'`-kind channel — the single wire scheme for file transfer (see
+   * `WshClient.download` in `client.mjs`).
    *
    * @param {string} remotePath - File path on the remote host
    * @param {object} [opts]
@@ -146,76 +85,10 @@ export class WshFileTransfer {
    * @returns {Promise<Uint8Array>} File content
    */
   async download(remotePath, { onProgress, timeout = RESPONSE_TIMEOUT_MS } = {}) {
-    if (typeof this.#client.download === 'function') {
-      return await this.#client.download(remotePath, { onProgress, timeout });
-    }
-
-    if (!remotePath || typeof remotePath !== 'string') {
-      throw new Error('remotePath is required');
-    }
-
-    // 1. Request a file download channel
-    const openMsg = open({
-      kind: CHANNEL_KIND.FILE,
-      command: 'download',
-    });
-    openMsg.path = remotePath;
-
-    await this.#client.sendControl(openMsg);
-
-    // 2. Wait for OPEN_OK or OPEN_FAIL
-    const response = await this._waitForMessage(
-      (msg) => msg.type === MSG.OPEN_OK || msg.type === MSG.OPEN_FAIL,
-      timeout
-    );
-
-    if (response.type === MSG.OPEN_FAIL) {
-      throw new Error(`Download rejected: ${response.reason || 'unknown reason'}`);
-    }
-
-    const channelId = response.channel_id;
-    const totalSize = response.size; // Server may include total file size
-
-    // 3. Open a dedicated data stream and read chunks
-    const stream = await this.#client.openStream();
-    const reader = stream.readable.getReader();
-    const chunks = [];
-    let received = 0;
-
-    try {
-      while (true) {
-        const { done, value } = await reader.read();
-        if (done) break;
-
-        chunks.push(value);
-        received += value.length;
-
-        try {
-          onProgress?.({ received, total: totalSize });
-        } catch { /* ignore callback errors */ }
-      }
-    } finally {
-      reader.releaseLock();
+    if (typeof this.#client.download !== 'function') {
+      throw new Error('WshFileTransfer requires a client exposing download() (e.g. WshClient)');
     }
-
-    // 4. Wait for EXIT confirmation
-    try {
-      const exitMsg = await this._waitForMessage(
-        (msg) => msg.type === MSG.EXIT && msg.channel_id === channelId,
-        timeout
-      );
-      if (exitMsg.code !== 0) {
-        throw new Error(`Download failed with exit code ${exitMsg.code}`);
-      }
-    } catch (err) {
-      // If the stream closed cleanly and we got data, the EXIT may have
-      // already been consumed or the server may not send one for downloads.
-      // Only rethrow if we have no data.
-      if (received === 0) throw err;
-    }
-
-    // Concatenate chunks into a single Uint8Array
-    return this._concatChunks(chunks, received);
+    return await this.#client.download(remotePath, { onProgress, timeout });
   }
 
   /**

package/src/index.d.ts

@@ -421,6 +421,7 @@ export function reversePeers(opts?: {
 export function reverseConnect(opts?: {
   targetFingerprint?: string;
   username?: string;
+  fromFingerprint?: string;
 }): WshMessage;
 
 export function reverseAccept(opts?: {
@@ -441,6 +442,16 @@ export function reverseReject(opts?: {
   reason?: string;
 }): WshMessage;
 
+export function relayForward(opts?: {
+  fromFingerprint?: string;
+  inner?: Uint8Array;
+}): WshMessage;
+
+/** Message types a relay may forward inside a RelayForward wrapper. */
+export const RELAY_FORWARDABLE: ReadonlySet<number>;
+
+export function isRelayForwardable(typeNum: number): boolean;
+
 // -- Message constructors (gateway) --
 
 export function openTcp(opts?: {
@@ -622,6 +633,37 @@ export function verifyChallenge(
   channelBinding?: Uint8Array,
 ): Promise<boolean>;
 
+/** Fields of a signed peer record (reverse-mode registration). See `signPeerRecord`. */
+export interface WshPeerRecord {
+  username: string;
+  peerType?: string;
+  shellBackend?: string;
+  capabilities?: string[];
+  supportsAttach?: boolean;
+  supportsReplay?: boolean;
+  supportsEcho?: boolean;
+  supportsTermSync?: boolean;
+  /** The signing peer's own monotonic counter (current-time-millis in practice). */
+  seq: number;
+}
+
+/**
+ * Build the signed transcript for a peer record -- domain-separated from
+ * `buildTranscript`'s auth-challenge transcript even under the same key.
+ * @returns 32-byte SHA-256 hash
+ */
+export function buildPeerRecordTranscript(record: WshPeerRecord): Promise<Uint8Array>;
+
+/** Client-side: sign a peer record with the identity key pair. */
+export function signPeerRecord(
+  privateKey: CryptoKey,
+  publicKey: CryptoKey,
+  record: WshPeerRecord,
+): Promise<{ signature: Uint8Array; publicKeyRaw: Uint8Array }>;
+
+/** Verify a peer record's signature against the claimed record fields. */
+export function verifyPeerRecord(publicKey: CryptoKey, signature: Uint8Array, record: WshPeerRecord): Promise<boolean>;
+
 /**
  * Compute the SHA-256 fingerprint of a raw public key.
  * @returns hex-encoded fingerprint
@@ -973,6 +1015,33 @@ export interface WshPeerInfo {
   supports_echo: boolean;
   supports_term_sync: boolean;
   last_seen: number | null;
+  /** Raw 32-byte Ed25519 public key from the peer's signed record, if present. */
+  public_key?: Uint8Array;
+  /** The signing peer's own monotonic counter, from the signed record. */
+  seq?: number;
+  /** Raw Ed25519 signature over the peer record's transcript, if present. */
+  record_signature?: Uint8Array;
+  /**
+   * Not a wire field -- computed client-side by `listPeers()` from
+   * `public_key`/`seq`/`record_signature` via `verifyPeerRecord`. `true`
+   * only if the signature verifies AND the key's fingerprint matches
+   * `fingerprint`; `false` for missing/tampered/mismatched records.
+   */
+  verified: boolean;
+}
+
+/** Result from WshClient.initiateE2E(). */
+export interface WshE2EResult {
+  /** Non-extractable AES-256-GCM key derived from the exchange. */
+  sharedSecret: CryptoKey;
+  /** The peer's ephemeral X25519 public key. */
+  peerPublicKey: Uint8Array;
+  /**
+   * Whether hybrid X25519+ML-KEM-768 mode actually took effect --
+   * `false` if `algorithm: 'X25519'` was requested, or if hybrid was
+   * requested but the peer didn't support it (automatic fallback).
+   */
+  hybrid: boolean;
 }
 
 /**
@@ -1057,6 +1126,27 @@ export class WshClient {
    */
   resumeSession(targetSessionId: string, token: string, opts?: { timeout?: number }): Promise<WshMessage>;
 
+  /**
+   * Detach from a remote session, leaving it running server-side.
+   */
+  detach(sessionId: string, timeout?: number): Promise<void>;
+
+  /**
+   * List sessions on the server this connection's key can see (a server
+   * round trip — distinct from the purely local listSessions()).
+   */
+  listRemoteSessions(timeout?: number): Promise<object[]>;
+
+  /**
+   * Grant another principal access to a session this connection owns.
+   */
+  grantSessionAccess(sessionId: string, principal: string, permissions?: string[]): Promise<void>;
+
+  /**
+   * Revoke a previously granted principal's access to a session.
+   */
+  revokeSessionAccess(sessionId: string, principal: string, reason?: string): Promise<void>;
+
   /**
    * Gracefully disconnect: close all sessions and the transport.
    */
@@ -1095,6 +1185,26 @@ export class WshClient {
    */
   sendRelayControl(msg: WshMessage): Promise<void>;
 
+  /**
+   * Initiate end-to-end encryption for a session: `'X25519'` (default,
+   * classical ECDH) or `'X25519+ML-KEM-768'` (hybrid, with automatic
+   * fallback to classical if the peer doesn't support it). Experimental
+   * -- the derived key is not yet wired to any actual encryption.
+   */
+  initiateE2E(sessionId: string, algorithm?: 'X25519' | 'X25519+ML-KEM-768', timeout?: number): Promise<WshE2EResult>;
+
+  /**
+   * Mark a peer fingerprint as an accepted reverse-connect bridge partner.
+   * Only RelayForward-wrapped messages whose from_fingerprint is trusted
+   * this way are unwrapped and delivered via onRelayMessage.
+   */
+  trustRelayPeer(fingerprint: string): void;
+
+  /**
+   * Stop trusting a peer as a relay-forward bridge partner.
+   */
+  untrustRelayPeer(fingerprint: string): void;
+
   /**
    * Upload a blob to a remote path.
    */

package/src/index.mjs

@@ -17,6 +17,7 @@ export {
   presence, controlChanged, metrics,
   mcpDiscover, mcpTools, mcpCall, mcpResult,
   reverseRegister, reverseList, reversePeers, reverseConnect, reverseAccept, reverseReject,
+  relayForward, RELAY_FORWARDABLE, isRelayForwardable,
   openTcp, openUdp, resolveDns, gatewayOk, gatewayFail, gatewayClose,
   inboundOpen, inboundAccept, inboundReject, dnsResult,
   listenRequest, listenOk, listenFail, listenClose, gatewayData,
@@ -44,6 +45,7 @@ export {
   generateKeyPair, exportPublicKeyRaw, exportPublicKeySSH,
   importPublicKeyRaw, exportPrivateKeyPKCS8, importPrivateKeyPKCS8,
   sign, verify, buildTranscript, signChallenge, verifyChallenge,
+  buildPeerRecordTranscript, signPeerRecord, verifyPeerRecord,
   fingerprint, shortFingerprint, generateNonce,
   parseSSHPublicKey, extractRawFromSSHWire, base64Decode,
 } from './auth.mjs';
@@ -52,6 +54,17 @@ export {
 export { WshTransport, WebTransportTransport, dispatchSerially, SerialQueue } from './transport.mjs';
 export { WebSocketTransport, WS_FRAME_TYPE } from './transport-ws.mjs';
 
+// QMux (QUIC-v1 frames over an ordered byte stream, draft-ietf-quic-qmux-02)
+// -- the wire multiplexing layer WebSocketTransport speaks. Exposed so an
+// alternate server implementation (not just the Rust wsh-server, which
+// vendors its own port) can speak the same framing without reimplementing
+// it -- see clawser's tools/wsh-server.mjs for exactly this use case.
+export { QMuxConnection, DEFAULTS as QMUX_DEFAULTS } from './qmux-connection.mjs';
+export {
+  ERROR_CODE as QMUX_ERROR_CODE, STREAM_INITIATOR as QMUX_STREAM_INITIATOR,
+  firstBidiStreamId, nextBidiStreamId, isClientInitiated, isBidirectional,
+} from './qmux.mjs';
+
 // Session + Client
 export { WshSession } from './session.mjs';
 export { WshVirtualSessionBackend, normalizeSessionData } from './virtual-session.mjs';

package/src/messages.gen.mjs

@@ -62,6 +62,7 @@ export const MSG = Object.freeze({
   REVERSE_CONNECT:   0x53,
   REVERSE_ACCEPT:    0x54,
   REVERSE_REJECT:    0x55,
+  RELAY_FORWARD:     0x56,
 
   // Session
   SESSION_LIST:      0x5f,
@@ -457,7 +458,7 @@ export function mcpResult({ result } = {}) {
   };
 }
 
-export function reverseRegister({ username, capabilities = [], peerType = "host", shellBackend = "pty", supportsAttach = false, supportsReplay = false, supportsEcho = false, supportsTermSync = false, publicKey } = {}) {
+export function reverseRegister({ username, capabilities = [], peerType = "host", shellBackend = "pty", supportsAttach = false, supportsReplay = false, supportsEcho = false, supportsTermSync = false, publicKey, seq, recordSignature } = {}) {
   return {
     type: MSG.REVERSE_REGISTER,
     username,
@@ -469,6 +470,8 @@ export function reverseRegister({ username, capabilities = [], peerType = "host"
     supports_echo: supportsEcho,
     supports_term_sync: supportsTermSync,
     public_key: publicKey,
+    seq,
+    record_signature: recordSignature,
   };
 }
 
@@ -483,11 +486,12 @@ export function reversePeers({ peers } = {}) {
   };
 }
 
-export function reverseConnect({ targetFingerprint, username } = {}) {
+export function reverseConnect({ targetFingerprint, username, fromFingerprint } = {}) {
   return {
     type: MSG.REVERSE_CONNECT,
     target_fingerprint: targetFingerprint,
     username,
+    from_fingerprint: fromFingerprint,
   };
 }
 
@@ -515,6 +519,14 @@ export function reverseReject({ targetFingerprint, username, reason } = {}) {
   };
 }
 
+export function relayForward({ fromFingerprint, inner } = {}) {
+  return {
+    type: MSG.RELAY_FORWARD,
+    from_fingerprint: fromFingerprint,
+    inner,
+  };
+}
+
 export function sessionList({ sessions } = {}) {
   return {
     type: MSG.SESSION_LIST,
@@ -759,13 +771,12 @@ export function copilotDetach({ sessionId, reason } = {}) {
   return msg;
 }
 
-export function keyExchange({ algorithm, publicKey, sessionId } = {}) {
-  return {
-    type: MSG.KEY_EXCHANGE,
-    algorithm,
-    public_key: publicKey,
-    session_id: sessionId,
-  };
+export function keyExchange({ algorithm, publicKey, sessionId, kemPublicKey, kemCiphertext } = {}) {
+  const msg = { type: MSG.KEY_EXCHANGE, algorithm, session_id: sessionId };
+  if (publicKey !== undefined) msg.public_key = publicKey;
+  if (kemPublicKey !== undefined) msg.kem_public_key = kemPublicKey;
+  if (kemCiphertext !== undefined) msg.kem_ciphertext = kemCiphertext;
+  return msg;
 }
 
 export function encryptedFrame({ nonce, ciphertext, sessionId } = {}) {
@@ -859,13 +870,14 @@ export function fileResult({ channelId, success, metadata = {}, errorMessage } =
   return msg;
 }
 
-export function fileChunk({ channelId, offset, data, isFinal } = {}) {
+export function fileChunk({ channelId, offset, data, isFinal, totalSize } = {}) {
   return {
     type: MSG.FILE_CHUNK,
     channel_id: channelId,
     offset,
     data,
     is_final: isFinal,
+    total_size: totalSize,
   };
 }
 
@@ -903,6 +915,50 @@ export function terminalConfig({ channelId, frontend, options = {} } = {}) {
   };
 }
 
+// ── Relay forwarding ─────────────────────────────────────────────────
+
+// Message types a relay may forward inside a RelayForward wrapper.
+export const RELAY_FORWARDABLE = new Set([
+  MSG.OPEN,
+  MSG.OPEN_OK,
+  MSG.OPEN_FAIL,
+  MSG.CLOSE,
+  MSG.EXIT,
+  MSG.RESIZE,
+  MSG.SIGNAL,
+  MSG.SESSION_DATA,
+  MSG.GATEWAY_DATA,
+  MSG.GATEWAY_OK,
+  MSG.GATEWAY_FAIL,
+  MSG.GATEWAY_CLOSE,
+  MSG.MCP_DISCOVER,
+  MSG.MCP_TOOLS,
+  MSG.MCP_CALL,
+  MSG.MCP_RESULT,
+  MSG.REVERSE_ACCEPT,
+  MSG.REVERSE_REJECT,
+  MSG.GUEST_JOIN,
+  MSG.GUEST_REVOKE,
+  MSG.COPILOT_ATTACH,
+  MSG.COPILOT_DETACH,
+  MSG.FILE_OP,
+  MSG.FILE_RESULT,
+  MSG.FILE_CHUNK,
+  MSG.POLICY_EVAL,
+  MSG.ECHO_ACK,
+  MSG.ECHO_STATE,
+  MSG.TERM_SYNC,
+  MSG.TERM_DIFF,
+]);
+
+/**
+ * @param {number} typeNum
+ * @returns {boolean}
+ */
+export function isRelayForwardable(typeNum) {
+  return RELAY_FORWARDABLE.has(typeNum);
+}
+
 // ── Utility ───────────────────────────────────────────────────────────
 
 /**

package/src/messages.mjs

@@ -1,3 +1,3 @@
 // Auto-generated messages — DO NOT EDIT messages.gen.mjs directly
-// Edit web/packages/wsh/spec/wsh-v1.yaml and run: node web/packages/wsh/spec/codegen.mjs
+// Edit spec/wsh-v1.yaml and run: node spec/codegen.mjs
 export * from './messages.gen.mjs';