tunnelfetch 1.0.0

package/src/http2/hpack.js

@@ -0,0 +1,420 @@
+// HPACK (RFC 7541): header compression for HTTP/2.
+//
+// HPACK is a hostile-input parser and is treated as one throughout. The dynamic table is a
+// documented denial-of-service surface (RFC 7541 s7.1, s7.3): a peer can try to make a decoder
+// allocate unbounded memory, reference a table slot that does not exist, or blow up a small
+// header block into a huge header list. Every one of those is refused here rather than absorbed:
+//
+//   * the dynamic table is bounded by the size we advertised in SETTINGS (never the peer's wish),
+//     and an index outside the valid range is a typed error naming the index and the bound;
+//   * the decoded header LIST is bounded independently, because a bounded table still permits a
+//     bomb built from references, and a length that disagrees with the buffer is fatal;
+//   * a decoded integer is bounded so a run of continuation bytes cannot spin or overflow;
+//   * Huffman decoding (huffman.js) rejects invalid padding, so a "valid" block with junk tail
+//     bits does not decode to something a stricter peer would read differently.
+//
+// The encoder is deliberately STATELESS: it references the static table and emits everything else
+// as a literal. It never reads its own dynamic table, so its output does not depend on request
+// history and is trivially reproducible — which is what lets the offline suite pin it byte for
+// byte, and what lets it match curl's first-request encoding exactly. It still emits the
+// incremental-indexing opcode where curl does (so the peer's table state, and thus the wire
+// fingerprint, matches), it simply never depends on the entries that creates.
+
+import { Http2Error, LimitError, codes } from '../errors.js';
+import { concat, utf8 } from '../util/bytes.js';
+import { huffmanDecode, huffmanEncode, huffmanEncodedLength } from './huffman.js';
+
+const decoder = new TextDecoder('utf-8', { fatal: false });
+
+/** RFC 7541 Appendix A. Index 0 is a placeholder so table[i] is the RFC's entry i (1-based). */
+const STATIC_TABLE = [
+  ['', ''],
+  [':authority', ''],
+  [':method', 'GET'],
+  [':method', 'POST'],
+  [':path', '/'],
+  [':path', '/index.html'],
+  [':scheme', 'http'],
+  [':scheme', 'https'],
+  [':status', '200'],
+  [':status', '204'],
+  [':status', '206'],
+  [':status', '304'],
+  [':status', '400'],
+  [':status', '404'],
+  [':status', '500'],
+  ['accept-charset', ''],
+  ['accept-encoding', 'gzip, deflate'],
+  ['accept-language', ''],
+  ['accept-ranges', ''],
+  ['accept', ''],
+  ['access-control-allow-origin', ''],
+  ['age', ''],
+  ['allow', ''],
+  ['authorization', ''],
+  ['cache-control', ''],
+  ['content-disposition', ''],
+  ['content-encoding', ''],
+  ['content-language', ''],
+  ['content-length', ''],
+  ['content-location', ''],
+  ['content-range', ''],
+  ['content-type', ''],
+  ['cookie', ''],
+  ['date', ''],
+  ['etag', ''],
+  ['expect', ''],
+  ['expires', ''],
+  ['from', ''],
+  ['host', ''],
+  ['if-match', ''],
+  ['if-modified-since', ''],
+  ['if-none-match', ''],
+  ['if-range', ''],
+  ['if-unmodified-since', ''],
+  ['last-modified', ''],
+  ['link', ''],
+  ['location', ''],
+  ['max-forwards', ''],
+  ['proxy-authenticate', ''],
+  ['proxy-authorization', ''],
+  ['range', ''],
+  ['referer', ''],
+  ['refresh', ''],
+  ['retry-after', ''],
+  ['server', ''],
+  ['set-cookie', ''],
+  ['strict-transport-security', ''],
+  ['transfer-encoding', ''],
+  ['user-agent', ''],
+  ['vary', ''],
+  ['via', ''],
+  ['www-authenticate', ''],
+];
+const STATIC_COUNT = STATIC_TABLE.length - 1; // 61
+
+/** The overhead RFC 7541 s4.1 charges every dynamic entry, on top of its name and value octets. */
+const ENTRY_OVERHEAD = 32;
+
+/** Default SETTINGS_HEADER_TABLE_SIZE (RFC 9113 s6.5.2): the size we advertise, so the size the
+ *  peer's encoder may fill in our decoder. A size update above this is a COMPRESSION_ERROR. */
+export const DEFAULT_HEADER_TABLE_SIZE = 4096;
+
+// A single integer with many continuation bytes is a spin/overflow attempt; 6 bytes past the
+// prefix already covers any length this client will ever see (2^35), so more is refused.
+const MAX_INTEGER_CONTINUATION_BYTES = 6;
+
+// ---------------------------------------------------------------------- integer / string coding
+
+/**
+ * Decode an HPACK variable-length integer (RFC 7541 s5.1) with an `n`-bit prefix.
+ * @param {Uint8Array} buf
+ * @param {number} pos index of the prefix byte
+ * @param {number} n prefix bit width (1..8)
+ * @returns {{ value: number, pos: number }}
+ */
+function decodeInteger(buf, pos, n) {
+  const max = (1 << n) - 1;
+  if (pos >= buf.length) {
+    throw new Http2Error(codes.HTTP2_COMPRESSION, 'truncated HPACK integer prefix');
+  }
+  let value = buf[pos] & max;
+  pos++;
+  if (value < max) return { value, pos };
+  let m = 0;
+  let bytes = 0;
+  for (;;) {
+    if (pos >= buf.length) {
+      throw new Http2Error(codes.HTTP2_COMPRESSION, 'truncated HPACK integer continuation');
+    }
+    if (++bytes > MAX_INTEGER_CONTINUATION_BYTES) {
+      throw new Http2Error(
+        codes.HTTP2_COMPRESSION,
+        `HPACK integer has more than ${MAX_INTEGER_CONTINUATION_BYTES} continuation bytes`,
+      );
+    }
+    const b = buf[pos++];
+    value += (b & 0x7f) * 2 ** m;
+    if (!Number.isSafeInteger(value)) {
+      throw new Http2Error(codes.HTTP2_COMPRESSION, 'HPACK integer overflows a safe integer');
+    }
+    if ((b & 0x80) === 0) break;
+    m += 7;
+  }
+  return { value, pos };
+}
+
+/**
+ * Decode an HPACK string literal (RFC 7541 s5.2): a Huffman flag, a length, then the octets.
+ * @param {Uint8Array} buf
+ * @param {number} pos
+ * @returns {{ bytes: Uint8Array, pos: number }}
+ */
+function decodeString(buf, pos) {
+  if (pos >= buf.length) {
+    throw new Http2Error(codes.HTTP2_COMPRESSION, 'truncated HPACK string');
+  }
+  const huffman = (buf[pos] & 0x80) !== 0;
+  const { value: len, pos: p } = decodeInteger(buf, pos, 7);
+  if (p + len > buf.length) {
+    throw new Http2Error(
+      codes.HTTP2_COMPRESSION,
+      `HPACK string length ${len} runs past the end of the header block`,
+      { length: len, available: buf.length - p },
+    );
+  }
+  const raw = buf.subarray(p, p + len);
+  return { bytes: huffman ? huffmanDecode(raw) : raw.slice(), pos: p + len };
+}
+
+/** Encode an HPACK integer with an `n`-bit prefix; `prefixBits` are the high bits of the first byte. */
+function encodeInteger(value, n, prefixBits) {
+  const max = (1 << n) - 1;
+  if (value < max) return Uint8Array.of(prefixBits | value);
+  const out = [prefixBits | max];
+  let v = value - max;
+  while (v >= 0x80) {
+    out.push((v & 0x7f) | 0x80);
+    v = Math.floor(v / 128);
+  }
+  out.push(v);
+  return Uint8Array.from(out);
+}
+
+/** Encode an HPACK string literal, Huffman-coding it only when that is strictly shorter. */
+function encodeString(bytes) {
+  if (huffmanEncodedLength(bytes) < bytes.length) {
+    const packed = huffmanEncode(bytes);
+    return concat([encodeInteger(packed.length, 7, 0x80), packed]);
+  }
+  return concat([encodeInteger(bytes.length, 7, 0x00), bytes]);
+}
+
+// ---------------------------------------------------------------------- decoder
+
+/**
+ * @typedef {object} HpackDecoderOptions
+ * @property {number} [maxTableSize] the SETTINGS_HEADER_TABLE_SIZE we advertised; the dynamic
+ *   table may not exceed it and a size update above it is fatal. Default 4096.
+ * @property {number} [maxHeaderListSize] fail-closed cap on the decoded header list (sum of
+ *   name+value+32 per field). Default 262144. We do not advertise this to the peer, so it is a
+ *   self-protection bound, not a promise; over it is a LimitError.
+ */
+
+/**
+ * A stateful HPACK decoder. One per connection per direction: the dynamic table is shared state
+ * across every header block on the connection, so a single decoder instance must live as long as
+ * the connection does.
+ */
+export class HpackDecoder {
+  /** @param {HpackDecoderOptions} [opts] */
+  constructor({ maxTableSize = DEFAULT_HEADER_TABLE_SIZE, maxHeaderListSize = 262144 } = {}) {
+    /** @type {Array<[string, string, number]>} name, value, entry-size — newest at index 0 */
+    this._dynamic = [];
+    this._size = 0;
+    this._maxSize = maxTableSize;
+    this._limit = maxTableSize; // the hard ceiling a size update may not exceed
+    this._maxHeaderListSize = maxHeaderListSize;
+  }
+
+  /** Current number of entries, exposed for tests that assert eviction. */
+  get dynamicLength() {
+    return this._dynamic.length;
+  }
+
+  /**
+   * Look up index `i` (RFC 7541 s2.3.3: 1..STATIC_COUNT is static, above that is dynamic,
+   * newest first). Fails closed on 0 and on anything past the end of the dynamic table.
+   * @param {number} i
+   * @returns {[string, string]}
+   */
+  _lookup(i) {
+    if (i === 0) {
+      throw new Http2Error(codes.HTTP2_COMPRESSION, 'HPACK index 0 is not a valid table entry');
+    }
+    if (i <= STATIC_COUNT) return STATIC_TABLE[i];
+    const d = i - STATIC_COUNT - 1;
+    if (d >= this._dynamic.length) {
+      throw new Http2Error(
+        codes.HTTP2_COMPRESSION,
+        `HPACK index ${i} is out of range (static 1..${STATIC_COUNT}, ` +
+          `dynamic holds ${this._dynamic.length})`,
+        { index: i, staticCount: STATIC_COUNT, dynamicLength: this._dynamic.length },
+      );
+    }
+    const [name, value] = this._dynamic[d];
+    return [name, value];
+  }
+
+  /** Insert into the dynamic table, evicting oldest entries until it fits (RFC 7541 s4.4). */
+  _insert(name, value) {
+    const entrySize = name.length + value.length + ENTRY_OVERHEAD;
+    // Adding an entry larger than the whole table empties the table and stores nothing.
+    while (this._size + entrySize > this._maxSize && this._dynamic.length > 0) {
+      this._size -= this._dynamic.pop()[2];
+    }
+    if (entrySize <= this._maxSize) {
+      this._dynamic.unshift([name, value, entrySize]);
+      this._size += entrySize;
+    }
+  }
+
+  /** Apply a dynamic table size update (RFC 7541 s6.3), refusing one above what we advertised. */
+  _resize(newSize) {
+    if (newSize > this._limit) {
+      throw new Http2Error(
+        codes.HTTP2_COMPRESSION,
+        `dynamic table size update to ${newSize} exceeds the advertised limit ${this._limit}`,
+        { requested: newSize, limit: this._limit },
+      );
+    }
+    this._maxSize = newSize;
+    while (this._size > this._maxSize && this._dynamic.length > 0) {
+      this._size -= this._dynamic.pop()[2];
+    }
+  }
+
+  /**
+   * Decode one header block into an ordered list of [name, value] pairs.
+   * @param {Uint8Array} block
+   * @returns {Array<[string, string]>}
+   */
+  decode(block) {
+    const out = [];
+    let listSize = 0;
+    let pos = 0;
+    // A dynamic table size update is only legal before any header field in the block (s4.2).
+    let sawField = false;
+    const add = (name, value) => {
+      listSize += name.length + value.length + ENTRY_OVERHEAD;
+      if (listSize > this._maxHeaderListSize) {
+        throw new LimitError(
+          codes.HTTP2_HEADER,
+          `decoded header list reached ${listSize} bytes, over the ` +
+            `${this._maxHeaderListSize} byte limit`,
+          { limit: this._maxHeaderListSize },
+        );
+      }
+      out.push([name, value]);
+    };
+
+    while (pos < block.length) {
+      const first = block[pos];
+      if (first & 0x80) {
+        // 6.1 Indexed Header Field.
+        const { value: idx, pos: p } = decodeInteger(block, pos, 7);
+        pos = p;
+        const [name, value] = this._lookup(idx);
+        add(name, value);
+        sawField = true;
+      } else if (first & 0x40) {
+        // 6.2.1 Literal with Incremental Indexing.
+        ({ pos } = this._literal(block, pos, 6, out.length, add, (n, v) => this._insert(n, v)));
+        sawField = true;
+      } else if (first & 0x20) {
+        // 6.3 Dynamic Table Size Update.
+        if (sawField) {
+          throw new Http2Error(
+            codes.HTTP2_COMPRESSION,
+            'dynamic table size update must precede every header field in the block (RFC 7541 s4.2)',
+          );
+        }
+        const { value: newSize, pos: p } = decodeInteger(block, pos, 5);
+        pos = p;
+        this._resize(newSize);
+      } else {
+        // 6.2.2 Literal without Indexing (0x00) and 6.2.3 Literal Never Indexed (0x10) — both
+        // 4-bit prefix, neither touches the dynamic table.
+        ({ pos } = this._literal(block, pos, 4, out.length, add, null));
+        sawField = true;
+      }
+    }
+    return out;
+  }
+
+  /**
+   * Shared body of the three literal representations: an optionally indexed name, then a value.
+   * @param {(name: string, value: string) => void} add
+   * @param {null | ((name: string, value: string) => void)} index insert into the dynamic table, or null
+   */
+  _literal(block, pos, prefixBits, _fieldIndex, add, index) {
+    const { value: nameIdx, pos: p1 } = decodeInteger(block, pos, prefixBits);
+    let name;
+    let p = p1;
+    if (nameIdx === 0) {
+      const s = decodeString(block, p);
+      name = decoder.decode(s.bytes);
+      p = s.pos;
+    } else {
+      name = this._lookup(nameIdx)[0];
+    }
+    const vs = decodeString(block, p);
+    const value = decoder.decode(vs.bytes);
+    add(name, value);
+    if (index) index(name, value);
+    return { pos: vs.pos };
+  }
+}
+
+// ---------------------------------------------------------------------- encoder
+
+/**
+ * Find a static-table entry. Returns `{ index }` for a full name+value match, `{ nameIndex }`
+ * for a name-only match, or null. The dynamic table is intentionally not consulted; see the
+ * module header for why a stateless encoder is the right trade here.
+ */
+function staticLookup(name, value) {
+  let nameIndex = 0;
+  for (let i = 1; i <= STATIC_COUNT; i++) {
+    if (STATIC_TABLE[i][0] === name) {
+      if (STATIC_TABLE[i][1] === value) return { index: i };
+      if (nameIndex === 0) nameIndex = i;
+    }
+  }
+  return nameIndex ? { nameIndex } : null;
+}
+
+/**
+ * @typedef {object} HpackField
+ * @property {string} name already lowercased by the caller — HPACK does not case-fold, and
+ *   HTTP/2 forbids uppercase field names on the wire (RFC 9113 s8.2.1)
+ * @property {string} value
+ * @property {'incremental' | 'without' | 'never'} [indexing] how to represent it when it is not a
+ *   full static match. Default 'incremental', which is what curl uses for most fields.
+ */
+
+/**
+ * Encode an ordered list of header fields into one HPACK block. Order is preserved exactly, which
+ * is load-bearing: HTTP/2 requires all pseudo-headers before regular ones, and the pseudo-header
+ * ORDER is part of the client fingerprint the caller is matching.
+ *
+ * @param {HpackField[]} fields
+ * @returns {Uint8Array}
+ */
+export function encodeHeaderBlock(fields) {
+  const parts = [];
+  for (const f of fields) {
+    const name = f.name;
+    const valueBytes = utf8(f.value);
+    const found = staticLookup(name, f.value);
+    if (found && found.index !== undefined) {
+      // A full match is the same one byte for everyone; curl uses it for :method and :scheme.
+      parts.push(encodeInteger(found.index, 7, 0x80));
+      continue;
+    }
+    const indexing = f.indexing ?? 'incremental';
+    // prefix pattern and width per representation (RFC 7541 s6.2).
+    const [prefixBits, prefixWidth] =
+      indexing === 'incremental' ? [0x40, 6] : indexing === 'never' ? [0x10, 4] : [0x00, 4];
+    const nameIndex = found ? found.nameIndex : 0;
+    if (nameIndex) {
+      parts.push(encodeInteger(nameIndex, prefixWidth, prefixBits));
+    } else {
+      parts.push(encodeInteger(0, prefixWidth, prefixBits), encodeString(utf8(name)));
+    }
+    parts.push(encodeString(valueBytes));
+  }
+  return concat(parts);
+}
+
+export { STATIC_TABLE, STATIC_COUNT };

