@johnhenry/wsh 0.27.1 → 0.29.0

package/README.md

@@ -63,7 +63,7 @@ Or via CDN:
 - **MCP bridge** -- discover and invoke remote MCP tools through the control channel
 - **Session recording** -- own JSON schema (not asciicast v2 -- see note below) recording and playback with seek/pause/resume
 - **Key management** -- IndexedDB storage with OPFS encrypted backup (PBKDF2 + AES-256-GCM)
-- **97 message types** -- handshake, channel, gateway, guest sharing, compression negotiation, copilot, policy, authorized-key management, and more
+- **98 message types** -- handshake, channel, gateway, guest sharing, compression negotiation, copilot, policy, authorized-key management, and more
 
 > **Session recording is not asciicast v2.** Both `SessionRecorder`
 > implementations capture more than asciicast v2's three event codes
@@ -186,6 +186,14 @@ restricted host with no shell. `fs.root` confines every path: `..`, absolute
 paths and symlinks pointing out of it are refused -- for `write` and `rename`
 (both paths) exactly as for `read`.
 
+### TLS (`wss://`) and host extensions
+
+`tls: { cert, key }` (PEM, the options of `https.createServer`) serves the WebSocket listener over TLS on the same
+port. `extensions: { [type]: (msg, { username, fingerprint, send }) => void }` handles application-defined control
+messages whose `type` is a string, from authenticated connections only. On a relay,
+`relay: { onUnreachable(from, targetFingerprint, request) }` is told when an operator asked for a peer that is not
+registered (the operator still gets `no such peer`), so the host can reach that peer another way, such as a Web Push.
+
 ### WebTransport listener
 
 The client's ladder prefers WebTransport (`https://`) and falls back to `wss://`;
@@ -342,23 +350,45 @@ const s = await client.openSession({ type: 'exec', command: 'echo hello' });
   checked against the allowlist (a non-forwardable or undecodable inner is
   dropped, logged), and re-wrapped with the real sender; traffic from a connection
   that is not bridged is never forwarded.
-- **One operator per peer at a time**, by design: a `RelayForward` names its
-  sender but not its recipient, and nothing on the wire tells a peer that one
-  of several operators left, so replies could not be addressed and a departed
-  operator's work could not be cleaned up. A second `ReverseConnect` to a peer
-  that already has an operator (or a request awaiting its answer) is rejected
-  with `ReverseReject.reason` `busy: this peer already has an operator ...`
-  (exported as `BUSY_PEER` from `src/server/relay.mjs`), and an operator that
-  already has a bridge or a request in flight is rejected with `busy: you
-  already have a bridge ...` (`BUSY_OPERATOR`); a request the peer does not
-  answer within `connectTimeoutMs` (default 8 s) is `peer did not respond`.
-  A bridge lasts as long as both connections: when either ends, the relay
-  closes the other, so nothing an operator started outlives it (the reverse
-  host kills its processes). `createReverseHost` redials with backoff by
-  default (`reconnect: false` to turn it off), so it is registered again for
-  the next operator. Lifting the limit needs a spec addition (a recipient on
-  `RelayForward`, a bridge-ended notice) shared with the Rust side; it is
-  tracked rather than built.
+- **One operator per peer at a time, unless you raise it.** The default: a
+  second `ReverseConnect` to a peer that already has an operator (or a request
+  awaiting its answer) is rejected with `ReverseReject.reason` `busy: this peer
+  already has an operator ...` (exported as `BUSY_PEER` from
+  `src/server/relay.mjs`), and an operator that already has a bridge or a
+  request in flight is rejected with `busy: you already have a bridge ...`
+  (`BUSY_OPERATOR`); a request the peer does not answer within
+  `connectTimeoutMs` (default 8 s) is `peer did not respond`. A bridge lasts as
+  long as both connections: when either ends, the relay closes the other, so
+  nothing an operator started outlives it (the reverse host kills its
+  processes). `createReverseHost` redials with backoff by default
+  (`reconnect: false` to turn it off), so it is registered again for the next
+  operator.
+- **Several operators per peer (opt-in on both ends).** Set
+  `relay: { maxOperatorsPerPeer: n }` on the relay and
+  `createReverseHost({ maxOperators: n })` on the peer. Three things make it
+  work, all optional on the wire so nothing older breaks: a peer states
+  `relay-multi-operator` in `ReverseAccept.features`; it addresses each message
+  to one operator with `RelayForward.to_fingerprint` (the relay routes it there
+  and re-wraps it with the peer as sender -- the field is never delivered, and
+  a forward addressed to nobody it serves is dropped, as is an unaddressed one
+  while two or more are bridged; with exactly one operator an unaddressed reply
+  still goes to it); and when one operator leaves the relay sends the peer a
+  `ReverseClose { target_fingerprint }` and keeps the peer registered, instead
+  of closing it. Each operator is accepted on its own identity (`accept` runs
+  per operator) and gets its own connection state on the host -- channels,
+  processes, files -- so when one leaves only its work is cleaned up. The relay
+  advertises `relay-multi-operator` in its `ServerHello` when it is configured
+  for several, and a host only claims it then, so a host with `maxOperators` on
+  an older or default relay serves one operator exactly as before. A peer that
+  never stated the feature stays held to one operator (and is closed when its
+  operator leaves) even on a multi-operator relay; a peer answers one
+  `ReverseConnect` at a time (a concurrent one is told `busy: ... retry in a
+  moment`), since a `ReverseAccept` does not name its operator; and at the cap
+  the reason is `busy: this peer already has its maximum of n operators`
+  (`busyPeerFull(n)`). The **Rust relay is still one operator per peer**: it
+  never sends `ReverseClose` and rejects the second operator; the new spec
+  fields are regenerated into the Rust types and ignored there. Tracked for the
+  Rust relay in #93.
 - **On the peer**, the bridged operator is served by the same connection code as
   a direct client, over an in-memory message pipe instead of a socket. Nothing a
   client opens can cross the relay but control messages, so exec sessions are
