kinetex 1.2.0 → 1.4.0

package/dist/esm/client.js

@@ -7,13 +7,20 @@ import { ProgressTracker, withUploadProgress } from "./progress.js";
 import { DedupMap } from "./dedup.js";
 import { CircuitBreakerRegistry, } from "./circuit-breaker.js";
 import { WSClient } from "./ws.js";
-import { KinetexError, HTTPStatusError, toRequestId } from "./types.js";
+import { KinetexError, HTTPStatusError, AbortError, RedirectError, toRequestId } from "./types.js";
 import { isValidHeaderName, isValidHeaderValue, isSafeURL, uint8ArrayToBase64, randomBytes, } from "./utils.js";
-import { getAuthFingerprint } from "./cache.js";
-import { createRateLimitInterceptor } from "./interceptors.js";
+import { getAuthFingerprint, CREDENTIAL_HEADERS } from "./cache.js";
+import { createRateLimitInterceptor, ConcurrencyLimiter } from "./interceptors.js";
 import { SigV4Signer } from "./aws-sigv4.js";
-import { createDigestAuthorization } from "./digest.js";
+import { createDigestAuthorizer } from "./digest.js";
+import { generateIdempotencyKey, isValidIdempotencyKey, parseRetryAfter } from "./headers.js";
+import { DEFAULT_ACCEPT_ENCODING, encodeMultipart } from "./core.js";
 import { createTransport, sendWithTimeout, decompressBodyStream, readRawBody, parseBody, RUNTIME, IS_NODE, } from "./core.js";