package/src/http2/huffman.js

@@ -0,0 +1,203 @@
+// HPACK Huffman coding (RFC 7541 s5.2 and Appendix B).
+//
+// The code table is the RFC's verbatim — 256 symbols plus EOS at index 256 — and the decoder is
+// deliberately the paranoid kind, because a Huffman string is attacker-controlled input inside a
+// header block. RFC 7541 s5.2 names three decoding errors and this decoder raises every one:
+//
+//   * a decoded EOS symbol (256) is illegal in a string literal,
+//   * padding longer than 7 bits is illegal (that many bits could have started another symbol),
+//   * padding that is not the most-significant bits of EOS — i.e. not all ones — is illegal.
+//
+// A decoder that shrugged any of those off would let two peers disagree on what a header said,
+// which in HPACK is the same class of ambiguity that request smuggling is in HTTP/1.1.
+
+import { Http2Error, codes } from '../errors.js';
+
+// RFC 7541 Appendix B. HUFFMAN_CODE[sym] is the code right-aligned in an integer of HUFFMAN_LEN[sym]
+// bits; index 256 is EOS. Every code fits in 30 bits, so plain numbers suffice (no BigInt).
+const HUFFMAN_CODE = [
+  0x1ff8, 0x7fffd8, 0xfffffe2, 0xfffffe3, 0xfffffe4, 0xfffffe5, 0xfffffe6, 0xfffffe7,
+  0xfffffe8, 0xffffea, 0x3ffffffc, 0xfffffe9, 0xfffffea, 0x3ffffffd, 0xfffffeb, 0xfffffec,
+  0xfffffed, 0xfffffee, 0xfffffef, 0xffffff0, 0xffffff1, 0xffffff2, 0x3ffffffe, 0xffffff3,
+  0xffffff4, 0xffffff5, 0xffffff6, 0xffffff7, 0xffffff8, 0xffffff9, 0xffffffa, 0xffffffb,
+  0x14, 0x3f8, 0x3f9, 0xffa, 0x1ff9, 0x15, 0xf8, 0x7fa,
+  0x3fa, 0x3fb, 0xf9, 0x7fb, 0xfa, 0x16, 0x17, 0x18,
+  0x0, 0x1, 0x2, 0x19, 0x1a, 0x1b, 0x1c, 0x1d,
+  0x1e, 0x1f, 0x5c, 0xfb, 0x7ffc, 0x20, 0xffb, 0x3fc,
+  0x1ffa, 0x21, 0x5d, 0x5e, 0x5f, 0x60, 0x61, 0x62,
+  0x63, 0x64, 0x65, 0x66, 0x67, 0x68, 0x69, 0x6a,
+  0x6b, 0x6c, 0x6d, 0x6e, 0x6f, 0x70, 0x71, 0x72,
+  0xfc, 0x73, 0xfd, 0x1ffb, 0x7fff0, 0x1ffc, 0x3ffc, 0x22,
+  0x7ffd, 0x3, 0x23, 0x4, 0x24, 0x5, 0x25, 0x26,
+  0x27, 0x6, 0x74, 0x75, 0x28, 0x29, 0x2a, 0x7,
+  0x2b, 0x76, 0x2c, 0x8, 0x9, 0x2d, 0x77, 0x78,
+  0x79, 0x7a, 0x7b, 0x7ffe, 0x7fc, 0x3ffd, 0x1ffd, 0xffffffc,
+  0xfffe6, 0x3fffd2, 0xfffe7, 0xfffe8, 0x3fffd3, 0x3fffd4, 0x3fffd5, 0x7fffd9,
+  0x3fffd6, 0x7fffda, 0x7fffdb, 0x7fffdc, 0x7fffdd, 0x7fffde, 0xffffeb, 0x7fffdf,
+  0xffffec, 0xffffed, 0x3fffd7, 0x7fffe0, 0xffffee, 0x7fffe1, 0x7fffe2, 0x7fffe3,
+  0x7fffe4, 0x1fffdc, 0x3fffd8, 0x7fffe5, 0x3fffd9, 0x7fffe6, 0x7fffe7, 0xffffef,
+  0x3fffda, 0x1fffdd, 0xfffe9, 0x3fffdb, 0x3fffdc, 0x7fffe8, 0x7fffe9, 0x1fffde,
+  0x7fffea, 0x3fffdd, 0x3fffde, 0xfffff0, 0x1fffdf, 0x3fffdf, 0x7fffeb, 0x7fffec,
+  0x1fffe0, 0x1fffe1, 0x3fffe0, 0x1fffe2, 0x7fffed, 0x3fffe1, 0x7fffee, 0x7fffef,
+  0xfffea, 0x3fffe2, 0x3fffe3, 0x3fffe4, 0x7ffff0, 0x3fffe5, 0x3fffe6, 0x7ffff1,
+  0x3ffffe0, 0x3ffffe1, 0xfffeb, 0x7fff1, 0x3fffe7, 0x7ffff2, 0x3fffe8, 0x1ffffec,
+  0x3ffffe2, 0x3ffffe3, 0x3ffffe4, 0x7ffffde, 0x7ffffdf, 0x3ffffe5, 0xfffff1, 0x1ffffed,
+  0x7fff2, 0x1fffe3, 0x3ffffe6, 0x7ffffe0, 0x7ffffe1, 0x3ffffe7, 0x7ffffe2, 0xfffff2,
+  0x1fffe4, 0x1fffe5, 0x3ffffe8, 0x3ffffe9, 0xffffffd, 0x7ffffe3, 0x7ffffe4, 0x7ffffe5,
+  0xfffec, 0xfffff3, 0xfffed, 0x1fffe6, 0x3fffe9, 0x1fffe7, 0x1fffe8, 0x7ffff3,
+  0x3fffea, 0x3fffeb, 0x1ffffee, 0x1ffffef, 0xfffff4, 0xfffff5, 0x3ffffea, 0x7ffff4,
+  0x3ffffeb, 0x7ffffe6, 0x3ffffec, 0x3ffffed, 0x7ffffe7, 0x7ffffe8, 0x7ffffe9, 0x7ffffea,
+  0x7ffffeb, 0xffffffe, 0x7ffffec, 0x7ffffed, 0x7ffffee, 0x7ffffef, 0x7fffff0, 0x3ffffee,
+  0x3fffffff,
+];
+
+const HUFFMAN_LEN = [
+  13, 23, 28, 28, 28, 28, 28, 28, 28, 24, 30, 28, 28, 30, 28, 28,
+  28, 28, 28, 28, 28, 28, 30, 28, 28, 28, 28, 28, 28, 28, 28, 28,
+  6, 10, 10, 12, 13, 6, 8, 11, 10, 10, 8, 11, 8, 6, 6, 6,
+  5, 5, 5, 6, 6, 6, 6, 6, 6, 6, 7, 8, 15, 6, 12, 10,
+  13, 6, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7,
+  7, 7, 7, 7, 7, 7, 7, 7, 8, 7, 8, 13, 19, 13, 14, 6,
+  15, 5, 6, 5, 6, 5, 6, 6, 6, 5, 7, 7, 6, 6, 6, 5,
+  6, 7, 6, 5, 5, 6, 7, 7, 7, 7, 7, 15, 11, 14, 13, 28,
+  20, 22, 20, 20, 22, 22, 22, 23, 22, 23, 23, 23, 23, 23, 24, 23,
+  24, 24, 22, 23, 24, 23, 23, 23, 23, 21, 22, 23, 22, 23, 23, 24,
+  22, 21, 20, 22, 22, 23, 23, 21, 23, 22, 22, 24, 21, 22, 23, 23,
+  21, 21, 22, 21, 23, 22, 23, 23, 20, 22, 22, 22, 23, 22, 22, 23,
+  26, 26, 20, 19, 22, 23, 22, 25, 26, 26, 26, 27, 27, 26, 24, 25,
+  19, 21, 26, 27, 27, 26, 27, 24, 21, 21, 26, 26, 28, 27, 27, 27,
+  20, 24, 20, 21, 22, 21, 21, 23, 22, 22, 25, 25, 24, 24, 26, 23,
+  26, 27, 26, 26, 27, 27, 27, 27, 27, 28, 27, 27, 27, 27, 27, 26,
+  30,
+];
+
+const EOS = 256;
+
+/**
+ * Bit trie, flat so decoding allocates nothing. Two child arrays index into themselves; a
+ * non-negative `sym[node]` marks a leaf. Built once from the code table at module load.
+ */
+const trie = buildTrie();
+
+function buildTrie() {
+  const left = [-1]; // child on bit 0
+  const right = [-1]; // child on bit 1
+  const sym = [-1];
+  let next = 1;
+  for (let s = 0; s < HUFFMAN_CODE.length; s++) {
+    const code = HUFFMAN_CODE[s];
+    const len = HUFFMAN_LEN[s];
+    let node = 0;
+    for (let i = len - 1; i >= 0; i--) {
+      const bit = (code >>> i) & 1;
+      const arr = bit ? right : left;
+      if (arr[node] === -1) {
+        arr[node] = next;
+        left[next] = -1;
+        right[next] = -1;
+        sym[next] = -1;
+        next++;
+      }
+      node = arr[node];
+    }
+    sym[node] = s;
+  }
+  return { left, right, sym };
+}
+
+/**
+ * The number of bytes `bytes` would occupy Huffman-encoded, so a caller can choose the shorter
+ * of literal and Huffman exactly the way nghttp2 does (this is what makes curl leave the accept
+ * value un-encoded when its Huffman form is not shorter).
+ * @param {Uint8Array} bytes
+ * @returns {number}
+ */
+export function huffmanEncodedLength(bytes) {
+  let bits = 0;
+  for (let i = 0; i < bytes.length; i++) bits += HUFFMAN_LEN[bytes[i]];
+  return (bits + 7) >> 3;
+}
+
+/**
+ * Huffman-encode octets, padding the final byte with the most-significant bits of EOS (all ones)
+ * per RFC 7541 s5.2.
+ * @param {Uint8Array} bytes
+ * @returns {Uint8Array}
+ */
+export function huffmanEncode(bytes) {
+  const out = new Uint8Array(huffmanEncodedLength(bytes));
+  let o = 0;
+  // Bit accumulator holding `nbits` pending bits (nbits stays < 8 between symbols, so the widest
+  // intermediate is < 8 + 30 = 38 bits — comfortably inside a double, no 32-bit shift, no BigInt).
+  let acc = 0;
+  let nbits = 0;
+  for (let i = 0; i < bytes.length; i++) {
+    const sym = bytes[i];
+    acc = acc * 2 ** HUFFMAN_LEN[sym] + HUFFMAN_CODE[sym];
+    nbits += HUFFMAN_LEN[sym];
+    while (nbits >= 8) {
+      nbits -= 8;
+      out[o++] = Math.floor(acc / 2 ** nbits) & 0xff;
+      acc %= 2 ** nbits; // drop the bits just emitted so acc always holds exactly `nbits` bits
+    }
+  }
+  if (nbits > 0) {
+    // Pad the last byte with EOS's leading bits, which are all ones (RFC 7541 s5.2).
+    const pad = 8 - nbits;
+    out[o++] = (acc * 2 ** pad + (2 ** pad - 1)) & 0xff;
+  }
+  return out;
+}
+
+/**
+ * Huffman-decode octets, failing closed on every error RFC 7541 s5.2 names.
+ * @param {Uint8Array} bytes
+ * @returns {Uint8Array}
+ */
+export function huffmanDecode(bytes) {
+  const { left, right, sym } = trie;
+  const out = [];
+  let node = 0;
+  let depth = 0; // bits consumed in the current, still-incomplete symbol
+  let allOnes = true; // whether every bit of the current partial symbol has been 1
+  for (let i = 0; i < bytes.length; i++) {
+    const byte = bytes[i];
+    for (let b = 7; b >= 0; b--) {
+      const bit = (byte >>> b) & 1;
+      node = bit ? right[node] : left[node];
+      depth++;
+      if (bit === 0) allOnes = false;
+      // The trie is a full prefix code, so a walk can never fall off it; node is always valid.
+      const s = sym[node];
+      if (s !== -1) {
+        if (s === EOS) {
+          throw new Http2Error(
+            codes.HTTP2_COMPRESSION,
+            'Huffman string contains the EOS symbol, which RFC 7541 s5.2 forbids in a literal',
+          );
+        }
+        out.push(s);
+        node = 0;
+        depth = 0;
+        allOnes = true;
+      }
+    }
+  }
+  if (depth > 0) {
+    // Whatever is left must be valid padding: at most 7 bits, and all ones (the EOS prefix).
+    if (depth > 7) {
+      throw new Http2Error(
+        codes.HTTP2_COMPRESSION,
+        `Huffman padding is ${depth} bits, over the 7-bit maximum RFC 7541 s5.2 allows`,
+        { padBits: depth },
+      );
+    }
+    if (!allOnes) {
+      throw new Http2Error(
+        codes.HTTP2_COMPRESSION,
+        'Huffman padding is not the most-significant bits of EOS (a non-one bit appears in it)',
+      );
+    }
+  }
+  return Uint8Array.from(out);
+}