@@ -368,17 +398,39 @@ const s = await client.openSession({ type: 'exec', command: 'echo hello' });
   are on the spec's `forwardable` list, so an operator and a peer can run
   `initiateE2E()` / `enableE2E()` with each other through the relay: it carries
   the CBOR of each as opaque bytes and holds no key, so it sees only public
-  values and ciphertext (`test/server-relay-bridge.test.mjs` checks the relay
-  never holds the plaintext). **`KeyExchange` is unauthenticated**: this
-  protects against a relay that only observes, not against one that substitutes
-  the exchanged keys, so if the relay operator is not trusted, authenticate the
-  derived key yourself (compare it out of band, or sign it with the keys the
-  bridge already names). Only a stock-client peer (a browser tab, `connectReverse`)
-  speaks E2E: **`createReverseHost` does not answer `KeyExchange` or open
-  `EncryptedFrame`s** (the Node host has no E2E layer at all), so against it traffic
-  is in the clear to the relay -- serve the relay over `wss://` and treat its
-  operator as trusted. Key exchange from a connection that is not bridged is
-  never carried.
+  values and ciphertext (`test/server-relay-bridge.test.mjs` and
+  `test/reverse-host-e2e.test.mjs` check the relay never holds the plaintext).
+  **`createReverseHost` answers it too** (`e2e` option, on by default; `false`
+  turns it off): for a session the host has opened (the id is the one in
+  `OpenOk`), an operator's `KeyExchange` is answered -- X25519, or hybrid
+  X25519+ML-KEM-768 when asked and available -- and from then on that session's
+  output is sealed into `EncryptedFrame`s (AAD = the session id, strict
+  counters, the `responder` role tag) and its input is opened from them.
+  Plaintext `SessionData` input for an encrypted session is ignored, so a relay
+  cannot inject stdin around the encryption, and a replayed, tampered or
+  spliced frame is dropped without consuming a counter. The host advertises
+  `e2e` (and `e2e-sign`) in `ReverseAccept.features`. Start E2E before the
+  session produces output you need confidential: output sent before the key
+  exists is plaintext, and a frame that reaches the operator before it has
+  called `enableE2E()` is dropped (open the session with a command that waits
+  for input, or use a shell and let the first prompt precede the exchange).
+  This is virtual-mode E2E (`EncryptedFrame`), so it is offered over a relay
+  bridge, not on direct connections (`createWshServer`).
+  **`KeyExchange` is unauthenticated by itself**, which protects against a
+  relay that only observes; to defeat one that substitutes keys the host
+  **signs its reply** with its identity key (Ed25519 over the label, session
+  id, algorithm and both ephemeral keys; the optional `KeyExchange.signature`),
+  and the operator checks it: `client.initiateE2E(sessionId, algorithm,
+  timeout, { verifyPeer: hostPublicKey })` -- the host's raw key, e.g. the
+  `public_key` of the record `listPeers()` verified -- rejects with
+  `code: 'E2E_PEER_UNAUTHENTICATED'` on a missing or wrong signature, and
+  resolves `peerAuthenticated: true` otherwise. Without `verifyPeer` nothing is
+  checked, as before. Signing is `e2e: { sign: 'auto' }` by default: the host
+  signs when the relay's `ServerHello` carries `e2e-sign` (this package's relay
+  does) because a relay built before the field existed -- notably Rust before
+  the release that regenerates it -- drops a connection that sends one;
+  `sign: true` forces it, `false` never. Key exchange from a connection that
+  is not bridged is never carried.
 - **Feature gates follow the host behind the bridge.** The host's own features
   (`file-write`, `file-rename`, `mcp-call-id`) are stated in the optional
   `ReverseAccept.features`; the relay forwards the list (bounded: at most 64
@@ -892,7 +944,7 @@ so options the platform gains later need no change here.
 
 | Export | Description |
 |--------|-------------|
-| `MSG` | 97 message type constants (hex opcodes) |
+| `MSG` | 98 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) |
@@ -942,7 +994,7 @@ than left to be found.
 | Typed RPC channels (`openRpc`, `rpc` sessions; `wsh-host`, `wsh-fs`, `mcp`) | `WshClient.openRpc()`, `RpcChannel` | Rust `wsh-server` (`rust-v0.4.0`+): `wsh-host`, and `wsh-fs` when `[rpc] fs_root` is set; no client yet in `wsh-client` | **No wire change**: `Open { kind: 'rpc', command: <protocol> }` plus `rpc*` `ServerHello` features, negotiated so it fails fast elsewhere; the Rust server serves it on WebSocket/QMux only |
 | Interactive shell UI | none -- this SDK is a protocol client, not a terminal emulator; pair with xterm.js/ghostty-web | `wsh connect`, `wsh sftp` (line-oriented REPL) | **Deliberately not unified** -- a browser embeds a terminal widget the host page owns; a CLI process owns its own TTY |
 | Attach / resume | `attachSession()`, `resumeSession()`, `WshSession.seq` | `attach_session()`, `resume_session()` | **Wire-unified** (`Attach`/`Resume`/`Presence`); `seq` = cumulative output bytes. `@johnhenry/wsh/server` honours `last_seq` (bounded ring, gap errors) and answers Presence with `channel_id`/`seq`; the Rust `wsh-server` does the same (`rust-v0.2.0`+; fixed 256 KiB ring) |