+/**
+ * Hard ceiling on redirect hops followed by the manual redirect follower.
+ * Overridable per client / per request with `maxRedirects`.
+ */
+const DEFAULT_MAX_REDIRECTS = 20;
 /** Default retry configuration used when no retry config is provided. */
 const DEFAULT_RETRY = {
     maxRetries: 3,
@@ -160,14 +167,118 @@ const HAR_REDACT_HEADERS = new Set([
     "passwd",
     "secret",
 ]);
+/**
+ * `meta` key carrying the number of response-interceptor re-sends so a
+ * self-retriggering interceptor cannot loop forever.
+ */
+/** Request-meta key: a clock-skew correction has already been spent. */
+const AWS_SKEW_CORRECTED = "__awsSkewCorrected";
+const INTERCEPTOR_RESEND_DEPTH = "__interceptorResendDepth";
+/** Hard cap on consecutive response-interceptor re-sends (digest refresh, etc.). */
+const MAX_INTERCEPTOR_RESENDS = 5;
+/** Query-parameter names whose values are redacted in HAR output. */
+const HAR_REDACT_PARAMS = new Set([
+    "api_key",
+    "apikey",
+    "access_token",
+    "refresh_token",
+    "id_token",
+    "token",
+    "auth",
+    "authorization",
+    "key",
+    "secret",
+    "password",
+    "passwd",
+    "signature",
+    "sig",
+    "x-amz-signature",
+    "x-amz-credential",
+    "x-amz-security-token",
+    "x-goog-signature",
+    "sas",
+    "session",
+    "sessionid",
+    "jwt",
+    "code",
+]);
+/** Maximum number of body characters recorded in a HAR entry. */
+const HAR_MAX_BODY_CHARS = 8192;
+/** HTML/other content types whose bodies are never recorded in HAR output. */
+function isHARBodySafeToRecord(contentType) {
+    if (!contentType)
+        return false;
+    const ct = contentType.toLowerCase();
+    return (ct.includes("json") ||
+        ct.includes("xml") ||
+        ct.includes("text/plain") ||
+        ct.includes("application/javascript"));
+}
+/**
+ * Redact sensitive query-parameter values in a URL, preserving everything else
+ * (scheme, host, path, parameter names, ordering) so the HAR stays useful.
+ */
+function redactHARUrl(url) {
+    try {
+        const u = new URL(url);
+        let changed = false;
+        for (const key of [...u.searchParams.keys()]) {
+            if (HAR_REDACT_PARAMS.has(key.toLowerCase())) {
+                u.searchParams.set(key, "***REDACTED***");
+                changed = true;
+            }
+        }
+        // Hash can carry an implicit-access-token (S3, Firebase, share links).
+        if (u.hash && (u.hash.includes("token") || u.hash.includes("sig") || u.hash.length > 1)) {
+            u.hash = "#***REDACTED***";
+            changed = true;
+        }
+        return changed ? u.toString() : url;
+    }
+    catch {
+        // Unparseable URL — fall back to a regex that masks known param names.
+        return url.replace(/([?&])(api_key|apikey|access_token|refresh_token|token|secret|password|signature|sig)=([^&#]*)/gi, "$1$2=***REDACTED***");
+    }
+}
 /** Redact a single header value for HAR output. */
 function redactHARHeader(name, value) {
-    return HAR_REDACT_HEADERS.has(name.toLowerCase()) ? { name, value: "***REDACTED***" } : { name, value };
+    return HAR_REDACT_HEADERS.has(name.toLowerCase())
+        ? { name, value: "***REDACTED***" }
+        : { name, value };
 }
 /**
  * O(1) ring-buffer HAR entry recorder.
  * Stores up to `maxEntries` entries, evicting oldest first.
  */
+/**
+ * The `postData` block for a recorded request, or `{}` when there is nothing
+ * safe or possible to record.
+ *
+ * Kept out of `record()` so the recorder's entry literal reads as the HAR it
+ * claims to conform to, and so the "may I record this?" decision has one home.
+ */
+function harPostData(req) {
+    if (!req.body)
+        return {};
+    const mimeType = req.headers["content-type"] ?? "";
+    // Same policy as the response body: skip anything that is not plain text.
+    if (mimeType && !isHARBodySafeToRecord(mimeType))
+        return {};
+    let text;
+    if (typeof req.body === "string") {
+        text = req.body;
+    }
+    else if (req.body instanceof Uint8Array) {
+        text = new TextDecoder().decode(req.body);
+    }
+    else if (req.body instanceof ArrayBuffer) {
+        text = new TextDecoder().decode(new Uint8Array(req.body));
+    }
+    else {
+        return {}; // stream / FormData / Blob: not readable without consuming it
+    }
+    return { postData: { mimeType, text: text.slice(0, HAR_MAX_BODY_CHARS) } };
+}
 class HARRecorder {
     /** Ring buffer of entries keyed by monotonic counter. */
     _buf = new Map();
@@ -204,10 +315,16 @@ class HARRecorder {
             // Browser Resource Timing API — accurate per-request breakdown
             if (typeof performance !== "undefined" &&
                 typeof performance.getEntriesByType === "function") {
-                const entries = performance.getEntriesByType("resource");
-                // Find the most recent entry matching this URL
-                const entry = entries.filter((e) => e.name === res.url).pop();
-                if (entry && entry.requestStart > 0) {
+                // getEntriesByName narrows the buffer instead of scanning every resource
+                // entry for each recorded request (was O(entries) per request).
+                const entries = (typeof performance.getEntriesByName === "function"
+                    ? performance.getEntriesByName(res.url)
+                    : performance.getEntriesByType("resource").filter((e) => e.name === res.url));
+                // Most recent entry for this URL. Entries are startTime-ordered, so the
+                // last one is the most recent — and, unlike a name-only match, we also
+                // require it to be recent enough to actually belong to this request.
+                const entry = entries[entries.length - 1];
+                if (entry && entry.requestStart > 0 && Date.now() - entry.startTime < 60_000) {
                     sendMs = Math.max(0, entry.responseStart - entry.requestStart);
                     receiveMs = Math.max(0, entry.responseEnd - entry.responseStart);
                     waitMs = Math.max(0, total - sendMs - receiveMs);
@@ -224,12 +341,16 @@ class HARRecorder {
             time: total,
             request: {
                 method: req.method,
-                url: req.url,
+                // Redacted: HAR logs are routinely exported and shared, and a query
+                // string is just as leaky as a header (?api_key=, ?access_token=,
+                // ?signature=). Previously only headers were redacted, so the full URL
+                // and every query value landed in the log verbatim.
+                url: redactHARUrl(req.url),
                 httpVersion: res.httpVersion,
                 headers: Object.entries(req.headers).map(([name, value]) => redactHARHeader(name, value)),
                 queryString: (() => {
                     try {
-                        return Array.from(new URL(req.url).searchParams.entries()).map(([name, value]) => ({
+                        return Array.from(new URL(redactHARUrl(req.url)).searchParams.entries()).map(([name, value]) => ({
                             name,
                             value,
                         }));
@@ -249,6 +370,17 @@ class HARRecorder {
                         return req.body.byteLength;
                     return -1; // Unknown (stream, FormData, etc.)
                 })(),
+                // `postData` is declared on `HAREntry` as "Posted data, if applicable"
+                // and was never written, so a HAR exported from a client that POSTs
+                // anything shows an empty request body in every viewer — the response
+                // body, the query string, the headers and the URL are all there, and
+                // the one part that explains what was actually sent is not. The gates
+                // are the ones the response side already uses: a body is recorded only
+                // when its content type is safe to record, it is truncated to the same
+                // limit, and a body that cannot be read without consuming it (a stream,
+                // a FormData) is omitted rather than guessed at — which is what the
+                // `bodySize: -1` above already admits.
+                ...harPostData(req),
             },
             response: {
                 status: res.status,
@@ -258,9 +390,14 @@ class HARRecorder {
                 content: {
                     size: res.rawBody?.byteLength ?? 0,
                     mimeType: res.headers["content-type"] ?? "application/octet-stream",
-                    ...(typeof res.data === "string" ? { text: res.data } : {}),
+                    // Body text is only kept for non-HTML payloads and is truncated:
+                    // response bodies routinely carry tokens and PII.
+                    ...(typeof res.data === "string" && isHARBodySafeToRecord(res.headers["content-type"])
+                        ? { text: res.data.slice(0, HAR_MAX_BODY_CHARS) }
+                        : {}),
                 },
-                redirectURL: res.headers["location"] ?? "",
+                // The Location header can itself carry a signed URL — redact it too.
+                redirectURL: res.headers["location"] ? redactHARUrl(res.headers["location"]) : "",
                 bodySize: res.rawBody?.byteLength ?? 0,
             },
             timings: {
@@ -383,22 +520,15 @@ async function applyAuth(req, auth) {
  * Headers stripped when a redirect crosses origins (FIX H2).
  * These carry credentials and must never be forwarded to a different origin.
  */
+// Derived from the single CREDENTIAL_HEADERS list in cache.ts so the strip
+// list, the dedup key and the cache key can never drift apart. (The previous
+// list also carried `www-authenticate`, a RESPONSE header that can never appear
+// on an outgoing request.)
 const CROSS_ORIGIN_STRIP_HEADERS = new Set([
-    "authorization",
-    "cookie",
-    "proxy-authorization",
-    "x-api-key",
-    "x-auth-token",
-    "x-access-token",
-    "x-refresh-token",
-    "x-csrf-token",
-    "x-session-id",
-    "x-session-token",
-    "x-secret",
-    "x-secret-key",
-    "x-private-key",
-    "api-key",
-    "apikey",
+    ...CREDENTIAL_HEADERS,
+    // Response-only per RFC 9110, so it can never legitimately appear on an
+    // outgoing request — kept in the strip list as defence in depth for callers
+    // that copy a full header bag (including response headers) onto a request.
     "www-authenticate",
 ]);
 /**
@@ -429,7 +559,7 @@ function redactUserInfo(url) {
  * @returns Fully-qualified URL string.
  * @throws {KinetexError} EVALIDATION — if URL is unsafe, params exceed limits, or URL too long.
  */
-function buildURL(base, url, params) {
+function buildURL(base, url, params, allowedSchemes = ["http", "https"]) {
     const MAX_QUERY_PARAM_COUNT = 100;
     const MAX_URL_LENGTH = 8192;
     let full;
@@ -458,13 +588,18 @@ function buildURL(base, url, params) {
         }
     }
     if (!params || Object.keys(params).length === 0) {
-        if (!isSafeURL(full)) {
+        if (!isSafeURL(full, allowedSchemes)) {
             throw new KinetexError(`URL "${redactUserInfo(full)}" failed safety check — blocked private/loopback address or forbidden scheme`, "EVALIDATION");
         }
         return full;
     }
     try {
         const u = new URL(full);
+        // The params branch screens the URL after appending them, so it needs the
+        // same scheme list as the no-params branch above.
+        if (!isSafeURL(u, allowedSchemes)) {
+            throw new KinetexError(`URL "${redactUserInfo(full)}" failed safety check — blocked private/loopback address or forbidden scheme`, "EVALIDATION");
+        }
         let paramCount = 0;
         for (const [key, value] of Object.entries(params)) {
             if (value === null || value === undefined)
@@ -659,7 +794,13 @@ function computeRetryDelay(cfg, attempt, retryAfterMs) {
         return cfg.maxDelayMs;
     }
     const capped = Math.min(exp, cfg.maxDelayMs);
-    return Math.floor(capped + capped * cfg.jitter * Math.random());
+    const jittered = capped + capped * cfg.jitter * Math.random();
+    // `maxDelayMs` is documented as a maximum, so the cap must be re-applied
+    // *after* jitter. It was not: base 1000, cap 1200, jitter 1 returned 2000ms,
+    // so the option never bounded worst-case latency at all — it bounded only the
+    // pre-jitter base. With the default jitter of 0.3 a 30 s cap still allowed
+    // 39 s.
+    return Math.min(Math.floor(jittered), cfg.maxDelayMs);
 }
 /**
  * Extract and parse the Retry-After header value.
@@ -671,15 +812,21 @@ function getRetryAfterMs(headers) {
     const ra = headers["retry-after"];
     if (!ra)
         return null;
-    if (/^\d+$/.test(ra.trim())) {
-        const seconds = parseInt(ra, 10);
-        if (!isFinite(seconds) || seconds < 0)
-            return null;
+    // Delegate to the single RFC 7231 §7.1.1 parser instead of a second,
+    // looser copy: Date.parse() accepts "-5", "1.5" and "+5" as dates, which
+    // used to yield a 0 ms (i.e. "ignore Retry-After") back-off on a 429.
+    const parsed = parseRetryAfter(ra);
+    if (parsed.delay !== null) {
         const MAX_RETRY_AFTER_SEC = 86_400; // 24 hours
-        return Math.min(seconds, MAX_RETRY_AFTER_SEC) * 1000;
+        return Math.min(parsed.delay, MAX_RETRY_AFTER_SEC) * 1000;
+    }
+    if (parsed.date) {
+        // A date in the past genuinely means "retry now" — 0 is the answer, not a
+        // parse failure. Cap at 24 h so a bogus far-future date cannot stall.
+        const MAX_RETRY_AFTER_MS = 86_400_000;
+        return Math.max(0, Math.min(parsed.date.getTime() - Date.now(), MAX_RETRY_AFTER_MS));
     }
-    const ms = Date.parse(ra);
-    return isNaN(ms) ? null : Math.max(0, Math.min(ms - Date.now(), 86_400_000));
+    return null;
 }
 // ============================================================================
 // §8  MAIN KINETEX CLASS
@@ -693,11 +840,12 @@ function getRetryAfterMs(headers) {
  *
  * const client = kinetex({ baseURL: "https://api.example.com" });
  *
- * // Fluent chain
- * const user = await client.get("/users/1").json<User>();
+ * // Fluent chain — `get()` returns a Promise, so use the uppercase
+ * // `GET()` builder if you want to chain `.json()` onto it.
+ * const user = await client.GET("/users/1").json<User>();
  *
- * // Standard send
- * const res = await client.send<User>({ url: "/users/1", method: "GET" });
+ * // Standard send — `send(url, method, options)`, not an object argument
+ * const res = await client.send<User>("/users/1", "GET");
  * ```
  */
 export class Kinetex {
@@ -733,6 +881,14 @@ export class Kinetex {
     _circuitBreakerKeyFn = null;
     /** Active WebSocket connections tracked for cleanup on destroy(). */
     _wsClients = new Set();
+    /**
+     * Optional bulkhead bounding in-flight requests. `null` when
+     * `concurrencyLimit` is not configured, which keeps the hot path free of a
+     * limiter check.
+     */
+    _concurrencyLimiter;
+    /** SigV4 signer kept so a clock-skew correction survives across retries. */
+    _awsSigner = null;
     /**
      * @param config - Global client configuration.
      */
@@ -751,10 +907,17 @@ export class Kinetex {
             const rlInterceptor = createRateLimitInterceptor(config.rateLimit);
             this.interceptors.addRequest(rlInterceptor);
         }
+        // Concurrency limiter (bulkhead). Held as an object rather than a request
+        // interceptor because a permit must survive until the request settles,
+        // and interceptors cannot wrap the downstream call.
+        this._concurrencyLimiter = config.concurrencyLimit
+            ? new ConcurrencyLimiter(config.concurrencyLimit)
+            : null;
         // AWS SigV4 request signing — registered synchronously (static import).
         // Active immediately; no race between first request and interceptor registration.
         if (config.awsSigning) {
             const signer = new SigV4Signer(config.awsSigning);
+            this._awsSigner = signer;
             this.interceptors.addRequest(async (ctx) => {
                 const req = ctx.request;
                 let signableBody = null;
@@ -772,7 +935,15 @@ export class Kinetex {
             });
         }
         // Transport — pass strictHeaders option through to FetchTransport
-        this.transport = createTransport(config.fetch, config.httpVersion !== "HTTP/1.1", undefined, config.strictHeaders ? { strict: true } : undefined);
+        this.transport = createTransport(config.fetch, config.httpVersion !== "HTTP/1.1", 
+        // The HTTP/2 session pool was configurable on the transport but the
+        // client always passed `undefined` here, so `sessionPool` on the client
+        // config could not tune it.
+        config.sessionPool, {
+            ...(config.strictHeaders ? { strict: true } : {}),
+            ...(config.dispatcher !== undefined ? { dispatcher: config.dispatcher } : {}),
+            ...(config.proxy !== undefined ? { proxy: config.proxy } : {}),
+        });
         // Register config-level interceptors
         if (config.interceptors) {
             config.interceptors.request?.forEach((fn) => this.interceptors.addRequest(fn));
@@ -782,6 +953,11 @@ export class Kinetex {
         // Digest auth interceptor — handles 401 → parse challenge → retry
         if (config.auth?.type === "digest") {
             const digestConfig = config.auth;
+            // Per-client nonce counter. RFC 7616 requires `nc` to strictly increase
+            // for every request reusing a nonce; the stateless helper always used
+            // 00000001, so any server enforcing replay protection rejected the second
+            // authenticated request with 401.
+            const digestAuthorizer = createDigestAuthorizer();
             this.interceptors.addResponse(async (ctx) => {
                 if (!ctx.response)
                     return;
@@ -793,8 +969,9 @@ export class Kinetex {
                 if (ctx.request.meta.__digestRetried)
                     return;
                 const method = ctx.request.method;
-                const uri = new URL(ctx.request.url).pathname + new URL(ctx.request.url).search;
-                const authHeader = await createDigestAuthorization(wwwAuth, digestConfig.username, digestConfig.password, method, uri);
+                const parsedUrl = new URL(ctx.request.url);
+                const uri = parsedUrl.pathname + parsedUrl.search;
+                const authHeader = await digestAuthorizer(wwwAuth, digestConfig.username, digestConfig.password, method, uri);
                 return {
                     ...ctx.request,
                     headers: { ...ctx.request.headers, authorization: authHeader },
@@ -893,22 +1070,30 @@ export class Kinetex {
         const errEject = this.useError(async (ctx) => {
             if (!ctx.error)
                 return;
+            const hookReq = {
+                url: ctx.request.url,
+                method: ctx.request.method,
+                headers: ctx.request.headers,
+                body: ctx.request.body,
+                signal: ctx.request.signal,
+                meta: ctx.request.meta,
+            };
+            // A failed request can still have produced a response: HTTPStatusError
+            // carries the KinetexResponse, and createLoggingHooks' onError reads
+            // `err.response?.status`. Hardcoding null here made every bridged
+            // onError hook see no response, so log entries silently recorded a null
+            // status for 4xx/5xx. Only genuinely response-less errors (network,
+            // timeout, abort) keep null.
+            const errResponse = toHookResponse(ctx.error.response, hookReq);
             const hookErr = {
                 error: ctx.error,
-                request: {
-                    url: ctx.request.url,
-                    method: ctx.request.method,
-                    headers: ctx.request.headers,
-                    body: ctx.request.body,
-                    signal: ctx.request.signal,
-                    meta: ctx.request.meta,
-                },
-                response: null,
+                request: hookReq,
+                response: errResponse,
                 attempt: ctx.attempt,
             };
             const hookCtx = {
                 request: hookErr.request,
-                response: null,
+                response: errResponse,
                 error: ctx.error,
                 startedAt: ctx.startedAt,
                 attempt: ctx.attempt,
@@ -1162,20 +1347,19 @@ export class Kinetex {
     /**
      * Returns deduplication metrics.
      *
-     * @returns An object with `hits` (coalesced request count), `misses` (actual network request count),
-     *          and `inFlightCount` (currently in-flight requests), or `null` if dedup is not enabled.
+     * The full `DedupMap.getStats()` snapshot, so a caller has to reach for one
+     * shape rather than two. The wrapper used to expose only `hits`, `misses`
+     * and `inFlightCount` — which meant the hit rate, the only figure anyone
+     * actually wants from a dedup map, was unavailable on the client even
+     * though the map computed it.
+     *
+     * @returns `{ hits, misses, totalRequests, hitRate, inFlightCount, trackedKeys }`,
+     *          or `null` if dedup is not enabled.
      */
     get dedupMetrics() {
         if (!this._dedup)
             return null;
-        return {
-            /** Number of requests that shared an in-flight or windowed response. */
-            hits: this._dedup.hits,
-            /** Number of requests that triggered a real network call. */
-            misses: this._dedup.misses,
-            /** Number of currently in-flight requests. */
-            inFlightCount: this._dedup.inFlightCount,
-        };
+        return this._dedup.getStats();
     }
     // ── §8.5d  Circuit Breaker ────────────────────────────────────────────────
     /**
@@ -1251,7 +1435,20 @@ export class Kinetex {
      * ```
      */
     async ws(url, options = {}) {
-        const fullURL = buildURL(this.cfg.baseURL, url, this.cfg.params);
+        // `ws://` / `wss://` have to be allowed here, and only here. The default
+        // `["http", "https"]` is what stops an ordinary HTTP request from being
+        // pointed at a WebSocket scheme, and every other buildURL caller keeps it.
+        // Without this opt-in the documented `client.ws("wss://…")` form — the one
+        // in the README and in this method's own JSDoc — failed the SSRF scheme
+        // check and threw EVALIDATION on every call, so `client.ws()` could not
+        // connect to anything. Only the scheme list is widened: the loopback and
+        // private-range checks still apply to WebSocket URLs.
+        const fullURL = buildURL(this.cfg.baseURL, url, this.cfg.params, [
+            "http",
+            "https",
+            "ws",
+            "wss",
+        ]);
         const headers = mergeHeaders(this.cfg.headers, options.headers);
         // Apply auth headers manually since WS handshake goes through the browser
         // WS API which doesn't use the kinetex transport pipeline.
@@ -1294,7 +1491,12 @@ export class Kinetex {
             if (this.cfg.baseURL) {
                 const baseUrl = new URL(this.cfg.baseURL);
                 const wsIsSecure = wsUrl.protocol === "wss:";
-                const httpIsSecure = baseUrl.protocol === "https:";
+                // A baseURL may itself be a WebSocket URL — `kinetex({ baseURL:
+                // "wss://…" })` then `client.ws("/path")` is the natural spelling, and
+                // it is what the README's origin-validation section shows. Comparing
+                // `wss:` only against `https:` rejected that pairing outright, so a
+                // client configured with a WebSocket baseURL could never open a socket.
+                const httpIsSecure = baseUrl.protocol === "https:" || baseUrl.protocol === "wss:";
                 if (wsIsSecure !== httpIsSecure || wsUrl.host !== baseUrl.host) {
                     throw new KinetexError(`WebSocket origin ${wsUrl.origin} does not match baseURL origin ${baseUrl.origin}`, "EVALIDATION");
                 }
@@ -1389,15 +1591,17 @@ export class Kinetex {
         }
         // ── Build initial request ─────────────────────────────────────────────
         const fullUrl = buildURL(options.baseURL ?? this.cfg.baseURL, url, mergeParams(this.cfg.params, options.params));
-        // FIX (M7): proxy configuration was stored but never consumed — a silent
-        // no-op that sent traffic directly to the target, bypassing the user's
-        // proxy entirely. Fail fast with actionable guidance instead.
-        const proxy = options.proxy ?? this.cfg.proxy;
-        if (proxy) {
-            throw new KinetexError("proxy is configured but kinetex's built-in transports cannot route through it: " +
-                "HTTP(S) proxies require a custom fetch with a proxy agent (e.g. undici ProxyAgent " +
-                "passed via the `fetch` option), and SOCKS5 requires createSocks5Tunnel() from " +
-                "kinetex/socks5. Set up one of those instead of relying on `proxy` silently doing nothing.", "EVALIDATION");
+        // A client-level `proxy` is honoured by the Node transport, which tunnels
+        // every connection through it with CONNECT. A per-request `proxy` cannot be:
+        // the transport pools one connection per origin, so honouring a per-request
+        // proxy would mean tearing the pool down mid-flight. Reject it with an
+        // accurate reason rather than silently ignoring it.
+        const perRequestProxy = options.proxy;
+        if (perRequestProxy) {
+            throw new KinetexError("A per-request `proxy` is not supported because the transport pools one connection " +
+                "per origin — set `proxy` on the client instead, or use a custom `fetch` with a " +
+                "proxy agent for per-request routing. SOCKS5 requires createSocks5Tunnel() from " +
+                "kinetex/socks5.", "EVALIDATION");
         }
         // Enforce HTTPS-only if configured
         if (this.cfg.httpsOnly) {
@@ -1413,6 +1617,14 @@ export class Kinetex {
                 throw new KinetexError(`Invalid URL: ${err}`, "EVALIDATION");
             }
         }
+        // A multipart body has no size until it is encoded, and the encoding is
+        // the same call the dispatch path makes below, so it is done once here and
+        // the result reused. The guard used to estimate it with a flat 76 bytes per
+        // part, which is less than the framing `encodeMultipart` actually writes
+        // for its 70-character generated boundary: a form sized to exactly the
+        // estimate passed this check and then went out roughly 45 bytes per part
+        // over the limit the caller had set.
+        let preEncodedForm;
         // Enforce request size limit if configured
         const maxRequestSize = options.maxRequestSize ?? this.cfg.maxRequestSize ?? 0;
         if (maxRequestSize > 0 && options.body) {
@@ -1440,19 +1652,13 @@ export class Kinetex {
                 bodySize = new TextEncoder().encode(options.body.toString()).byteLength;
             }
             else if (options.body instanceof FormData) {
-                // FIX (H4): estimate multipart size instead of skipping entirely —
-                // the old skip allowed unbounded uploads past the configured limit.
-                const boundaryOverhead = 76; // per part: --boundary, headers, CRLF (conservative)
-                for (const [name, value] of options.body) {
-                    bodySize += new TextEncoder().encode(name).byteLength + boundaryOverhead;
-                    if (typeof value === "string") {
-                        bodySize += new TextEncoder().encode(value).byteLength;
-                    }
-                    else {
-                        bodySize += value.size;
-                    }
-                }
-                bodySize += boundaryOverhead; // final boundary
+                // FIX (H4): the old branch skipped FormData entirely, which allowed
+                // unbounded uploads past the configured limit; it then replaced the
+                // skip with an estimate whose per-part constant was smaller than the
+                // framing it stood in for. The exact bytes are the only honest
+                // answer, and they are needed a few lines below anyway.
+                preEncodedForm = await encodeMultipart(options.body);
+                bodySize = preEncodedForm.bytes.byteLength;
             }
             else if (options.body instanceof ReadableStream) {
                 // FIX (H4): a stream's size cannot be known without consuming it —
@@ -1461,7 +1667,14 @@ export class Kinetex {
                 throw new KinetexError(`maxRequestSize cannot be enforced for ReadableStream bodies — pass maxRequestSize: 0 to opt out, or buffer the body first`, "EVALIDATION");
             }
             else if (options.body && typeof options.body === "object") {
-                bodySize = new TextEncoder().encode(JSON.stringify(options.body)).byteLength;
+                try {
+                    bodySize = new TextEncoder().encode(JSON.stringify(options.body)).byteLength;
+                }
+                catch (err) {
+                    // A circular (or BigInt-containing) body threw a raw TypeError from
+                    // inside the size guard, masking the real serialization error.
+                    throw new KinetexError(`Cannot measure request body size: ${err instanceof Error ? err.message : String(err)}`, "EVALIDATION");
+                }
             }
             if (bodySize > maxRequestSize) {
                 throw new KinetexError(`Request body size ${bodySize} bytes exceeds limit of ${maxRequestSize} bytes`, "EVALIDATION");
@@ -1469,13 +1682,48 @@ export class Kinetex {
         }
         let req = {
             url: fullUrl,
-            method,
+            // Use the normalized method, not the caller's casing: `send(url, "patch")`
+            // passed validation above but used to put the literal string "patch" on
+            // the wire. fetch() only normalizes delete/get/head/options/post/put, so a
+            // lowercase PATCH/CONNECT went out verbatim and servers answered 405.
+            method: normalizedMethod,
             headers: mergeHeaders(this.cfg.headers, options.headers),
-            body: options.body ?? null,
+            // A plain object/array is accepted by the public API (RequestBody) and is
+            // JSON-encoded in the block immediately below, so the request object only
+            // ever holds a real BodyInit by the time this function returns.
+            body: (options.body ?? null),
             signal: options.signal ?? null,
+            // Resolved once here so the manual redirect follower sees the same
+            // effective values the caller asked for. Spread (not `??`) because the
+            // project uses exactOptionalPropertyTypes.
+            ...(options.followRedirects !== undefined || this.cfg.followRedirects !== undefined
+                ? { followRedirects: options.followRedirects ?? this.cfg.followRedirects }
+                : {}),
+            ...(options.maxRedirects !== undefined || this.cfg.maxRedirects !== undefined
+                ? { maxRedirects: options.maxRedirects ?? this.cfg.maxRedirects }
+                : {}),
             meta: { ...options.meta },
             httpVersion: options.httpVersion ?? this.cfg.httpVersion ?? "HTTP/2",
         };
+        // A `FormData` body is encoded here rather than handed to the transport,
+        // because the encoding and the `Content-Type` that describes it have to be
+        // produced together. The raw Node transports bypass fetch, and
+        // `serializeRawBody` — the function written so they would not send an empty
+        // body — covered `URLSearchParams` and `Blob` but not `FormData`, so on the
+        // default transport on Node a form upload went out with no body and no
+        // `Content-Type` and the server recorded an empty form. The response was an
+        // ordinary 200, so nothing downstream could tell.
+        if (req.body !== null && req.body instanceof FormData && !req.headers["content-type"]) {
+            const encoded = preEncodedForm ?? (await encodeMultipart(req.body));
+            req = {
+                ...req,
+                headers: {
+                    ...req.headers,
+                    "content-type": `multipart/form-data; boundary=${encoded.boundary}`,
+                },
+                body: encoded.bytes,
+            };
+        }
         // Default Content-Type for JSON bodies
         if (req.body !== null &&
             typeof req.body === "object" &&
@@ -1492,6 +1740,18 @@ export class Kinetex {
                 body: JSON.stringify(req.body),
             };
         }
+        // A URLSearchParams body is urlencoded by the raw Node transports, which
+        // do not set a content-type the way fetch does. Without this the server
+        // receives the bytes but cannot parse them as a form.
+        if (req.body !== null &&
+            typeof URLSearchParams !== "undefined" &&
+            req.body instanceof URLSearchParams &&
+            !req.headers["content-type"]) {
+            req = {
+                ...req,
+                headers: { ...req.headers, "content-type": "application/x-www-form-urlencoded" },
+            };
+        }
         // ── Apply auth ─────────────────────────────────────────────────────────
         const auth = options.auth !== false ? (options.auth ?? this.cfg.auth) : undefined;
         if (auth)
@@ -1512,33 +1772,52 @@ export class Kinetex {
         // Works with any OpenTelemetry SDK — just call client.setTracer(tracer).
         // If no tracer is set we still propagate a randomly-generated trace ID
         // when the caller passes options.meta.traceId (useful for manual tracing).
+        // Everything between startSpan() and the dispatch try/catch below can
+        // throw (traceparent building, the circuit-breaker key fn, auth
+        // fingerprinting). Wrap it so a failure still ends the span instead of
+        // abandoning it — an unended span is never exported and never reports the
+        // error, and holds its attributes in the tracer's memory.
         let _otelSpan = null;
-        if (this._otelTracer) {
-            _otelSpan = this._otelTracer.startSpan(`HTTP ${req.method}`, { kind: 3 /* CLIENT */ });
-            const { traceparent, traceId, spanId } = buildTraceparent(_otelSpan);
-            _otelSpan.setAttribute("http.request.method", req.method);
-            _otelSpan.setAttribute("url.full", req.url);
-            try {
-                _otelSpan.setAttribute("server.address", new URL(req.url).hostname);
+        try {
+            if (this._otelTracer) {
+                _otelSpan = this._otelTracer.startSpan(`HTTP ${req.method}`, { kind: 3 /* CLIENT */ });
+                const { traceparent, traceId, spanId } = buildTraceparent(_otelSpan);
+                _otelSpan.setAttribute("http.request.method", req.method);
+                _otelSpan.setAttribute("url.full", req.url);
+                try {
+                    _otelSpan.setAttribute("server.address", new URL(req.url).hostname);
+                }
+                catch {
+                    // Skip hostname attribute if URL is invalid
+                }
+                req = {
+                    ...req,
+                    headers: { ...req.headers, traceparent },
+                    meta: { ...req.meta, traceId, spanId },
+                };
             }
-            catch {
-                // Skip hostname attribute if URL is invalid
+            else if (req.meta["traceId"] && !req.headers["traceparent"]) {
+                // Manual trace propagation — caller set traceId in meta
+                const traceId = String(req.meta["traceId"]);
+                const spanId = randomHex(16);
+                req = {
+                    ...req,
+                    headers: { ...req.headers, traceparent: `00-${traceId}-${spanId}-01` },
+                    meta: { ...req.meta, spanId },
+                };
             }
-            req = {
-                ...req,
-                headers: { ...req.headers, traceparent },
-                meta: { ...req.meta, traceId, spanId },
-            };
         }
-        else if (req.meta["traceId"] && !req.headers["traceparent"]) {
-            // Manual trace propagation — caller set traceId in meta
-            const traceId = String(req.meta["traceId"]);
-            const spanId = randomHex(16);
-            req = {
-                ...req,
-                headers: { ...req.headers, traceparent: `00-${traceId}-${spanId}-01` },
-                meta: { ...req.meta, spanId },
-            };
+        catch (tracingErr) {
+            if (_otelSpan) {
+                _otelSpan.setStatus({
+                    code: 2 /* ERROR */,
+                    message: tracingErr instanceof Error ? tracingErr.message : String(tracingErr),
+                });
+                if (tracingErr instanceof Error)
+                    _otelSpan.recordException(tracingErr);
+                _otelSpan.end();
+            }
+            throw tracingErr;
         }
         // Determine key for dedup + circuit breaker.
         // Uses circuitBreakerKeyFn if configured (e.g. per-method isolation),
@@ -1570,8 +1849,13 @@ export class Kinetex {
         // SECURITY: The dedup key includes a fingerprint of auth-sensitive headers
         // so requests from different users (different Authorization / Cookie) are
         // NEVER coalesced — each user gets their own isolated in-flight slot.
-        const authFp = await getAuthFingerprint(req.headers ?? {});
-        const _dedupKey = `${req.method}:${req.url}${authFp ? ":" + authFp : ""}`;
+        // Fingerprinting hashes the credential headers with SHA-256, so it is only
+        // paid when dedup is actually enabled.
+        let _dedupKey = "";
+        if (this._dedup) {
+            const authFp = await getAuthFingerprint(req.headers ?? {});
+            _dedupKey = `${req.method}:${req.url}${authFp ? ":" + authFp : ""}`;
+        }
         const _dedupedFactory = this._dedup
             ? () => this._dedup
                 .execute(req.method, _dedupKey, _execFactory)
@@ -1611,12 +1895,95 @@ export class Kinetex {
      * and retries on failure per the retry config.
      */
     async _executeWithRetry(req, retryCfg, timeout, options, startMs, wallClockMs) {
+        // A permit is held for the whole logical request — including every retry
+        // attempt — and released in `finally`, so a throw or an exhausted retry
+        // budget can never leak one and permanently shrink the pool.
+        const run = async () => {
+            if (!this._concurrencyLimiter) {
+                return await this._executeWithRetryInner(req, retryCfg, timeout, options, startMs, wallClockMs);
+            }
+            await this._concurrencyLimiter.acquire(req.signal);
+            try {
+                return await this._executeWithRetryInner(req, retryCfg, timeout, options, startMs, wallClockMs);
+            }
+            finally {
+                this._concurrencyLimiter.release();
+            }
+        };
+        // Metrics measure the whole logical request, retries included, and are
+        // emitted from `finally` so failures and aborts are counted too. The
+        // no-tracer case is not short-circuited here: `_recordMetrics` returns
+        // immediately when telemetry is off, and this client then pays nothing
+        // beyond the call it already makes on every request.
+        const metricsStart = Date.now();
+        let status;
+        let errorCode;
+        try {
+            const res = await run();
+            status = res.status;
+            return res;
+        }
+        catch (err) {
+            errorCode = err.code;
+            throw err;
+        }
+        finally {
+            this._recordMetrics(req, status, errorCode, Date.now() - metricsStart);
+        }
+    }
+    /**
+     * Emit request metrics to the configured tracer, if it supports them.
+     *
+     * Failures here are swallowed on purpose: telemetry must never be able to
+     * fail a request that otherwise succeeded.
+     *
+     * @param req - The originating request.
+     * @param status - Final HTTP status, or undefined if the request threw.
+     * @param errorCode - `KinetexError` code, or undefined on success.
+     * @param durationMs - Wall-clock duration of the logical request.
+     */
+    _recordMetrics(req, status, errorCode, durationMs) {
+        const tracer = this._otelTracer;
+        if (!tracer)
+            return;
+        // `req.url` is always an absolute, already-parsed URL by the time a
+        // request reaches here: `buildURL()` constructs it and the SSRF safety
+        // check parses it again before dispatch, so there is nothing to guard.
+        const attributes = {
+            "http.request.method": req.method,
+            "server.address": new URL(req.url).hostname,
+        };
+        if (status !== undefined)
+            attributes["http.response.status_code"] = status;
+        if (errorCode !== undefined)
+            attributes["error.type"] = errorCode;
+        try {
+            // Seconds, per OTel semantic conventions for http.client.request.duration.
+            tracer.recordHistogram?.("http.client.request.duration", durationMs / 1000, attributes);
+            tracer.incrementCounter?.("http.client.request.count", 1, attributes);
+            if (errorCode !== undefined) {
+                tracer.incrementCounter?.("http.client.error.count", 1, attributes);
+            }
+        }
+        catch {
+            // Swallowed — see the doc comment.
+        }
+    }
+    /** Retry loop body. See {@link _executeWithRetry} for the concurrency gate. */
+    async _executeWithRetryInner(req, retryCfg, timeout, options, startMs, wallClockMs) {
         let attempt = 0;
         while (true) {
             attempt++;
             // If caller aborted between retries, stop immediately
             if (req.signal?.aborted) {
-                throw createAbortError();
+                throw createAbortError(req);
+            }
+            // A ReadableStream / Blob body is not replayable: the first attempt
+            // consumes (and locks) it, so a retry re-wraps an already-locked stream
+            // for upload progress and sends an empty body. Fail loudly on the retry
+            // instead of silently transmitting nothing.
+            if (attempt > 1 && isNonReplayableBody(req.body)) {
+                throw new KinetexError("Cannot retry a request whose body is a stream or Blob — the body was consumed by the first attempt. Buffer it first, or disable retry for this request.", "EVALIDATION", { request: req });
             }
             try {
                 const res = await this._executeOnce(req, timeout, options, startMs, attempt, wallClockMs, retryCfg);
@@ -1646,20 +2013,68 @@ export class Kinetex {
                 return res;
             }
             catch (err) {
-                if (retryCfg && attempt <= retryCfg.maxRetries) {
+                if (globalThis.__KINETEX_DEBUG_RETRY) {
+                    console.log("DBG catch", {
+                        attempt,
+                        maxRetries: retryCfg === false ? "FALSE" : retryCfg?.maxRetries,
+                        methods: retryCfg === false ? "FALSE" : retryCfg?.methods,
+                        code: err?.code,
+                        method: req.method,
+                    });
+                }
+                // Clock-skew correction. `SigV4Signer.handleClockSkewError` existed and
+                // `detectClockSkew` was a public export, but nothing in the library
+                // ever called them: a client with a wrong clock got a 403
+                // `RequestTimeTooSkewed`, retried if 403 happened to be in `statuses`,
+                // and re-signed the identical wrong timestamp every attempt. Correcting
+                // here is bounded to one attempt per logical request, so a server that
+                // keeps reporting a different time cannot spin.
+                let clockSkewCorrected = false;
+                const skewResponse = err.response;
+                if (this._awsSigner && skewResponse && err.code === "EHTTPSTATUS") {
+                    // `data` is the parsed body: a string for text, a Uint8Array for any
+                    // other content type (which is what an XML error body arrives as),
+                    // and an object only for JSON.
+                    const raw = skewResponse.data;
+                    const body = typeof raw === "string"
+                        ? raw
+                        : raw instanceof Uint8Array
+                            ? new TextDecoder().decode(raw)
+                            : raw instanceof ArrayBuffer
+                                ? new TextDecoder().decode(new Uint8Array(raw))
+                                : JSON.stringify(raw ?? "");
+                    if (this._awsSigner.handleClockSkewError(skewResponse.status, body, skewResponse.headers)) {
+                        clockSkewCorrected = !req.meta[AWS_SKEW_CORRECTED];
+                        if (clockSkewCorrected)
+                            req.meta[AWS_SKEW_CORRECTED] = true;
+                    }
+                }
+                if (retryCfg && (attempt <= retryCfg.maxRetries || clockSkewCorrected)) {
+                    // A thrown HTTPStatusError already carries the full response. This
+                    // path used to hand hooks a context with `response: null` and a hard
+                    // `null` Retry-After, so the *default* case — throwOnError: true,
+                    // which is what every 429/503 goes through — ignored the server's
+                    // Retry-After entirely and never fired lifecycle onRetry hooks.
+                    const errResponse = skewResponse ?? null;
                     const retryCtx = {
                         request: req,
-                        response: null,
+                        response: errResponse,
                         error: err,
                         attempt,
                         maxRetries: retryCfg.maxRetries,
                     };
-                    const doRetry = retryCfg.shouldRetry
-                        ? await retryCfg.shouldRetry(retryCtx)
-                        : shouldRetry(retryCfg, retryCtx);
+                    const doRetry = clockSkewCorrected
+                        ? true
+                        : retryCfg.shouldRetry
+                            ? await retryCfg.shouldRetry(retryCtx)
+                            : shouldRetry(retryCfg, retryCtx);
                     if (doRetry) {
-                        const delay = computeRetryDelay(retryCfg, attempt, null);
+                        const delay = computeRetryDelay(retryCfg, attempt, errResponse ? getRetryAfterMs(errResponse.headers) : null);
                         await retryCfg.onRetry?.(retryCtx, delay);
+                        await this.cfg.hooks?.onRetry?.reduce(async (p, fn) => {
+                            await p;
+                            await fn(retryCtx);
+                        }, Promise.resolve());
                         await sleep(delay, req.signal);
                         continue;
                     }
@@ -1686,11 +2101,25 @@ export class Kinetex {
     // intermediate redirect responses. When a cookie jar is active we must follow
     // redirects ourselves one hop at a time so we can capture cookies at each step.
     /**
-     * Follow redirects manually, one hop at a time, to capture Set-Cookie headers.
-     * fetch() auto-follows redirects but silently drops Set-Cookie from intermediary hops.
+     * Follow redirects manually, one hop at a time.
+     *
+     * Two independent reasons this path exists:
+     *  1. fetch() auto-follows redirects but silently drops Set-Cookie from
+     *     intermediary hops, so an active cookie jar must see every hop itself.
+     *  2. Per the Fetch spec, a cross-origin redirect only drops
+     *     `authorization` / `cookie` / `proxy-authorization`. Custom credential
+     *     headers (apikey, X-Company-Key, ...) are forwarded verbatim, so any
+     *     request carrying one must also be followed manually.
+     *
+     * @param jar - Optional cookie jar. When omitted, no cookie header is
+     *              rebuilt and intermediate Set-Cookie headers are ignored.
      */
     async _sendFollowingRedirects(req, timeout, jar, appliedAuth) {
-        const MAX_REDIRECTS = 20;
+        // `maxRedirects` / `followRedirects` were documented on KinetexConfig and
+        // SendOptions but never read, so the documented default and the enforced one
+        // had drifted apart. Both are honoured here now.
+        const maxRedirects = Math.max(0, req.maxRedirects ?? DEFAULT_MAX_REDIRECTS);
+        const followRedirects = req.followRedirects !== false && maxRedirects > 0;
         let currentReq = { ...req, redirect: "manual" };
         const origin0 = (() => {
             try {
@@ -1702,7 +2131,7 @@ export class Kinetex {
         })();
         // Track visited URLs to detect redirect loops
         const visited = new Set();
-        for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+        for (let hop = 0; hop <= maxRedirects; hop++) {
             // FIX H2 (part 2): re-apply auth on every hop ONLY while we remain on the
             // original origin. Once a redirect has crossed origins, credential-bearing
             // headers must not be re-injected — otherwise the cross-origin strip in
@@ -1751,19 +2180,35 @@ export class Kinetex {
             if (isRedirect) {
                 // Check for redirect loops
                 if (visited.has(raw.url)) {
-                    throw new KinetexError(`Redirect loop detected: ${raw.url}`, "ENETWORK", {
-                        request: req,
-                    });
+                    throw new RedirectError(`Redirect loop detected: ${raw.url}`, req);
                 }
                 visited.add(raw.url);
                 // Capture cookies from this redirect hop
-                jar.processResponseHeaders(raw.headers, {
+                jar?.processResponseHeaders(raw.headers, {
                     url: raw.url,
                 });
-                if (hop === MAX_REDIRECTS) {
-                    throw new KinetexError(`Too many redirects (exceeded ${MAX_REDIRECTS})`, "ENETWORK", {
-                        request: req,
-                    });
+                // `followRedirects: false` (or `maxRedirects: 0`) hands the 3xx back to
+                // the caller instead of chasing it — the same shape fetch() returns for
+                // `redirect: "manual"`. It reported `redirected: true`, which is the one
+                // value `redirected` must never take: no hop was taken, `res.url` is
+                // still the request's own URL, and the whole point of the option is that
+                // the caller now has to read `Location` and decide for itself. A caller
+                // branching on `if (res.redirected)` to detect a cross-origin bounce was
+                // told it had already been redirected to a URL it never requested.
+                if (!followRedirects)
+                    return { ...raw, redirected: false };
+                if (hop === maxRedirects) {
+                    // `EREDIRECT`, not `ENETWORK`. A redirect chain that has run out of
+                    // hops is a deterministic answer from the origin: the same request
+                    // produces the same chain. As an `ENETWORK` it fell into
+                    // `shouldRetry`'s network-error case and the whole chain was replayed
+                    // once per attempt — 16 requests against a server already looping,
+                    // under a `maxRedirects: 3` the caller had set, and after the whole
+                    // backoff schedule before the error they asked for finally arrived.
+                    // `shouldRetry` already had a non-retryable `EREDIRECT` case, and
+                    // `RedirectError` was already exported and documented; nothing
+                    // constructed it.
+                    throw new RedirectError(`Too many redirects (exceeded ${maxRedirects})`, req);
                 }
                 // Drain the redirect body (usually empty, but must be cancelled)
                 if (raw.body) {
@@ -1786,6 +2231,19 @@ export class Kinetex {
                     if (protocol !== "http:" && protocol !== "https:") {
                         throw new KinetexError(`Unsafe redirect to ${protocol} detected — only HTTP(S) allowed`, "ENETWORK", { request: req });
                     }
+                    // SSRF GATE (P0): the initial URL is screened by buildURL → isSafeURL,
+                    // but a redirect target never went through that check. Without this a
+                    // public host could 302 the client straight at link-local/loopback
+                    // addresses (169.254.169.254, 127.0.0.1, 10/8, ::1, …) and the whole
+                    // private-network block list would be bypassable. Re-validate every hop.
+                    if (!isSafeURL(nextUrl)) {
+                        throw new KinetexError(`Unsafe redirect target blocked: ${redactUserInfo(location)}`, "EVALIDATION", { request: req });
+                    }
+                    // httpsOnly must hold for redirect legs too, otherwise a redirect is a
+                    // trivial downgrade from https:// to http:// past the pre-flight guard.
+                    if (this.cfg.httpsOnly && protocol !== "https:") {
+                        throw new KinetexError(`HTTPS-only mode enabled but redirect target uses ${protocol}`, "EVALIDATION", { request: req });
+                    }
                 }
                 catch (err) {
                     if (err instanceof KinetexError)
@@ -1801,30 +2259,50 @@ export class Kinetex {
                     ? "GET"
                     : currentReq.method;
                 const nextBody = nextMethod === "GET" || nextMethod === "HEAD" ? null : currentReq.body;
-                // Rebuild Cookie header for the next hop using the updated jar
-                const cookieHeader = jar.getCookieHeader({ url: nextUrl, http: true });
                 const nextHeaders = { ...currentReq.headers };
-                if (cookieHeader) {
-                    nextHeaders["cookie"] = cookieHeader;
-                }
-                else {
-                    delete nextHeaders["cookie"];
-                }
                 // FIX H2: When the redirect crosses origins, strip credential-bearing
                 // headers (Authorization, Cookie, proxy auth, API keys) so secrets are
                 // never forwarded to a different origin (RFC 9110 7.1 semantics).
-                // Cookies for the new origin are re-established by the jar lookup above;
-                // jar scoping guarantees only same-site cookies apply.
+                //
+                // ORDERING (this must happen BEFORE the cookie header is rebuilt): the
+                // previous order computed the new origin's cookie header first and then
+                // deleted it again in the strip loop, so every cross-origin hop was
+                // sent without the cookies the jar had just scoped for it.
+                let crossOrigin = false;
                 try {
-                    if (new URL(nextUrl).origin !== new URL(currentReq.url).origin) {
-                        for (const h of CROSS_ORIGIN_STRIP_HEADERS) {
-                            delete nextHeaders[h];
-                        }
-                    }
+                    crossOrigin = new URL(nextUrl).origin !== new URL(currentReq.url).origin;
                 }
                 catch {
                     /* nextUrl was already validated above */
                 }
+                if (crossOrigin) {
+                    for (const h of CROSS_ORIGIN_STRIP_HEADERS) {
+                        delete nextHeaders[h];
+                    }
+                    // An `apikey` auth header name is chosen by the application, so it is
+                    // not in the well-known list. It is a credential all the same, and it
+                    // was being forwarded verbatim to the new origin.
+                    if (appliedAuth && appliedAuth.type === "apikey") {
+                        delete nextHeaders[appliedAuth.header.toLowerCase()];
+                    }
+                }
+                // Rebuild the Cookie header for the next hop from the updated jar.
+                // Jar scoping guarantees only cookies that match the NEW origin are
+                // attached, which is exactly the post-strip state we want.
+                if (jar) {
+                    const cookieHeader = jar.getCookieHeader({ url: nextUrl, http: true });
+                    if (cookieHeader) {
+                        nextHeaders["cookie"] = cookieHeader;
+                    }
+                    else {
+                        delete nextHeaders["cookie"];
+                    }
+                }
+                else if (crossOrigin) {
+                    // No jar: drop the caller's cookie header with the other credentials
+                    // (mirrors what fetch() does for a cross-origin redirect).
+                    delete nextHeaders["cookie"];
+                }
                 currentReq = {
                     ...currentReq,
                     url: nextUrl,
@@ -1837,10 +2315,12 @@ export class Kinetex {
             }
             // Not a redirect — return the final raw response as-is.
             // _executeOnce will capture its Set-Cookie headers via the normal path.
-            return raw;
+            // The chain was followed by hand, so report `redirected: true` for hop > 0
+            // to match what fetch() reports under redirect: "follow".
+            return hop > 0 ? { ...raw, redirected: true } : raw;
         }
         // Unreachable
-        throw new KinetexError("Redirect loop", "ENETWORK", { request: req });
+        throw new RedirectError("Redirect loop", req);
     }
     // ── §8.8  Single attempt ──────────────────────────────────────────────────
     /**
@@ -1877,9 +2357,16 @@ export class Kinetex {
         }
         this._trace(_traceId, "lifecycle_before", "end", startMs, attempt);
         // ── Cache lookup ───────────────────────────────────────────────────────
+        // `noCache()` sets `cache: { forceRefresh: true }`, and `forceRefresh` was
+        // declared on `CacheRequestConfig` and read *nowhere*: the lookup below ran
+        // exactly as if no option had been passed, so a warm entry was served and
+        // the fluent method documented as "Force a fresh fetch, bypassing any cached
+        // response" did not fetch. The fix is to skip the read for this request —
+        // the write still happens, which is what "refresh" means.
+        const forceRefresh = options.cache !== false && options.cache?.forceRefresh === true;
         if (options.cache !== false && this.cfg.cache) {
             const cache = await this.getCache();
-            if (cache) {
+            if (cache && !forceRefresh) {
                 const cacheReq = { url: req.url, method: req.method, headers: req.headers };
                 const hit = await cache.get(cacheReq);
                 if (hit && !hit.stale) {
@@ -1943,7 +2430,15 @@ export class Kinetex {
                                 }
                             }
                             finally {
-                                (await this.getCache())?.clearSWRInFlight(cacheReq);
+                                // Must not be able to skip: if getCache() rejects, the in-flight
+                                // marker survives and this key can never revalidate again, so
+                                // every future stale hit would be served stale forever.
+                                try {
+                                    (await this.getCache())?.clearSWRInFlight(cacheReq);
+                                }
+                                catch {
+                                    /* isolate — never leave the SWR marker stuck */
+                                }
                             }
                         })();
                     }
@@ -2037,21 +2532,39 @@ export class Kinetex {
                 ...req,
                 headers: {
                     ...req.headers,
-                    "accept-encoding": "gzip, deflate, br",
+                    "accept-encoding": DEFAULT_ACCEPT_ENCODING,
                 },
             };
         }
         // ── Dispatch ───────────────────────────────────────────────────────────
-        // When a cookie jar is active we must follow redirects manually so we can
-        // capture Set-Cookie headers from every intermediate hop — fetch() drops
-        // them silently when auto-following.
+        // Redirects are ALWAYS followed by hand, and that is not a preference.
+        //
+        // `_sendFollowingRedirects` is the only place kinetex checks a redirect
+        // *target*: the SSRF gate (`isSafeURL` on every hop), the `httpsOnly`
+        // policy, the redirect-loop detector, the `maxRedirects` cap, and the
+        // RFC 7231 method downgrade for 301/302/303. It also exists to capture
+        // intermediate Set-Cookie and to strip credentials across origins, which is
+        // why it used to be entered only when a cookie jar or a forwarded credential
+        // header happened to be configured.
+        //
+        // An ordinary GET is neither. So an ordinary GET's redirects were chased by
+        // the transport instead, and every check above was skipped: the HTTP/2
+        // transport's own loop resolved any `Location` and dialled it, and
+        // `FetchTransport` handed fetch `redirect: "follow"`, which does the same.
+        // A 302 to `http://127.0.0.1:9/` opened the socket (`ECONNREFUSED` came
+        // back from the loopback port, which is the point — nothing refused the
+        // connection first), and a 302 to `http://169.254.169.254/` was answered by
+        // the cloud metadata service. `httpsOnly: true` changed nothing on either
+        // path; both reported the same opaque `Protocol error`.
+        //
+        // The two reasons the follower was originally introduced are reasons it is
+        // *necessary*, not an exhaustive list of when it applies.
         const dispatchJar = await this.getCookieJar();
+        const effectiveAuth = options.auth !== false ? (options.auth ?? this.cfg.auth) : undefined;
         this._trace(_traceId, "transport_send", "start", startMs, attempt);
         let raw;
         try {
-            raw = dispatchJar
-                ? await this._sendFollowingRedirects(req, timeout, dispatchJar, options.auth !== false ? (options.auth ?? this.cfg.auth) : undefined)
-                : await sendWithTimeout(this.transport, req, timeout);
+            raw = await this._sendFollowingRedirects(req, timeout, dispatchJar ?? undefined, effectiveAuth);
         }
         catch (err) {
             // Cancel the progress-tracking ReadableStream to release the underlying
@@ -2069,6 +2582,20 @@ export class Kinetex {
             throw err;
         }
         this._trace(_traceId, "transport_send", "end", startMs, attempt);
+        // ── Lifecycle: after request ───────────────────────────────────────────
+        // "After the request is sent (before response is processed)" — the window
+        // between the transport answering and the response being built, and the
+        // only place a caller can observe that the wire round trip is over without
+        // also having to see the parsed response. It was declared on `LifecycleHooks`
+        // and documented twice in the README, and never invoked: a caller who
+        // registered it got silence, on every code path, for every status.
+        //
+        // Deliberately *not* fired on the throw above: the request was not sent.
+        if (this.cfg.hooks?.onAfterRequest) {
+            for (const fn of this.cfg.hooks.onAfterRequest) {
+                await fn(req, this._hookCtx(ctx));
+            }
+        }
         // ── Handle 304 Not Modified ────────────────────────────────────────────
         if (raw.status === 304) {
             const cache = await this.getCache();
@@ -2111,9 +2638,18 @@ export class Kinetex {
                 },
                 ...(req.signal !== null ? { signal: req.signal } : {}),
             });
+            // Capture the SOURCE in its own binding. `bodyStream` is reassigned to
+            // this wrapper immediately after construction, so closing over it made
+            // `cancel()` cancel *itself*: readRawBody's reader.cancel() (size limit,
+            // abort, read error) re-entered this function, which threw
+            // "Invalid state: ReadableStream is locked" from inside the cancel
+            // algorithm and left that inner promise unhandled (process-level crash on
+            // Node). start() only worked by accident, relying on the async-fn body
+            // running synchronously up to the first await.
+            const source = bodyStream;
             bodyStream = new ReadableStream({
                 async start(controller) {
-                    const reader = bodyStream.getReader();
+                    const reader = source.getReader();
                     try {
                         while (true) {
                             const { done, value } = await reader.read();
@@ -2133,8 +2669,10 @@ export class Kinetex {
                         reader.releaseLock();
                     }
                 },
-                cancel() {
-                    bodyStream?.cancel();
+                cancel(reason) {
+                    // Forward cancellation to the real source and swallow its failure:
+                    // a rejection here is never observed by the cancelling reader.
+                    void source.cancel(reason).catch(() => { });
                 },
             });
         }
@@ -2159,9 +2697,9 @@ export class Kinetex {
             status: raw.status,
             statusText: raw.statusText,
             headers: raw.headers,
-            data: this.cfg.transformResponse
-                ? this.cfg.transformResponse(data, {})
-                : data,
+            // transformResponse is applied below, once `res` exists, so it receives
+            // the real response object instead of the `{}` placeholder it used to get.
+            data,
             rawBody,
             url: raw.url,
             cached: false,
@@ -2171,6 +2709,14 @@ export class Kinetex {
             request: req,
             attempt,
         };
+        // Apply transformResponse now that the response object exists, so the hook
+        // receives the real response (status/headers/url) rather than the empty
+        // placeholder it used to be handed.
+        if (this.cfg.transformResponse) {
+            // `data` is readonly on the public type; the cast is confined to this one
+            // write, immediately after construction.
+            res.data = this.cfg.transformResponse(res.data, res);
+        }
         // ── Store in cache ─────────────────────────────────────────────────────
         if (options.cache !== false && this.cfg.cache) {
             const cache = await this.getCache();
@@ -2249,6 +2795,16 @@ export class Kinetex {
                 current = result;
             }
             else if ("url" in result && "method" in result && !("status" in result)) {
+                // Re-sending from a response interceptor used to be unbounded: an
+                // interceptor that always returns a modified request (the classic
+                // token-refresh shape, but also a mis-written one) recursed forever,
+                // each level a fresh _executeOnce with a fresh interceptor context.
+                // The depth therefore travels on request meta, which _executeOnce
+                // carries into the nested call (ctx.store would not survive it).
+                const resendDepth = Number(_req.meta[INTERCEPTOR_RESEND_DEPTH] ?? 0);
+                if (resendDepth >= MAX_INTERCEPTOR_RESENDS) {
+                    throw new KinetexError(`Response interceptor re-send limit reached (${MAX_INTERCEPTOR_RESENDS}) — refusing to loop`, "EVALIDATION", { request: _req });
+                }
                 if (retryCfg && attempt <= retryCfg.maxRetries) {
                     const retryCtx = {
                         request: _req,
@@ -2265,7 +2821,13 @@ export class Kinetex {
                     }, Promise.resolve());
                     await sleep(delay, _req.signal);
                 }
-                return this._executeOnce(result, timeout, options, startMs, attempt + 1, undefined, retryCfg);
+                return this._executeOnce({
+                    ...result,
+                    meta: {
+                        ...result.meta,
+                        [INTERCEPTOR_RESEND_DEPTH]: resendDepth + 1,
+                    },
+                }, timeout, options, startMs, attempt + 1, undefined, retryCfg);
             }
         }
         return current;
@@ -2556,7 +3118,10 @@ export class Kinetex {
      * Call this when the client is no longer needed to prevent memory leaks.
      * @returns A promise that resolves when cleanup is complete.
      */
-    async destroy() {
+    // Not `async`: nothing here awaits, so the returned promise is resolved
+    // explicitly instead. The signature stays Promise<void> — callers and the
+    // docs `await client.destroy()`.
+    destroy() {
         // Close all tracked WebSocket connections
         for (const ws of this._wsClients) {
             try {
@@ -2567,23 +3132,22 @@ export class Kinetex {
             }
         }
         this._wsClients.clear();
-        if (this._cache) {
-            try {
-                await this._cache.clear();
-            }
-            catch {
-                /* best-effort */
-            }
-        }
+        // NOTE: the cache is deliberately NOT cleared here. destroy() releases
+        // resources; it must not purge data, and a user-supplied adapter
+        // (localStorage / Cloudflare KV / Redis) would lose every persisted entry.
+        // Call `client.getCache().then(c => c.clear())` explicitly to empty it.
         if (IS_NODE && this.transport && "destroy" in this.transport) {
             this.transport.destroy();
         }
+        // Reject anyone still parked on the queue — it can never drain now.
+        this._concurrencyLimiter?.drain();
         this._cookieJar = null;
         this._logger = null;
         this._dedup?.clear();
         this._circuitBreakers?.clear?.();
         this._otelTracer = null;
         this.interceptors.clear();
+        return Promise.resolve();
     }
 }
 // ============================================================================
@@ -2631,6 +3195,34 @@ export class FluentRequest {
         };
         return this;
     }
+    /**
+     * Attach an `Idempotency-Key`, generating one when none is given.
+     *
+     * Lets a retried `POST` be recognised as the same logical operation by the
+     * server instead of creating a duplicate. Because the header is set on the
+     * request options — not regenerated per attempt — every retry of this
+     * request carries the same key, which is the entire point.
+     *
+     * @param value - An explicit key, or `undefined` to generate a v4 UUID.
+     * @throws {TypeError} If `value` is not a valid key (see `isValidIdempotencyKey`).
+     *
+     * @example
+     * ```ts
+     * await client.POST("/charges").withJSON(body).idempotencyKey().json();
+     * ```
+     */
+    idempotencyKey(value) {
+        const key = value === undefined ? generateIdempotencyKey() : value;
+        if (!isValidIdempotencyKey(key)) {
+            throw new TypeError(`idempotencyKey: ${typeof key === "string" ? JSON.stringify(key) : typeof key} is not a ` +
+                "valid Idempotency-Key — expected 1-255 visible ASCII characters");
+        }
+        this._options.headers = {
+            ...this._options.headers,
+            "idempotency-key": key,
+        };
+        return this;
+    }
     /** Merge a headers map. */
     headers(headers) {
         this._options.headers = {
@@ -2837,16 +3429,40 @@ export class FluentRequest {
 // §15  UTILITIES
 // ============================================================================
 /**
- * Create an AbortError that is compatible across runtimes.
- * Uses DOMException where available (browser/Deno), falls back to plain Error.
+ * Convert a KinetexResponse into the lifecycle HookResponse shape, or null
+ * when the request never produced one (network error, timeout, abort).
+ *
+ * Used by the error-hook bridge so onError hooks can read the HTTP status of
+ * a failed request instead of always seeing null.
+ */
+function toHookResponse(res, request) {
+    if (!res)
+        return null;
+    return {
+        status: res.status,
+        statusText: res.statusText,
+        headers: res.headers,
+        body: res.rawBody ?? null,
+        request,
+    };
+}
+/**
+ * The abort error raised by the retry loop itself.
+ *
+ * This used to build a bare `DOMException`, which is a real `Error` but not a
+ * `KinetexError`: it carries no `code`, so `err.code === "EABORT"` and
+ * `err.isAbort` were both false here while every other abort path in the
+ * library (see core.ts) raised `EABORT`. Callers documented to see `AbortError`
+ * therefore got a structurally different error depending on whether the signal
+ * fired mid-request or mid-retry-delay. The library's own `AbortError` keeps
+ * `name === "AbortError"`, so name-based checks like `isAbortError` are
+ * unaffected.
+ *
+ * @param request - The request being retried, attached when available.
+ * @returns A KinetexError with code `EABORT`.
  */
-function createAbortError() {
-    if (typeof DOMException !== "undefined") {
-        return new DOMException("Aborted", "AbortError");
-    }
-    const err = new Error("Aborted");
-    err.name = "AbortError";
-    return err;
+function createAbortError(request) {
+    return new AbortError(request);
 }
 /**
  * Merge two query parameter maps into one.
@@ -2882,6 +3498,16 @@ function sleep(ms, signal) {
         signal?.addEventListener("abort", onAbort, { once: true });
     });
 }
+/**
+ * True for request bodies that cannot be sent twice: a ReadableStream is
+ * consumed (and locked) by the first attempt, and a Blob-backed stream is
+ * derived from an already-read handle. Both are fine once, never on retry.
+ */
+function isNonReplayableBody(body) {
+    if (body instanceof ReadableStream)
+        return true;
+    return typeof Blob !== "undefined" && body instanceof Blob;
+}
 /** Cross-runtime performance.now() — falls back to Date.now(). */
 function perfNow() {
     return typeof performance !== "undefined" ? performance.now() : Date.now();
@@ -2942,7 +3568,13 @@ export function createMethodCircuitBreakerKey(req) {
 export class BatchQueue {
     /** The parent Kinetex instance used to send requests. */
     _client;
-    /** Maximum number of requests to flush at once. */
+    /**
+     * Maximum number of requests taken out of the queue per flush.
+     * NOTE: this is a batching size, NOT a concurrency limit — every request in a
+     * batch is dispatched immediately and in parallel, and `flush()` drains the
+     * whole queue the same way. Use `maxBatch` to bound how much is dispatched per
+     * tick, and a semaphore or rate limiter to bound actual parallelism.
+     */
     _maxBatch;
     /** Milliseconds to wait before flushing an incomplete batch. */
     _flushMs;
@@ -2956,8 +3588,19 @@ export class BatchQueue {
      */
     constructor(client, options = {}) {
         this._client = client;
-        this._maxBatch = options.maxBatch ?? 100;
-        this._flushMs = options.flushMs ?? 0;
+        // maxBatch must be a positive integer: _flushNow() splices exactly
+        // `_maxBatch` items, so 0 (or a negative value) spliced nothing and made
+        // flush() spin forever on a queue it could never drain.
+        const maxBatch = options.maxBatch ?? 100;
+        if (!Number.isInteger(maxBatch) || maxBatch < 1) {
+            throw new RangeError(`BatchQueue maxBatch must be a positive integer (got ${maxBatch})`);
+        }
+        this._maxBatch = maxBatch;
+        const flushMs = options.flushMs ?? 0;
+        if (!Number.isFinite(flushMs) || flushMs < 0) {
+            throw new RangeError(`BatchQueue flushMs must be a non-negative finite number (got ${flushMs})`);
+        }
+        this._flushMs = flushMs;
     }
     /**
      * Enqueue a request. Returns a promise that resolves when the batch
@@ -3018,7 +3661,11 @@ export class BatchQueue {
      * Loops until the queue is empty so items beyond maxBatch are not orphaned.
      */
     flush() {
-        while (this._queue.length > 0)
+        // The constructor guarantees _maxBatch >= 1, so every _flushNow() removes at
+        // least one item. The counter is defence in depth against a future change
+        // reintroducing a zero-progress flush (which would spin forever).
+        let guard = this._queue.length + 1;
+        while (this._queue.length > 0 && guard-- > 0)
             this._flushNow();
     }
     /** How many requests are currently queued (not yet sent). */