@johnhenry/wsh 0.14.0 → 0.15.0

package/README.md

@@ -1,4 +1,4 @@
-# wsh-upon-star
+# @johnhenry/wsh
 
 Full documentation: [opensource.johnhenry.me/wsh](https://opensource.johnhenry.me/wsh/)
 
@@ -8,7 +8,7 @@ Full documentation: [opensource.johnhenry.me/wsh](https://opensource.johnhenry.m
 
 Browser-native remote command execution over WebTransport/WebSocket with Ed25519 authentication.
 
-wsh-upon-star is a pure-JS client library that connects browsers to remote shells. It implements its own binary protocol (CBOR over length-prefixed frames) with Ed25519 challenge-response auth, channel multiplexing, session management, and MCP tool bridging.
+wsh is a pure-JS client library that connects browsers to remote shells. It implements its own binary protocol — CBOR messages over QMux-multiplexed WebSocket or native WebTransport streams — with Ed25519 challenge-response auth, session management, and MCP tool bridging.
 
 ## Install
 
@@ -26,16 +26,28 @@ Or via CDN:
 
 ## Features
 
-- **Ed25519 authentication** -- challenge-response via Web Crypto API, SSH key format support
-- **Dual transport** -- WebTransport (native streams) and WebSocket (multiplexed virtual streams) with identical API
+- **Ed25519 authentication** -- challenge-response via Web Crypto API with a transcript binding username and session id, SSH key format support
+- **Dual transport** -- WebTransport (native streams) and WebSocket (QMux-multiplexed streams) with identical API
 - **CBOR encoding** -- compact binary wire format with length-prefixed framing
-- **Session management** -- open, attach, resume, detach, rename PTY/exec sessions
-- **Reverse mode** -- register as a peer and accept incoming connections through a relay
-- **File transfer** -- scp-like upload/download over dedicated streams in 64KB chunks
+- **Session management** -- open, attach, resume, detach, rename PTY/exec sessions, with session-scoped resume tokens and per-principal access grants
+- **Reverse mode** -- register as a peer (via a signed peer record) and accept incoming connections through a relay
+- **File transfer** -- scp-like upload/download as `FileChunk` control messages in 64KB chunks
 - **MCP bridge** -- discover and invoke remote MCP tools through the control channel
 - **Session recording** -- asciicast v2 compatible recording and playback with seek/pause/resume
 - **Key management** -- IndexedDB storage with OPFS encrypted backup (PBKDF2 + AES-256-GCM)
-- **80+ message types** -- handshake, channel, gateway, guest sharing, compression negotiation, copilot, policy, and more
+- **95 message types** -- handshake, channel, gateway, guest sharing, compression negotiation, copilot, policy, and more
+
+## Wire Protocol: QMux
+
+Over WebSocket, wsh multiplexes streams with QMux (draft-ietf-quic-qmux-02):
+QUIC-v1 frames -- RFC 9000 varints, STREAM, RESET_STREAM, STOP_SENDING,
+MAX_DATA/MAX_STREAM_DATA/MAX_STREAMS, CONNECTION_CLOSE, DATAGRAM, plus
+RESET_STREAM_AT from draft-ietf-quic-reliable-stream-reset -- carried in
+self-delimiting Records over the ordered, reliable WebSocket byte stream.
+The control channel is QMux stream 0, and every stream gets QUIC-style
+windowed flow control, so a slow consumer exerts real backpressure.
+`QMuxConnection` and the frame codec primitives are exported so alternate
+server implementations can speak the same framing.
 
 ## Quick Start
 
@@ -94,6 +106,27 @@ console.log(new TextDecoder().decode(stdout));
 console.log('Exit code:', exitCode);
 ```
 
+## Attach and Resume
+
+Opening a PTY/exec session returns a session-scoped credential alongside the channel:
+
+```js
+session.sessionId;   // server-assigned session id (undefined for e.g. file channels)
+session.resumeToken; // token minted at open time; only the opener receives it
+
+// The original opener, reclaiming its session from a fresh connection:
+await client.resumeSession(session.sessionId, session.resumeToken);
+
+// Any other authorized principal attaches without a token -- ownership
+// or an ACL grant is enough:
+await client.grantSessionAccess(session.sessionId, 'bob');  // by the owner
+await otherClient.attachSession(session.sessionId);         // by 'bob'
+
+// Other session-management round trips:
+await client.detach(session.sessionId);   // leave it running server-side
+await client.listRemoteSessions();        // sessions this key can see
+```
+
 ## API Overview
 
 ### Core Classes
@@ -117,17 +150,19 @@ console.log('Exit code:', exitCode);
 | `SessionPlayer` | Replay recordings with original timing |
 | `generateKeyPair()` | Create Ed25519 key pair via Web Crypto |
 | `signChallenge()` | Build transcript + sign for auth handshake |
+| `signPeerRecord()` / `verifyPeerRecord()` | Sign / verify reverse-mode peer records |
 | `fingerprint()` | SHA-256 hex fingerprint of a public key |
 
 ### Protocol
 
 | Export | Description |
 |--------|-------------|
-| `MSG` | 80+ message type constants (hex opcodes) |
+| `MSG` | 95 message type constants (hex opcodes) |
 | `CHANNEL_KIND` | Channel types: `pty`, `exec`, `meta`, `file`, `tcp`, `udp`, `job` |
 | `AUTH_METHOD` | Auth methods: `pubkey`, `password` |
 | `cborEncode` / `cborDecode` | CBOR codec (maps, arrays, strings, ints, bytes, bools, null, floats) |
 | `frameEncode` / `FrameDecoder` | 4-byte big-endian length-prefixed framing |
+| `QMuxConnection` + QMux primitives | QMux stream state machine, error codes, and stream-id helpers for building alternate servers |
 
 ## Protocol Specification
 
@@ -137,6 +172,25 @@ The `spec/` directory contains the protocol definition:
 - `wsh-v1.md` -- human-readable protocol specification
 - `codegen.mjs` -- generates `messages.gen.mjs` from the YAML spec
 
+## Security
+
+- **Auth transcript binding** -- challenge signatures cover
+  `SHA-256("wsh-v1\0" || lp(username) || lp(session_id) || nonce || channel_binding)`,
+  so a signature can't be replayed against a different session or relabeled
+  to a different username.
+- **Signed peer records** -- reverse-mode registration is self-signed by the
+  peer's identity key (the libp2p RFC 0002/0003 pattern), in a signing
+  domain separate from the auth challenge. `listPeers()` verifies every
+  entry client-side and reports a `verified` boolean, independent of
+  trusting the relay.
+- **Hybrid post-quantum E2E (experimental)** --
+  `initiateE2E(sessionId, 'X25519+ML-KEM-768')` combines X25519 ECDH with
+  ML-KEM-768 via HKDF-SHA256, preferring native WebCrypto ML-KEM-768 (Node
+  24.7+) with the optional `@noble/post-quantum` pure-JS fallback, and
+  falling back to classical X25519 automatically when the peer can't do
+  hybrid (check the returned `hybrid` flag). The derived AES-256-GCM key is
+  not yet wired to actual frame encryption.
+
 ## Browser Compatibility
 
 Requires a browser (or Node.js 24+) with:
@@ -147,6 +201,10 @@ Requires a browser (or Node.js 24+) with:
 - TextEncoder/TextDecoder
 - ReadableStream/WritableStream
 
+Hybrid ML-KEM-768 key exchange prefers native WebCrypto ML-KEM (Node 24.7+,
+some browsers); elsewhere the optional `@noble/post-quantum` dependency is
+loaded dynamically.
+
 ## License
 
 MIT

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@johnhenry/wsh",
-  "version": "0.14.0",
-  "description": "Web Shell \u2014 browser-native remote command execution over WebTransport and WebSocket with Ed25519 authentication",
+  "version": "0.15.0",
+  "description": "Web Shell — browser-native remote command execution over WebTransport and WebSocket with Ed25519 authentication",
   "type": "module",
   "main": "./src/index.mjs",
   "exports": {

package/src/e2e-frame.mjs

@@ -0,0 +1,177 @@
+/**
+ * EncryptedFrame sealing/opening for wsh's opt-in end-to-end encryption
+ * layer (see `client.mjs`'s `initiateE2E`, which derives the AES-256-GCM
+ * `CryptoKey` this module seals/opens with, and `spec/wsh-v1.yaml`'s
+ * `EncryptedFrame` message).
+ *
+ * This is PR 1 of a multi-PR E2E rollout: it implements the AEAD
+ * primitives and wires them into virtual-mode sessions only (see
+ * `session.mjs`'s `enableE2E`). Stream-mode sessions (raw WebTransport
+ * byte streams with no message boundaries) are explicitly out of scope
+ * here -- they need separate ad hoc chunk-framing design.
+ *
+ * ── Nonce construction ─────────────────────────────────────────────
+ * Nonces are the AES-GCM-mandated 96 bits (12 bytes), built as:
+ *
+ *   [ 8-byte big-endian monotonic counter ][ 4-byte sender-role tag ]
+ *
+ * The counter starts at 0 and increments by one for every frame a given
+ * sender seals (never reused, per `openFrame`'s strict expected-counter
+ * check below). The 4-byte role tag is fixed per sender for the
+ * lifetime of one E2E-enabled connection (see `session.mjs`'s
+ * `enableE2E({ role })`) and differs between the two peers of a
+ * session, so the two directions of one session structurally cannot
+ * produce a colliding nonce even under fully concurrent bidirectional
+ * traffic -- the 8-byte counter alone would collide if both sides ever
+ * reached the same count, but the two peers' tags never match, so the
+ * full 12-byte nonces never match either.
+ *
+ * ── AAD ────────────────────────────────────────────────────────────
+ * The frame's `session_id` (UTF-8 bytes) is bound as AES-GCM
+ * "additional authenticated data": it's authenticated but never
+ * encrypted, so ciphertext can't be spliced from one session onto
+ * another by a relay that only ever sees ciphertext (the server, for a
+ * genuinely E2E session) -- decryption fails if the session_id supplied
+ * to `openFrame` doesn't match the one the ciphertext was sealed under.
+ *
+ * ── Replay/reorder protection ─────────────────────────────────────
+ * `openFrame` requires the frame's nonce counter to be *exactly* the
+ * caller-supplied `expectedCounter` -- not merely "not yet seen" or
+ * "not too old". This is intentionally strict for v1: any replayed,
+ * duplicated, dropped, or reordered frame is rejected outright rather
+ * than tolerated or reordered-and-delivered. A later PR can relax this
+ * to a sliding window if wsh ever needs to tolerate out-of-order
+ * delivery for E2E frames; today's virtual-mode transport already
+ * delivers control messages in order, so strict-next-counter is not a
+ * practical limitation.
+ *
+ * ── Key lifetime ───────────────────────────────────────────────────
+ * The `key` passed to `sealFrame`/`openFrame` is connection-scoped, not
+ * session-scoped: a session that is detached and later Resumed/Attached
+ * on a new connection MUST run a fresh `initiateE2E()` and call
+ * `enableE2E()` again with the new key. Never persist or reuse a
+ * `sharedSecret` (or its counters) across a resume -- see
+ * `session.mjs`'s `enableE2E` doc comment.
+ */
+
+const NONCE_LENGTH = 12;
+const COUNTER_LENGTH = 8;
+const ROLE_TAG_LENGTH = 4;
+
+const textEncoder = new TextEncoder();
+
+/**
+ * Encode a non-negative integer counter as an 8-byte big-endian value.
+ * @param {number} counter
+ * @returns {Uint8Array}
+ */
+function encodeCounter(counter) {
+  if (!Number.isInteger(counter) || counter < 0) {
+    throw new Error(`e2e-frame: counter must be a non-negative integer, got ${counter}`);
+  }
+  const bytes = new Uint8Array(COUNTER_LENGTH);
+  const view = new DataView(bytes.buffer);
+  // DataView.setBigUint64 covers the full 64-bit range; counters here
+  // never realistically approach it, but there's no reason to cap early.
+  view.setBigUint64(0, BigInt(counter), false);
+  return bytes;
+}
+
+/**
+ * Build the 12-byte nonce for a given (counter, role tag) pair. Exported
+ * mainly for tests -- callers should go through `sealFrame`/`openFrame`.
+ *
+ * @param {number} counter
+ * @param {Uint8Array} roleTag - exactly 4 bytes
+ * @returns {Uint8Array}
+ */
+export function buildNonce(counter, roleTag) {
+  if (!(roleTag instanceof Uint8Array) || roleTag.length !== ROLE_TAG_LENGTH) {
+    throw new Error(`e2e-frame: roleTag must be a ${ROLE_TAG_LENGTH}-byte Uint8Array`);
+  }
+  const nonce = new Uint8Array(NONCE_LENGTH);
+  nonce.set(encodeCounter(counter), 0);
+  nonce.set(roleTag, COUNTER_LENGTH);
+  return nonce;
+}
+
+/**
+ * Seal a plaintext frame under an AES-256-GCM key.
+ *
+ * @param {CryptoKey} key - non-extractable AES-GCM CryptoKey (e.g. from `client.mjs`'s `initiateE2E`)
+ * @param {string} sessionId - bound as AAD
+ * @param {Uint8Array} roleTag - 4-byte sender role tag, distinct between the two peers of a session
+ * @param {number} counter - this sender's next monotonic send counter (0, 1, 2, ...)
+ * @param {Uint8Array} plaintext
+ * @returns {Promise<{nonce: Uint8Array, ciphertext: Uint8Array}>}
+ */
+export async function sealFrame(key, sessionId, roleTag, counter, plaintext) {
+  if (!key || typeof key !== 'object') {
+    throw new Error('e2e-frame: sealFrame requires a CryptoKey');
+  }
+  const nonce = buildNonce(counter, roleTag);
+  const aad = textEncoder.encode(sessionId);
+  const ciphertext = new Uint8Array(await crypto.subtle.encrypt(
+    { name: 'AES-GCM', iv: nonce, additionalData: aad },
+    key,
+    plaintext
+  ));
+  return { nonce, ciphertext };
+}
+
+/**
+ * Open (decrypt + authenticate) a sealed frame.
+ *
+ * Throws if:
+ *  - the AEAD authentication tag doesn't verify (tampered ciphertext,
+ *    wrong key, or `sessionId` mismatch since it's bound as AAD), or
+ *  - the frame's nonce counter isn't exactly `expectedCounter` (replay,
+ *    reorder, or drop -- see this module's doc comment).
+ *
+ * @param {CryptoKey} key
+ * @param {string} sessionId - must match what the frame was sealed with (bound as AAD)
+ * @param {number} expectedCounter - the exact next counter this peer expects from the sender
+ * @param {{nonce: Uint8Array, ciphertext: Uint8Array}} frame
+ * @returns {Promise<Uint8Array>} plaintext
+ */
+export async function openFrame(key, sessionId, expectedCounter, { nonce, ciphertext }) {
+  if (!key || typeof key !== 'object') {
+    throw new Error('e2e-frame: openFrame requires a CryptoKey');
+  }
+  if (!(nonce instanceof Uint8Array) || nonce.length !== NONCE_LENGTH) {
+    throw new Error(`e2e-frame: nonce must be a ${NONCE_LENGTH}-byte Uint8Array`);
+  }
+  const actualCounter = Number(new DataView(nonce.buffer, nonce.byteOffset, nonce.byteLength).getBigUint64(0, false));
+  if (actualCounter !== expectedCounter) {
+    throw new Error(
+      `e2e-frame: replay/reorder detected -- expected counter ${expectedCounter}, got ${actualCounter}`
+    );
+  }
+  const aad = textEncoder.encode(sessionId);
+  try {
+    return new Uint8Array(await crypto.subtle.decrypt(
+      { name: 'AES-GCM', iv: nonce, additionalData: aad },
+      key,
+      ciphertext
+    ));
+  } catch (err) {
+    throw new Error(`e2e-frame: authentication failed while opening frame (${err.message})`);
+  }
+}
+
+export const E2E_NONCE_LENGTH = NONCE_LENGTH;
+export const E2E_ROLE_TAG_LENGTH = ROLE_TAG_LENGTH;
+
+/**
+ * Deterministic 4-byte role tags for the two sides of one E2E-enabled
+ * connection. Callers pick a role at `enableE2E()` time -- 'initiator'
+ * is naturally the side that called `initiateE2E()` first / sent round-1
+ * KeyExchange, 'responder' the other side; any consistent, non-
+ * overlapping assignment works since these are just fixed structural
+ * tags, not secret values.
+ * @type {Record<'initiator'|'responder', Uint8Array>}
+ */
+export const ROLE_TAGS = Object.freeze({
+  initiator: Uint8Array.from([0x69, 0x6e, 0x69, 0x74]), // "init"
+  responder: Uint8Array.from([0x72, 0x65, 0x73, 0x70]), // "resp"
+});

package/src/index.d.ts

@@ -126,6 +126,7 @@ export const MSG: {
   readonly REVERSE_CONNECT: 0x53;
   readonly REVERSE_ACCEPT: 0x54;
   readonly REVERSE_REJECT: 0x55;
+  readonly RELAY_FORWARD: 0x56;
 
   // Gateway
   readonly OPEN_TCP: 0x70;
@@ -249,6 +250,7 @@ export function serverHello(opts?: {
 
 export function challenge(opts?: {
   nonce?: Uint8Array;
+  sessionId?: string;
 }): WshMessage;
 
 export function authMethods(opts?: {
@@ -264,7 +266,7 @@ export function auth(opts?: {
 
 export function authOk(opts?: {
   sessionId?: string;
-  token?: string;
+  token?: Uint8Array;
   ttl?: number;
 }): WshMessage;
 
@@ -287,6 +289,8 @@ export function openOk(opts?: {
   streamIds?: number[];
   dataMode?: string;
   capabilities?: string[];
+  sessionId?: string;
+  token?: Uint8Array;
 }): WshMessage;
 
 export function openFail(opts?: {
@@ -337,14 +341,14 @@ export function pong(opts?: {
 
 export function attach(opts?: {
   sessionId?: string;
-  token?: string;
+  token?: Uint8Array;
   mode?: string;
   deviceLabel?: string;
 }): WshMessage;
 
 export function resume(opts?: {
   sessionId?: string;
-  token?: string;
+  token?: Uint8Array;
   lastSeq?: number;
 }): WshMessage;
 
@@ -410,6 +414,10 @@ export function reverseRegister(opts?: {
   supportsEcho?: boolean;
   supportsTermSync?: boolean;
   publicKey?: Uint8Array | null;
+  /** The signing peer's own monotonic counter for its signed peer record. */
+  seq?: number;
+  /** Ed25519 signature over the peer record transcript (see signPeerRecord). */
+  recordSignature?: Uint8Array;
 }): WshMessage;
 
 export function reverseList(): WshMessage;
@@ -536,6 +544,262 @@ export function gatewayData(opts?: {
   data?: Uint8Array;
 }): WshMessage;
 
+// -- Message constructors (session extras) --
+
+export function clipboard(opts?: {
+  direction?: string;
+  data?: string;
+}): WshMessage;
+
+export function recordingExport(opts?: {
+  sessionId?: string;
+  format?: string;
+  data?: string;
+}): WshMessage;
+
+export function commandJournal(opts?: {
+  sessionId?: string;
+  command?: string;
+  exitCode?: number;
+  durationMs?: number;
+  cwd?: string;
+  timestamp?: number;
+}): WshMessage;
+
+export function metricsRequest(): WshMessage;
+
+export function suspendSession(opts?: {
+  sessionId?: string;
+  action?: string;
+}): WshMessage;
+
+export function restartPty(opts?: {
+  sessionId?: string;
+  command?: string;
+}): WshMessage;
+
+export function sessionListRequest(): WshMessage;
+
+export function sessionList(opts?: {
+  sessions?: unknown[];
+}): WshMessage;
+
+export function detach(opts?: {
+  sessionId?: string;
+}): WshMessage;
+
+export function detachOk(opts?: {
+  sessionId?: string;
+}): WshMessage;
+
+export function detachFail(opts?: {
+  reason?: string;
+}): WshMessage;
+
+// -- Message constructors (guest sharing) --
+
+export function guestInvite(opts?: {
+  sessionId?: string;
+  ttl?: number;
+  permissions?: string[];
+}): WshMessage;
+
+export function guestJoin(opts?: {
+  token?: string;
+  deviceLabel?: string;
+}): WshMessage;
+
+export function guestRevoke(opts?: {
+  token?: string;
+  reason?: string;
+}): WshMessage;
+
+export function shareSession(opts?: {
+  sessionId?: string;
+  mode?: string;
+  ttl?: number;
+}): WshMessage;
+
+export function shareRevoke(opts?: {
+  shareId?: string;
+  reason?: string;
+}): WshMessage;
+
+// -- Message constructors (compression / rate control / linking) --
+
+export function compressBegin(opts?: {
+  algorithm?: string;
+  level?: number;
+}): WshMessage;
+
+export function compressAck(opts?: {
+  algorithm?: string;
+  accepted?: boolean;
+}): WshMessage;
+
+export function rateControl(opts?: {
+  sessionId?: string;
+  maxBytesPerSec?: number;
+  policy?: string;
+}): WshMessage;
+
+export function rateWarning(opts?: {
+  sessionId?: string;
+  queuedBytes?: number;
+  action?: string;
+}): WshMessage;
+
+export function sessionLink(opts?: {
+  sourceSession?: string;
+  targetHost?: string;
+  targetPort?: number;
+  targetUser?: string;
+}): WshMessage;
+
+export function sessionUnlink(opts?: {
+  linkId?: string;
+  reason?: string;
+}): WshMessage;
+
+// -- Message constructors (copilot) --
+
+export function copilotAttach(opts?: {
+  sessionId?: string;
+  model?: string;
+  contextWindow?: number;
+}): WshMessage;
+
+export function copilotSuggest(opts?: {
+  sessionId?: string;
+  suggestion?: string;
+  confidence?: number;
+}): WshMessage;
+
+export function copilotDetach(opts?: {
+  sessionId?: string;
+  reason?: string;
+}): WshMessage;
+
+// -- Message constructors (e2e / echo / termsync) --
+
+export function keyExchange(opts?: {
+  algorithm?: string;
+  publicKey?: Uint8Array;
+  sessionId?: string;
+  kemPublicKey?: Uint8Array;
+  kemCiphertext?: Uint8Array;
+}): WshMessage;
+
+export function encryptedFrame(opts?: {
+  nonce?: Uint8Array;
+  ciphertext?: Uint8Array;
+  sessionId?: string;
+}): WshMessage;
+
+export function echoAck(opts?: {
+  channelId?: number;
+  echoSeq?: number;
+}): WshMessage;
+
+export function echoState(opts?: {
+  channelId?: number;
+  echoSeq?: number;
+  cursorX?: number;
+  cursorY?: number;
+  pending?: number;
+}): WshMessage;
+
+export function termSync(opts?: {
+  channelId?: number;
+  frameSeq?: number;
+  stateHash?: Uint8Array;
+}): WshMessage;
+
+export function termDiff(opts?: {
+  channelId?: number;
+  frameSeq?: number;
+  baseSeq?: number;
+  patch?: Uint8Array;
+}): WshMessage;
+
+// -- Message constructors (scaling / principals) --
+
+export function nodeAnnounce(opts?: {
+  nodeId?: string;
+  endpoint?: string;
+  load?: number;
+  capacity?: number;
+}): WshMessage;
+
+export function nodeRedirect(opts?: {
+  targetNode?: string;
+  targetEndpoint?: string;
+  sessionId?: string;
+  reason?: string;
+}): WshMessage;
+
+export function sessionGrant(opts?: {
+  sessionId?: string;
+  principal?: string;
+  permissions?: string[];
+}): WshMessage;
+
+export function sessionRevoke(opts?: {
+  sessionId?: string;
+  principal?: string;
+  reason?: string;
+}): WshMessage;
+
+// -- Message constructors (file channel / policy / terminal) --
+
+export function fileOp(opts?: {
+  channelId?: number;
+  op?: string;
+  path?: string;
+  offset?: number;
+  length?: number;
+}): WshMessage;
+
+export function fileResult(opts?: {
+  channelId?: number;
+  success?: boolean;
+  metadata?: Record<string, unknown>;
+  errorMessage?: string;
+}): WshMessage;
+
+export function fileChunk(opts?: {
+  channelId?: number;
+  offset?: number;
+  data?: Uint8Array;
+  isFinal?: boolean;
+  totalSize?: number;
+}): WshMessage;
+
+export function policyEval(opts?: {
+  requestId?: string;
+  action?: string;
+  principal?: string;
+  context?: Record<string, unknown>;
+}): WshMessage;
+
+export function policyResult(opts?: {
+  requestId?: string;
+  allowed?: boolean;
+  reason?: string;
+}): WshMessage;
+
+export function policyUpdate(opts?: {
+  policyId?: string;
+  rules?: Record<string, unknown>;
+  version?: number;
+}): WshMessage;
+
+export function terminalConfig(opts?: {
+  channelId?: number;
+  frontend?: string;
+  options?: Record<string, unknown>;
+}): WshMessage;
+
 // -- Utility --
 
 /**
@@ -595,17 +859,30 @@ export function sign(privateKey: CryptoKey, data: Uint8Array): Promise<Uint8Arra
  */
 export function verify(publicKey: CryptoKey, signature: Uint8Array, data: Uint8Array): Promise<boolean>;
 
+/** Options binding extra context into the auth transcript. */
+export interface WshTranscriptOptions {
+  /** Username this transcript is bound to (default ''). */
+  username?: string;
+  /** Reserved for a transport-layer identity binding; no caller populates it yet. */
+  channelBinding?: Uint8Array;
+}
+
 /**
  * Build the authentication transcript hash for challenge-response signing.
  *
- * transcript = SHA-256("wsh-v1\0" || session_id || nonce || channel_binding)
+ * transcript = SHA-256(
+ *   "wsh-v1\0" || lp(username) || lp(session_id) || nonce || channel_binding
+ * )
+ *
+ * where lp() is a 4-byte big-endian length prefix on the variable-length
+ * string fields.
  *
  * @returns 32-byte SHA-256 hash
  */
 export function buildTranscript(
   sessionId: string,
   nonce: Uint8Array,
-  channelBinding?: Uint8Array,
+  opts?: WshTranscriptOptions,
 ): Promise<Uint8Array>;
 
 /**
@@ -619,7 +896,7 @@ export function signChallenge(
   publicKey: CryptoKey,
   sessionId: string,
   nonce: Uint8Array,
-  channelBinding?: Uint8Array,
+  opts?: WshTranscriptOptions,
 ): Promise<{ signature: Uint8Array; publicKeyRaw: Uint8Array }>;
 
 /**
@@ -630,7 +907,7 @@ export function verifyChallenge(
   signature: Uint8Array,
   sessionId: string,
   nonce: Uint8Array,
-  channelBinding?: Uint8Array,
+  opts?: WshTranscriptOptions,
 ): Promise<boolean>;
 
 /** Fields of a signed peer record (reverse-mode registration). See `signPeerRecord`. */
@@ -789,18 +1066,194 @@ export class WshTransport {
  */
 export class WebTransportTransport extends WshTransport {}
 
+/**
+ * Dispatch a fixed, already-available batch of items one at a time,
+ * fully awaiting each handler call before dispatching the next. Use
+ * SerialQueue instead for items arriving incrementally via a push
+ * callback.
+ */
+export function dispatchSerially<T>(
+  items: Iterable<T>,
+  handler: (item: T) => void | Promise<void>,
+): Promise<void>;
+
+/**
+ * A queue drained one item at a time, awaiting each dispatch before
+ * starting the next. Use where items arrive incrementally over time via
+ * a push callback (e.g. a transport's raw `message` event).
+ */
+export class SerialQueue<T = unknown> {
+  constructor(handler: (item: T) => void | Promise<void>);
+  push(item: T): void;
+}
+
 // ============================================================================
 // transport-ws.mjs -- WebSocket transport
 // ============================================================================
 
 /**
- * wsh transport over a single WebSocket with multiplexed virtual streams.
+ * wsh transport over a single WebSocket, multiplexed with QMux
+ * (draft-ietf-quic-qmux-02). The control channel is QMux stream 0.
  *
  * Provides the same interface as WebTransportTransport so that upper
  * layers (session, client) work identically over either transport.
  */
 export class WebSocketTransport extends WshTransport {}
 
+/**
+ * @deprecated The old hand-rolled 5-byte mux's frame-type byte values.
+ * wsh now speaks QMux instead; this export is kept only for source
+ * compatibility and is no longer produced or consumed anywhere.
+ */
+export const WS_FRAME_TYPE: {
+  readonly CONTROL: 0x01;
+  readonly DATA: 0x02;
+  readonly OPEN_STREAM: 0x03;
+  readonly CLOSE_STREAM: 0x04;
+};
+
+// ============================================================================
+// qmux.mjs / qmux-connection.mjs -- QMux multiplexing layer
+// ============================================================================
+
+/** Default QMux flow-control parameters. */
+export const QMUX_DEFAULTS: {
+  /** Connection-wide receive window in bytes (8 MiB). */
+  readonly initialMaxData: number;
+  /** Per-stream receive window in bytes (1 MiB). */
+  readonly initialMaxStreamData: number;
+  /** Initial bidirectional stream credit. */
+  readonly initialMaxStreamsBidi: number;
+};
+
+/** QUIC transport error codes used by wsh (RFC 9000 Section 20.1 subset). */
+export const QMUX_ERROR_CODE: {
+  readonly NO_ERROR: 0x00;
+  readonly INTERNAL_ERROR: 0x01;
+  readonly FLOW_CONTROL_ERROR: 0x03;
+  readonly STREAM_LIMIT_ERROR: 0x04;
+  readonly STREAM_STATE_ERROR: 0x05;
+  readonly FINAL_SIZE_ERROR: 0x06;
+  readonly FRAME_ENCODING_ERROR: 0x07;
+  readonly TRANSPORT_PARAMETER_ERROR: 0x08;
+  readonly PROTOCOL_VIOLATION: 0x0a;
+  readonly APPLICATION_ERROR: 0x0c;
+};
+
+/** Stream-initiator bit values (QUIC stream-id low bit). */
+export const QMUX_STREAM_INITIATOR: {
+  readonly CLIENT: 0;
+  readonly SERVER: 1;
+};
+
+/** First bidirectional stream ID for the given initiator (0 or 1). */
+export function firstBidiStreamId(initiator: 0 | 1): number;
+
+/** Next bidirectional stream ID after `id` for the same initiator (+4). */
+export function nextBidiStreamId(id: number): number;
+
+/** Whether a stream ID was opened by the client side. */
+export function isClientInitiated(streamId: number): boolean;
+
+/** Whether a stream ID is bidirectional (wsh only uses bidi streams). */
+export function isBidirectional(streamId: number): boolean;
+
+/**
+ * One multiplexed QMux stream: a minimal push/pull data API (not DOM
+ * Streams -- WebSocketTransport wraps these in ReadableStream/
+ * WritableStream for the rest of wsh).
+ */
+export interface QMuxStream {
+  /** Stream ID. */
+  id: number;
+
+  /** In-order data delivery. */
+  onData: ((data: Uint8Array) => void) | null;
+
+  /** Clean FIN: all data delivered. */
+  onEnd: (() => void) | null;
+
+  /** Peer aborted (after any reliable prefix was delivered). */
+  onReset: ((errorCode: number) => void) | null;
+
+  /** The whole connection died (transport closed/errored). */
+  onDestroy: ((err: Error) => void) | null;
+
+  /** Send state: 'ready' | 'send' | 'reset_sent' | 'data_sent'. */
+  readonly sendState: string;
+
+  /** Receive state: 'recv' | 'size_known' | 'data_recvd' | 'reset_recvd'. */
+  readonly recvState: string;
+
+  /** Write bytes, awaiting flow-control window as needed. */
+  write(bytes: Uint8Array): Promise<void>;
+
+  /** Half-close the send side (send FIN). */
+  close(): Promise<void>;
+
+  /**
+   * Abort the send side. A non-zero `reliableSize` uses RESET_STREAM_AT
+   * (draft-ietf-quic-reliable-stream-reset) to guarantee that prefix is
+   * still delivered.
+   */
+  reset(errorCode?: number, reliableSize?: number): void;
+
+  /** Tell the peer to stop sending. */
+  stopSending(errorCode?: number): void;
+}
+
+/**
+ * QMux connection: stream state machine + windowed flow control over an
+ * ordered, reliable byte stream. Transport-agnostic -- it takes a
+ * `send(bytes)` callback for outbound record bytes and is fed inbound
+ * bytes via `receiveBytes()`. Exported so alternate server
+ * implementations can speak the same framing as WebSocketTransport.
+ */
+export class QMuxConnection {
+  constructor(opts: {
+    /** Whether this endpoint is the client (determines stream-id parity). */
+    isClient: boolean;
+    /** Callback receiving encoded QMux record bytes to transmit. */
+    send: (bytes: Uint8Array) => void;
+    initialMaxData?: number;
+    initialMaxStreamData?: number;
+    initialMaxStreamsBidi?: number;
+  });
+
+  /** Called for peer-initiated streams. */
+  onStreamOpen: ((stream: QMuxStream) => void) | null;
+
+  /** Called for DATAGRAM frames. */
+  onDatagram: ((data: Uint8Array) => void) | null;
+
+  /** Called on peer CONNECTION_CLOSE. */
+  onClose: ((errorCode: number, reason: string) => void) | null;
+
+  /** Called on protocol errors. */
+  onError: ((err: Error) => void) | null;
+
+  /** Send the QX_TRANSPORT_PARAMETERS handshake frame -- must be the first frame sent. */
+  sendHandshake(): void;
+
+  /** Open a new locally-initiated bidirectional stream. */
+  openStream(): Promise<QMuxStream>;
+
+  /** Look up an existing stream by ID. */
+  getStream(id: number): QMuxStream | undefined;
+
+  /** Send a DATAGRAM frame. */
+  sendDatagram(bytes: Uint8Array): void;
+
+  /** Feed inbound bytes from the underlying transport. */
+  receiveBytes(chunk: Uint8Array): void;
+
+  /** Send CONNECTION_CLOSE and shut down. */
+  close(errorCode?: number, reason?: string): void;
+
+  /** Forcibly tear down every stream (transport died; nothing is sent). */
+  destroy(err: Error): void;
+}
+
 // ============================================================================
 // session.mjs -- WshSession
 // ============================================================================
@@ -881,6 +1334,9 @@ export class WshSession {
   /** Last terminal diff received for the session. */
   readonly lastTermDiff: Record<string, unknown> | null;
 
+  /** Whether `enableE2E()` has been called and E2E sealing is active for this session. */
+  readonly e2eEnabled: boolean;
+
   constructor(
     transport: WshTransport,
     channelId: number,
@@ -897,9 +1353,21 @@ export class WshSession {
   /**
    * Write data to the session's stdin stream.
    * Accepts a Uint8Array for raw bytes or a string (UTF-8 encoded).
+   * Sealed into an EncryptedFrame instead of plaintext SessionData when
+   * `enableE2E()` has been called (virtual-mode sessions only).
    */
   write(data: Uint8Array | string): Promise<void>;
 
+  /**
+   * Opt in to end-to-end encryption for this session's data plane
+   * (virtual-mode sessions only). `sharedSecret` must come from a fresh
+   * `WshClient.initiateE2E()` call on the *current* connection --
+   * E2E state is connection-scoped, not session-scoped, so a session
+   * Resumed/Attached on a new connection must run `initiateE2E()` and
+   * `enableE2E()` again rather than reusing a prior key.
+   */
+  enableE2E(sharedSecret: CryptoKey, opts: { role: 'initiator' | 'responder' }): void;
+
   /**
    * Request the remote PTY to resize.
    */
@@ -1257,7 +1725,13 @@ export class WshClient {
   /**
    * Download a file from a remote path.
    */
-  download(remotePath: string): Promise<Uint8Array>;
+  download(
+    remotePath: string,
+    opts?: {
+      onProgress?: (progress: { received: number; total: number }) => void;
+      timeout?: number;
+    },
+  ): Promise<Uint8Array>;
 
   /**
    * Discover MCP tools available on the remote server.

package/src/messages.gen.mjs

@@ -777,9 +777,10 @@ export function keyExchange({ algorithm, publicKey, sessionId, kemPublicKey, kem
   return msg;
 }
 
-export function encryptedFrame({ nonce, ciphertext, sessionId } = {}) {
+export function encryptedFrame({ channelId, nonce, ciphertext, sessionId } = {}) {
   return {
     type: MSG.ENCRYPTED_FRAME,
+    channel_id: channelId,
     nonce,
     ciphertext,
     session_id: sessionId,

package/src/session.mjs

@@ -9,6 +9,7 @@ import {
   MSG, resize as resizeMsg, signal as signalMsg, close as closeMsg,
 } from './messages.mjs';
 import { WshVirtualSessionBackend } from './virtual-session.mjs';
+import { sealFrame, openFrame, ROLE_TAGS } from './e2e-frame.mjs';
 
 // ── Session states ────────────────────────────────────────────────────
 
@@ -77,6 +78,27 @@ export class WshSession {
   /** @type {WshVirtualSessionBackend|null} */
   #virtualBackend = null;
 
+  /**
+   * Non-extractable AES-256-GCM CryptoKey set by `enableE2E()`, or `null`
+   * if E2E is not enabled for this session. Connection-scoped -- see
+   * `enableE2E`'s doc comment for why this must never be reused across a
+   * Resume/Attach.
+   * @type {CryptoKey|null}
+   */
+  #e2eKey = null;
+
+  /** @type {Uint8Array|null} This side's 4-byte nonce role tag, set by `enableE2E()`. */
+  #e2eSendRoleTag = null;
+
+  /** @type {Uint8Array|null} The peer's 4-byte nonce role tag, set by `enableE2E()`. */
+  #e2eRecvRoleTag = null;
+
+  /** @type {number} Next outgoing frame counter for this side. */
+  #e2eSendCounter = 0;
+
+  /** @type {number} Next expected incoming frame counter from the peer. */
+  #e2eRecvCounter = 0;
+
   /**
    * The readable side of the stdout data stream.
    * @type {ReadableStream<Uint8Array>|null}
@@ -292,6 +314,60 @@ export class WshSession {
     this.#state = STATE_ACTIVE;
   }
 
+  /** Whether `enableE2E()` has been called and E2E sealing is active for this session. */
+  get e2eEnabled() {
+    return this.#e2eKey !== null;
+  }
+
+  /**
+   * Opt in to end-to-end encryption for this session's data plane
+   * (virtual-mode sessions only in this PR; stream-mode is out of
+   * scope -- see `e2e-frame.mjs`'s doc comment). After this call,
+   * `write()` seals outgoing data into `EncryptedFrame` messages instead
+   * of plaintext `SessionData`, and incoming `EncryptedFrame` messages
+   * are opened and delivered via `onData` exactly like `SessionData` is
+   * today; plaintext `SessionData` from a peer is no longer expected
+   * once this side has opted in (it's simply passed through unchanged,
+   * as before -- this method doesn't add any negotiation-failure
+   * handling; that's a later PR).
+   *
+   * IMPORTANT -- key lifetime: `sharedSecret` must come from a *fresh*
+   * `WshClient.initiateE2E()` call on the *current* connection. E2E
+   * state here is connection-scoped, not session-scoped: if this
+   * session is later detached and Resumed/Attached on a new connection,
+   * callers MUST run `initiateE2E()` again and call `enableE2E()` again
+   * with the new key -- never persist or reuse a `sharedSecret` (or its
+   * counters) across a resume. Calling `enableE2E()` again on an
+   * already-enabled session is fine and resets counters cleanly (a
+   * fresh key naturally means fresh counters), but the caller is
+   * responsible for actually supplying a fresh key when doing so.
+   *
+   * @param {CryptoKey} sharedSecret - AES-256-GCM CryptoKey from `WshClient.initiateE2E()`
+   * @param {object} opts
+   * @param {'initiator'|'responder'} opts.role - which side of the KeyExchange this session was;
+   *   determines this side's nonce role tag (see `e2e-frame.mjs`'s `ROLE_TAGS`). The two peers of
+   *   one session MUST pick opposite roles, or their nonces can collide.
+   */
+  enableE2E(sharedSecret, { role } = {}) {
+    if (!sharedSecret || typeof sharedSecret !== 'object') {
+      throw new Error('enableE2E: sharedSecret must be a CryptoKey (see WshClient.initiateE2E)');
+    }
+    if (role !== 'initiator' && role !== 'responder') {
+      throw new Error("enableE2E: opts.role must be 'initiator' or 'responder'");
+    }
+    if (this.#dataMode !== 'virtual') {
+      throw new Error('enableE2E: only virtual-mode sessions are supported in this version (stream-mode is out of scope)');
+    }
+    if (!this.#sessionId) {
+      throw new Error('enableE2E: session has no server-assigned session_id to bind as AAD -- was OPEN_OK missing session_id?');
+    }
+    this.#e2eKey = sharedSecret;
+    this.#e2eSendRoleTag = ROLE_TAGS[role];
+    this.#e2eRecvRoleTag = role === 'initiator' ? ROLE_TAGS.responder : ROLE_TAGS.initiator;
+    this.#e2eSendCounter = 0;
+    this.#e2eRecvCounter = 0;
+  }
+
   // ── Public API ──────────────────────────────────────────────────────
 
   /**
@@ -308,6 +384,15 @@ export class WshSession {
       if (this.#virtualBackend === null) {
         throw new Error('Session not yet activated — virtual backend unavailable');
       }
+      if (this.#e2eKey !== null) {
+        const bytes = typeof data === 'string' ? textEncoder.encode(data) : data;
+        const counter = this.#e2eSendCounter++;
+        const { nonce, ciphertext } = await sealFrame(
+          this.#e2eKey, this.#sessionId, this.#e2eSendRoleTag, counter, bytes
+        );
+        await this.#virtualBackend.writeEncrypted({ nonce, ciphertext, sessionId: this.#sessionId });
+        return;
+      }
       await this.#virtualBackend.write(data);
       return;
     }
@@ -437,6 +522,40 @@ export class WshSession {
         break;
       }
 
+      case MSG.ENCRYPTED_FRAME: {
+        if (this.#e2eKey === null) {
+          console.error('[wsh:session] received EncryptedFrame but E2E is not enabled on this session — dropping');
+          break;
+        }
+        if (msg.session_id !== this.#sessionId) {
+          console.error('[wsh:session] EncryptedFrame session_id mismatch — dropping (possible splice attempt)');
+          break;
+        }
+        // openFrame is async; _handleControlMessage is a synchronous
+        // dispatch entry point (see the SESSION_DATA case above and its
+        // callers), so this fires the decrypt-and-deliver as a
+        // background task rather than awaiting it here. Per-channel
+        // control messages are already dispatched serially by the
+        // caller (see transport.mjs's dispatchSerially/SerialQueue), so
+        // frames still arrive at openFrame() in wire order; only the
+        // delivery of *this* frame's plaintext to onData is deferred by
+        // one microtask/macrotask relative to synchronous cases.
+        const counter = this.#e2eRecvCounter++;
+        openFrame(this.#e2eKey, this.#sessionId, counter, { nonce: msg.nonce, ciphertext: msg.ciphertext })
+          .then((plaintext) => {
+            this.#virtualBackend?.pushData(plaintext);
+            try {
+              this.onData?.(plaintext);
+            } catch (err) {
+              console.error('[wsh:session] onData handler error:', err);
+            }
+          })
+          .catch((err) => {
+            console.error('[wsh:session] failed to open EncryptedFrame:', err);
+          });
+        break;
+      }
+
       case MSG.FILE_CHUNK: {
         if (this.#fileChunkWaiter) {
           const { resolve } = this.#fileChunkWaiter;

package/src/virtual-session.mjs

@@ -1,4 +1,4 @@
-import { sessionData as sessionDataMsg } from './messages.mjs';
+import { sessionData as sessionDataMsg, encryptedFrame as encryptedFrameMsg } from './messages.mjs';
 
 const textEncoder = new TextEncoder();
 
@@ -65,6 +65,25 @@ export class WshVirtualSessionBackend {
     );
   }
 
+  /**
+   * Send a pre-sealed EncryptedFrame instead of plaintext SessionData.
+   * Used by `WshSession.write()` when E2E is enabled for this session
+   * (see `session.mjs`'s `enableE2E`).
+   *
+   * @param {{nonce: Uint8Array, ciphertext: Uint8Array, sessionId: string}} frame
+   * @returns {Promise<void>}
+   */
+  async writeEncrypted({ nonce, ciphertext, sessionId }) {
+    await this.#sendControl(
+      encryptedFrameMsg({
+        channelId: this.#channelId,
+        nonce,
+        ciphertext,
+        sessionId,
+      })
+    );
+  }
+
   async read() {
     if (this.#readQueue.length > 0) {
       return { done: false, value: this.#readQueue.shift() };