@johnhenry/wsh 0.16.0 → 0.17.0

package/src/mlkem.mjs

@@ -66,7 +66,34 @@ function bytesEqual(a, b) {
   return diff === 0;
 }
 
+/**
+ * Which implementation serves ML-KEM-768, with an override for testing.
+ *
+ * The noble branch is the ONLY path a browser can take -- no browser
+ * implements the experimental WebCrypto ML-KEM draft -- and until this
+ * override existed no test had ever executed a line of it. `getBackend()`
+ * memoised a probe that always succeeds on the repo's target runtime, so
+ * every assertion ran against native, and every noble call
+ * (`ml_kem768.keygen`, `.encapsulate`, `.decapsulate`) was untouched. A
+ * change in noble's argument order or seed semantics -- it is pinned only to
+ * `^0.7.0` and called through three positional APIs -- would break hybrid PQ
+ * key exchange for every browser consumer while this repo stayed green.
+ *
+ * `WSH_MLKEM_BACKEND=noble` forces it. Read defensively: this module runs in
+ * browsers, where `process` does not exist.
+ */
+function backendOverride() {
+  try {
+    const value = globalThis.process?.env?.WSH_MLKEM_BACKEND;
+    return value === 'noble' || value === 'native' ? value : null;
+  } catch {
+    return null;
+  }
+}
+
 async function getBackend() {
+  const forced = backendOverride();
+  if (forced) return forced;
   if (!backendPromise) {
     backendPromise = probeNativeSupport().then((supported) => (supported ? 'native' : 'noble'));
   }

package/src/session.mjs

@@ -20,6 +20,17 @@ const STATE_OPENING = 'opening';
 const STATE_ACTIVE  = 'active';
 const STATE_CLOSED  = 'closed';
 
+/**
+ * Stream-mode data and control streams are independently-multiplexed
+ * transport streams (QUIC/QMux) with no guaranteed relative delivery
+ * order (wsh #24). When the data stream reaches EOF, the server-sent
+ * `CLOSE` control message -- not the data-stream FIN -- is the
+ * authoritative close signal, so `_pumpDataStream()` waits up to this
+ * long for `CLOSE` to arrive before falling back to closing on data-EOF
+ * alone (a safety net for servers that never send `CLOSE`).
+ */
+const DATA_EOF_CLOSE_GRACE_MS = 300;
+
 // ── Text encoding ─────────────────────────────────────────────────────
 
 const textEncoder = new TextEncoder();
@@ -133,6 +144,18 @@ export class WshSession {
   /** @type {number|null} Exit code received from the server. */
   #exitCode = null;
 
+  /**
+   * Pending fallback timer scheduled when the data stream hits EOF
+   * before a `CLOSE` control message has arrived (wsh #24). Cleared
+   * as soon as `CLOSE` arrives (or the session is otherwise closed) so
+   * a prompt `CLOSE` short-circuits the wait instead of idling out the
+   * full grace period.
+   * @type {ReturnType<typeof setTimeout>|null}
+   */
+  #closeGraceTimer = null;
+  /** Why the session closed, when it closed for a reason worth naming. */
+  #closeReason = null;
+
   // ── Callbacks ───────────────────────────────────────────────────────
 
   /**
@@ -454,7 +477,7 @@ export class WshSession {
     for (const { nonce, ciphertext } of wireChunks) {
       const counter = this.#e2eRecvCounter++;
       try {
-        const plaintext = await openFrame(this.#e2eKey, this.#sessionId, counter, { nonce, ciphertext });
+        const plaintext = await openFrame(this.#e2eKey, this.#sessionId, counter, { nonce, ciphertext, expectedRoleTag: this.#e2eRecvRoleTag });
         plaintexts.push(plaintext);
       } catch (err) {
         console.error(
@@ -580,6 +603,7 @@ export class WshSession {
     // Optimistically mark closed so no further writes are accepted.
     this.#state = STATE_CLOSED;
     this.#abort.abort();
+    this.#clearCloseGraceTimer();
 
     // Send CLOSE to the server (best-effort).
     try {
@@ -660,7 +684,7 @@ export class WshSession {
         // 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 })
+        openFrame(this.#e2eKey, this.#sessionId, counter, { nonce: msg.nonce, ciphertext: msg.ciphertext, expectedRoleTag: this.#e2eRecvRoleTag })
           .then((plaintext) => {
             this.#virtualBackend?.pushData(plaintext);
             try {
@@ -697,15 +721,12 @@ export class WshSession {
       }
 
       case MSG.CLOSE: {
-        // Server-initiated close.
-        if (this.#state !== STATE_CLOSED) {
-          this.#state = STATE_CLOSED;
-          this.#abort.abort();
-          this.#virtualBackend?.close();
-          this.#releaseStreams();
-          this.#resolvePendingFileChunk(null);
-          this.#emitClose();
-        }
+        // Server-initiated close. This is the authoritative close signal
+        // for stream-mode sessions (wsh #24) -- it always short-circuits
+        // any pending data-EOF grace timer, regardless of which arrived
+        // first.
+        this.#clearCloseGraceTimer();
+        this.#closeNow();
         break;
       }
 
@@ -848,11 +869,32 @@ export class WshSession {
           if (this.#e2eKey !== null && this.#streamAccumulator) {
             const deliverable = await this.#openStreamChunks(value);
             if (deliverable === null) {
-              // Authentication failure (or corrupt framing) -- matches
-              // the strict "no skip-and-continue" philosophy of
-              // virtual-mode's counter check: tear the session down
-              // rather than deliver anything from this point on.
-              break;
+              /*
+               * Authentication failure (or corrupt framing) -- the strict
+               * "no skip-and-continue" philosophy of virtual-mode's counter
+               * check: tear the session down rather than deliver anything
+               * from this point on.
+               *
+               * `break` alone did not tear anything down. It left the loop,
+               * and control fell through to the data-EOF grace timer, so the
+               * session stayed `active` and writable for the full 300ms and
+               * then closed as an ordinary EOF: onClose with no error,
+               * onExit never fired, exitCode still null. An application could
+               * not tell "the peer forged data at me" from "the process
+               * exited and the server forgot to send CLOSE" -- the two were
+               * byte-identical to observe.
+               *
+               * Closed immediately, and the reason recorded so the two are
+               * distinguishable. `StreamAuthenticationError` was already
+               * built here and handed only to console.error; it is now the
+               * close reason as well.
+               */
+              this.#closeReason = new StreamAuthenticationError(
+                'wsh: stream authentication failed -- session torn down'
+              );
+              this.#clearCloseGraceTimer();
+              this.#closeNow();
+              return;
             }
             for (const plaintext of deliverable) {
               try {
@@ -879,17 +921,69 @@ export class WshSession {
       reader.releaseLock();
     }
 
-    // If the data stream ended but we haven't received a CLOSE message,
-    // transition to closed state.
-    if (this.#state !== STATE_CLOSED) {
-      this.#state = STATE_CLOSED;
-      this.#releaseStreams();
-      this.#emitClose();
+    // The data stream ended, but its FIN carries no ordering guarantee
+    // relative to the control stream (wsh #24): a server that closes the
+    // data stream and sends EXIT/CLOSE around the same time can have
+    // this EOF arrive before those control messages. Closing the session
+    // here unconditionally would resolve onClose without onExit ever
+    // having fired. Instead, give the (expected) CLOSE control message a
+    // bounded grace period to arrive -- its handler clears this timer and
+    // performs the real transition -- and only self-close on timeout as a
+    // fallback for servers that never send CLOSE after ending the data
+    // stream.
+    if (this.#state !== STATE_CLOSED && this.#closeGraceTimer === null) {
+      this.#closeGraceTimer = setTimeout(() => {
+        this.#closeGraceTimer = null;
+        this.#closeNow();
+      }, DATA_EOF_CLOSE_GRACE_MS);
+      this.#closeGraceTimer?.unref?.();
     }
   }
 
   // ── Private helpers ─────────────────────────────────────────────────
 
