@johnhenry/wsh 0.14.0 → 0.16.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.16.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,181 @@
+/**
+ * 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 module's AEAD primitives were introduced in wsh #19 (virtual-mode
+ * only) and, as of wsh #22 (PR 1 of 3), are reused unchanged by
+ * stream-mode sessions too: `stream-frame.mjs` wraps `sealFrame`/
+ * `openFrame` in inline length-prefixed chunk framing for raw
+ * WebTransport byte streams (no message boundaries), while
+ * `session.mjs`'s `enableE2E` now dispatches to either transport based
+ * on the session's `dataMode`. This module itself needed no changes for
+ * that -- see `stream-frame.mjs`'s doc comment for the 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"
+});