@johnhenry/wsh 0.15.0 → 0.16.1

package/package.json

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

package/src/e2e-frame.mjs

@@ -4,11 +4,15 @@
  * `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.
+ * 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:

package/src/session.mjs

@@ -10,6 +10,9 @@ import {
 } from './messages.mjs';
 import { WshVirtualSessionBackend } from './virtual-session.mjs';
 import { sealFrame, openFrame, ROLE_TAGS } from './e2e-frame.mjs';
+import {
+  ChunkAccumulator, encodeChunk, resolveCoalesceOptions, WriteCoalescer, StreamAuthenticationError,
+} from './stream-frame.mjs';
 
 // ── Session states ────────────────────────────────────────────────────
 
@@ -17,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();
@@ -99,6 +113,22 @@ export class WshSession {
   /** @type {number} Next expected incoming frame counter from the peer. */
   #e2eRecvCounter = 0;
 
+  /**
+   * Reassembles the raw stdout byte stream into complete sealed chunks
+   * when E2E is enabled on a stream-mode session. `null` for virtual-mode
+   * sessions or when E2E is not enabled.
+   * @type {import('./stream-frame.mjs').ChunkAccumulator|null}
+   */
+  #streamAccumulator = null;
+
+  /**
+   * Batches outgoing stream-mode writes before sealing, per the
+   * write-coalescing design (wsh #22). `null` means coalescing is
+   * disabled (`coalesce: false`) -- every write() seals immediately.
+   * @type {WriteCoalescer|null}
+   */
+  #streamCoalescer = null;
+
   /**
    * The readable side of the stdout data stream.
    * @type {ReadableStream<Uint8Array>|null}
@@ -114,6 +144,16 @@ 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;
+
   // ── Callbacks ───────────────────────────────────────────────────────
 
   /**
@@ -320,16 +360,26 @@ export class WshSession {
   }
 
   /**
-   * 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).
+   * Opt in to end-to-end encryption for this session's data plane.
+   * Works for both virtual-mode and stream-mode sessions (wsh #22
+   * generalized this from virtual-mode-only, #19).
+   *
+   * Virtual-mode: after this call, `write()` seals outgoing data into
+   * `EncryptedFrame` control 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).
+   *
+   * Stream-mode: outgoing bytes are sealed and framed inline in the raw
+   * byte stream (`stream-frame.mjs`'s `[len][nonce][ciphertext]` chunk
+   * format, reusing the same `sealFrame`/`openFrame` primitives) --
+   * invisible to the control-message spec, no new CBOR message type.
+   * Small writes are batched before sealing per `opts.coalesce` (see
+   * below); incoming bytes are reassembled via a `ChunkAccumulator` and
+   * opened per-chunk before reaching `onData`.
    *
    * IMPORTANT -- key lifetime: `sharedSecret` must come from a *fresh*
    * `WshClient.initiateE2E()` call on the *current* connection. E2E
@@ -347,17 +397,18 @@ export class WshSession {
    * @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.
+   * @param {false|{maxBytes?: number, maxDelayMs?: number}} [opts.coalesce] - stream-mode only:
+   *   override the default write-coalescing profile derived from this session's `kind`
+   *   ('pty'|'exec'), or pass `false` to seal every write() immediately with no batching.
+   *   Ignored for virtual-mode sessions (each write() is already one EncryptedFrame).
    */
-  enableE2E(sharedSecret, { role } = {}) {
+  enableE2E(sharedSecret, { role, coalesce } = {}) {
     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?');
     }
@@ -366,6 +417,75 @@ export class WshSession {
     this.#e2eRecvRoleTag = role === 'initiator' ? ROLE_TAGS.responder : ROLE_TAGS.initiator;
     this.#e2eSendCounter = 0;
     this.#e2eRecvCounter = 0;
+
+    if (this.#dataMode === 'stream') {
+      // Two-data-plane counter isolation note: send/recv counters above
+      // are per-session (this instance), not shared with any other data
+      // plane -- a session is always exactly one of stream/virtual today,
+      // so there's nothing to cross-wire, but a future refactor that let
+      // one session span both planes simultaneously would need separate
+      // counters per plane.
+      this.#streamAccumulator = new ChunkAccumulator();
+      const profile = resolveCoalesceOptions(this.kind, coalesce);
+      this.#streamCoalescer = profile
+        ? new WriteCoalescer(profile, (bytes) => this.#sealAndWriteStreamChunk(bytes))
+        : null;
+    } else {
+      this.#streamAccumulator = null;
+      this.#streamCoalescer = null;
+    }
+  }
+
+  /**
+   * Seal one stream-mode chunk and write it to the stdin stream. Used
+   * directly by write() when coalescing is disabled, and as the flush
+   * callback for `#streamCoalescer` otherwise.
+   * @private
+   */
+  async #sealAndWriteStreamChunk(bytes) {
+    if (this.#stdinWriter === null) {
+      throw new Error('Session not yet bound — stdin writer unavailable');
+    }
+    const counter = this.#e2eSendCounter++;
+    const { nonce, ciphertext } = await sealFrame(
+      this.#e2eKey, this.#sessionId, this.#e2eSendRoleTag, counter, bytes
+    );
+    await this.#stdinWriter.write(encodeChunk(nonce, ciphertext));
+  }
+
+  /**
+   * Feed newly-read bytes through the stream E2E accumulator and open
+   * every complete chunk it yields.
+   *
+   * @param {Uint8Array} bytes
+   * @returns {Promise<Uint8Array[]|null>} the opened plaintext chunks, in order,
+   *   or `null` if framing was corrupt or a chunk failed authentication
+   *   (already logged; caller should tear the pump down).
+   * @private
+   */
+  async #openStreamChunks(bytes) {
+    let wireChunks;
+    try {
+      wireChunks = this.#streamAccumulator.feed(bytes);
+    } catch (err) {
+      console.error('[wsh:session] stream E2E framing error:', err);
+      return null;
+    }
+    const plaintexts = [];
+    for (const { nonce, ciphertext } of wireChunks) {
+      const counter = this.#e2eRecvCounter++;
+      try {
+        const plaintext = await openFrame(this.#e2eKey, this.#sessionId, counter, { nonce, ciphertext });
+        plaintexts.push(plaintext);
+      } catch (err) {
+        console.error(
+          '[wsh:session] stream E2E chunk failed authentication:',
+          new StreamAuthenticationError(err.message)
+        );
+        return null;
+      }
+    }
+    return plaintexts;
   }
 
   // ── Public API ──────────────────────────────────────────────────────