package/src/http2/index.js

@@ -0,0 +1,21 @@
+// HTTP/2 (RFC 9113) over a byte duplex: frame layer, HPACK (RFC 7541), and the multiplexing
+// connection engine. This barrel is the layer's public face; client.js drives it, and the pieces
+// are individually importable for testing.
+//
+// The whole reason this exists is access, not speed: some sites treat HTTP/1.1 as a bot signal and
+// let curl's HTTP/2 through, so the client posture here is matched to curl's on the wire. It is not
+// a performance win on a CPU-billed runtime — HPACK is work HTTP/1.1 does not do. See the README.
+
+export { Http2Connection, Http2Retryable, buildRequestFields } from './connection.js';
+export { HpackDecoder, encodeHeaderBlock } from './hpack.js';
+export { huffmanDecode, huffmanEncode } from './huffman.js';
+export {
+  readFrame,
+  serializeFrame,
+  settingsFrame,
+  windowUpdateFrame,
+  dataFrame,
+  headersFrame,
+  parseSettings,
+} from './frames.js';
+export { ALPN_H2, ALPN_HTTP11 } from './constants.js';

package/src/index.js

@@ -0,0 +1,46 @@
+// tunnelfetch — a fetch-shaped HTTP client that can route through a proxy on runtimes that only
+// expose raw TCP.
+//
+// Why this exists, in one paragraph: on Cloudflare Workers `fetch()` has no proxy option,
+// `node:net`/`node:tls` are built on the same socket API and inherit its limits, and the socket
+// API's own TLS verifies the certificate against the hostname passed to `connect()` — which,
+// inside a CONNECT or SOCKS5 tunnel, is the proxy rather than the origin. It also exposes no peer
+// certificate, so the check cannot be redone afterwards. Measured on the edge: a tunnelled
+// `startTls()` fails closed, which is the right failure but leaves no route at all. The only
+// remaining path is to speak TLS ourselves, which is what this package does.
+//
+// Nothing here installs itself. `install()` is explicit and returns its own undo.
+
+export { Client, createFetch, install } from './client.js';
+export { warmup } from './warmup.js';
+export { ConnectionPool, poolKey } from './pool.js';
+export { openConnection, targetFromUrl, nativeFetchCanServe } from './transport.js';
+export { openTunnel, parseProxy } from './proxy/index.js';
+export { CookieJar } from './client/cookies.js';
+export { verifyChain, rootStoreProvenance } from './trust/index.js';
+
+export {
+  TunnelFetchError,
+  ProxyError,
+  HttpError,
+  TlsError,
+  TlsUnsupportedError,
+  Http2Error,
+  CertificateError,
+  TimeoutError,
+  LimitError,
+  ConfigError,
+  codes,
+} from './errors.js';
+
+import { createFetch } from './client.js';
+
+/**
+ * A ready-made fetch with default options: no proxy, system trust, one connection per call.
+ * Equivalent to httpx.get() versus httpx.Client() — reach for `new Client()` when connection
+ * reuse or a cookie jar matters, which for anything crawl-shaped it does.
+ *
+ * A `connect` function must still be supplied per call (or via `createFetch`) for any request the
+ * platform's own fetch cannot serve; see the README for why that is not defaulted.
+ */
+export const fetch = createFetch();