kinetex 1.3.0 → 1.5.0

package/dist/cjs/core.js

@@ -1,7 +1,7 @@
 // Node.js globals accessed via globalThis for cross-runtime compatibility
 const g = globalThis;
 import { KinetexError, TimeoutError, SizeLimitError } from "./types.js";
-import { concatUint8Arrays, mergeSignals, isAbortError, safeJSONParse } from "./utils.js";
+import { concatUint8Arrays, mergeSignals, isAbortError, safeJSONParse, isSafeURL, isBlockedAddress, randomBytes, } from "./utils.js";
 import { isValidHeaderName, isValidHeaderValue } from "./headers.js";
 // ============================================================================
 // §1  RUNTIME DETECTION
@@ -65,7 +65,26 @@ let _runtimeOverride = null;
  * setRuntime(null);                 // restore detection
  * ```
  */
+/** Every value {@link Runtime} admits, for runtime validation. */
+const KNOWN_RUNTIMES = [
+    "node",
+    "deno",
+    "bun",
+    "browser",
+    "cloudflare-workers",
+    "edge",
+    "unknown",
+];
 export function setRuntime(rt) {
+    // The parameter is typed, but nothing checks it at runtime, and the callers
+    // that matter pass a value read from configuration. A typo — "denno" — was
+    // stored verbatim and became the effective runtime, and every branch in the
+    // library gated on `RUNTIME === "..."` then missed: no fetch, no HTTP/2, no
+    // proxy, no Node-only path, with nothing thrown and nothing logged. An
+    // unrecognised value is a mistake worth reporting at the point it is made.
+    if (rt !== null && !KNOWN_RUNTIMES.includes(rt)) {
+        throw new TypeError(`setRuntime: unknown runtime ${JSON.stringify(rt)}. Expected one of: ${KNOWN_RUNTIMES.join(", ")}`);
+    }
     _runtimeOverride = rt;
 }
 /**
@@ -117,6 +136,14 @@ export class FetchTransport {
     fetchFn;
     strict;
     onDroppedHeader;
+    dispatcher;
+    /** Per-request timeout; omitted means no timeout. */
+    requestTimeoutMs;
+    /**
+     * Permit connections to hosts resolving into private/loopback space.
+     * Default: false.
+     */
+    _allowPrivateNetwork;
     /**
      * @param fetchFnOrOptions - Custom fetch function or options object
      */
@@ -125,12 +152,76 @@ export class FetchTransport {
             this.fetchFn = fetchFnOrOptions;
             this.strict = false;
             this.onDroppedHeader = undefined;
+            this.dispatcher = undefined;
+            this.requestTimeoutMs = undefined;
+            this._allowPrivateNetwork = false;
         }
         else {
             this.fetchFn = fetchFnOrOptions.fetchFn ?? globalThis.fetch;
             this.strict = fetchFnOrOptions.strict ?? false;
             this.onDroppedHeader = fetchFnOrOptions.onDroppedHeader;
+            this.dispatcher = fetchFnOrOptions.dispatcher;
+            this.requestTimeoutMs = fetchFnOrOptions.requestTimeoutMs;
+            this._allowPrivateNetwork = fetchFnOrOptions.allowPrivateNetwork ?? false;
+        }
+    }
+    /**
+     * Refuse a host that resolves into blocked address space.
+     *
+     * The Node transports close DNS rebinding properly: they resolve once and
+     * pin the checked address to the socket (`createPinnedLookup`). `fetch` has no
+     * resolver hook — undici owns the connection and exposes no way to install
+     * one — so the only place to intervene is before the call.
+     *
+     * That closes the case that matters in practice: a name resolving to loopback
+     * or the cloud metadata address is refused outright, which is the vector
+     * behind the classic SSRF-through-DNS attacks. What it cannot close is a
+     * resolver that answers public on this lookup and private on the connect a
+     * moment later. Closing *that* needs a resolver hook `fetch` does not offer,
+     * and claiming otherwise would be worse than saying so.
+     *
+     * The host has already passed the lexical screen by this point, so this is a
+     * second line of defence rather than the first.
+     */
+    async assertReachableHost(url) {
+        if (this._allowPrivateNetwork)
+            return;
+        // A caller-supplied `fetch` owns its own name resolution — its dispatcher,
+        // agent or resolver may answer something the system resolver never would,
+        // and vice versa. Screening the *system* answer for a name this transport
+        // will not resolve is theatre: it cannot observe the connection that
+        // actually happens, so it neither protects the caller nor describes the
+        // risk honestly. The lexical screen still applies to every URL, including
+        // redirects; the resolution half of the defence is the transport's job, and
+        // a custom one is the caller's.
+        if (this.fetchFn !== globalThis.fetch)
+            return;
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            return; // Malformed URLs fail later, with a better message.
+        }
+        if (!parsed.hostname || isIP(parsed.hostname))
+            return;
+        let addresses;
+        try {
+            // `all: true` so every candidate is inspected, matching what the socket
+            // would have been able to reach.
+            addresses = await new Promise((resolve, reject) => {
+                dnsLookup(parsed.hostname, { all: true }, (err, res) => err ? reject(err) : resolve(res));
+            });
+        }
+        catch {
+            // Resolution failed; let the request itself report it rather than
+            // inventing a different failure.
+            return;
         }
+        const safe = filterSafeAddresses(addresses);
+        if (safe.length > 0)
+            return;
+        throw blockedHostError(url, addresses);
     }
     /**
      * Send a request via the native fetch() API.
@@ -143,6 +234,7 @@ export class FetchTransport {
      * @returns Raw response from the server
      */
     async send(req) {
+        await this.assertReachableHost(req.url);
         // Validate and sanitize headers to prevent injection attacks
         const sanitizedHeaders = {};
         for (const [name, value] of Object.entries(req.headers ?? {})) {
@@ -164,6 +256,20 @@ export class FetchTransport {
                 }
                 continue;
             }
+            // `__proto__` is a legal header name — it is made of token characters,
+            // so it passes the check above — and `sanitizedHeaders[name] = value` is a
+            // [[Set]], so it went to the inherited setter, which ignores a primitive.
+            // The header did not overwrite anything: it vanished, and the caller was
+            // never told. Written as a data property, which is what was meant.
+            if (name === "__proto__") {
+                Object.defineProperty(sanitizedHeaders, name, {
+                    value,
+                    writable: true,
+                    enumerable: true,
+                    configurable: true,
+                });
+                continue;
+            }
             sanitizedHeaders[name] = value;
         }
         // Strip the accept-encoding value INJECTED by client.ts so fetch() can add
@@ -195,16 +301,53 @@ export class FetchTransport {
                 init.duplex = "half";
             }
         }
+        // Forwarded only when set: an explicit `dispatcher: undefined` would
+        // otherwise override a globally-installed dispatcher on the runtime.
+        if (this.dispatcher !== undefined) {
+            init.dispatcher = this.dispatcher;
+        }
+        // fetch() has no timeout of its own, so one is enforced here with an
+        // AbortController. Composed with the caller's signal rather than replacing
+        // it, so cancelling the caller still cancels the request.
+        const timeoutMs = this.requestTimeoutMs;
+        const timeoutCtl = timeoutMs === undefined ? undefined : new AbortController();
+        let timedOut = false;
+        const onCallerAbort = () => timeoutCtl?.abort();
+        if (timeoutCtl && req.signal) {
+            if (req.signal.aborted)
+                timeoutCtl.abort();
+            else
+                req.signal.addEventListener("abort", onCallerAbort, { once: true });
+        }
+        const timer = timeoutCtl && timeoutMs !== undefined
+            ? setTimeout(() => {
+                timedOut = true;
+                timeoutCtl.abort();
+            }, timeoutMs)
+            : undefined;
+        const initWithSignal = timeoutCtl && !init.signal ? { ...init, signal: timeoutCtl.signal } : init;
         let response;
         try {
-            response = await this.fetchFn(req.url, init);
+            response = await this.fetchFn(req.url, initWithSignal);
         }
         catch (err) {
+            // Clear the timer on every exit path, and drop the listener we added.
+            if (timer !== undefined)
+                clearTimeout(timer);
+            if (timeoutCtl && req.signal)
+                req.signal.removeEventListener("abort", onCallerAbort);
+            if (timedOut) {
+                throw new KinetexError(`HTTP/1.1 request to ${req.url} timed out after ${timeoutMs}ms`, "ETIMEOUT", { request: req, cause: err });
+            }
             if (isAbortError(err)) {
                 throw new KinetexError("Request was aborted", "EABORT", { request: req, cause: err });
             }
             throw new KinetexError(err instanceof Error ? err.message : "Network request failed", "ENETWORK", { request: req, cause: err });
         }
+        if (timer !== undefined)
+            clearTimeout(timer);
+        if (timeoutCtl && req.signal)
+            req.signal.removeEventListener("abort", onCallerAbort);
         const headers = normalizeHeaders(response.headers);
         const httpVersion = detectHTTPVersion(response, headers);
         // Determine if the runtime already decompressed the body.
@@ -264,6 +407,27 @@ export class NodeHTTP2Transport {
     _requestTimeoutMs;
     /** Cached HTTP/1.1 fallback transport — reuse instead of creating fresh FetchTransport per call */
     _http1Fallback = null;
+    /**
+     * Dedicated keep-alive agent for the legacy `node:https` path.
+     *
+     * This path called `https.request(options)` with no `agent`, so behaviour was
+     * whatever the global agent happened to do — and that default is a moving
+     * target. Node 19 turned `keepAlive` on for `https.globalAgent`, so this path
+     * silently changed from a TCP + TLS handshake per request (Node 18 and
+     * earlier) to pooled connections, with no code change here to explain it.
+     *
+     * An explicit agent makes the behaviour identical on every supported Node
+     * version, bounds the idle-socket pool (the global agent keeps 256 free
+     * sockets, which is a lot to hold open for a legacy fallback), and gives
+     * callers a way to opt out.
+     */
+    /** Whether to permit connections into private/loopback address space. */
+    _allowPrivateNetwork;
+    _http1KeepAlive;
+    _http1MaxSockets;
+    _http1Agent = null;
+    /** HTTP(S) CONNECT proxy, or undefined for a direct connection. */
+    _proxy;
     /**
      * @param options - Session pool and transport configuration
      */
@@ -271,6 +435,10 @@ export class NodeHTTP2Transport {
         this.sessionTTLMs = options.sessionTTLMs ?? 5 * 60_000;
         this.pingIntervalMs = options.pingIntervalMs ?? 30_000;
         this.maxSessions = options.maxSessions ?? 100;
+        this._allowPrivateNetwork = options.allowPrivateNetwork ?? false;
+        this._http1KeepAlive = options.http1KeepAlive ?? true;
+        this._http1MaxSockets = options.http1MaxSockets ?? 16;
+        this._proxy = options.proxy;
         this._strict = options.strict ?? false;
         this._onDroppedHeader = options.onDroppedHeader;
         this._ca = options.ca;
@@ -333,10 +501,32 @@ export class NodeHTTP2Transport {
                     this._evictSession(lruOrigin, lruSession.session);
             }
         }
+        // With a proxy, the tunnel (and, for an https origin, the TLS handshake
+        // to the target) is established *before* http2.connect is called.
+        //
+        // `createConnection` must return a socket synchronously — node:http2 does
+        // not await it, and handing it a Promise yields a session built on a
+        // thenable, which fails deep inside the stream layer with
+        // "stream.pause is not a function". So the async work happens here and
+        // the already-open socket is passed back synchronously.
+        let proxiedSocket = null;
+        if (this._proxy !== undefined) {
+            proxiedSocket = await this._createProxiedSocket(origin, undefined, req);
+        }
         const session = await new Promise((resolve, reject) => {
             const s = http2.connect(origin, {
                 rejectUnauthorized: true,
+                // Resolve-and-check, so a hostname that points at a private address is
+                // refused before anything is dialled. See `createPinnedLookup`.
+                ...(this._allowPrivateNetwork ? {} : { lookup: PINNED_LOOKUP }),
                 ...(this._ca !== undefined ? { ca: this._ca } : {}),
+                // Already connected (and already TLS-wrapped for an https origin),
+                // so node:http2 must use it as-is rather than negotiating again.
+                ...(proxiedSocket !== null
+                    ? {
+                        createConnection: (() => proxiedSocket),
+                    }
+                    : {}),
             });
             // FIX 11: use configurable connect timeout instead of hardcoded 30 000 ms
             // FIX 9: unref() the timer so it does not prevent process exit
@@ -425,6 +615,29 @@ export class NodeHTTP2Transport {
             throw err;
         }
     }
+    /**
+     * Refuse one header on the HTTP/2 path. Strict mode raises `EVALIDATION`
+     * before anything is dialled; non-strict notifies the callback (if any) and
+     * warns, never dropping silently.
+     *
+     * Both the pseudo-header filter and the validation loop go through here so
+     * the two cannot drift apart, which is what let a caller-supplied `:path`
+     * reach the wire while `FetchTransport` dropped the identical header.
+     */
+    _rejectHeader(name, value, reason, request) {
+        if (this._strict) {
+            throw new KinetexError(`Strict mode: header "${name}" ${reason}`, "EVALIDATION", {
+                request,
+            });
+        }
+        if (this._onDroppedHeader) {
+            this._onDroppedHeader(name, value);
+        }
+        else if (typeof console !== "undefined") {
+            console.warn(`[kinetex] Invalid header dropped (HTTP/2): "${name}" — ${reason}. ` +
+                `Pass strictHeaders: true to throw instead.`);
+        }
+    }
     /**
      * Send a request over HTTP/2 with iterative redirect following.
      * Each hop reuses or creates a session for the target origin.
@@ -457,14 +670,69 @@ export class NodeHTTP2Transport {
                 session = existing.session;
                 this.sessionUsage.set(origin, Date.now());
             }
-            // Build headers for this hop
+            // A `FormData` body has to be encoded BEFORE the header block is built:
+            // the multipart boundary is generated during encoding, and a boundary
+            // that cannot reach `content-type` leaves a body the peer cannot parse.
+            // This transport bypasses fetch, so nothing else would have encoded it.
+            // The client's own path never reaches this — it encodes the form and sets
+            // the header together before dispatch — but a caller handing a `FormData`
+            // straight to a transport would otherwise send a body whose boundary no
+            // header ever named.
+            let bodyForHop = currentReq.body;
+            let encodedForHop;
+            if (currentReq.body instanceof FormData) {
+                encodedForHop = await serializeRawBody(currentReq.body);
+                bodyForHop = encodedForHop.bytes;
+                // Request headers are lowercased before they reach the transport, so
+                // a direct key read is the right test here.
+                if (encodedForHop.contentType !== undefined && !currentReq.headers["content-type"]) {
+                    currentReq = {
+                        ...currentReq,
+                        headers: { ...currentReq.headers, "content-type": encodedForHop.contentType },
+                    };
+                }
+            }
+            // Build headers for this hop. The transport owns the request line, so a
+            // caller-supplied pseudo-header (":path", ":authority", ":method",
+            // ":scheme") is refused rather than merged.
+            //
+            // They used to be spread over the transport's own values, which meant a
+            // caller could send a request to a path and a `:authority` that the URL
+            // argument never contained — the URL that `isSafeURL` screened is not
+            // the URL that got dialled. The validation loop below could not catch it
+            // either, because it skipped every name starting with ":", so even
+            // `strict: true` returned 200 for a hijacked `:path`, and
+            // `FetchTransport` dropped the very same header because ":" is not a
+            // token character. Same request, two transports, two answers.
             const h2ReqHeaders = {
                 ":method": currentReq.method,
                 ":path": currentUrl.pathname + currentUrl.search,
                 ":scheme": "https",
                 ":authority": currentUrl.host,
-                ...currentReq.headers,
             };
+            for (const [hName, hValue] of Object.entries(currentReq.headers)) {
+                if (hName.startsWith(":")) {
+                    this._rejectHeader(hName, Array.isArray(hValue) ? hValue.join(", ") : String(hValue), "is not a valid header name", currentReq);
+                    continue;
+                }
+                // `__proto__` is a legal header name — it is made of token characters,
+                // so it passes `isValidHeaderName` — and `h2ReqHeaders[name] = value`
+                // is a [[Set]], so it hit the inherited setter, which ignores a
+                // primitive. The header did not overwrite anything: it vanished, and
+                // neither the callback nor the warning said so. Written as a data
+                // property, which is what `FetchTransport` already does — the two
+                // transports disagreed about whether it is sent at all.
+                if (hName === "__proto__") {
+                    Object.defineProperty(h2ReqHeaders, hName, {
+                        value: hValue,
+                        writable: true,
+                        enumerable: true,
+                        configurable: true,
+                    });
+                    continue;
+                }
+                h2ReqHeaders[hName] = hValue;
+            }
             // Header validation (HTTP/2 control-character check). Runs in BOTH modes:
             // strict throws, non-strict drops with callback/warn — matching the
             // FetchTransport contract. (Previously the whole loop was gated on
@@ -475,35 +743,29 @@ export class NodeHTTP2Transport {
                 if (hName.startsWith(":"))
                     continue;
                 const hStr = Array.isArray(hValue) ? hValue.join(", ") : String(hValue);
-                let hasForbidden = false;
-                for (let ci = 0; ci < hStr.length; ci++) {
-                    const code = hStr.charCodeAt(ci);
-                    if ((code >= 0x00 && code <= 0x08) || (code >= 0x0a && code <= 0x1f) || code === 0x7f) {
-                        hasForbidden = true;
-                        break;
-                    }
-                }
-                if (hasForbidden) {
-                    if (this._strict) {
-                        throw new KinetexError(`Strict mode: header "${hName}" contains forbidden control characters`, "EVALIDATION", { request: currentReq });
-                    }
-                    // FIX (H3): non-strict mode must match FetchTransport behavior —
-                    // notify the callback (if any) and warn, never drop silently.
-                    if (this._onDroppedHeader) {
-                        this._onDroppedHeader(hName, hStr);
-                    }
-                    else if (typeof console !== "undefined") {
-                        console.warn(`[kinetex] Invalid header dropped (HTTP/2): "${hName}" — value contains illegal control characters. ` +
-                            `Pass strictHeaders: true to throw instead.`);
-                    }
+                // The same two checks FetchTransport runs, through the same helpers —
+                // not a hand-rolled control-character scan. The scan checked the value
+                // only, so a header *name* that was not a token ("X Bad", "X\u00e9")
+                // reached `session.request()` and came back as a raw
+                // ERR_INVALID_HTTP2_HEADER / ERR_INVALID_HEADER_VALUE instead of being
+                // dropped in non-strict mode or raising EVALIDATION in strict mode; and
+                // it had no upper bound, so a value above U+00FF — which FetchTransport
+                // refuses because no ByteString header value can carry it — was sent on
+                // this path and dropped on that one. Same request, two transports, two
+                // answers. The comment above this loop claimed they matched; they did
+                // not, and HTTP/2 is the default on Node.
+                const nameOk = isValidHeaderName(hName);
+                const valueOk = isValidHeaderValue(hStr);
+                if (!nameOk || !valueOk) {
+                    this._rejectHeader(hName, hStr, nameOk ? "contains forbidden control characters" : "is not a valid header name", currentReq);
                     delete h2ReqHeaders[hName];
                 }
             }
-            const endStream = !currentReq.body || currentReq.method === "GET" || currentReq.method === "HEAD";
+            const endStream = !bodyForHop || currentReq.method === "GET" || currentReq.method === "HEAD";
             const stream = session.request(h2ReqHeaders, { endStream });
             // FIX 6 (backpressure): attachBodyToH2Stream now awaits drain events
-            if (currentReq.body && !endStream) {
-                attachBodyToH2Stream(stream, currentReq.body).catch((err) => {
+            if (bodyForHop && !endStream) {
+                attachBodyToH2Stream(stream, bodyForHop).catch((err) => {
                     stream.destroy(err instanceof Error ? err : new Error(String(err)));
                 });
             }
@@ -589,8 +851,9 @@ export class NodeHTTP2Transport {
             try {
                 if (raw.body) {
                     const drain = raw.body.getReader();
-                    // eslint-disable-next-line no-constant-condition
-                    while (true) {
+                    // `for(;;)` rather than `while (true)`: same loop, no condition for a
+                    // linter to have an opinion about.
+                    for (;;) {
                         const { done } = await drain.read();
                         if (done)
                             break;
@@ -603,14 +866,38 @@ export class NodeHTTP2Transport {
             }
             const location = raw.headers["location"];
             let nextHref;
+            let nextProtocol;
             try {
-                nextHref = new URL(location, currentReq.url).href;
+                const nextUrl = new URL(location, currentReq.url);
+                nextHref = nextUrl.href;
+                nextProtocol = nextUrl.protocol.toLowerCase();
             }
             catch {
                 throw new KinetexError(`Invalid redirect Location: ${location}`, "ENETWORK", {
                     request: req,
                 });
             }
+            // The same two gates the client's manual redirect follower applies, for
+            // the same reasons. They were absent here, and this loop is the *only*
+            // follower on this path whenever the request arrives without
+            // `redirect: "manual"` — which is every direct use of this transport.
+            //
+            //  - Protocol. This transport hardcodes `:scheme: "https"` and speaks
+            //    HTTP/2, so a cleartext target cannot be dialled at all: the hop
+            //    failed as `ERR_HTTP2_ERROR: Protocol error` with nothing to connect
+            //    it to the target. A downgrade was therefore possible by accident
+            //    rather than refused on purpose, and an `httpsOnly` client could not
+            //    tell the difference.
+            //  - SSRF. The hop origin is dialled directly by `http2.connect` below,
+            //    with no `isSafeURL` screen — the client's follower screens every hop
+            //    precisely because "a redirect target never went through that
+            //    check". A 302 to `http://127.0.0.1:9/` opened the socket.
+            if (nextProtocol !== "https:") {
+                throw new KinetexError(`HTTP/2 redirect to a non-HTTPS target blocked: ${nextProtocol}//…`, "EVALIDATION", { request: req });
+            }
+            if (!isSafeURL(nextHref)) {
+                throw new KinetexError(`Unsafe redirect target blocked: ${nextHref.replace(/:\/\/[^/@]*@/, "://…@")}`, "EVALIDATION", { request: req });
+            }
             // RFC 7231 §6.4: 301/302/303 → downgrade to GET; 307/308 → preserve method
             const nextMethod = raw.status === 301 || raw.status === 302 || raw.status === 303 ? "GET" : currentReq.method;
             const nextBody = nextMethod === "GET" || nextMethod === "HEAD" ? null : currentReq.body;