@@ -401,6 +521,16 @@ export class WshSession {
     }
 
     const bytes = typeof data === 'string' ? textEncoder.encode(data) : data;
+
+    if (this.#e2eKey !== null) {
+      if (this.#streamCoalescer) {
+        await this.#streamCoalescer.write(bytes);
+      } else {
+        await this.#sealAndWriteStreamChunk(bytes);
+      }
+      return;
+    }
+
     await this.#stdinWriter.write(bytes);
   }
 
@@ -471,6 +601,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 {
@@ -482,6 +613,16 @@ export class WshSession {
     }
 
     if (this.#dataMode === 'stream') {
+      // Flush any bytes still batched by write-coalescing before closing
+      // the writer, so a pending buffer isn't silently dropped.
+      if (this.#streamCoalescer) {
+        try {
+          await this.#streamCoalescer.flush();
+        } catch (err) {
+          console.error('[wsh:session] failed to flush coalesced stream E2E writes on close:', err);
+        }
+      }
+
       // Release the stdin writer.
       try {
         await this.#stdinWriter?.close();
@@ -578,7 +719,11 @@ export class WshSession {
       }
 
       case MSG.CLOSE: {
-        // Server-initiated close.
+        // 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();
         if (this.#state !== STATE_CLOSED) {
           this.#state = STATE_CLOSED;
           this.#abort.abort();
@@ -710,13 +855,44 @@ export class WshSession {
         if (this.#abort.signal.aborted) break;
 
         const { done, value } = await reader.read();
-        if (done) break;
+        if (done) {
+          // Clean EOF: catch a torn (truncated) chunk left in the E2E
+          // accumulator, if any -- per the design, no partial-chunk
+          // plaintext is ever released, so this is purely a diagnostic
+          // (the stream is ending either way).
+          if (this.#e2eKey !== null && this.#streamAccumulator) {
+            try {
+              this.#streamAccumulator.finish();
+            } catch (err) {
+              console.error('[wsh:session] stream E2E torn chunk at stream end:', err);
+            }
+          }
+          break;
+        }
 
         if (value && value.byteLength > 0) {
-          try {
-            this.onData?.(value);
-          } catch (err) {
-            console.error('[wsh:session] onData handler error:', err);
+          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;
+            }
+            for (const plaintext of deliverable) {
+              try {
+                this.onData?.(plaintext);
+              } catch (err) {
+                console.error('[wsh:session] onData handler error:', err);
+              }
+            }
+          } else {
+            try {
+              this.onData?.(value);
+            } catch (err) {
+              console.error('[wsh:session] onData handler error:', err);
+            }
           }
         }
       }
@@ -729,17 +905,43 @@ 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;
+        if (this.#state !== STATE_CLOSED) {
+          this.#state = STATE_CLOSED;
+          this.#releaseStreams();
+          this.#emitClose();
+        }
+      }, 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
+   */
+  #clearCloseGraceTimer() {
+    if (this.#closeGraceTimer !== null) {
+      clearTimeout(this.#closeGraceTimer);
+      this.#closeGraceTimer = null;
+    }
+  }
+
   /**
    * Release stream resources without sending a CLOSE message.
    * @private

package/src/stream-frame.mjs

@@ -0,0 +1,372 @@
+/**
+ * Stream-mode chunk framing for wsh's opt-in end-to-end encryption layer
+ * (see `session.mjs`'s `enableE2E`, which now accepts stream-backed
+ * sessions -- this module supplies the framing wrapper that makes that
+ * possible; the AEAD primitives themselves live in `e2e-frame.mjs` and
+ * are reused unchanged).
+ *
+ * This is PR 1 of 3 in the stream-mode E2E rollout (wsh #22, follow-up
+ * to the virtual-mode rollout in #19). See that issue for the full
+ * design doc; the short version below is enough to work on this module.
+ *
+ * ── Why framing is needed at all ──────────────────────────────────────
+ * Stream-mode sessions are raw WebTransport bidirectional byte streams
+ * with no message boundaries (`transport.mjs`'s `openStream()`: "Data
+ * streams carry raw bytes with no framing overhead"). Virtual-mode reuses
+ * the control-message envelope (`EncryptedFrame`) to carry one sealed
+ * frame per `SessionData` 1:1, but a byte stream has no such envelope --
+ * a single `read()` may return a partial chunk, multiple chunks, or a
+ * chunk split across two reads. This module's `ChunkAccumulator` restores
+ * chunk boundaries on the read side; `encodeChunk` builds them on the
+ * write side.
+ *
+ * ── Wire format ────────────────────────────────────────────────────────
+ *
+ *   [ 4-byte big-endian length prefix N ][ 12-byte nonce ][ N bytes: ciphertext + 16-byte GCM tag ]
+ *
+ * - N counts only the ciphertext+tag bytes that follow the nonce (the
+ *   nonce itself is a fixed 12-byte wire constant, not counted -- avoids
+ *   an off-by-12 footgun).
+ * - The nonce is 12 bytes, clear (not secret -- same convention as
+ *   virtual-mode's `EncryptedFrame.nonce`); it encodes the same
+ *   8-byte-counter + 4-byte-role-tag scheme from `e2e-frame.mjs`, reused
+ *   verbatim: a stream "chunk index" is exactly the same thing as
+ *   virtual-mode's "message counter" (see `buildNonce`/`ROLE_TAGS`).
+ * - The length field is NOT bound as AEAD additional authenticated data:
+ *   there's no tampering scenario it prevents that the GCM tag doesn't
+ *   already catch -- a corrupted length either fails decryption outright
+ *   or misaligns the *next* chunk's boundary, but plaintext is never
+ *   released without passing authentication either way.
+ * - Chunk size: soft target ~16 KiB plaintext, hard cap 64 KiB (a `u32`
+ *   length prefix has ample headroom above that). See `resolveCoalesceOptions`
+ *   for how writes are batched up to (well below) that cap before sealing.
+ *
+ * ── Failure modes at stream end ───────────────────────────────────────
+ * `ChunkAccumulator` distinguishes:
+ *  1. Clean EOF -- buffer empty when `finish()` is called.
+ *  2. Torn chunk -- partial bytes buffered (not enough for a complete
+ *     chunk) when `finish()` is called -- throws `StreamTornChunkError`.
+ *  3. Failed AEAD authentication on an otherwise-complete chunk -- this
+ *     is *not* raised by this module (it has no key); callers use
+ *     `StreamAuthenticationError` to report it after calling `openFrame`
+ *     from `e2e-frame.mjs` (see `session.mjs`'s stream read path).
+ * No partial-chunk plaintext is ever released in any case.
+ *
+ * ── Efficiency note ────────────────────────────────────────────────────
+ * `ChunkAccumulator` uses a cursor-based internal buffer (append via an
+ * amortized-doubling growable `Uint8Array`, consume via advancing a read
+ * offset) rather than repeatedly `Uint8Array.slice()`-ing the whole
+ * buffer on every `feed()` call, which would go quadratic under many
+ * small `read()`s. The only per-chunk `slice()` calls are for the two
+ * pieces (`nonce`, `ciphertext`) actually handed back to the caller.
+ */
+
+import { sealFrame } from './e2e-frame.mjs';
+
+const LENGTH_PREFIX_BYTES = 4;
+const NONCE_BYTES = 12;
+const GCM_TAG_BYTES = 16;
+
+/** Soft target plaintext chunk size (see module doc comment). */
+export const CHUNK_SOFT_TARGET_BYTES = 16 * 1024;
+
+/** Hard cap on plaintext chunk size; ciphertext+tag never exceeds this + 16. */
+export const CHUNK_HARD_CAP_BYTES = 64 * 1024;
+
+/**
+ * Sanity bound on the wire length prefix, used only to fail fast on an
+ * obviously-corrupt/malicious length field (e.g. a torn/garbled header)
+ * rather than buffering unboundedly while waiting for a chunk that will
+ * never complete. Generous headroom above `CHUNK_HARD_CAP_BYTES` so a
+ * legitimate sender is never rejected.
+ */
+const MAX_WIRE_CIPHERTEXT_BYTES = CHUNK_HARD_CAP_BYTES + GCM_TAG_BYTES;
+
+/**
+ * Thrown by `ChunkAccumulator.finish()` when the internal buffer still
+ * holds partial (incomplete) chunk bytes at stream EOF -- a truncated
+ * stream, not a clean close. Distinct from `StreamAuthenticationError`
+ * so callers can tell "the stream ended mid-chunk" apart from "a
+ * complete chunk arrived but failed to authenticate".
+ */
+export class StreamTornChunkError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'StreamTornChunkError';
+  }
+}
+
+/**
+ * Thrown by callers (see `session.mjs`'s stream read path) when a
+ * complete, well-framed chunk fails AEAD authentication in
+ * `openFrame()` (tampered ciphertext, wrong key, or session_id
+ * mismatch). Distinct from `StreamTornChunkError` -- this module itself
+ * never throws it, since `ChunkAccumulator` has no key and cannot
+ * authenticate anything.
+ */
+export class StreamAuthenticationError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'StreamAuthenticationError';
+  }
+}
+
+/**
+ * Encode one sealed chunk for the wire: `[len][nonce][ciphertext]`.
+ *
+ * @param {Uint8Array} nonce - exactly 12 bytes
+ * @param {Uint8Array} ciphertext - ciphertext + GCM tag, as returned by `sealFrame`
+ * @returns {Uint8Array}
+ */
+export function encodeChunk(nonce, ciphertext) {
+  if (!(nonce instanceof Uint8Array) || nonce.length !== NONCE_BYTES) {
+    throw new Error(`stream-frame: nonce must be a ${NONCE_BYTES}-byte Uint8Array`);
+  }
+  if (!(ciphertext instanceof Uint8Array)) {
+    throw new Error('stream-frame: ciphertext must be a Uint8Array');
+  }
+  const out = new Uint8Array(LENGTH_PREFIX_BYTES + NONCE_BYTES + ciphertext.length);
+  new DataView(out.buffer).setUint32(0, ciphertext.length, false);
+  out.set(nonce, LENGTH_PREFIX_BYTES);
+  out.set(ciphertext, LENGTH_PREFIX_BYTES + NONCE_BYTES);
+  return out;
+}
+
+/**
+ * Reassembles a raw byte stream into complete `{nonce, ciphertext}`
+ * chunks. See the module doc comment for the wire format and the
+ * efficiency note on the internal buffer strategy.
+ */
+export class ChunkAccumulator {
+  /** @type {Uint8Array} */
+  #buf = new Uint8Array(0);
+  /** @type {number} Read cursor -- bytes before this offset are already consumed. */
+  #start = 0;
+  /** @type {number} Write cursor -- bytes before this offset are valid buffered data. */
+  #end = 0;
+
+  /**
+   * Feed newly-read bytes in and pull out every complete chunk now
+   * available. Any trailing partial chunk stays buffered for the next
+   * `feed()` call.
+   *
+   * @param {Uint8Array} bytes
+   * @returns {Array<{nonce: Uint8Array, ciphertext: Uint8Array}>}
+   */
+  feed(bytes) {
+    if (bytes && bytes.length > 0) {
+      this.#append(bytes);
+    }
+    const chunks = [];
+    for (;;) {
+      const chunk = this.#tryParseOne();
+      if (chunk === null) break;
+      chunks.push(chunk);
+    }
+    // Once fully drained, reset cursors so the buffer doesn't retain a
+    // large-but-empty backing array indefinitely.
+    if (this.#start === this.#end) {
+      this.#start = 0;
+      this.#end = 0;
+    }
+    return chunks;
+  }
+
+  /**
+   * Call at clean stream EOF. Throws `StreamTornChunkError` if partial
+   * chunk bytes are still buffered (a truncated stream); otherwise a
+   * no-op.
+   */
+  finish() {
+    const remaining = this.#end - this.#start;
+    if (remaining > 0) {
+      throw new StreamTornChunkError(
+        `stream-frame: stream ended with ${remaining} torn (incomplete) chunk bytes buffered`
+      );
+    }
+  }
+
+  /** @private */
+  #append(bytes) {
+    const liveLength = this.#end - this.#start;
+    const needed = liveLength + bytes.length;
+    if (needed > this.#buf.length - this.#start) {
+      // Grow (and compact away already-consumed prefix bytes) with
+      // amortized doubling, so repeated small feed() calls stay linear
+      // overall rather than re-copying the whole live region every time.
+      const newCapacity = Math.max(needed, this.#buf.length * 2, 4096);
+      const newBuf = new Uint8Array(newCapacity);
+      newBuf.set(this.#buf.subarray(this.#start, this.#end), 0);
+      this.#buf = newBuf;
+      this.#end = liveLength;
+      this.#start = 0;
+    }
+    this.#buf.set(bytes, this.#end);
+    this.#end += bytes.length;
+  }
+
+  /** @private */
+  #tryParseOne() {
+    const available = this.#end - this.#start;
+    if (available < LENGTH_PREFIX_BYTES + NONCE_BYTES) return null;
+    const headerView = new DataView(this.#buf.buffer, this.#buf.byteOffset + this.#start, LENGTH_PREFIX_BYTES);
+    const n = headerView.getUint32(0, false);
+    if (n > MAX_WIRE_CIPHERTEXT_BYTES) {
+      throw new StreamTornChunkError(
+        `stream-frame: chunk length ${n} exceeds max ${MAX_WIRE_CIPHERTEXT_BYTES} -- corrupt or malicious framing`
+      );
+    }
+    const total = LENGTH_PREFIX_BYTES + NONCE_BYTES + n;
+    if (available < total) return null; // wait for more bytes
+    const nonceStart = this.#start + LENGTH_PREFIX_BYTES;
+    const ciphertextStart = nonceStart + NONCE_BYTES;
+    const nonce = this.#buf.slice(nonceStart, ciphertextStart);
+    const ciphertext = this.#buf.slice(ciphertextStart, this.#start + total);
+    this.#start += total;
+    return { nonce, ciphertext };
+  }
+}
+
+// ── Write coalescing ─────────────────────────────────────────────────
+//
+// Purely local, sender-side batching of small consecutive write() calls
+// into one sealed chunk -- NOT a wire protocol change (the receiver has
+// no idea how many writes got merged, see wsh #22's design-doc update).
+// Smart defaults derive from session `type` (already known at
+// `openSession()` time); callers can override via `enableE2E(key, {
+// coalesce })` or fully disable via `coalesce: false`.
+
+/**
+ * Default coalescing profiles by session kind.
+ *  - `pty` (interactive): latency-first -- flush on a short timer or a
+ *    small byte threshold, whichever fires first. This isn't "batching
+ *    keystrokes"; it mainly catches writes issued in the same event-loop
+ *    tick (multi-byte UTF-8, escape sequences, paste bursts) -- a single
+ *    keystroke still goes out almost immediately.
+ *  - `exec` (bulk): throughput-first -- longer timer and the full 16 KiB
+ *    soft target from the chunk-size design above.
+ * @type {Record<'pty'|'exec', {maxBytes: number, maxDelayMs: number}>}
+ */
+export const DEFAULT_COALESCE_PROFILES = Object.freeze({
+  pty: Object.freeze({ maxBytes: 4 * 1024, maxDelayMs: 6 }),
+  exec: Object.freeze({ maxBytes: CHUNK_SOFT_TARGET_BYTES, maxDelayMs: 30 }),
+});
+
+/**
+ * Resolve the effective coalescing config for a session.
+ *
+ * @param {'pty'|'exec'} kind
+ * @param {false|{maxBytes?: number, maxDelayMs?: number}|undefined} override
+ * @returns {{maxBytes: number, maxDelayMs: number}|null} `null` means "coalescing disabled -- seal every write immediately"
+ */
+export function resolveCoalesceOptions(kind, override) {
+  if (override === false) return null;
+  const base = DEFAULT_COALESCE_PROFILES[kind] || DEFAULT_COALESCE_PROFILES.exec;
+  if (override && typeof override === 'object') {
+    const maxBytes = Number.isFinite(override.maxBytes) && override.maxBytes > 0 ? override.maxBytes : base.maxBytes;
+    const maxDelayMs = Number.isFinite(override.maxDelayMs) && override.maxDelayMs >= 0 ? override.maxDelayMs : base.maxDelayMs;
+    return { maxBytes, maxDelayMs };
+  }
+  return { ...base };
+}
+
+/**
+ * Batches consecutive `write()` calls and flushes them as one chunk once
+ * `maxBytes` is buffered or `maxDelayMs` has elapsed since the first
+ * buffered byte of the current batch, whichever comes first.
+ *
+ * `write()` resolves once bytes are queued, not once they're actually
+ * flushed -- coalescing is local batching, so "queued" is the caller-
+ * visible unit of success (matching wsh #22's resolved design). Flush
+ * errors surface on the promise returned by the *next* `write()`/
+ * `flush()` call that observes the same underlying flush chain.
+ */
+export class WriteCoalescer {
+  #maxBytes;
+  #maxDelayMs;
+  #onFlush;
+  #pending = [];
+  #pendingLength = 0;
+  #timer = null;
+  #chain = Promise.resolve();
+
+  /**
+   * @param {{maxBytes: number, maxDelayMs: number}} options
+   * @param {function(Uint8Array): Promise<void>} onFlush - called with the merged buffered bytes
+   */
+  constructor({ maxBytes, maxDelayMs }, onFlush) {
+    if (!(maxBytes > 0)) {
+      throw new Error('stream-frame: WriteCoalescer requires a positive maxBytes');
+    }
+    if (!(maxDelayMs >= 0)) {
+      throw new Error('stream-frame: WriteCoalescer requires a non-negative maxDelayMs');
+    }
+    if (typeof onFlush !== 'function') {
+      throw new Error('stream-frame: WriteCoalescer requires an onFlush callback');
+    }
+    this.#maxBytes = maxBytes;
+    this.#maxDelayMs = maxDelayMs;
+    this.#onFlush = onFlush;
+  }
+
+  /**
+   * Buffer bytes for later coalesced sealing.
+   * @param {Uint8Array} bytes
+   * @returns {Promise<void>}
+   */
+  write(bytes) {
+    this.#pending.push(bytes);
+    this.#pendingLength += bytes.length;
+    if (this.#pendingLength >= this.#maxBytes) {
+      return this.flush();
+    }
+    if (this.#timer === null) {
+      this.#timer = setTimeout(() => {
+        this.#timer = null;
+        this.flush().catch(() => {
+          // Errors are observed via #chain by the next write()/flush()
+          // caller; swallow here so an unobserved timer-driven flush
+          // doesn't produce an unhandled rejection.
+        });
+      }, this.#maxDelayMs);
+      if (typeof this.#timer.unref === 'function') this.#timer.unref();
+    }
+    return this.#chain;
+  }
+
+  /**
+   * Force-flush any currently-buffered bytes immediately (used on
+   * session close and by the byte/timer thresholds above).
+   * @returns {Promise<void>}
+   */
+  flush() {
+    if (this.#timer !== null) {
+      clearTimeout(this.#timer);
+      this.#timer = null;
+    }
+    if (this.#pending.length === 0) {
+      return this.#chain;
+    }
+    const merged = concatBytes(this.#pending, this.#pendingLength);
+    this.#pending = [];
+    this.#pendingLength = 0;
+    this.#chain = this.#chain.then(() => this.#onFlush(merged));
+    return this.#chain;
+  }
+}
+
+/** @private */
+function concatBytes(parts, totalLength) {
+  if (parts.length === 1) return parts[0];
+  const out = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const part of parts) {
+    out.set(part, offset);
+    offset += part.length;
+  }
+  return out;
+}
+
+// Re-exported for convenience so callers that only need stream-mode
+// sealing don't have to import from two modules.
+export { sealFrame };