-| Reverse-connect / relay peer | `connectReverse()`, `trustRelayPeer()`; `@johnhenry/wsh/server`: `relay` option and `createReverseHost()` | `wsh reverse`, `wsh agent` (persistent, with startup-unit install) | **Wire-unified** (registration, discovery, signed peer records); **daemonization is CLI-only** -- a browser tab cannot be a background OS service. The Node relay is default-deny and bridges one operator per peer (`busy:` reasons say so); E2E and bridged feature gates need `rust-v0.3.0`+ on the Rust side |
+| Reverse-connect / relay peer | `connectReverse()`, `trustRelayPeer()`; `@johnhenry/wsh/server`: `relay` option and `createReverseHost()` | `wsh reverse`, `wsh agent` (persistent, with startup-unit install) | **Wire-unified** (registration, discovery, signed peer records); **daemonization is CLI-only** -- a browser tab cannot be a background OS service. The Node relay is default-deny and bridges one operator per peer unless `maxOperatorsPerPeer` is raised (`busy:` reasons say so); E2E and bridged feature gates need `rust-v0.3.0`+ on the Rust side; several operators per peer and the signed `KeyExchange` are JS-relay only for now |
 | Post-quantum E2E (experimental) | `initiateE2E()` (WebCrypto ML-KEM-768 or `@noble/post-quantum` fallback) | `E2eKeyExchange` (`ml-kem` crate) | **Wire-unified** algorithm and transcript; key material backends differ by platform necessity |
 | Session recording/replay | `SessionRecorder`/`SessionPlayer` (asciicast v2) | none | **JS-only** -- no current Rust consumer needs playback; the format itself (asciicast v2) is not proprietary if one is added later |
 | Self-signed cert pinning | `serverCertificateHashes` (WebTransport option) | N/A -- Rust dials a cert its own TLS stack already trusts, or `--generate-cert`'s self-signed cert out of band | **Deliberately not unified** -- this is a browser-specific WebTransport API shape, not a wire-protocol concept |
