tunnelfetch 1.0.1 → 1.1.1

package/src/client.js

@@ -14,7 +14,7 @@ import { ConfigError, HttpError, TunnelFetchError, codes } from './errors.js';
 import { ByteReader, ByteWriter, UnexpectedEofError, concat, utf8 } from './util/bytes.js';
 import { serializeRequestHead } from './http1/request.js';
 import { bodyFraming, readResponseBody, readResponseHead } from './http1/response.js';
-import { ACCEPT_ENCODING, decodeBody } from './client/decode.js';
+import { acceptEncodingFor, decodeBody } from './client/decode.js';
 import { CookieJar } from './client/cookies.js';
 import { DEFAULT_MAX_REDIRECTS, nextRequest, shouldRedirect } from './client/redirect.js';
 import { ConnectionPool, poolKey } from './pool.js';
@@ -71,8 +71,16 @@ const NULL_BODY_STATUS = new Set([101, 204, 205, 304]);
  *   one across Clients or to persist it.
  * @property {number} [maxRedirects] default 20.
  * @property {number} [maxBodyBytes] enforced from Content-Length before a byte is read.
- * @property {boolean} [decompress] gzip/deflate. Default true. Never `br`; the runtime cannot
- *   decompress it, so it is never advertised either.
+ * @property {boolean} [decompress] gzip/deflate. Default true.
+ * @property {Record<string, import('./client/decode.js').BodyDecoder>} [decoders] extra
+ *   content-codings this client can read, e.g. `{ br: (s) => ... }`. Registering one is what
+ *   makes advertising it honest, so each name is appended to Accept-Encoding — a client that
+ *   asked for a coding it cannot decode would turn every such response into garbage. `br` and
+ *   `zstd` are not built in because the runtime's DecompressionStream has neither and this
+ *   package takes no dependencies; supply your own and the cost, and the supply chain, are
+ *   yours and visible. Measured on the edge: WASM brotli decodes at about 2x native gzip, and
+ *   the wire bytes it saves do not pay that back — see the README. The reason to turn it on is
+ *   matching a browser's Accept-Encoding, not saving CPU.
  * @property {boolean} [keepAlive] default true.
  * @property {boolean} [http2] offer HTTP/2 via ALPN and speak it when the server selects it.
  *   Default true. The goal is ACCESS, not speed — some sites treat HTTP/1.1 as a bot signal — and
