quico 0.2.0 → 0.4.0

package/src/tls_bridge.js

@@ -14,8 +14,8 @@
 
 import { TLSSession, createSecureContext as _lemonCreateSecureContext } from 'lemon-tls';
 import nodeTls from 'node:tls';
-import { Emitter } from './utils.js';
-import { build_transport_params } from './transport.js';
+import { DEBUG, Emitter } from './utils.js';
+import { build_transport_params, parse_transport_params } from './transport.js';
 import {
   TLS_CIPHER_SUITES
 } from './crypto.js';
@@ -52,10 +52,28 @@ function TLSBridge(options) {
   var originalDcid = options.originalDcid || new Uint8Array(0);
   var localCid = options.localCid || new Uint8Array(0); // client's own SCID
   var hostname = options.hostname || null;
+  // Peer certificate verification. Defaults to true, matching node:tls — but
+  // until now the option was never plumbed through at all, so quico could not
+  // talk to a server whose certificate wasn't signed by a publicly trusted CA:
+  // no local development against self-signed certs, no internal PKI, and no
+  // interop (the QUIC interop runner mints its own CA and addresses hosts as
+  // server4 / server6, so every implementation disables verification there).
+  var rejectUnauthorized = options.rejectUnauthorized !== false;
+  var ca = options.ca || null;
+  // ALPN protocol(s) to advertise. Default ['h3']; normalize string → array.
+  var supportedAlpns = (function () {
+    var a = options.alpn || ['h3'];
+    return Array.isArray(a) ? a : [a];
+  })();
 
   function feedMessage(data) {
     if (!session) {
-      var sessionOpts = { isServer: isServer, SNICallback: options.SNICallback };
+      var sessionOpts = {
+        isServer: isServer,
+        SNICallback: options.SNICallback,
+        rejectUnauthorized: rejectUnauthorized
+      };
+      if (ca) sessionOpts.ca = ca;
       if (!isServer) {
         sessionOpts.sessionId = new Uint8Array(0); // QUIC: no compatibility mode
         if (hostname) sessionOpts.servername = hostname;
@@ -71,24 +89,76 @@ function TLSBridge(options) {
 
         session.set_context({
           local_supported_versions: [0x0304],
-          local_supported_alpns: ['h3'],
+          local_supported_alpns: supportedAlpns,
           local_supported_groups: [29, 23, 24],
           local_supported_cipher_suites: [0x1301, 0x1302],
           local_extensions: [{ type: 0x39, data: quicParams }],
-          local_supported_signature_algorithms: [0x0401, 0x0501, 0x0601],
+          // Signature schemes offered to the peer (client: in the ClientHello;
+          // server: in CertificateRequest). Full modern list, ordered PSS/ECDSA/
+          // EdDSA first, legacy pkcs1 last (TLS 1.2 compat only — TLS 1.3 never
+          // signs pkcs1). Two bugs lived in the old pkcs1-only list:
+          //   1. Cloudflare zones with ECDSA-only certs reject the ClientHello
+          //      outright (alert 40 handshake_failure — seen live against
+          //      speed.cloudflare.com; claude.ai worked only because that zone
+          //      also carries an RSA cert).
+          //   2. lemon-tls hardcodes THIS full list in the HRR CH2, and RFC 8446
+          //      §4.1.2 requires CH2 to match CH1 exactly — offering a different
+          //      list in CH1 made every HRR flow non-compliant.
+          local_supported_signature_algorithms: [
+            0x0804, 0x0805, 0x0806,          // rsa_pss_rsae_sha256/384/512
+            0x0403, 0x0503, 0x0603,          // ecdsa_secp256r1/384r1/521r1
+            0x0807, 0x0808,                  // ed25519, ed448
+            0x0401, 0x0501, 0x0601           // rsa_pkcs1 (TLS 1.2 legacy)
+          ],
         });
         helloHandled = true; // ClientHello will be generated from this set_context
       }
     }
-    session.message(data);
+    // Only feed real handshake bytes. QUICConnection.connect() calls
+    // feedMessage(new Uint8Array(0)) as a "trigger" to start the handshake,
+    // but the ClientHello is actually built by lemon-tls from set_context()
+    // above, on its own timer — the empty feed was always a no-op in intent.
+    //
+    // It stopped being harmless once lemon-tls hardened parse failures into
+    // fatalAlert(): an empty buffer fails as "truncated u8 at 0", which sets
+    // the session state to 'error' permanently, so the ClientHello timer then
+    // early-returns and NO handshake is ever sent. Guard here rather than
+    // making lemon-tls lenient — rejecting malformed handshake input is the
+    // correct behavior for a TLS stack facing a hostile peer.
+    if (data && data.length > 0) session.message(data);
   }
 
   function setupSessionEvents() {
 
+    // Peer's QUIC transport parameters ride in the TLS quic_transport_parameters
+    // extension (type 0x39): client's in the ClientHello, server's in the
+    // EncryptedExtensions. lemon-tls surfaces every received handshake message via
+    // 'handshakeMessage' with the parsed extensions, so we extract the 0x39 data,
+    // parse it, and hand the params to the QUIC layer (which seeds remote_max_data,
+    // max_ack_delay, ack_delay_exponent, etc. — previously hardcoded defaults).
+    var peerParamsEmitted = false;
+    session.on('handshakeMessage', function (type, data, message) {
+      if (peerParamsEmitted || !message || !Array.isArray(message.extensions)) return;
+      for (var i = 0; i < message.extensions.length; i++) {
+        var e = message.extensions[i];
+        if (e && (e.type === 0x39 || e.type === 57) && e.data) {
+          try {
+            var parsed = parse_transport_params(e.data, 0);
+            peerParamsEmitted = true;
+            if (DEBUG) console.log('[tls] peer transport params parsed (' + e.data.length + 'B)');
+            ev.emit('peerTransportParams', parsed);
+          } catch (err) {
+            if (DEBUG) console.log('[tls] peer transport params parse failed: ' + err.message);
+          }
+          break;
+        }
+      }
+    });
+
     session.on('hello', function () {
       if (helloHandled) return; // prevent double-fire
       helloHandled = true;
-      console.log('[tls] hello — configuring TLS');
+      if (DEBUG) console.log('[tls] hello — configuring TLS');
 
       // Transport params — shared defaults + role-specific fields
       var tp = defaultTransportParams();
@@ -107,13 +177,29 @@ function TLSBridge(options) {
 
       var tlsContext = {
         local_supported_versions: [0x0304],
-        local_supported_alpns: ['h3'],
+        local_supported_alpns: supportedAlpns,
         local_supported_groups: [29, 23, 24],
         local_supported_cipher_suites: [0x1301, 0x1302, 0xc02f, 0xc030, 0xcca8],
         local_extensions: [
           { type: 0x39, data: quicParams }
         ],
-        local_supported_signature_algorithms: [0x0401, 0x0501, 0x0601],
+        // Signature schemes offered to the peer (client: in the ClientHello;
+        // server: in CertificateRequest). Full modern list, ordered PSS/ECDSA/
+        // EdDSA first, legacy pkcs1 last (TLS 1.2 compat only — TLS 1.3 never
+        // signs pkcs1). Two bugs lived in the old pkcs1-only list:
+        //   1. Cloudflare zones with ECDSA-only certs reject the ClientHello
+        //      outright (alert 40 handshake_failure — seen live against
+        //      speed.cloudflare.com; claude.ai worked only because that zone
+        //      also carries an RSA cert).
+        //   2. lemon-tls hardcodes THIS full list in the HRR CH2, and RFC 8446
+        //      §4.1.2 requires CH2 to match CH1 exactly — offering a different
+        //      list in CH1 made every HRR flow non-compliant.
+        local_supported_signature_algorithms: [
+          0x0804, 0x0805, 0x0806,          // rsa_pss_rsae_sha256/384/512
+          0x0403, 0x0503, 0x0603,          // ecdsa_secp256r1/384r1/521r1
+          0x0807, 0x0808,                  // ed25519, ed448
+          0x0401, 0x0501, 0x0601           // rsa_pkcs1 (TLS 1.2 legacy)
+        ],
       };
 
       session.set_context(tlsContext);
@@ -125,7 +211,7 @@ function TLSBridge(options) {
       else if (epoch === 1) quicEpoch = 'handshake';
       else quicEpoch = 'app';
 
-      console.log('[tls] outgoing: epoch=' + quicEpoch + ' type=' + type + ' len=' + data.length);
+      if (DEBUG) console.log('[tls] outgoing: epoch=' + quicEpoch + ' type=' + type + ' len=' + data.length);
       ev.emit('send', quicEpoch, data);
     });
 
@@ -135,7 +221,7 @@ function TLSBridge(options) {
       handshakeSecretsEmitted = true;
       var cipher = session.getCipher();
       var hashName = TLS_CIPHER_SUITES[cipher] ? TLS_CIPHER_SUITES[cipher].hash : 'sha256';
-      console.log('[tls] handshake secrets ready');
+      if (DEBUG) console.log('[tls] handshake secrets ready');
       ev.emit('handshakeSecrets', { local: localSecret, remote: remoteSecret, cipher: cipher, hash: hashName });
     });
 
@@ -144,18 +230,34 @@ function TLSBridge(options) {
       appSecretsEmitted = true;
       var cipher = session.getCipher();
       var hashName = TLS_CIPHER_SUITES[cipher] ? TLS_CIPHER_SUITES[cipher].hash : 'sha256';
-      console.log('[tls] app secrets ready');
+      if (DEBUG) console.log('[tls] app secrets ready');
       ev.emit('appSecrets', { local: localSecret, remote: remoteSecret, cipher: cipher, hash: hashName });
     });
 
     session.on('secureConnect', function () {
-      console.log('[tls] secureConnect');
+      if (DEBUG) console.log('[tls] secureConnect');
       ev.emit('secureConnect');
     });
 
     session.on('keyUpdate', function (info) {
       ev.emit('keyUpdate', info.direction, info.secret);
     });
+
+    // NSS SSLKEYLOGFILE lines, forwarded to whoever owns the connection.
+    //
+    // lemon-tls already formats these correctly for TLS 1.3 — including
+    // picking client_random from the right side based on role — and QUIC uses
+    // the identical label set (CLIENT_HANDSHAKE_TRAFFIC_SECRET,
+    // SERVER_TRAFFIC_SECRET_0, ...), so no translation is needed here.
+    //
+    // Note that subscribing has a cost: lemon-tls skips building these strings
+    // entirely while listenerCount('keylog') is 0. We accept that, matching
+    // node:tls, which also always emits 'keylog'. Two short buffers per
+    // handshake is not a measurable expense, and having key logs available
+    // without a rebuild is worth far more when debugging a live capture.
+    session.on('keylog', function (line) {
+      ev.emit('keylog', line);
+    });
   }
 
   return {
@@ -208,4 +310,4 @@ function createSecureContext(options) {
   return ctx;
 }
 
-export { TLSBridge, createSecureContext };
+export { TLSBridge, createSecureContext };

package/src/transport.js

@@ -13,6 +13,7 @@
  */
 
 import {
+  DEBUG,
   concatUint8Arrays,
   writeVarInt,
   readVarInt
@@ -142,7 +143,7 @@ function parse_quic_datagram(array) {
       : array.slice(start, end);
 
     if (packets.length > 0) {
-      console.log('[quic] coalesced pkt #' + packets.length + ' type=' + pkt.type + ' offset=' + start + ' len=' + pkt.totalLength + ' firstByte=0x' + array[start].toString(16).padStart(2,'0'));
+      if (DEBUG) console.log('[quic] coalesced pkt #' + packets.length + ' type=' + pkt.type + ' offset=' + start + ' len=' + pkt.totalLength + ' firstByte=0x' + array[start].toString(16).padStart(2,'0'));
     }
 
     packets.push(pkt);
@@ -153,6 +154,94 @@ function parse_quic_datagram(array) {
 }
 
 
+// ============================================================
+//  Version Negotiation (RFC 9000 §6, §17.2.1)
+// ============================================================
+
+/** QUIC versions this implementation can actually speak. */
+var SUPPORTED_VERSIONS = [0x00000001];
+
+/**
+ * Is this a version we can handle?
+ * Version 0 identifies a Version Negotiation packet, not a real version.
+ */
+function is_supported_version(version) {
+  return SUPPORTED_VERSIONS.indexOf(version >>> 0) !== -1;
+}
+
+/**
+ * Build a Version Negotiation packet (RFC 9000 §17.2.1).
+ *
+ * A server MUST send one when it receives a long-header packet carrying a
+ * version it does not support — it is how a client discovers what the server
+ * speaks, and how any QUIC prober checks whether a server is alive without
+ * completing a handshake. The interop runner's simulator does exactly that
+ * before starting a test, so without this the server looks dead.
+ *
+ * The packet is unusual: no encryption, no packet number, no frames, and no
+ * connection state. It is valid only as an immediate response.
+ *
+ * IMPORTANT: the connection IDs are swapped. The DCID we send is the SCID we
+ * received, and vice versa — the client matches the reply against its own
+ * Source CID, so getting this backwards makes the packet be ignored.
+ *
+ *   byte 0    1 (long header) + 7 unpredictable bits
+ *   1..4      version 0x00000000
+ *   5         DCID length, then DCID
+ *   ...       SCID length, then SCID
+ *   ...       list of supported versions, 4 bytes each
+ *
+ * @param {Uint8Array} recvDcid  DCID from the client's packet (becomes our SCID)
+ * @param {Uint8Array} recvScid  SCID from the client's packet (becomes our DCID)
+ */
+function build_version_negotiation(recvDcid, recvScid) {
+  var dcid = recvScid || new Uint8Array(0);
+  var scid = recvDcid || new Uint8Array(0);
+
+  // RFC 9000 §17.2.1: the low 7 bits are unused and SHOULD be random, so that
+  // clients don't come to depend on a fixed value.
+  var first = 0x80 | (Math.floor(Math.random() * 128) & 0x7f);
+
+  var versions = SUPPORTED_VERSIONS.slice();
+
+  // A reserved ("greased") version, per RFC 9000 §6.3. Its pattern is
+  // 0x?a?a?a?a, and no endpoint will ever support it. Including one keeps
+  // clients honest: any client that assumes it understands every version in
+  // the list will break here rather than in the field.
+  var grease = ((Math.floor(Math.random() * 16) << 28) |
+                (0x0a << 24) |
+                (Math.floor(Math.random() * 16) << 20) |
+                (0x0a << 16) |
+                (Math.floor(Math.random() * 16) << 12) |
+                (0x0a << 8) |
+                (Math.floor(Math.random() * 16) << 4) |
+                0x0a) >>> 0;
+  versions.push(grease);
+
+  var out = new Uint8Array(1 + 4 + 1 + dcid.length + 1 + scid.length + versions.length * 4);
+  var o = 0;
+
+  out[o++] = first;
+  out[o++] = 0; out[o++] = 0; out[o++] = 0; out[o++] = 0;   // version 0
+
+  out[o++] = dcid.length;
+  out.set(dcid, o); o += dcid.length;
+
+  out[o++] = scid.length;
+  out.set(scid, o); o += scid.length;
+
+  for (var i = 0; i < versions.length; i++) {
+    var v = versions[i] >>> 0;
+    out[o++] = (v >>> 24) & 0xff;
+    out[o++] = (v >>> 16) & 0xff;
+    out[o++] = (v >>> 8) & 0xff;
+    out[o++] = v & 0xff;
+  }
+
+  return out;
+}
+
+
 // ============================================================
 //  QUIC Frame encoding (RFC 9000 §12.4)
 // ============================================================
@@ -201,18 +290,25 @@ function encode_quic_frames(frames) {
     } else if (frame.type === 'stream') {
       var typeByte = 0x08;
       var hasOffset = (frame.offset != null && frame.offset > 0);
-      var hasLen = (frame.data && frame.data.length > 0);
       var hasFin = !!frame.fin;
-
+      var dataLen = (frame.data && frame.data.length) ? frame.data.length : 0;
+
+      // ALWAYS emit the LEN field. A STREAM frame without the LEN bit means
+      // "data runs to the end of the packet"; if anything follows it in the
+      // packet (another frame — e.g. a zero-length FIN-only batched with
+      // others — or padding), the peer reads those trailing bytes as stream
+      // data and the offset overshoots the declared final size
+      // (FINAL_SIZE / PROTOCOL_VIOLATION 0xa). An explicit length is always
+      // safe and self-delimiting.
       if (hasOffset) typeByte |= 0x04;
-      if (hasLen) typeByte |= 0x02;
+      typeByte |= 0x02; // LEN — always present
       if (hasFin) typeByte |= 0x01;
 
       parts.push(concatUint8Arrays([
         new Uint8Array([typeByte]),
         writeVarInt(frame.id),
         hasOffset ? writeVarInt(frame.offset) : new Uint8Array(0),
-        hasLen ? writeVarInt(frame.data.length) : new Uint8Array(0),
+        writeVarInt(dataLen),
         frame.data || new Uint8Array(0)
       ]));
 
@@ -315,18 +411,14 @@ function encode_quic_frames(frames) {
       ]));
 
     } else if (frame.type === 'datagram') {
-      if (frame.contextId != null) {
-        parts.push(concatUint8Arrays([
-          new Uint8Array([0x31]),
-          writeVarInt(frame.contextId),
-          frame.data
-        ]));
-      } else {
-        parts.push(concatUint8Arrays([
-          new Uint8Array([0x30]),
-          frame.data
-        ]));
-      }
+      // Emit the 0x30 form (no Length): the datagram data runs to the end of
+      // the packet. QUICO sends each DATAGRAM as the sole/last frame of its
+      // packet, so the length-prefixed 0x31 form is not needed here. (The
+      // parser above accepts both forms on receive.)
+      parts.push(concatUint8Arrays([
+        new Uint8Array([0x30]),
+        frame.data
+      ]));
     }
   }
 
@@ -498,13 +590,21 @@ function parse_quic_frames(buf) {
       frames.push({ type: 'handshake_done' });
 
     } else if (type === 0x30 || type === 0x31) {
-      var contextId = null;
+      // RFC 9221 DATAGRAM frame. The 0x31 form carries an explicit Length
+      // varint and the datagram data is exactly that many bytes; the 0x30 form
+      // has no Length and the data runs to the end of the packet (so a 0x30
+      // DATAGRAM must be the last frame). The optional field is a Length — not
+      // a "context ID" (that draft-era concept was removed before RFC 9221).
+      var data;
       if (type === 0x31) {
-        var cid = safeReadVarInt(); if (!cid) break;
-        contextId = cid.value;
+        var len = safeReadVarInt(); if (!len) break;
+        var end = offset + len.value;
+        if (end > buf.length) break; // truncated / invalid length
+        data = buf.slice(offset, end); offset = end;
+      } else {
+        data = buf.slice(offset); offset = buf.length;
       }
-      var data = buf.slice(offset); offset = buf.length;
-      frames.push({ type: 'datagram', contextId: contextId, data: data });
+      frames.push({ type: 'datagram', data: data });
 
     } else {
       // Unknown frame — stop
@@ -604,24 +704,28 @@ function parse_transport_params(buf, start) {
 
     var id = idVar.value;
 
+    // Safe inner varint: a malformed param could carry an empty/short value,
+    // in which case readVarInt returns null — never dereference .value blindly.
+    function vi(bytes) { var r = readVarInt(bytes, 0); return r ? r.value : 0; }
+
     switch (id) {
       case 0x00: out.original_destination_connection_id = valueBytes; break;
-      case 0x01: out.max_idle_timeout = readVarInt(valueBytes, 0).value; break;
+      case 0x01: out.max_idle_timeout = vi(valueBytes); break;
       case 0x02: out.stateless_reset_token = valueBytes; break;
-      case 0x03: out.max_udp_payload_size = readVarInt(valueBytes, 0).value; break;
-      case 0x04: out.initial_max_data = readVarInt(valueBytes, 0).value; break;
-      case 0x05: out.initial_max_stream_data_bidi_local = readVarInt(valueBytes, 0).value; break;
-      case 0x06: out.initial_max_stream_data_bidi_remote = readVarInt(valueBytes, 0).value; break;
-      case 0x07: out.initial_max_stream_data_uni = readVarInt(valueBytes, 0).value; break;
-      case 0x08: out.initial_max_streams_bidi = readVarInt(valueBytes, 0).value; break;
-      case 0x09: out.initial_max_streams_uni = readVarInt(valueBytes, 0).value; break;
-      case 0x0a: out.ack_delay_exponent = readVarInt(valueBytes, 0).value; break;
-      case 0x0b: out.max_ack_delay = readVarInt(valueBytes, 0).value; break;
+      case 0x03: out.max_udp_payload_size = vi(valueBytes); break;
+      case 0x04: out.initial_max_data = vi(valueBytes); break;
+      case 0x05: out.initial_max_stream_data_bidi_local = vi(valueBytes); break;
+      case 0x06: out.initial_max_stream_data_bidi_remote = vi(valueBytes); break;
+      case 0x07: out.initial_max_stream_data_uni = vi(valueBytes); break;
+      case 0x08: out.initial_max_streams_bidi = vi(valueBytes); break;
+      case 0x09: out.initial_max_streams_uni = vi(valueBytes); break;
+      case 0x0a: out.ack_delay_exponent = vi(valueBytes); break;
+      case 0x0b: out.max_ack_delay = vi(valueBytes); break;
       case 0x0c: out.disable_active_migration = true; break;
-      case 0x0e: out.active_connection_id_limit = readVarInt(valueBytes, 0).value; break;
+      case 0x0e: out.active_connection_id_limit = vi(valueBytes); break;
       case 0x0f: out.initial_source_connection_id = valueBytes; break;
       case 0x10: out.retry_source_connection_id = valueBytes; break;
-      case 0x20: out.max_datagram_frame_size = readVarInt(valueBytes, 0).value; break;
+      case 0x20: out.max_datagram_frame_size = vi(valueBytes); break;
       default:
         if (!out.unknown) out.unknown = [];
         out.unknown.push({ id: id, bytes: valueBytes });
@@ -641,6 +745,11 @@ export {
   parse_quic_datagram,
   parse_quic_packet,
 
+  // Version negotiation
+  SUPPORTED_VERSIONS,
+  is_supported_version,
+  build_version_negotiation,
+
   // Frame encode/decode
   encode_quic_frames,
   parse_quic_frames,

package/src/utils.js

@@ -13,6 +13,16 @@
  */
 
 
+// ============================================================
+//  Debug flag — set QUICO_DEBUG=1 to enable verbose logging.
+//  Read once at module load. Call sites guard with `if (DEBUG)`
+//  so the (expensive) log-string construction is skipped entirely
+//  when debugging is off.
+// ============================================================
+
+var DEBUG = !!(typeof process !== 'undefined' && process.env && process.env.QUICO_DEBUG);
+
+
 // ============================================================
 //  Emitter — lightweight event emitter (single shared copy)
 // ============================================================
@@ -124,10 +134,12 @@ function readVarInt(array, offset) {
       array[offset + 7]
     ) >>> 0;
     var full = BigInt(hi) * 4294967296n + BigInt(lo);
-    if (full <= BigInt(Number.MAX_SAFE_INTEGER)) {
-      return { value: Number(full), byteLength: 8 };
-    }
-    return { value: full, byteLength: 8 };
+    // Always return a Number. QUIC fields (lengths, offsets, IDs, limits) never
+    // legitimately exceed 2^53, and a malicious 8-byte value that does will be
+    // rejected by the parsers' bounds checks anyway. Returning a BigInt here
+    // would throw "Cannot mix BigInt and other types" the moment the value is
+    // combined with a Number offset during parsing.
+    return { value: Number(full), byteLength: 8 };
   }
 
   return null;
@@ -164,6 +176,46 @@ function uint8Equal(a, b) {
 }
 
 
+// ============================================================
+//  WebTransport framing helpers (draft-ietf-webtrans-http3 / RFC 9297)
+//
+//  Both client (webtransport.js) and server (h3.js) build the same
+//  byte layouts, so they live here to avoid duplicating the prefix
+//  construction across the stream and datagram send paths.
+// ============================================================
+
+/**
+ * Build a WebTransport stream header: VarInt(streamType) + VarInt(sessionId) [+ data].
+ * streamType is 0x41 for a bidirectional WT stream, 0x54 for a unidirectional one.
+ * The header prefixes the FIRST chunk on a WT stream (or a lone FIN frame); pass
+ * `data` for "header + payload", omit it for a header-only (e.g. FIN) frame.
+ */
+function wt_stream_header(isBidi, sessionId, data) {
+  var typePrefix = writeVarInt(isBidi ? 0x41 : 0x54);
+  var sessionPrefix = writeVarInt(sessionId);
+  var dataLen = (data && data.byteLength) ? data.byteLength : 0;
+  var out = new Uint8Array(typePrefix.length + sessionPrefix.length + dataLen);
+  out.set(typePrefix, 0);
+  out.set(sessionPrefix, typePrefix.length);
+  if (dataLen) out.set(data, typePrefix.length + sessionPrefix.length);
+  return out;
+}
+
+/**
+ * Build a WebTransport datagram payload: VarInt(quarter_stream_id) + data.
+ * The quarter-stream-id is the session's CONNECT stream id divided by 4
+ * (RFC 9297 §2.1). Pass the session stream id; the division is done here.
+ */
+function wt_datagram_payload(sessionStreamId, data) {
+  var prefix = writeVarInt(Math.floor(sessionStreamId / 4));
+  var dataLen = (data && data.byteLength) ? data.byteLength : 0;
+  var out = new Uint8Array(prefix.length + dataLen);
+  out.set(prefix, 0);
+  if (dataLen) out.set(data, prefix.length);
+  return out;
+}
+
+
 // ============================================================
 //  ACK range helpers (flat [from,to, from,to, ...] format)
 // ============================================================
@@ -280,11 +332,14 @@ function ranges_to_ack_frame(flatRanges, ecnStats, ackDelay) {
 
 
 export {
+  DEBUG,
   Emitter,
   writeVarInt,
   readVarInt,
   concatUint8Arrays,
   uint8Equal,
+  wt_stream_header,
+  wt_datagram_payload,
   ack_frame_to_ranges,
   ranges_to_ack_frame
 };