@@ -1014,11 +1066,12 @@ out explicitly below rather than left to be discovered.
   `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.
-- **E2E through a relay is opt-in and unauthenticated key agreement.** The relay
-  carries `KeyExchange` / `EncryptedFrame` between a bridged operator and peer
-  without being able to read the sealed frames, but `KeyExchange` carries no
-  signature: a relay that substitutes keys is not detected (see the [relay
-  section](#relay--reverse-mode)).
+- **E2E through a relay is opt-in.** The relay carries `KeyExchange` /
+  `EncryptedFrame` between a bridged operator and peer without being able to
+  read the sealed frames. `KeyExchange` is unauthenticated unless the peer signs
+  it and the operator asks for that (`initiateE2E(..., { verifyPeer })`; a
+  `createReverseHost` signs by default): without `verifyPeer` a relay that
+  substitutes keys is not detected (see the [relay section](#relay--reverse-mode)).
 - **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

package/package.json

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

package/src/client.mjs

@@ -15,7 +15,7 @@ import {
   hello, auth as authMsg, open as openMsg, close as closeMsg,
   attach as attachMsg, resume as resumeMsg, ping as pingMsg, pong as pongMsg,
   reverseRegister as reverseRegisterMsg, reverseList as reverseListMsg,
-  reverseConnect as reverseConnectMsg,
+  reverseConnect as reverseConnectMsg, relayForward as relayForwardMsg,
   mcpDiscover as mcpDiscoverMsg, mcpCall as mcpCallMsg,
   suspendSession as suspendSessionMsg, restartPty as restartPtyMsg,
   metricsRequest as metricsRequestMsg,
@@ -39,8 +39,9 @@ import {
 } from './messages.mjs';
 import { signChallenge, exportPublicKeyRaw, signPeerRecord, verifyPeerRecord, importPublicKeyRaw, fingerprint as computeFingerprint } from './auth.mjs';
 import { generateMlKemKeyPair, mlKemEncapsulate, mlKemDecapsulate } from './mlkem.mjs';
+import { compareBytes, combineHybridSecret, verifyKeyExchangeSignature } from './e2e-exchange.mjs';
 import { WshSession } from './session.mjs';
-import { cborDecode } from './cbor.mjs';
+import { cborDecode, cborEncode } from './cbor.mjs';
 import {
   RpcChannel, RpcError, RPC_ERROR, RPC_FEATURE, RPC_PROTOCOL_NAME_RE, RPC_DEFAULT_MAX_MESSAGE,
   rpcProtocolFeature, parseRpcFeatures,
@@ -148,44 +149,6 @@ async function verifyPeerInfoRecord(peer) {
   }
 }
 
-/**
- * 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;
-}
-
-/**
- * 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);
-}
-
 /**
  * `expectHostKey` accepts a hex fingerprint, a raw 32-byte key, or an
  * `ssh-ed25519 AAAA...` line; all normalize to the hex fingerprint.
@@ -1259,10 +1222,19 @@ export class WshClient {
    * the transport internals directly.
    *
    * @param {object} msg
+   * @param {{ to?: string }} [opts] - `to`: the operator this is for, when this peer serves several
+   *   (`relay-multi-operator`, wsh #89): the message is sent as a `RelayForward` addressed to that
+   *   fingerprint. Leave it out for a peer's only operator.
    * @returns {Promise<void>}
    */
-  async sendRelayControl(msg) {
+  async sendRelayControl(msg, { to } = {}) {
     this.#assertAuthenticated('sendRelayControl');
+    if (to !== undefined) {
+      // A peer serving several operators addresses each message: the relay routes the wrapper to `to`
+      // and re-wraps it with this peer's fingerprint (from_fingerprint here is overwritten, not trusted).
+      if (typeof to !== 'string' || !to) throw new TypeError('sendRelayControl: to must be an operator fingerprint');
+      msg = relayForwardMsg({ fromFingerprint: '', toFingerprint: to, inner: cborEncode(msg) });
+    }
     await this.#transport.sendControl(msg);
   }
 
@@ -1784,12 +1756,19 @@ export class WshClient {
    * agility, not a hard cutover; check the returned `hybrid` flag to see
    * which actually happened.
    *
+   * `KeyExchange` carries only ephemeral keys, so on its own it does not stop a relay that substitutes them.
+   * Pass `verifyPeer` -- the peer's long-term Ed25519 public key, e.g. the `public_key` of the peer record you
+   * listed -- to require that the peer signed its half (a reverse host does: `e2e-sign` in its features); the
+   * exchange is refused with `code: 'E2E_PEER_UNAUTHENTICATED'` if the signature is missing or does not verify.
+   *
    * @param {string} sessionId - Session ID
    * @param {string} [algorithm='X25519'] - 'X25519' or 'X25519+ML-KEM-768'
    * @param {number} [timeout=10000]
-   * @returns {Promise<{sharedSecret: CryptoKey, peerPublicKey: Uint8Array, hybrid: boolean}>}
+   * @param {object} [opts]
+   * @param {Uint8Array | CryptoKey} [opts.verifyPeer] - the peer's Ed25519 public key (raw 32 bytes or imported)
+   * @returns {Promise<{sharedSecret: CryptoKey, peerPublicKey: Uint8Array, hybrid: boolean, peerAuthenticated: boolean}>}
    */
-  async initiateE2E(sessionId, algorithm = 'X25519', timeout = DEFAULT_OPEN_TIMEOUT) {
+  async initiateE2E(sessionId, algorithm = 'X25519', timeout = DEFAULT_OPEN_TIMEOUT, { verifyPeer } = {}) {
     this.#assertAuthenticated('initiateE2E');
     const wantHybrid = algorithm === 'X25519+ML-KEM-768';
 
@@ -1835,6 +1814,22 @@ export class WshClient {
 
     const peerMsg = await peerMsgPromise;
 
+    let peerAuthenticated = false;
+    if (verifyPeer !== undefined) {
+      const ok = await verifyKeyExchangeSignature(verifyPeer, peerMsg.signature, {
+        sessionId, algorithm, initiatorKey: localPub, responderKey: new Uint8Array(peerMsg.public_key ?? []),
+      });
+      if (!ok) {
+        throw Object.assign(
+          new Error(peerMsg.signature === undefined
+            ? 'initiateE2E: the peer did not sign its key exchange (verifyPeer was given)'
+            : 'initiateE2E: the peer\'s key exchange signature does not verify against verifyPeer'),
+          { code: 'E2E_PEER_UNAUTHENTICATED' },
+        );
+      }
+      peerAuthenticated = true;
+    }
+
     // Round 2 has the same shape as round 1, so it needs the same treatment.
     // Whether we encapsulate or decapsulate is decided entirely by data
     // already in hand, so decide it now and register the ciphertext waiter
@@ -1899,7 +1894,7 @@ export class WshClient {
       ['encrypt', 'decrypt']
     );
 
-    return { sharedSecret, peerPublicKey: new Uint8Array(peerMsg.public_key), hybrid: hybridActive };
+    return { sharedSecret, peerPublicKey: new Uint8Array(peerMsg.public_key), hybrid: hybridActive, peerAuthenticated };
   }
 
   // ── Structured File Channel ───────────────────────────────────────
@@ -2476,7 +2471,7 @@ export class WshClient {
    * @param {object} msg
    * @private
    */
-  #handleControl(msg) {
+  #handleControl(msg, from) {
     const type = msg.type;
 
     // Unwrap RelayForward: only deliver the inner message if it came from a
@@ -2502,7 +2497,7 @@ export class WshClient {
         console.warn('[wsh:client] dropping RelayForward wrapping a non-forwardable type:', inner.type);
         return;
       }
-      this.#handleControl(inner);
+      this.#handleControl(inner, msg.from_fingerprint);
       return;
     }
 
@@ -2668,7 +2663,7 @@ export class WshClient {
     // sessions share the same top-level API.
     if (this.onRelayMessage && this._isRelayForwardable(type)) {
       try {
-        this.onRelayMessage(msg);
+        this.onRelayMessage(msg, from);
       } catch (err) {
         console.error('[wsh:client] onRelayMessage handler error:', err);
       }
@@ -2701,6 +2696,15 @@ export class WshClient {
         this.#transport?.sendControl(pingMsg({ id: ++this.#pingId })).catch(() => {});
         break;
 
+      case MSG.REVERSE_CLOSE:
+        // The relay telling a peer that serves several operators that one of them left (wsh #89).
+        try {
+          this.onReverseClose?.(msg);
+        } catch (err) {
+          console.error('[wsh:client] onReverseClose handler error:', err);
+        }
+        break;
+
       case MSG.REVERSE_CONNECT:
         try {
           this.onReverseConnect?.(msg);

package/src/e2e-exchange.mjs

@@ -0,0 +1,227 @@
+/**
+ * The key-exchange half of wsh's opt-in end-to-end encryption that is not the
+ * initiating client: the RESPONDER a host runs when an operator sends it a
+ * `KeyExchange` (wsh #90), plus the pieces both sides share -- the hybrid
+ * secret combiner, the byte comparison that picks the ML-KEM encapsulator, and
+ * the signed transcript that lets a host authenticate its half.
+ *
+ * `WshClient.initiateE2E()` is the initiator. The two sides derive the same
+ * AES-256-GCM key (see `e2e-frame.mjs` for how it is used to seal frames).
+ *
+ * ── Authenticating the responder ────────────────────────────────────
+ * `KeyExchange` carries only ephemeral public keys, so by itself it protects
+ * against a relay that observes, not one that substitutes keys. A responder
+ * given a signing key therefore signs, with its long-term Ed25519 identity, a
+ * transcript binding the label, the session id, the algorithm, and BOTH
+ * ephemeral X25519 keys (initiator's first). The initiator verifies it against
+ * the host key it meant to reach (`initiateE2E(..., { verifyPeer })`): a relay
+ * that swaps either ephemeral key cannot produce a matching signature.
+ */
+
+import { sign as signBytes, verify as verifyBytes, importPublicKeyRaw } from './auth.mjs';
+import { keyExchange } from './messages.gen.mjs';
+import { generateMlKemKeyPair, mlKemEncapsulate, mlKemDecapsulate, MLKEM768_PUBLIC_KEY_LENGTH } from './mlkem.mjs';
+
+export const E2E_ALGORITHM_CLASSICAL = 'X25519';
+export const E2E_ALGORITHM_HYBRID = 'X25519+ML-KEM-768';
+/** Host feature (in `ReverseAccept.features`): this host answers `KeyExchange` and seals/opens `EncryptedFrame`s. */
+export const E2E_FEATURE = 'e2e';
+/** Host feature: the host signs its `KeyExchange` reply, so the operator can authenticate it. */
+export const E2E_SIGN_FEATURE = 'e2e-sign';
+
+const LABEL = new TextEncoder().encode('wsh-e2e-keyexchange-v1\0');
+const enc = new TextEncoder();
+const MAX_PENDING = 8;
+const PENDING_TTL_MS = 15_000;
+
+/**
+ * Lexicographic byte comparison, used by hybrid mode to assign the ML-KEM
+ * "encapsulator" role without an extra round trip.
+ * @returns {number} <0 if a<b, >0 if a>b, 0 if equal
+ */
+export 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;
+}
+
+/**
+ * Combine the classical (X25519 ECDH) and post-quantum (ML-KEM-768) outputs
+ * into one AES-256-GCM key via HKDF-SHA256, so the final key is only as weak
+ * as the *stronger* of the two.
+ * @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
+ */
+export 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: enc.encode('wsh-hybrid-e2e-v1') },
+    hkdfKey,
+    256
+  );
+  return new Uint8Array(bits);
+}
+
+const lp = (bytes) => {
+  const out = new Uint8Array(4 + bytes.length);
+  new DataView(out.buffer).setUint32(0, bytes.length);
+  out.set(bytes, 4);
+  return out;
+};
+
+/**
+ * The bytes a responder signs: label, session id, the INITIATOR's algorithm string, then the initiator's and
+ * responder's ephemeral X25519 public keys, each length-prefixed.
+ * @param {{ sessionId: string, algorithm: string, initiatorKey: Uint8Array, responderKey: Uint8Array }} t
+ * @returns {Uint8Array}
+ */
+export function keyExchangeTranscript({ sessionId, algorithm, initiatorKey, responderKey }) {
+  const parts = [LABEL, lp(enc.encode(sessionId)), lp(enc.encode(algorithm)), lp(initiatorKey), lp(responderKey)];
+  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+  let off = 0;
+  for (const p of parts) { out.set(p, off); off += p.length; }
+  return out;
+}
+
+/**
+ * Verify a responder's `KeyExchange.signature`.
+ * @param {Uint8Array | CryptoKey} peerIdentity - the host's raw 32-byte Ed25519 public key (or an imported one)
+ * @param {Uint8Array | undefined} signature
+ * @param {Parameters<typeof keyExchangeTranscript>[0]} transcript
+ * @returns {Promise<boolean>}
+ */
+export async function verifyKeyExchangeSignature(peerIdentity, signature, transcript) {
+  if (!(signature instanceof Uint8Array) || signature.length !== 64) return false;
+  try {
+    const key = peerIdentity instanceof Uint8Array ? await importPublicKeyRaw(peerIdentity) : peerIdentity;
+    return await verifyBytes(key, signature, keyExchangeTranscript(transcript));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The responder side of `KeyExchange`, for a host. One instance per connection.
+ *
+ * `respond(msg)` takes each inbound `KeyExchange` and returns the messages to send back and, once the exchange is
+ * complete, the derived key:
+ *   - a round-1 message (has `public_key`): generate an ephemeral key, answer, and -- classical, or hybrid with the
+ *     host as encapsulator -- derive straight away; as decapsulator it waits for the round-2 ciphertext;
+ *   - a round-2 message (only `kem_ciphertext`): finish a pending hybrid exchange.
+ */
+export class E2EResponder {
+  #sign;
+  #hybrid;
+  /** @type {Map<string, { sharedBits: Uint8Array, localKem: { secretKeySeed: Uint8Array }, timer: any }>} */
+  #pending = new Map();
+
+  /**
+   * @param {object} [opts]
+   * @param {CryptoKey | null} [opts.signKey] - long-term Ed25519 private key; given, the reply is signed
+   * @param {boolean} [opts.hybrid=true] - offer X25519+ML-KEM-768 when the initiator asks for it
+   */
+  constructor({ signKey = null, hybrid = true } = {}) {
+    this.#sign = signKey;
+    this.#hybrid = hybrid;
+  }
+
+  get signs() { return !!this.#sign; }
+
+  /** Forget unfinished exchanges (the connection ended). */
+  close() {
+    for (const p of this.#pending.values()) clearTimeout(p.timer);
+    this.#pending.clear();
+  }
+
+  /**
+   * `emit(reply)` (optional) is called with each reply as soon as it is ready -- the round-1 reply BEFORE the key
+   * derivation and ML-KEM encapsulation, so the peer has it (and has registered for the ciphertext) well before the
+   * ciphertext follows. Without `emit` the replies are returned in `replies`.
+   *
+   * @param {object} msg - a KeyExchange
+   * @param {(reply: object) => Promise<void> | void} [emit]
+   * @returns {Promise<{ replies: object[], key?: CryptoKey, sessionId: string, hybrid?: boolean }>}
+   */
+  async respond(msg, emit) {
+    const sessionId = msg.session_id;
+    if (typeof sessionId !== 'string' || !sessionId) throw new Error('KeyExchange without a session_id');
+    if (msg.public_key === undefined && msg.kem_ciphertext !== undefined) return this.#finish(msg, sessionId);
+    return this.#begin(msg, sessionId, emit);
+  }
+
+  async #begin(msg, sessionId, emit) {
+    const replies = [];
+    const out = async (reply) => { if (emit) await emit(reply); else replies.push(reply); };
+    const algorithm = msg.algorithm;
+    if (algorithm !== E2E_ALGORITHM_CLASSICAL && algorithm !== E2E_ALGORITHM_HYBRID) throw new Error(`unsupported E2E algorithm ${JSON.stringify(algorithm)}`);
+    const peerPub = msg.public_key;
+    if (!(peerPub instanceof Uint8Array) || peerPub.length !== 32) throw new Error('KeyExchange public_key must be a 32-byte X25519 key');
+    const peerKem = msg.kem_public_key;
+    const wantHybrid = algorithm === E2E_ALGORITHM_HYBRID && this.#hybrid
+      && peerKem instanceof Uint8Array && peerKem.length === MLKEM768_PUBLIC_KEY_LENGTH;
+
+    // A fresh exchange for this session replaces an unfinished one.
+    this.#drop(sessionId);
+
+    const ephemeral = await crypto.subtle.generateKey({ name: 'X25519' }, false, ['deriveBits']);
+    const localPub = new Uint8Array(await crypto.subtle.exportKey('raw', ephemeral.publicKey));
+    let localKem = null;
+    if (wantHybrid) {
+      try { localKem = await generateMlKemKeyPair(); } catch { localKem = null; } // no ML-KEM backend here: fall back to classical
+    }
+    const hybrid = !!localKem;
+
+    const reply = {
+      algorithm: hybrid ? E2E_ALGORITHM_HYBRID : E2E_ALGORITHM_CLASSICAL,
+      publicKey: localPub,
+      sessionId,
+      kemPublicKey: localKem?.publicKey,
+    };
+    if (this.#sign) {
+      reply.signature = await signBytes(this.#sign, keyExchangeTranscript({ sessionId, algorithm, initiatorKey: peerPub, responderKey: localPub }));
+    }
+    await out(keyExchange(reply));
+
+    const peerKey = await crypto.subtle.importKey('raw', peerPub, { name: 'X25519' }, false, []);
+    const sharedBits = new Uint8Array(await crypto.subtle.deriveBits({ name: 'X25519', public: peerKey }, ephemeral.privateKey, 256));
+
+    if (!hybrid) return { replies, key: await toAesKey(sharedBits), sessionId, hybrid: false };
+
+    if (compareBytes(localPub, peerPub) < 0) {
+      // The lower key encapsulates against the other side's ML-KEM key.
+      const { ciphertext, sharedSecret } = await mlKemEncapsulate(peerKem);
+      await new Promise((resolve) => setTimeout(resolve, 0)); // let the round-1 reply land before the ciphertext follows
+      await out(keyExchange({ algorithm: E2E_ALGORITHM_HYBRID, sessionId, kemCiphertext: ciphertext }));
+      return { replies, key: await toAesKey(await combineHybridSecret(sharedBits, sharedSecret)), sessionId, hybrid: true };
+    }
+    // The higher key decapsulates: wait for the peer's ciphertext.
+    while (this.#pending.size >= MAX_PENDING) this.#drop(this.#pending.keys().next().value);
+    const timer = setTimeout(() => this.#drop(sessionId), PENDING_TTL_MS);
+    timer.unref?.();
+    this.#pending.set(sessionId, { sharedBits, localKem, timer });
+    return { replies, sessionId, hybrid: true };
+  }
+
+  async #finish(msg, sessionId) {
+    const pending = this.#pending.get(sessionId);
+    if (!pending) throw new Error('unexpected KeyExchange ciphertext (no hybrid exchange in progress for this session)');
+    this.#drop(sessionId);
+    const kemSecret = await mlKemDecapsulate(pending.localKem.secretKeySeed, new Uint8Array(msg.kem_ciphertext));
+    return { replies: [], key: await toAesKey(await combineHybridSecret(pending.sharedBits, kemSecret)), sessionId, hybrid: true };
+  }
+
+  #drop(sessionId) {
+    const p = this.#pending.get(sessionId);
+    if (p) { clearTimeout(p.timer); this.#pending.delete(sessionId); }
+  }
+}
+
+function toAesKey(bits) {
+  return crypto.subtle.importKey('raw', bits, { name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt']);
+}