@@ -93,7 +101,7 @@ export class Client {
    * @param {ClientOptions} [options]
    */
   constructor(options = {}) {
-    this.options = { ...options };
+    this.options = snapshotOptions(options);
     this.pool = new ConnectionPool(options.pool);
     // HTTP/2 connections are NOT pooled the way h1 is: one connection multiplexes many concurrent
     // streams, so it is not checked out per request. It lives here, keyed exactly like the h1 pool,
@@ -118,6 +126,12 @@ export class Client {
       typeof options.now === 'number' ? { now: () => options.now } : {},
     );
     this._closed = false;
+    // Response bodies that have not finished arriving. `fetch` resolves at the response HEAD, so a
+    // caller holding a Response may still be streaming over a connection this Client owns — and on
+    // HTTP/2 that connection is SHARED and torn down by close(), not checked out of the pool the
+    // way an h1 socket is. Anything that decides when a Client is done needs to see these.
+    /** @type {Set<Promise<void>>} */
+    this._inflight = new Set();
     // Bound so a Client can be handed straight to an SDK expecting a bare function.
     this.fetch = this.fetch.bind(this);
   }
@@ -134,6 +148,19 @@ export class Client {
     return performFetch(this, input, init);
   }
 
+  /**
+   * Resolve once every response body handed out by this Client has finished, one way or another —
+   * read to the end, cancelled, or failed. Deliberately NOT folded into close(): close() is the
+   * forceful teardown, and a teardown that waits on the streams it is tearing down would hang on
+   * any body the caller abandoned. This is for callers that want the graceful order.
+   *
+   * Looping rather than a single Promise.all because a body settling can start another (a redirect
+   * drains its predecessor), and a set sampled once would miss the successor.
+   */
+  async idle() {
+    while (this._inflight.size) await Promise.all([...this._inflight]);
+  }
+
   /** Release every pooled socket and shared HTTP/2 connection. A Client that is finished must be
    *  closed or sockets leak for the isolate's lifetime. */
   async close() {
@@ -156,11 +183,27 @@ export class Client {
 export function createFetch(options = {}) {
   return async function tunnelFetch(input, init) {
     const client = new Client(options);
+    let response;
     try {
-      return await client.fetch(input, init);
-    } finally {
+      response = await client.fetch(input, init);
+    } catch (err) {
       await client.close();
+      throw err;
     }
+    // NOT `finally { await client.close() }`. `fetch` resolves when the response HEAD arrives and
+    // the body is still on the wire, so closing here tore down the connection out from under the
+    // caller — invisibly on HTTP/1.1, where the socket is checked out of the pool and closeAll()
+    // could not reach it, but fatally on HTTP/2, where the connection is shared and close() ends
+    // every stream on it. `res.text()` then failed with HTTP2_PROTOCOL.
+    //
+    // Not awaited, or this would deadlock: the body only drains when the caller reads it, and the
+    // caller cannot read a Response that has not been returned yet.
+    //
+    // A caller who neither reads nor cancels the body would leave the Client open — the same leak
+    // as forgetting to close one — except that the idle deadline aborts a stalled body, which
+    // settles the completion and fires this anyway.
+    void client.idle().then(() => client.close().catch(() => {}));
+    return response;
   };
 }
 
@@ -422,6 +465,96 @@ function registerHttp2(client, key, conn) {
  * @param {unknown} err
  * @returns {boolean}
  */
+/**
+ * Take a private, frozen copy of the security-relevant configuration.
+ *
+ * `{ ...options }` is a SHALLOW copy, so `client.options.trust` stayed the caller's own object: a
+ * caller could flip `revocation` or swap `pins` after construction and the next request would run
+ * under the new policy over a pool of connections verified under the old one. The pool key covers
+ * every field the verifier reads (see trustFingerprint), but a key computed from a mutable object
+ * is only as stable as the object.
+ *
+ * `proxy` is deliberately NOT frozen: openTunnel treats a frozen proxy as already normalised and
+ * skips parseProxy, so freezing a raw object here would bypass its validation entirely. Proxy
+ * identity is part of the pool key on its own, so a changed proxy gets a different key regardless.
+ *
+ * @param {ClientOptions} options
+ * @returns {Readonly<ClientOptions>}
+ */
+function snapshotOptions(options) {
+  const o = { ...options };
+  if (o.trust && typeof o.trust === 'object') o.trust = deepCopyConfig(o.trust);
+  if (o.tls && typeof o.tls === 'object') o.tls = deepCopyConfig(o.tls);
+  if (o.timeouts && typeof o.timeouts === 'object') o.timeouts = Object.freeze({ ...o.timeouts });
+  return Object.freeze(o);
+}
+
+/**
+ * Recursively copy and freeze a configuration value so nothing the caller still holds can change
+ * what this Client trusts.
+ *
+ * A shallow freeze is not enough, and the gap was found in review: `Object.freeze([...anchors])`
+ * gives a frozen ARRAY whose elements are still the caller's `Uint8Array`s, and freezing a typed
+ * array does not freeze its bytes. Writing into the DER of a trust anchor after the first request
+ * therefore changed the certificate material this Client validated against — while the pool key
+ * stayed put, because `anchorDigest` memoises per array object. The same shape applies to `tls`,
+ * where `groups`, `ciphers` and `clientRandom` are all caller-owned mutable buffers.
+ *
+ * Only plain objects, arrays and byte arrays are copied. Everything else is passed through by
+ * REFERENCE, deliberately: `trust.verify` is a function whose identity is what distinguishes one
+ * custom policy from another in the pool key (see `customCounter`), and an AbortSignal or a
+ * CookieJar is a live object, not data. Copying either would break them.
+ *
+ * @template T
+ * @param {T} value
+ * @param {number} [depth]
+ * @returns {T}
+ */
+function deepCopyConfig(value, depth = 0) {
+  // Certificate material is not deeply nested; a bound turns a pathological input into an error
+  // rather than a stack overflow, and nothing legitimate comes close to it.
+  if (depth > 8) {
+    throw new ConfigError(
+      codes.CONFIG_INVALID,
+      'trust or tls configuration nests more than 8 levels deep; refusing to copy it',
+    );
+  }
+  if (ArrayBuffer.isView(value)) {
+    // Not frozen: V8 refuses to freeze a typed array that has elements. Immutability here comes
+    // from the copy being PRIVATE — the caller has no reference to it — rather than from
+    // Object.freeze. Copying the underlying buffer slice rather than the view also detaches it
+    // from any sibling view over the same memory.
+    const Ctor = /** @type {any} */ (value.constructor);
+    return new Ctor(value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength));
+  }
+  if (Array.isArray(value)) {
+    return Object.freeze(value.map((v) => deepCopyConfig(v, depth + 1)));
+  }
+  if (value && typeof value === 'object') {
+    const proto = Object.getPrototypeOf(value);
+    // Only plain objects. A class instance is a live thing with behaviour, and rebuilding it from
+    // its own enumerable properties would produce something that merely looks like it.
+    if (proto !== Object.prototype && proto !== null) return value;
+    const out = {};
+    for (const [k, v] of Object.entries(value)) out[k] = deepCopyConfig(v, depth + 1);
+    return Object.freeze(out);
+  }
+  return value;
+}
+
+/**
+ * Remember a body until it settles. Never rejects: a failed body is still a finished one, and this
+ * set exists to answer "is anything still arriving", not "did it go well".
+ */
+function trackBody(client, completed) {
+  const settled = completed.then(
+    () => {},
+    () => {},
+  );
+  client._inflight.add(settled);
+  settled.then(() => client._inflight.delete(settled));
+}
+
 function serverNeverSawIt(err) {
   if (err instanceof UnexpectedEofError) return err.detail?.got === 0;
   return err instanceof TunnelFetchError && err.code === codes.TLS_TRUNCATED && err.detail?.got === 0;
@@ -493,6 +626,7 @@ async function sendAndReceive(client, conn, current, { key, deadlines, reused })
 
   // The connection goes back to the pool only when the body reaches the end its framing declared.
   // `completed` resolving false means the caller cancelled and the stream position is unknown.
+  trackBody(client, raw.completed);
   raw.completed.then(
     (ok) => {
       deadlines.dispose();
@@ -556,6 +690,7 @@ async function sendAndReceiveH2(client, h2, current, { deadlines }) {
   const raw = head.body;
   // Dispose the per-request deadline once the body is done, however it ends. Unlike h1 there is no
   // pool.release: the connection stays shared and alive for the next stream.
+  trackBody(client, raw.completed);
   raw.completed.then(
     () => deadlines.dispose(),
     () => deadlines.dispose(),
@@ -585,7 +720,7 @@ function buildH2Request(client, current, target) {
 
   if (!headers.has('accept')) headers.set('accept', '*/*');
   if (!headers.has('accept-encoding') && o.decompress !== false) {
-    headers.set('accept-encoding', ACCEPT_ENCODING);
+    headers.set('accept-encoding', acceptEncodingFor(o.decoders));
   }
   if (client.jar) {
     const cookie = client.jar.headerFor(current.url);
@@ -624,7 +759,7 @@ function decodeResponseBody(body, headers, options) {
   if (options.decompress === false) return body;
   const encoding = headers.get('content-encoding');
   if (!encoding) return body;
-  return decodeBody(body, encoding);
+  return decodeBody(body, encoding, options.decoders ?? null);
 }
 
 function buildResponse(headInfo, body, framing, conn) {
@@ -669,7 +804,7 @@ function buildHeaders(client, current, target) {
   if (!headers.has('accept-encoding') && client.options.decompress !== false) {
     // Never advertise br or zstd: the runtime has no DecompressionStream for either, so the
     // reward for asking would be a body we cannot decode.
-    headers.set('accept-encoding', ACCEPT_ENCODING);
+    headers.set('accept-encoding', acceptEncodingFor(client.options.decoders));
   }
   if (client.jar) {
     const cookie = client.jar.headerFor(current.url);

package/src/http2/connection.js

@@ -117,10 +117,25 @@ export class Http2Retryable extends Http2Error {}
  * @property {number} [maxConcurrentStreams] our advertised SETTINGS_MAX_CONCURRENT_STREAMS.
  * @property {number} [maxHeaderTableSize] our advertised SETTINGS_HEADER_TABLE_SIZE.
  * @property {number} [maxHeaderListSize] self-protection cap on a decoded response header list.
+ * @property {number} [maxHeaderBlockBytes] cap on the RAW bytes of one HEADERS+CONTINUATION run,
+ *   before HPACK decoding. Default 262144, matching the decoded cap. This is the bound that stops
+ *   a CONTINUATION flood; `maxHeaderListSize` cannot, because it is only reachable once the whole
+ *   block has been assembled in memory.
  * @property {(err: Error | null) => void} [onClose] called once when the connection dies, so a
  *   registry can drop it.
  */
 
+/**
+ * The declared content-length, or null when absent. A list with conflicting values is refused by
+ * the header layer before this is reached; a malformed single value is treated as absent rather
+ * than as zero, because guessing a length is the failure mode being closed here.
+ */
+function contentLengthOf(headers) {
+  const raw = headers.get?.('content-length') ?? null;
+  if (raw === null) return null;
+  return /^\d+$/.test(raw.trim()) ? Number(raw.trim()) : null;
+}
+
 export class Http2Connection {
   /**
    * @param {import('../tls/connect.js').ByteDuplex | { readable: ReadableStream<Uint8Array>,
@@ -169,7 +184,18 @@ export class Http2Connection {
     // Header-block continuation state: while assembling a HEADERS+CONTINUATION run, no other frame
     // may interleave (RFC 9113 s6.10). Non-null means "the next frame must be CONTINUATION on this
     // stream id".
-    this._continuation = null; // { streamId, fragments: Uint8Array[], endStream, kind }
+    this._continuation = null; // { streamId, fragments: Uint8Array[], bytes, endStream, kind }
+    // A header block arrives as a HEADERS frame plus any number of CONTINUATION frames, and it is
+    // only decodable once the last one lands — so the fragments must be held. `maxHeaderListSize`
+    // bounds the DECODED list and is checked in _completeHeaderBlock, which is to say after the
+    // whole block is already in memory: a peer that simply never sets END_HEADERS never reaches
+    // it. That is the CONTINUATION flood (the class behind CVE-2024-27316 and its siblings), and
+    // it is bounded here instead, on the raw bytes, as they arrive.
+    //
+    // 262144 by default, the same figure as the decoded cap. HPACK does not expand — an indexed
+    // reference makes a small input decode LARGER, never the reverse — so a block whose raw size
+    // exceeds the decoded cap could not have produced an acceptable header list anyway.
+    this._maxHeaderBlockBytes = opts.maxHeaderBlockBytes ?? 262144;
     this._expectFirstSettings = true;
 
     this._fatal = null; // set once; rejects every stream and every future request
@@ -306,6 +332,9 @@ export class Http2Connection {
       /** @type {Uint8Array[]} */
       recvQueue: [],
       recvEnded: false,
+      /** @type {number | null} declared content-length, null when absent */
+      declaredLength: null,
+      receivedLength: 0,
       /** @type {Error | null} */
       bodyError: null,
       /** @type {(() => void) | null} */
@@ -368,7 +397,13 @@ export class Http2Connection {
       this._connSendWindow -= n;
       const end = offset >= body.byteLength;
       await this._write(dataFrame(streamId, slice, end));
-      if (end) stream.localEnded = true;
+      if (end) {
+        stream.localEnded = true;
+        // The remote half may have ended long ago — a server is free to answer before the upload
+        // finishes — in which case nothing else will ever re-check, and the stream stays in the
+        // map for the life of the connection. Every other place that ends a half calls this.
+        this._maybeCloseStream(stream);
+      }
     }
   }
 
@@ -673,12 +708,43 @@ export class Http2Connection {
     if (flags & FLAG.END_HEADERS) {
       this._completeHeaderBlock(streamId, fragment, endStream);
     } else {
-      this._continuation = { streamId, fragments: [fragment.slice()], endStream };
+      this._continuation = {
+        streamId,
+        fragments: [fragment.slice()],
+        bytes: fragment.length,
+        endStream,
+      };
+      // The opening frame alone can exceed the cap when SETTINGS_MAX_FRAME_SIZE is large.
+      if (!this._headerBlockWithinCap()) return;
     }
   }
 
+  /**
+   * Enforce the raw header-block cap, killing the connection when it is passed.
+   * Connection-level rather than stream-level on purpose: the fragments are HPACK input, and
+   * abandoning a partial block would leave the shared decoder desynchronised for every other
+   * stream — which RFC 9113 s4.3 makes a connection error in its own right.
+   * @returns {boolean} true when assembly may continue
+   */
+  _headerBlockWithinCap() {
+    const { bytes, streamId } = this._continuation;
+    if (bytes <= this._maxHeaderBlockBytes) return true;
+    this._continuation = null;
+    this._die(
+      new Http2Error(
+        codes.HTTP2_PROTOCOL,
+        `header block on stream ${streamId} reached ${bytes} bytes across HEADERS and ` +
+          `CONTINUATION frames, over the ${this._maxHeaderBlockBytes} byte cap`,
+        { streamId, bytes, cap: this._maxHeaderBlockBytes },
+      ),
+    );
+    return false;
+  }
+
   _onContinuation(flags, payload) {
     this._continuation.fragments.push(payload.slice());
+    this._continuation.bytes += payload.length;
+    if (!this._headerBlockWithinCap()) return;
     if (flags & FLAG.END_HEADERS) {
       const { streamId, fragments, endStream } = this._continuation;
       this._continuation = null;
@@ -734,6 +800,13 @@ export class Http2Connection {
       return;
     }
     stream.responseReceived = true;
+    // RFC 9113 s8.1.1: a message with a content-length that disagrees with the DATA delivered is
+    // malformed. h1 enforces this through its framing; h2 declares the length in a header and
+    // delimits with END_STREAM, so the two can disagree — and a body that silently differs from
+    // its declared length is exactly the ambiguity this package refuses everywhere else. Held on
+    // the stream and checked as DATA arrives and again at END_STREAM.
+    stream.declaredLength = contentLengthOf(head.headers);
+    stream.receivedLength = 0;
     if (endStream) {
       // No body and no trailers: the completion contract is satisfiable now, exactly like the h1
       // "complete at creation" case, so a caller that never reads the (empty) body still lets the
@@ -777,6 +850,13 @@ export class Http2Connection {
   }
 
   _onData(flags, streamId, payload) {
+    if (streamId === 0) {
+      // RFC 9113 s6.1: DATA is always associated with a stream, and a zero id MUST be a connection
+      // error. Absorbing it silently was letting a peer push bytes with no stream to charge them
+      // to, which is the shape of a smuggling primitive as much as a resource one.
+      this._die(new Http2Error(codes.HTTP2_PROTOCOL, 'DATA frame on stream 0'));
+      return;
+    }
     const stream = this._streams.get(streamId);
     // Flow control is accounted at the connection level for EVERY DATA frame, even one for a
     // stream we have already closed — the peer spent connection window to send it, and not
@@ -824,11 +904,40 @@ export class Http2Connection {
     if (overhead > 0) this._replenishConn(overhead);
     // The stream window was debited by flowLen; credit the overhead back on the stream too.
     if (overhead > 0) this._replenish(stream, overhead);
+    stream.receivedLength += data.byteLength;
+    // Caught on the way past rather than only at END_STREAM, so an over-long body is refused
+    // before the excess is queued for the caller.
+    if (stream.declaredLength !== null && stream.receivedLength > stream.declaredLength) {
+      this._resetStream(
+        stream,
+        H2_ERROR.PROTOCOL_ERROR,
+        new Http2Error(
+          codes.HTTP2_PROTOCOL,
+          `response body is longer than its content-length: ${stream.receivedLength} bytes so ` +
+            `far against a declared ${stream.declaredLength}`,
+          { declared: stream.declaredLength, received: stream.receivedLength },
+        ),
+      );
+      return;
+    }
     if (data.byteLength > 0) {
       stream.recvQueue.push(data.slice());
       this._wakePull(stream);
     }
     if (flags & FLAG.END_STREAM) {
+      if (stream.declaredLength !== null && stream.receivedLength !== stream.declaredLength) {
+        this._resetStream(
+          stream,
+          H2_ERROR.PROTOCOL_ERROR,
+          new Http2Error(
+            codes.HTTP2_PROTOCOL,
+            `response body ended at ${stream.receivedLength} bytes against a declared ` +
+              `content-length of ${stream.declaredLength}`,
+            { declared: stream.declaredLength, received: stream.receivedLength },
+          ),
+        );
+        return;
+      }
       stream.recvEnded = true;
       this._wakePull(stream);
       this._maybeCloseStream(stream);

package/src/pool.js

@@ -52,15 +52,31 @@ export function poolKey({ scheme, hostname, port, proxy, trust, tls }) {
 
 function trustFingerprint(trust) {
   const mode = trust?.mode ?? 'system';
-  if (mode === 'system') return 'system';
-  if (mode === 'none') return 'none';
+  // The fingerprint must cover exactly the fields the VERIFIER reads for this mode — no fewer, or
+  // a connection validated under one policy serves a request under another; no more, or the pool
+  // is split along axes that make no difference. src/trust/index.js states the set per mode by
+  // rejecting every other key outright (`forbidKeys`), so this mirrors those lists.
+  const rev = `rev=${trust?.revocation ?? 'staple'}`;
+  const pins = `pins=${[...(trust?.pins ?? [])].sort().join(',')}`;
+  // Anchors matter even when they are absent: omitting them means the system store, and a policy
+  // pinned against custom anchors is not the policy pinned against the system store.
+  const anchors =
+    trust?.anchors === undefined
+      ? 'anchors=system'
+      : `anchors=${trust.anchors.length}:${anchorDigest(trust.anchors)}`;
+
+  // 'none' forbids anchors/verify/revocation, so pins are the only thing that can vary — and they
+  // DO vary: pin-only trust still enforces them.
+  if (mode === 'none') return `none|${pins}`;
   if (mode === 'custom') {
     // Two different callbacks are two different policies and we cannot compare functions, so a
     // custom policy never shares a connection. Correct, and cheap: custom trust is rare.
+    // ('custom' forbids anchors/pins/revocation — the callback owns the whole decision.)
     return `custom:${customCounter(trust.verify)}`;
   }
-  if (mode === 'pinned') return `pinned:${[...(trust.pins ?? [])].sort().join(',')}`;
-  if (mode === 'anchors') return `anchors:${(trust.anchors ?? []).length}:${anchorDigest(trust.anchors)}`;
+  if (mode === 'system') return `system|${rev}`;
+  if (mode === 'anchors') return `anchors:${(trust.anchors ?? []).length}:${anchorDigest(trust.anchors)}|${rev}`;
+  if (mode === 'pinned') return `pinned|${pins}|${anchors}|${rev}`;
   return `unknown:${mode}`;
 }
 

package/types/client/decode.d.ts

@@ -1,13 +1,31 @@
+/**
+ * The Accept-Encoding to send given the caller's extra decoders.
+ *
+ * Registering a decoder is what makes advertising its coding honest — the two must move together
+ * or the client asks for bytes it cannot read. Order is registration order after the built-ins,
+ * so a caller matching a browser can produce exactly `gzip, deflate, br, zstd`.
+ *
+ * @param {Record<string, BodyDecoder> | null | undefined} decoders
+ * @returns {string}
+ */
+export function acceptEncodingFor(decoders: Record<string, BodyDecoder> | null | undefined): string;
 /**
  * Undo the response's Content-Encoding.
  *
+/**
+ * A caller-supplied content decoder: raw coded bytes in, decoded bytes out. Streaming, so a body
+ * is never fully buffered on this client's behalf.
+ * @typedef {(stream: ReadableStream<Uint8Array>) => ReadableStream<Uint8Array>} BodyDecoder
+ */
+/**
  * @param {ReadableStream<Uint8Array>} stream the raw body
  * @param {string|null|undefined} contentEncoding the Content-Encoding header value; a
  *   comma-separated list names codings in the order the SERVER applied them, so decoding
  *   applies them in reverse.
+ * @param {Record<string, BodyDecoder> | null} [decoders] caller-supplied codings
  * @returns {ReadableStream<Uint8Array>} decoded bytes
  */
-export function decodeBody(stream: ReadableStream<Uint8Array>, contentEncoding: string | null | undefined): ReadableStream<Uint8Array>;
+export function decodeBody(stream: ReadableStream<Uint8Array>, contentEncoding: string | null | undefined, decoders?: Record<string, BodyDecoder> | null): ReadableStream<Uint8Array>;
 /**
  * Extract the charset parameter from a Content-Type value, handling quoting and other
  * parameters: `text/html; boundary=x; charset="ISO-8859-4"` -> 'iso-8859-4'.
@@ -46,9 +64,21 @@ export function charsetFor(contentType: string | null | undefined, bodyPrefix?:
  */
 export function decodeText(bytes: Uint8Array, charset?: string): string;
 /**
- * The exact Accept-Encoding value the request layer must send. The target runtime's
+ * What the request layer advertises with no extra decoders registered. The target runtime's
  * DecompressionStream supports ONLY gzip / deflate / deflate-raw (verified empirically);
  * advertising `br` or `zstd` would invite bytes we can never decode, turning every response
  * from a brotli-preferring CDN into garbage. Keep this list and decodeBody in lockstep.
+ *
+ * It is also exactly what curl sends, which matters because this client presents curl's TLS and
+ * HTTP/2 fingerprints by default: a browser-shaped handshake paired with a curl-shaped
+ * Accept-Encoding is a mismatch a bot detector can read straight off the wire.
  */
 export const ACCEPT_ENCODING: "gzip, deflate";
+/**
+ * Undo the response's Content-Encoding.
+ *
+ * /**
+ * A caller-supplied content decoder: raw coded bytes in, decoded bytes out. Streaming, so a body
+ * is never fully buffered on this client's behalf.
+ */
+export type BodyDecoder = (stream: ReadableStream<Uint8Array>) => ReadableStream<Uint8Array>;