+  /**
+   * Cancel any pending data-EOF close-grace timer (wsh #24). Safe to call
+   * whether or not a timer is currently scheduled.
+   * @private
+   */
+  /**
+   * Close the session once, releasing everything a close has to release.
+   *
+   * There were two ways a stream-mode session reached `closed` and they did
+   * not agree. The CLOSE control handler aborted, closed the virtual backend,
+   * released the streams AND settled any parked file chunk. The data-EOF
+   * grace fallback -- the path taken when a server ends the data stream
+   * without sending CLOSE, which the comment above it says is real -- only
+   * released the streams and fired onClose.
+   *
+   * So `download()`, parked on `_readFileChunk()`, was never settled on that
+   * path. It documents returning `null` for a truncated transfer and
+   * `download()` turns that into a thrown error; via the fallback it returned
+   * nothing at all and the download hung forever, while `onClose` had already
+   * fired and the session read `closed`.
+   *
+   * One method rather than two call sites kept in step by hand: the drift is
+   * the bug, and the next field added to a close would have drifted the same
+   * way.
+   */
+  #closeNow() {
+    if (this.#state === STATE_CLOSED) return;
+    this.#state = STATE_CLOSED;
+    this.#abort.abort();
+    this.#virtualBackend?.close();
+    this.#releaseStreams();
+    this.#resolvePendingFileChunk(null);
+    this.#emitClose();
+  }
+
+  #clearCloseGraceTimer() {
+    if (this.#closeGraceTimer !== null) {
+      clearTimeout(this.#closeGraceTimer);
+      this.#closeGraceTimer = null;
+    }
+  }
+
   /**
    * Release stream resources without sending a CLOSE message.
    * @private
@@ -909,9 +1003,19 @@ export class WshSession {
    * Emit the onClose callback exactly once.
    * @private
    */