@@ -634,6 +921,10 @@ export class NodeHTTP2Transport {
                 const opts = {
                     fetchFn: globalThis.fetch,
                     strict: this._strict,
+                    // The h2 path enforces `_requestTimeoutMs` itself; without passing it
+                    // down, `new NodeHTTP2Transport({ requestTimeoutMs: 500 })` hung for
+                    // the full response time on any non-https URL or HTTP/1.1 request.
+                    requestTimeoutMs: this._requestTimeoutMs,
                 };
                 if (this._onDroppedHeader !== undefined)
                     opts.onDroppedHeader = this._onDroppedHeader;
@@ -649,12 +940,35 @@ export class NodeHTTP2Transport {
     async _sendHTTP1Legacy(req) {
         const https = await import("node:https");
         const url = new URL(req.url);
+        // A `FormData` body is encoded before the request options are built, for
+        // the same reason as on the HTTP/2 path: the multipart boundary is
+        // generated during encoding, and this transport bypasses fetch, so
+        // nothing else would encode it or announce the boundary. A caller-set
+        // `content-type` wins — they may have encoded the form themselves.
+        let legacyReq = req;
+        if (req.body instanceof FormData) {
+            const encoded = await serializeRawBody(req.body);
+            legacyReq = { ...req, body: encoded.bytes };
+            if (encoded.contentType !== undefined && !legacyReq.headers["content-type"]) {
+                legacyReq = {
+                    ...legacyReq,
+                    headers: { ...legacyReq.headers, "content-type": encoded.contentType },
+                };
+            }
+        }
         const options = {
             hostname: url.hostname,
             port: url.port || "443",
             path: url.pathname + url.search,
-            method: req.method,
-            headers: req.headers,
+            method: legacyReq.method,
+            headers: legacyReq.headers,
+            ...(this._http1KeepAlive ? { agent: this._getHttp1Agent(https) } : {}),
+            // `ca` was accepted by the transport but never reached this path, so a
+            // private or self-signed peer could not be reached without disabling
+            // verification process-wide.
+            ...(this._ca !== undefined ? { ca: this._ca } : {}),
+            // Same reason as the HTTP/2 path above.
+            ...(this._allowPrivateNetwork ? {} : { lookup: PINNED_LOOKUP }),
         };
         return new Promise((resolve, reject) => {
             const httpReq = https.request(options, (httpRes) => {
@@ -676,7 +990,13 @@ export class NodeHTTP2Transport {
                 });
             });
             httpReq.once("error", (err) => {
-                reject(new KinetexError(err.message, "ENETWORK", { request: req, cause: err }));
+                // An error raised while building the connection (a refused proxy
+                // tunnel, a TLS failure) is already a KinetexError carrying a
+                // meaningful code. Re-wrapping it as ENETWORK threw that away, so a
+                // 403 from the proxy and a DNS failure became indistinguishable.
+                reject(err instanceof KinetexError
+                    ? err
+                    : new KinetexError(err.message, "ENETWORK", { request: req, cause: err }));
             });
             // Remove the abort listener once the request settles so the httpReq
             // reference doesn't leak beyond the request lifetime.
@@ -689,13 +1009,76 @@ export class NodeHTTP2Transport {
             httpReq.once("close", cleanup);
             httpReq.once("error", cleanup);
             if (req.body && req.method !== "GET" && req.method !== "HEAD") {
-                pipeBodyToNodeReq(httpReq, req.body).catch(reject);
+                pipeBodyToNodeReq(httpReq, legacyReq.body).catch(reject);
             }
             else {
                 httpReq.end();
             }
         });
     }
+    /**
+     * Lazily create the keep-alive agent used by the legacy HTTP/1.1 path.
+     *
+     * @param https - The already-imported `node:https` module.
+     * @returns The shared agent, reused across requests.
+     */
+    _getHttp1Agent(https) {
+        if (!this._http1Agent) {
+            this._http1Agent = new https.Agent({
+                keepAlive: true,
+                maxSockets: this._http1MaxSockets,
+                maxFreeSockets: this._http1MaxSockets,
+                // A private/self-signed peer must be trusted before the socket enters
+                // the pool, otherwise the agent only fails later on reuse.
+                ...(this._ca !== undefined ? { ca: this._ca } : {}),
+            });
+            if (this._proxy !== undefined) {
+                // Assigned to the INSTANCE, not passed in the agent options:
+                // `new Agent({ createConnection })` only copies it into
+                // `agent.options`, while `Agent.prototype.createSocket` calls
+                // `this.createConnection(...)` — the prototype method. Passing it in
+                // the options is silently ignored and the agent dials the origin
+                // directly, bypassing the proxy entirely.
+                //
+                // `createSocket` does:
+                //     const s = this.createConnection(options, oncreate);
+                //     if (s) oncreate(null, s);
+                // so returning a Promise would be truthy and the agent would adopt
+                // the thenable as a socket. The callback form is the supported way to
+                // connect asynchronously: this returns undefined and reports the
+                // tunneled socket through `oncreate`.
+                //
+                // The tunnel is already TLS-wrapped for an https origin, which is
+                // exactly what https.Agent expects createConnection to return.
+                this._http1Agent.createConnection = ((opts, oncreate) => {
+                    void this._createProxiedSocket(`https://${String(opts.host ?? opts.servername ?? "localhost")}:${String(opts.port ?? 443)}`, undefined, undefined).then((socket) => oncreate(null, socket), (err) => oncreate(err));
+                    return undefined;
+                });
+            }
+        }
+        return this._http1Agent;
+    }
+    /**
+     * Open a socket to `origin` through the configured proxy.
+     *
+     * The returned socket is fully established — tunneled, and TLS-wrapped when
+     * the origin is `https:` — so it can be handed to a transport that requires
+     * its connection synchronously.
+     *
+     * @param origin - Target origin, e.g. `https://api.example.com:443`.
+     * @param req - Originating request, attached to any thrown error.
+     * @returns A socket connected to the target through the proxy.
+     */
+    async _createProxiedSocket(origin, _tlsOpts, req) {
+        const { connectThroughProxy } = await import("./proxy.js");
+        const target = new URL(origin);
+        return await connectThroughProxy(this._proxy, target, {
+            ...(this._ca !== undefined ? { ca: this._ca } : {}),
+            connectTimeoutMs: this._connectTimeoutMs,
+            ...(req?.signal != null ? { signal: req.signal } : {}),
+            ...(req !== undefined ? { request: req } : {}),
+        });
+    }
     /** @internal Evict one session and its associated ping timer. */
     _evictSession(origin, session) {
         const timer = this.pingTimers.get(origin);
@@ -721,6 +1104,10 @@ export class NodeHTTP2Transport {
             this._evictSession(origin, session);
         }
         this.sessions.clear();
+        // Drain the legacy HTTP/1.1 keep-alive pool too, so a destroyed transport
+        // leaves no idle sockets behind holding the event loop open.
+        this._http1Agent?.destroy();
+        this._http1Agent = null;
     }
 }
 // ============================================================================
@@ -743,14 +1130,23 @@ export function createTransport(fetchFn, preferHTTP2 = true, sessionOptions, tra
     // "Custom fetch implementation" behavior holds on every runtime.
     // Use NodeHTTP2Transport for Node.js when HTTP/2 is preferred and no custom
     // fetch is given. Falls back to FetchTransport otherwise.
-    if (IS_NODE && preferHTTP2 && fetchFn) {
+    // A dispatcher belongs to the fetch implementation, exactly like a custom
+    // fetch does — NodeHTTP2Transport speaks `node:http2` and has no notion of
+    // one. So it forces the same fallback rather than being silently dropped.
+    const needsFetchTransport = fetchFn !== undefined || transportOptions?.dispatcher !== undefined;
+    if (IS_NODE && preferHTTP2 && needsFetchTransport) {
         if (!isProductionEnvironment()) {
-            console.warn('[kinetex] httpVersion: "HTTP/2" is ignored when a custom `fetch` is configured — ' +
-                "NodeHTTP2Transport cannot use a custom fetch, so the request goes through " +
-                "FetchTransport (HTTP/1.1 semantics). Drop the `fetch` option to use HTTP/2.");
+            console.warn(fetchFn !== undefined
+                ? '[kinetex] httpVersion: "HTTP/2" is ignored when a custom `fetch` is configured — ' +
+                    "NodeHTTP2Transport cannot use a custom fetch, so the request goes through " +
+                    "FetchTransport (HTTP/1.1 semantics). Drop the `fetch` option to use HTTP/2."
+                : '[kinetex] httpVersion: "HTTP/2" is ignored when a `dispatcher` is configured — ' +
+                    "NodeHTTP2Transport talks to node:http2 directly and cannot use a fetch " +
+                    "dispatcher, so the request goes through FetchTransport (HTTP/1.1 semantics). " +
+                    "Drop the `dispatcher` option to use HTTP/2.");
         }
     }
-    if (IS_NODE && preferHTTP2 && !fetchFn) {
+    if (IS_NODE && preferHTTP2 && !needsFetchTransport) {
         return new NodeHTTP2Transport({
             ...(sessionOptions?.sessionTTLMs !== undefined
                 ? { sessionTTLMs: sessionOptions.sessionTTLMs }
@@ -758,6 +1154,17 @@ export function createTransport(fetchFn, preferHTTP2 = true, sessionOptions, tra
             ...(sessionOptions?.pingIntervalMs !== undefined
                 ? { pingIntervalMs: sessionOptions.pingIntervalMs }
                 : {}),
+            // maxSessions was a documented transport option but was never forwarded
+            // here, so the LRU cap was unreachable and the pool grew unbounded.
+            ...(sessionOptions?.maxSessions !== undefined
+                ? { maxSessions: sessionOptions.maxSessions }
+                : {}),
+            ...(sessionOptions?.http1KeepAlive !== undefined
+                ? { http1KeepAlive: sessionOptions.http1KeepAlive }
+                : {}),
+            ...(sessionOptions?.http1MaxSockets !== undefined
+                ? { http1MaxSockets: sessionOptions.http1MaxSockets }
+                : {}),
             ...(sessionOptions?.connectTimeoutMs !== undefined
                 ? { connectTimeoutMs: sessionOptions.connectTimeoutMs }
                 : {}),
@@ -765,9 +1172,14 @@ export function createTransport(fetchFn, preferHTTP2 = true, sessionOptions, tra
                 ? { requestTimeoutMs: sessionOptions.requestTimeoutMs }
                 : {}),
             ...(transportOptions?.strict !== undefined ? { strict: transportOptions.strict } : {}),
+            ...(transportOptions?.allowPrivateNetwork !== undefined
+                ? { allowPrivateNetwork: transportOptions.allowPrivateNetwork }
+                : {}),
             ...(transportOptions?.onDroppedHeader !== undefined
                 ? { onDroppedHeader: transportOptions.onDroppedHeader }
                 : {}),
+            ...(transportOptions?.ca !== undefined ? { ca: transportOptions.ca } : {}),
+            ...(transportOptions?.proxy !== undefined ? { proxy: transportOptions.proxy } : {}),
         });
     }
     return new FetchTransport({
@@ -776,6 +1188,15 @@ export function createTransport(fetchFn, preferHTTP2 = true, sessionOptions, tra
         ...(transportOptions?.onDroppedHeader !== undefined
             ? { onDroppedHeader: transportOptions.onDroppedHeader }
             : {}),
+        ...(transportOptions?.dispatcher !== undefined
+            ? { dispatcher: transportOptions.dispatcher }
+            : {}),
+        // Reaches the pre-flight DNS screen in FetchTransport. It was accepted by
+        // createTransport and then dropped, so every fetch-based runtime silently
+        // had the screen off.
+        ...(transportOptions?.allowPrivateNetwork !== undefined
+            ? { allowPrivateNetwork: transportOptions.allowPrivateNetwork }
+            : {}),
     });
 }
 // ============================================================================
@@ -877,11 +1298,19 @@ export async function readRawBody(stream, maxBytes, _url, signal) {
             const { done, value } = readResult;
             if (done)
                 break;
+            // Same policy as the readers in response.ts, reached through the same
+            // helper. The error class stays this entry point's own: `SizeLimitError`
+            // is a `KinetexError` carrying code `ESIZELIMIT`, where the response
+            // readers raise `ResponseSizeLimitError`, which is a bare `Error` with the
+            // same code. Both are public and documented, and merging them would be a
+            // breaking change, so the factory is passed in rather than shared.
             if (maxBytes > 0) {
-                const newTotal = total + value.byteLength;
-                if (newTotal > maxBytes) {
+                try {
+                    limitAction(value, total, { maxBytes }, "throw", (n, max) => new SizeLimitError(n, max));
+                }
+                catch (err) {
                     await reader.cancel("size limit exceeded");
-                    throw new SizeLimitError(newTotal, maxBytes);
+                    throw err;
                 }
             }
             chunks.push(value);
@@ -937,6 +1366,19 @@ export function parseBody(raw, contentType, customParser, onParseFailure, header
             if (result.success && result.value !== undefined) {
                 parseResult = result.value;
             }
+            else if (!result.success) {
+                // `safeJSONParse` refuses a payload for a reason it can name — a
+                // depth, a length, a key count, a prototype-pollution key — and that
+                // reason was dropped on the floor, so the caller was told "JSON parse
+                // failed" for a body that is perfectly valid JSON and merely larger
+                // than the limits this function chose. A response that quietly changes
+                // from parsed to raw text is worth one specific sentence about which
+                // limit it crossed, and the code is on the error so a handler can
+                // branch on it.
+                const failure = new Error(`JSON body rejected: ${result.message ?? "parse failed"} — falling back to raw text`);
+                Object.assign(failure, { code: result.error ?? "EPARSE" });
+                parseError = failure;
+            }
         }
         catch (e) {
             parseError = e instanceof Error ? e : new Error(String(e));
@@ -964,7 +1406,98 @@ export function parseBody(raw, contentType, customParser, onParseFailure, header
 // §9  UTILITIES
 // ============================================================================
 // FIX 12: normalizeHeaders centralised in utils.ts.
+import { lookup as dnsLookup } from "node:dns";
+import { isIP } from "node:net";
+/** One instance, shared: it holds no per-request state. */
+const PINNED_LOOKUP = createPinnedLookup();
+/**
+ * A `lookup` for node:http and node:http2 that closes the DNS-rebinding gap.
+ *
+ * `isSafeURL` reads the hostname the caller wrote. The socket, however, is
+ * dialled at whatever that hostname *resolves to*, and nothing between the two
+ * points re-checked the answer — so a name that resolves to a public address on
+ * the first lookup and to `127.0.0.1` on the second reached a private service.
+ * That is DNS rebinding, and it needs an attacker-controlled resolver, which is
+ * an ordinary capability for whoever controls the domain being requested.
+ *
+ * Resolving here and pinning the result closes it for the connection that
+ * follows: every address the resolver returns is checked against the same
+ * blocklist `isSafeURL` applies to a literal, and only a checked address is
+ * handed back for the dial. A name that resolves solely to private space fails
+ * instead of connecting.
+ *
+ * The alternative — checking the hostname again after connecting — is too late:
+ * the request is already on the wire.
+ *
+ * `dns.lookup` (not `resolve`) is used deliberately: it honours `/etc/hosts`,
+ * the resolver search list and `dns.setDefaultResultOrder`, so a host pinned in
+ * the system file resolves the way it would have without this, and the address
+ * handed back is the one the socket would have reached anyway.
+ */
+/**
+ * Drop every resolved address that falls in a blocked range.
+ *
+ * Exported separately from `createPinnedLookup` so the decision can be tested
+ * against addresses a resolver would have to be trusted to produce: a name
+ * that answers with a public address and a private one is the rebinding case,
+ * and it cannot be arranged offline through a real resolver.
+ */
+export function filterSafeAddresses(addresses) {
+    return addresses.filter((a) => a.family !== 0 && !isBlockedAddress(a.address));
+}
+/**
+ * The refusal a host whose every resolved address is blocked earns.
+ *
+ * Split out from {@link FetchTransport} so the message and code can be
+ * asserted without arranging a resolver that answers with a blocked address.
+ */
+export function blockedHostError(url, addresses) {
+    return new KinetexError(`URL "${url}" resolved only to blocked addresses (${addresses.map((a) => a.address).join(", ") || "none"})`, "EBLOCKEDHOST");
+}
+export function createPinnedLookup() {
+    return (hostname, options, callback) => {
+        // Node's declared callback takes an address even on failure, and it ignores
+        // it — callers branch on `err` first. Node's own resolvers call back with
+        // the error alone, so this matches them rather than inventing a bogus
+        // address.
+        const fail = (err) => {
+            callback(err);
+        };
+        // `all: true` so every candidate is inspected. Node sets it when
+        // `autoSelectFamily` is on (the default since Node 20), in which case the
+        // callback expects an array; when it is not, a single address is expected.
+        const wantsAll = options.all === true;
+        // Typed as `LookupAllOptions` so TypeScript selects the overload that
+        // yields `LookupAddress[]`. Left as a plain object literal it picks the
+        // single-address overload, and `.filter` below does not exist on a string.
+        const resolved = { ...options, all: true };
+        dnsLookup(hostname, resolved, (err, addresses) => {
+            if (err) {
+                fail(err);
+                return;
+            }
+            const safe = filterSafeAddresses(addresses ?? []);
+            if (safe.length === 0) {
+                // Report it as a name-resolution failure rather than a connection
+                // error: nothing was dialled, and the distinction matters to a caller
+                // deciding whether to retry or to fail over.
+                const blocked = (addresses ?? []).map((a) => a.address).join(", ") || "no addresses";
+                const e = new Error(`Refusing to connect to ${hostname}: it resolves only to a blocked address (${blocked})`);
+                e.code = "EBLOCKEDHOST";
+                fail(e);
+                return;
+            }
+            if (wantsAll) {
+                callback(null, safe);
+                return;
+            }
+            const first = safe[0];
+            callback(null, first.address, first.family);
+        });
+    };
+}
 import { normalizeHeaders as _normalizeHeaders } from "./utils.js";
+import { limitAction } from "./response.js";
 /**
  * Normalize a Headers object to a plain record.
  *
@@ -984,29 +1517,52 @@ export function normalizeHeaders(headers) {
  * @param _headers - Parsed response headers (reserved)
  * @returns Detected HTTP version
  */
+/**
+ * Translate a runtime-reported protocol string into the {@link HTTPVersion}
+ * union, or return null when it says nothing this library can act on.
+ *
+ * Accepts the spellings Deno and Bun actually use ("2", "2.0", "1", "1.0",
+ * "1.1") plus the union's own members, case- and whitespace-insensitively, so a
+ * peer cannot widen the field to a string by adding a prefix.
+ */
+function normalizeHTTPVersion(raw) {
+    const v = raw.trim().toLowerCase();
+    if (v === "2" || v === "2.0" || v === "h2" || v === "http/2" || v === "http/2.0")
+        return "HTTP/2";
+    if (v === "1" || v === "1.0" || v === "http/1" || v === "http/1.0")
+        return "HTTP/1.0";
+    if (v === "1.1" || v === "http/1.1")
+        return "HTTP/1.1";
+    return null;
+}
 function detectHTTPVersion(response, _headers) {
-    // Deno exposes response.type or we can infer from headers
-    // Runtime-specific property access requires type assertion
+    // Deno and Bun both expose `httpVersion` on the Response, and both spell it
+    // their own way: Deno answers "2.0", Bun answers "1.1" and "2". The Deno arm
+    // translated its values; the Bun arm returned whatever it was given, so a
+    // plain HTTP/1.1 response on Bun reported the string "1.1" — a value outside
+    // the `HTTPVersion` union, reaching every caller of `res.httpVersion` through
+    // a `[[typed]]` lie. A consumer switching on "HTTP/1.1" silently fell through,
+    // and on a runtime the library does not run in CI the type checker is the only
+    // thing that would have said so. Both arms now go through one translation, and
+    // anything unrecognised falls through to the evidence below rather than being
+    // reported as a protocol.
     const denoResponse = response;
-    if (denoResponse.httpVersion === "2.0" || denoResponse.httpVersion === "2") {
-        return "HTTP/2";
-    }
-    // Bun exposes httpVersion as a property
-    const bunResponse = response;
-    if (bunResponse.httpVersion) {
-        return bunResponse.httpVersion;
+    const runtimeVersion = denoResponse.httpVersion;
+    if (typeof runtimeVersion === "string") {
+        const normalized = normalizeHTTPVersion(runtimeVersion);
+        if (normalized)
+            return normalized;
     }
-    // HTTP/3 (QUIC) detection via Alt-Svc header.
+    // Server capability advertisement.
     // Servers that support HTTP/3 advertise: Alt-Svc: h3="...", h3-29="..."
-    // We detect the advertisement here and update accordingly.
+    //
+    // kinetex does not speak HTTP/3, and no runtime it targets has a stable
+    // HTTP/3 client, so an h3 advertisement is deliberately NOT reported as
+    // HTTP/3: the response in hand was served over HTTP/2, and saying otherwise
+    // would misreport the protocol actually used. A runtime that ever does
+    // negotiate h3 itself reaches the same answer below rather than claiming a
+    // version the transport cannot produce.
     const altSvc = response.headers.get("alt-svc");
-    // Check for active HTTP/3 negotiation (runtime-specific property)
-    const h3Response = response;
-    if (h3Response.httpVersion === "3" ||
-        h3Response.httpVersion === "3.0" ||
-        h3Response.protocol === "h3") {
-        return "HTTP/3";
-    }
     // Alt-Svc advertisement: infer HTTP version from the advertised protocols.
     // - h3 (QUIC) means the server supports HTTP/3
     // - h2 means the server supports HTTP/2
@@ -1154,7 +1710,7 @@ async function attachBodyToH2Stream(stream, body) {
         // The raw Node transports bypass fetch, so bodies fetch would normally
         // serialize (URLSearchParams, Blob) must be encoded here. Skipping them
         // silently sent an empty body to the server.
-        const bytes = await serializeRawBody(body);
+        const { bytes } = await serializeRawBody(body);
         stream.end(bytes);
     }
 }
@@ -1188,7 +1744,7 @@ async function pipeBodyToNodeReq(req, body) {
         // The raw Node transports bypass fetch, so bodies fetch would normally
         // serialize (URLSearchParams, Blob) must be encoded here. Skipping them
         // silently sent an empty body to the server.
-        const bytes = await serializeRawBody(body);
+        const { bytes } = await serializeRawBody(body);
         req.end(bytes);
     }
 }
@@ -1197,16 +1753,80 @@ async function pipeBodyToNodeReq(req, body) {
  * Node HTTP/1.1 and HTTP/2 transports do not silently send an empty payload.
  *
  * @param body - Request body that is not a stream, byte array, or string
- * @returns The encoded bytes to write (empty for unsupported types)
+ * @returns The encoded bytes to write, plus a content type to announce when the
+ *          encoding generated one (empty bytes for unsupported types)
  */
 async function serializeRawBody(body) {
     if (typeof URLSearchParams !== "undefined" && body instanceof URLSearchParams) {
-        return new TextEncoder().encode(body.toString());
+        return { bytes: new TextEncoder().encode(body.toString()) };
     }
     if (typeof Blob !== "undefined" && body instanceof Blob) {
-        return new Uint8Array(await body.arrayBuffer());
+        return { bytes: new Uint8Array(await body.arrayBuffer()) };
+    }
+    if (typeof FormData !== "undefined" && body instanceof FormData) {
+        const { bytes, boundary } = await encodeMultipart(body);
+        return { bytes, contentType: `multipart/form-data; boundary=${boundary}` };
+    }
+    return { bytes: new Uint8Array(0) };
+}
+/**
+ * Escape a multipart field name or filename for a `Content-Disposition`
+ * parameter. RFC 7578 §5.1 percent-encodes CR, LF and a double quote; a bare
+ * backslash is escaped too so a name cannot terminate the quoted string early.
+ */
+function escapeFieldName(name) {
+    return name.replace(/[\r\n"\\]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0")}`);
+}
+/**
+ * Encode a `FormData` as `multipart/form-data` (RFC 7578).
+ *
+ * The function this lives in was written to stop the raw Node transports from
+ * sending an *empty* body for the types fetch would have serialized, and it
+ * covered `URLSearchParams` and `Blob`. `FormData` was missed, so on the
+ * default transport on Node — `NodeHTTP2Transport`, which bypasses fetch
+ * entirely — a form upload went out as a request with no body at all and no
+ * `Content-Type`, and the server recorded an empty form. The response was an
+ * ordinary 200, so nothing looked wrong.
+ *
+ * The boundary is generated per call and written into the body. The transports
+ * that call this only ever see bytes, so the header is set by the client from
+ * `options.headers`; a body encoded here without a matching header is
+ * unparseable, which is why the boundary is returned alongside the bytes for a
+ * caller that has to announce it. Passing one in makes the output
+ * deterministic, which is what the test suite pins.
+ */
+export async function encodeMultipart(form, boundary) {
+    // 24 random bytes as hex: 192 bits is far past any collision concern, and hex
+    // is all legal in a boundary.
+    const bnd = boundary ?? `----kinetexFormBoundary${randomBytes(24)}`;
+    const encoder = new TextEncoder();
+    const chunks = [];
+    const push = (text) => {
+        chunks.push(encoder.encode(text));
+    };
+    for (const [name, value] of form.entries()) {
+        // A field name is application- and sometimes user-controlled, and CR/LF in
+        // one would forge a part header. Such a name is refused rather than sent
+        // or silently dropped.
+        if (/[\r\n"]/.test(name)) {
+            throw new KinetexError(`Cannot send a multipart field whose name contains CR, LF or a quote: ${JSON.stringify(name)}`, "EVALIDATION");
+        }
+        push(`--${bnd}\r\n`);
+        if (typeof value === "string") {
+            push(`Content-Disposition: form-data; name="${escapeFieldName(name)}"\r\n\r\n`);
+            push(value);
+            push("\r\n");
+            continue;
+        }
+        // A File/Blob part: RFC 7578 §4.2 wants its own type and filename.
+        push(`Content-Disposition: form-data; name="${escapeFieldName(name)}"; ` +
+            `filename="${escapeFieldName(value.name || "blob")}"\r\n` +
+            `Content-Type: ${value.type || "application/octet-stream"}\r\n\r\n`);
+        chunks.push(new Uint8Array(await value.arrayBuffer()));
+        push("\r\n");
     }
-    return new Uint8Array(0);
+    push(`--${bnd}--\r\n`);
+    return { bytes: concatUint8Arrays(chunks), boundary: bnd };
 }
 // ============================================================================
 // §10  DECOMPRESSION
@@ -1216,8 +1836,9 @@ async function serializeRawBody(body) {
  * Dynamically imports response.ts so that environments that don't use
  * decompression don't pay the code cost. The import is cached by the runtime.
  *
- * Supported encodings: gzip, deflate, br (brotli)
- * Unsupported encodings (zstd, etc.) are passed through compressed; caller must handle or error.
+ * Supported encodings: gzip, deflate, br (brotli), zstd.
+ * Unsupported encodings are passed through compressed; the caller must handle
+ * them.
  *
  * @param body    - Raw body stream (or null)
  * @param headers - Response headers (content-encoding is read and stripped on success)
@@ -1236,7 +1857,7 @@ export async function decompressBodyStream(body, headers) {
         .map((e) => e.trim())
         .filter(Boolean);
     // Check for unsupported encodings
-    const supportedEncodings = ["gzip", "deflate", "br", "identity"];
+    const supportedEncodings = ["gzip", "deflate", "br", "zstd", "identity"];
     for (const enc of encodings) {
         if (!supportedEncodings.includes(enc)) {
             console.warn(`[Kinetex] Unsupported Content-Encoding: ${enc}. ` +