@johnhenry/wsh 0.13.0 → 0.15.0

package/README.md

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

package/package.json

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

package/src/client.mjs

@@ -134,8 +134,18 @@ export class WshClient {
   /** @type {string|null} Session ID assigned by the server after authentication. */
   #sessionId = null;
 
-  /** @type {string|null} Resume token from AUTH_OK. */
-  #resumeToken = null;
+  /**
+   * @type {string|null} Connection-level token from AUTH_OK, bound to
+   * this connection's own auth session_id (from CHALLENGE/SERVER_HELLO) --
+   * NOT a PTY/exec session's token. Renamed from `#resumeToken` (clawser
+   * #48): the old name invited exactly the bug this fix addresses --
+   * attachSession() used to send this as if it were a valid token for the
+   * *target* session_id, which it can never be (it's scoped to a
+   * different session_id entirely). Not used for anything else currently;
+   * kept and exposed via `authToken` for potential future connection-level
+   * resume use, mirroring the Rust client's `WshClient::token()`.
+   */
+  #authToken = null;
 
   /** @type {import('./transport.mjs').WshTransport|null} Active transport. */
   #transport = null;
@@ -282,6 +292,16 @@ export class WshClient {
     return this.#sessionId;
   }
 
+  /**
+   * This connection's own AUTH-level token (from AUTH_OK), scoped to this
+   * connection's auth session_id -- NOT a PTY/exec session token. See
+   * `WshSession.resumeToken` for the per-session credential used by
+   * `resumeSession`.
+   */
+  get authToken() {
+    return this.#authToken;
+  }
+
   /** Read-only view of active sessions. */
   get sessions() {
     return new Map(this.#sessions);
@@ -341,7 +361,7 @@ export class WshClient {
     this.#channelCounter = 0;
     this.#waiters.clear();
     this.#sessionId = null;
-    this.#resumeToken = null;
+    this.#authToken = null;
 
     try {
       // ── Select and connect transport ──────────────────────────────
@@ -384,7 +404,7 @@ export class WshClient {
           if (challengeMsg.type === MSG.AUTH_OK) {
             // Server accepted without challenge (e.g. trusted key).
             this.#sessionId = challengeMsg.session_id || tempSessionId;
-            this.#resumeToken = challengeMsg.token || null;
+            this.#authToken = challengeMsg.token || null;
             this.#state = STATE_AUTHENTICATED;
             this.#startPing();
             return this.#sessionId;
@@ -460,7 +480,7 @@ export class WshClient {
       }
 
       this.#sessionId = authResult.session_id || tempSessionId;
-      this.#resumeToken = authResult.token || null;
+      this.#authToken = authResult.token || null;
       this.#state = STATE_AUTHENTICATED;
       this.#startPing();
 
@@ -538,37 +558,48 @@ export class WshClient {
   /**
    * Attach to an existing remote session (collaborative or read-only).
    *
+   * Authorization is satisfied by EITHER `token` OR the caller already
+   * owning/being ACL-granted access to `targetSessionId` server-side (see
+   * wsh-server's `check_session_access`) -- `token` is optional and, for
+   * the common case of attaching via ownership or a `grantSessionAccess`
+   * grant, should simply be omitted (a granted principal never receives
+   * the session's token to begin with -- only the opener does, via
+   * `WshSession.resumeToken`). Pass one explicitly only if you have it
+   * (e.g. this same process opened the session earlier, or the owner
+   * shared it with you out of band).
+   *
+   * Previously (clawser #48) this always sent this connection's own
+   * AUTH-level token, which can never verify against a *different*
+   * session_id -- making attachSession() unreachable for everyone,
+   * including the session's own owner from a fresh connection. Also fixed
+   * alongside that: the server actually replies with PRESENCE (success)
+   * or ERROR (failure), not OPEN_OK/OPEN_FAIL -- this used to wait on the
+   * wrong response stream entirely and would have hung even once the
+   * token bug was fixed.
+   *
    * @param {string} targetSessionId - Remote session ID to attach to
    * @param {object} [opts]
    * @param {boolean} [opts.readOnly=false] - Attach in read-only mode
+   * @param {Uint8Array} [opts.token] - Session-scoped token (optional; see above)
    * @param {number} [opts.timeout] - Timeout in ms
-   * @returns {Promise<object>} Server's response
+   * @returns {Promise<object>} Server's PRESENCE response
    */
-  async attachSession(targetSessionId, { readOnly = false, timeout = DEFAULT_OPEN_TIMEOUT } = {}) {
+  async attachSession(targetSessionId, { readOnly = false, token, timeout = DEFAULT_OPEN_TIMEOUT } = {}) {
     this.#assertAuthenticated('attachSession');
 
     const attachMode = readOnly ? 'readonly' : 'control';
     await this.#transport.sendControl(
-      attachMsg({ sessionId: targetSessionId, token: this.#resumeToken, mode: attachMode })
+      attachMsg({ sessionId: targetSessionId, token, mode: attachMode })
     );
 
-    // Shares #pendingOpens with openSession() -- both wait on the same
-    // OPEN_OK/OPEN_FAIL response stream, in the order their requests were
-    // sent (see #pendingOpens's doc comment). Unlike openSession(),
-    // attachSession() doesn't construct a WshSession, so it just wants
-    // the raw response either way.
-    const response = await new Promise((resolve, reject) => {
-      const entry = { mode: 'raw', resolve, reject };
-      entry.timer = setTimeout(() => {
-        const idx = this.#pendingOpens.indexOf(entry);
-        if (idx !== -1) this.#pendingOpens.splice(idx, 1);
-        reject(new Error('Timed out waiting for attach response'));
-      }, timeout);
-      this.#pendingOpens.push(entry);
-    });
+    const response = await this.#waitForMessage(
+      [MSG.PRESENCE, MSG.ERROR],
+      timeout,
+      'Timed out waiting for attach response'
+    );
 
-    if (response.type === MSG.OPEN_FAIL) {
-      throw new Error(`Failed to attach: ${response.reason || 'rejected'}`);
+    if (response.type === MSG.ERROR) {
+      throw new Error(`Failed to attach: ${response.message || 'rejected'}`);
     }
 
     return response;
@@ -577,26 +608,35 @@ export class WshClient {
   /**
    * Resume a previously disconnected session.
    *
+   * Unlike attachSession(), `token` is required and verified
+   * unconditionally server-side -- Resume is specifically for the
+   * connection that was handed this exact token (via
+   * `WshSession.resumeToken`, when it originally opened the session)
+   * coming back. A principal who only has ACL/ownership access but never
+   * held the token should use attachSession() instead.
+   *
    * @param {string} targetSessionId - Session ID to resume
-   * @param {string} token - Resume token from original AUTH_OK
-   * @param {number} [opts.timeout] - Timeout in ms
-   * @returns {Promise<object>} Server's response
+   * @param {Uint8Array} token - Session-scoped resume token (see `WshSession.resumeToken`)
+   * @param {object} [opts]
+   * @param {number} [opts.lastSeq=0] - Last sequence number this client already has (currently advisory -- the ring buffer replays its full contents regardless)
+   * @param {number} [opts.timeout=10000] - Timeout in ms
+   * @returns {Promise<object>} Server's PRESENCE response
    */
-  async resumeSession(targetSessionId, token, { timeout = DEFAULT_OPEN_TIMEOUT } = {}) {
+  async resumeSession(targetSessionId, token, { lastSeq = 0, timeout = DEFAULT_OPEN_TIMEOUT } = {}) {
     this.#assertAuthenticated('resumeSession');
 
     await this.#transport.sendControl(
-      resumeMsg({ sessionId: targetSessionId, token })
+      resumeMsg({ sessionId: targetSessionId, token, lastSeq })
     );
 
     const response = await this.#waitForMessage(
-      [MSG.AUTH_OK, MSG.AUTH_FAIL],
+      [MSG.PRESENCE, MSG.ERROR],
       timeout,
       'Timed out waiting for resume response'
     );
 
-    if (response.type === MSG.AUTH_FAIL) {
-      throw new Error(`Failed to resume: ${response.reason || 'rejected'}`);
+    if (response.type === MSG.ERROR) {
+      throw new Error(`Failed to resume: ${response.message || 'rejected'}`);
     }
 
     return response;
@@ -1667,7 +1707,7 @@ export class WshClient {
 
           if (challengeMsg.type === MSG.AUTH_OK) {
             this.#sessionId = challengeMsg.session_id || tempSessionId;
-            this.#resumeToken = challengeMsg.token || null;
+            this.#authToken = challengeMsg.token || null;
             this.#state = STATE_AUTHENTICATED;
             this.#startPing();
             return this.#sessionId;
@@ -1713,7 +1753,7 @@ export class WshClient {
       }
 
       this.#sessionId = authResult.session_id || tempSessionId;
-      this.#resumeToken = authResult.token || null;
+      this.#authToken = authResult.token || null;
       this.#state = STATE_AUTHENTICATED;
       this.#startPing();
 
@@ -1773,14 +1813,6 @@ export class WshClient {
       if (!pending) return;
       clearTimeout(pending.timer);
 
-      // attachSession() wants the raw response either way and never
-      // constructs a session -- it has no #sessions-registration race to
-      // protect against.
-      if (pending.mode === 'raw') {
-        pending.resolve(msg);
-        return;
-      }
-
       if (type === MSG.OPEN_FAIL) {
         pending.reject(new Error(`Failed to open session: ${msg.reason || 'rejected'}`));
         return;
@@ -1796,7 +1828,18 @@ export class WshClient {
         serverChannelId,
         streamIds,
         pending.kind,
-        { dataMode, capabilities }
+        {
+          dataMode,
+          capabilities,
+          // clawser #48: OpenOk now carries the session_id/token this
+          // channel belongs to (pty/exec only -- undefined for e.g. file
+          // channels, which have no Attach/Resume-able session). Exposed
+          // via WshSession.sessionId/resumeToken for a later
+          // attachSession()/resumeSession() call, possibly from a
+          // different connection.
+          sessionId: msg.session_id,
+          resumeToken: msg.token,
+        }
       );
       this.#sessions.set(serverChannelId, session);
 

package/src/e2e-frame.mjs

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