+  /**
+   * Why the session closed, or null for an ordinary close.
+   *
+   * A torn-down session and a clean exit used to be indistinguishable from
+   * the outside; this is what tells them apart.
+   */
+  get closeReason() {
+    return this.#closeReason;
+  }
+
   #emitClose() {
     try {
-      this.onClose?.();
+      this.onClose?.(this.#closeReason);
     } catch (err) {
       console.error('[wsh:session] onClose handler error:', err);
     }

package/src/transport-ws.mjs

@@ -214,8 +214,22 @@ export class WebSocketTransport extends WshTransport {
     // own stream objects -- without this, any reader still waiting on a
     // stream's readable side would hang forever, since nothing else
     // errors or closes it once the peer can no longer respond.
-    this.#qmux?.close();
-    this.#qmux?.destroy(new Error('Transport closed'));
+    //
+    // Each step is guarded separately. The courtesy CONNECTION_CLOSE is
+    // the one that can realistically throw -- it writes to the socket,
+    // and a socket that is already broken is the single most likely
+    // reason we are closing at all. Letting that throw would skip both
+    // the local `destroy()` (hanging every waiting reader, the exact
+    // thing above) and the socket close (leaking the connection), which
+    // makes the failure mode strictly worse than the failure that
+    // triggered it.
+    try {
+      this.#qmux?.close();
+    } catch { /* peer is unreachable; the local teardown below still matters */ }
+
+    try {
+      this.#qmux?.destroy(new Error('Transport closed'));
+    } catch { /* a stream's error callback threw; keep tearing down */ }
 
     if (this.#ws) {
       try {

package/src/transport.mjs

@@ -111,7 +111,7 @@ const STATE_CLOSED       = 'closed';
  * Abstract transport for the wsh protocol.
  *
  * Subclasses must implement:
- *   - _doConnect(url)
+ *   - _doConnect(url, options)
  *   - _doClose()
  *   - _doSendControl(msg)
  *   - _doOpenStream()
@@ -144,17 +144,40 @@ export class WshTransport {
   /**
    * Connect to a wsh server.
    * @param {string} url
+   * @param {object} [options] - Transport-specific connect options.
+   *   Ignored by transports that have none; `WebTransportTransport`
+   *   forwards them to the `WebTransport` constructor (see its docs for
+   *   `serverCertificateHashes`).
    */
-  async connect(url) {
+  async connect(url, options) {
     if (this.#state === STATE_CONNECTED || this.#state === STATE_CONNECTING) {
       throw new Error(`Transport already ${this.#state}`);
     }
     this.#state = STATE_CONNECTING;
     try {
-      await this._doConnect(url);
+      await this._doConnect(url, options);
       this.#state = STATE_CONNECTED;
     } catch (err) {
+      // A connect can fail *after* acquiring a real resource -- an open
+      // WebSocket whose QMux handshake then threw, a WebTransport whose
+      // session came up but whose control stream did not. Tear that down
+      // here, because a later `close()` cannot: it treats the `closed`
+      // state this line sets as "already torn down" and returns without
+      // calling `_doClose()`, so the socket would stay open for the life
+      // of the page. Every rung of WshClient's transport ladder that
+      // fails hits this path.
       this.#state = STATE_CLOSED;
+      try {
+        await this._doClose();
+      } catch {
+        // Best effort: the connect error is the one worth reporting, and
+        // tearing down a half-built transport can fail for its own
+        // uninteresting reasons.
+      }
+      // Deliberately no `_emitClose()`: a transport that never reached
+      // `connected` never announced itself, callers have not attached
+      // their handlers yet, and a close event for a connection that never
+      // opened is a lie.
       throw err;
     }
   }
@@ -235,7 +258,7 @@ export class WshTransport {
   // ── Abstract methods (must be overridden) ────────────────────────────
 
   /** @protected */
-  async _doConnect(_url) {
+  async _doConnect(_url, _options) {
     throw new Error('_doConnect not implemented');
   }
 
@@ -257,6 +280,140 @@ export class WshTransport {
 
 // ── WebTransport implementation ──────────────────────────────────────
 
+// ── WebTransport options ─────────────────────────────────────────────
+
+/** Digest length in bytes, keyed by the algorithm name WebTransport accepts. */
+const CERT_HASH_LENGTHS = Object.freeze({ 'sha-256': 32 });
+
+/**
+ * Decode one `serverCertificateHashes` value into the `BufferSource` the
+ * WebTransport constructor requires.
+ *
+ * Accepts, in addition to a `BufferSource` passed straight through:
+ *
+ * - **Hex**, with or without separators — this is what
+ *   `openssl x509 -fingerprint -sha256` prints
+ *   (`SHA256 Fingerprint=AB:CD:...`), and pasting that string in is the
+ *   single most likely thing a caller will try.
+ * - **Base64** or **base64url**, which is how the same digest usually
+ *   arrives over a QR code or a pairing payload.
+ *
+ * Throws on anything else, and on a digest whose decoded length is wrong
+ * for the algorithm. Failing here is the whole point: a wrong hash
+ * otherwise surfaces as an opaque `WebTransportError` from `wt.ready`
+ * with no indication that the *input* was malformed rather than the
+ * certificate mismatched.
+ *
+ * @param {*} value
+ * @param {string} algorithm - Lower-cased algorithm name (e.g. 'sha-256').
+ * @returns {Uint8Array}
+ */
+export function parseCertificateHash(value, algorithm = 'sha-256') {
+  const expected = CERT_HASH_LENGTHS[algorithm];
+  let bytes;
+
+  if (value instanceof Uint8Array) {
+    bytes = value;
+  } else if (ArrayBuffer.isView(value)) {
+    bytes = new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+  } else if (value instanceof ArrayBuffer) {
+    bytes = new Uint8Array(value);
+  } else if (typeof value === 'string') {
+    bytes = decodeHashString(value);
+  } else {
+    throw new TypeError(
+      'serverCertificateHashes value must be a BufferSource or a hex/base64 string, ' +
+      `got ${value === null ? 'null' : typeof value}`
+    );
+  }
+
+  if (expected !== undefined && bytes.length !== expected) {
+    throw new RangeError(
+      `serverCertificateHashes value for "${algorithm}" must be ${expected} bytes, got ${bytes.length}`
+    );
+  }
+  return bytes;
+}
+
+/**
+ * @param {string} str
+ * @returns {Uint8Array}
+ */
+function decodeHashString(str) {
+  // Strip the separators OpenSSL and friends emit, plus any surrounding
+  // whitespace: "SHA256 Fingerprint=" style output is colon-separated,
+  // and hand-copied values often carry spaces or dashes.
+  const compact = str.trim().replace(/^[^=]*fingerprint[^=]*=\s*/i, '');
+  const hexish = compact.replace(/[\s:-]/g, '');
+
+  if (/^[0-9a-fA-F]+$/.test(hexish) && hexish.length % 2 === 0) {
+    const out = new Uint8Array(hexish.length / 2);
+    for (let i = 0; i < out.length; i++) {
+      out[i] = Number.parseInt(hexish.slice(i * 2, i * 2 + 2), 16);
+    }
+    return out;
+  }
+
+  // Not hex — try base64 / base64url.
+  const b64 = compact.replace(/-/g, '+').replace(/_/g, '/');
+  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(b64)) {
+    throw new TypeError(
+      `serverCertificateHashes value is neither hex nor base64: ${JSON.stringify(str)}`
+    );
+  }
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+/**
+ * Normalise a caller-supplied options bag into a `WebTransportOptions`
+ * dictionary, or `undefined` when there is nothing to pass.
+ *
+ * Only `serverCertificateHashes` is transformed; every other key is
+ * forwarded verbatim, so options the platform gains later
+ * (`congestionControl`, `allowPooling`, `requireUnreliable`, the
+ * `anticipatedConcurrentIncoming*Streams` hints, …) work without a
+ * change here.
+ *
+ * @param {object} [options]
+ * @returns {object|undefined}
+ */
+export function normalizeWebTransportOptions(options) {
+  if (!options) return undefined;
+  const keys = Object.keys(options).filter((k) => options[k] !== undefined);
+  if (keys.length === 0) return undefined;
+
+  const out = {};
+  for (const key of keys) out[key] = options[key];
+
+  if (out.serverCertificateHashes !== undefined) {
+    const list = out.serverCertificateHashes;
+    if (!Array.isArray(list)) {
+      throw new TypeError('serverCertificateHashes must be an array');
+    }
+    if (list.length === 0) {
+      throw new TypeError(
+        'serverCertificateHashes must not be empty -- omit the option entirely to use the ' +
+        'normal certificate-authority path'
+      );
+    }
+    out.serverCertificateHashes = list.map((entry) => {
+      if (entry === null || typeof entry !== 'object' || Array.isArray(entry) ||
+          ArrayBuffer.isView(entry) || entry instanceof ArrayBuffer) {
+        // A bare digest is a natural thing to write; accept it rather
+        // than making the caller wrap every value in { algorithm, value }.
+        return { algorithm: 'sha-256', value: parseCertificateHash(entry, 'sha-256') };
+      }
+      const algorithm = String(entry.algorithm ?? 'sha-256').toLowerCase();
+      return { algorithm, value: parseCertificateHash(entry.value, algorithm) };
+    });
+  }
+
+  return out;
+}
+
 /**
  * wsh transport over the WebTransport API.
  *
@@ -287,16 +444,53 @@ export class WebTransportTransport extends WshTransport {
   /** @type {Promise<void>} Resolves when the incoming-stream acceptor finishes. */
   #incomingAcceptorDone = null;
 
+  /** @type {object|undefined} Default WebTransport options for every connect. */
+  #options;
+
+  /**
+   * @param {object} [options] - Forwarded to the `WebTransport`
+   *   constructor. Most usefully `serverCertificateHashes`, which lets
+   *   page JavaScript pin a specific short-lived self-signed certificate
+   *   by digest instead of requiring one a certificate authority signed:
+   *
+   *   ```js
+   *   new WebTransportTransport({
+   *     serverCertificateHashes: [
+   *       // hex (with or without colons), base64, or raw bytes
+   *       'a1:b2:c3:...',
+   *     ],
+   *   });
+   *   ```
+   *
+   *   The web platform imposes the rules, not wsh: the URL must be
+   *   `https:`, the connection is HTTP/3 only (there is no fallback to
+   *   HTTP/2 for a pinned certificate), the certificate must use an
+   *   ECDSA P-256 key and be valid for no more than 14 days, and
+   *   connection pooling is disabled. Options passed to `connect()`
+   *   override these per call.
+   */
+  constructor(options) {
+    super();
+    this.#options = options;
+  }
+
   // ── Lifecycle ──────────────────────────────────────────────────────
 
   /** @override */
-  async _doConnect(url) {
+  async _doConnect(url, options) {
     this.#abort = new AbortController();
     this.#decoder.reset();
     this.#nextStreamId = 1;
 
-    // Create the WebTransport session.
-    const wt = new WebTransport(url);
+    // Create the WebTransport session. Pass the options dictionary only
+    // when there is something in it: `new WebTransport(url)` and
+    // `new WebTransport(url, {})` are equivalent per spec, but an empty
+    // second argument is noise in a stack trace and in any engine that
+    // predates the dictionary.
+    const wtOptions = normalizeWebTransportOptions(
+      (this.#options || options) && { ...this.#options, ...options }
+    );
+    const wt = wtOptions ? new WebTransport(url, wtOptions) : new WebTransport(url);
     this.#wt = wt;
 
     // Wait for the connection to be ready.