kinetex 1.3.0 → 1.5.0

package/dist/cjs/client.js

@@ -4,16 +4,17 @@
  * retry, auth, cache, cookie jar, HAR, logging, progress, and SSE/GraphQL/Pagination.
  */
 import { ProgressTracker, withUploadProgress } from "./progress.js";
-import { DedupMap } from "./dedup.js";
+import { DedupMap, dedupKeyFrom, identityFingerprint } from "./dedup.js";
 import { CircuitBreakerRegistry, } from "./circuit-breaker.js";
 import { WSClient } from "./ws.js";
-import { KinetexError, HTTPStatusError, AbortError, toRequestId } from "./types.js";
-import { isValidHeaderName, isValidHeaderValue, isSafeURL, uint8ArrayToBase64, randomBytes, } from "./utils.js";
-import { getAuthFingerprint, CREDENTIAL_HEADERS } from "./cache.js";
-import { createRateLimitInterceptor } from "./interceptors.js";
+import { KinetexError, HTTPStatusError, AbortError, RedirectError, toRequestId } from "./types.js";
+import { isValidHeaderName, isValidHeaderValue, isSafeURL, uint8ArrayToBase64, randomBytes, perfNow, isSensitiveHeader, } from "./utils.js";
+import { CREDENTIAL_HEADERS } from "./cache.js";
+import { createRateLimitInterceptor, ConcurrencyLimiter } from "./interceptors.js";
 import { SigV4Signer } from "./aws-sigv4.js";
 import { createDigestAuthorizer } from "./digest.js";
-import { DEFAULT_ACCEPT_ENCODING } from "./core.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.
@@ -141,6 +142,15 @@ function randomHex(len) {
  * Mirrors logging.ts DEFAULT_REDACT_HEADERS — HAR logs are routinely exported
  * and shared, so credentials must never appear verbatim.
  */
+/**
+ * Ceiling on a buffered response body when the caller sets no limit.
+ *
+ * Roughly the largest JSON document that is still sane to hand to
+ * `JSON.parse`, and far below the point where a single response can take a
+ * process down. Not a security boundary on its own — it is the difference
+ * between one bad response being a failed request and being an OOM kill.
+ */
+const DEFAULT_MAX_RESPONSE_SIZE = 100 * 1024 * 1024;
 const HAR_REDACT_HEADERS = new Set([
     "authorization",
     "proxy-authorization",
@@ -170,6 +180,8 @@ const HAR_REDACT_HEADERS = new Set([
  * `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;
@@ -199,6 +211,92 @@ const HAR_REDACT_PARAMS = new Set([
     "jwt",
     "code",
 ]);
+/**
+ * Body field names whose values are redacted from a recorded HAR body.
+ *
+ * The same names already redacted from HAR headers and query parameters.
+ * Headers were covered and query parameters were covered, but a JSON request
+ * body was recorded verbatim: `{"password":"..."}` went into the export in
+ * clear text while `{"password":"..."}` in a header was masked. HAR files get
+ * attached to bug reports and handed to support teams, so a body is the most
+ * likely place for a credential to travel. Nested objects and arrays are
+ * walked to any depth.
+ */
+/**
+ * Replace the literal values this request's own credentials take, anywhere in
+ * a recorded body.
+ *
+ * Field-name redaction cannot help a `text/plain` body, where there are no
+ * field names — and a server echoing a token back is the common case (an
+ * error body quoting the offending header, a "session invalid" message).
+ * Matching the exact values kinetex already knows are sensitive is precise: no
+ * pattern matching, no false positives on ordinary text.
+ */
+function scrubKnownSecrets(text, req) {
+    const secrets = [];
+    // Credential headers are usually scheme-prefixed — `Bearer <token>` — and a
+    // body that echoes the token back echoes only the token, not the scheme.
+    // Scrubbing the whole header value would therefore match nothing.
+    const add = (v) => {
+        if (typeof v === "string" && v.length >= 8)
+            secrets.push(v);
+    };
+    for (const [name, value] of Object.entries(req.headers ?? {})) {
+        if (isSensitiveHeader(name, HAR_REDACT_HEADERS) && typeof value === "string") {
+            add(value);
+            const sp = value.indexOf(" ");
+            if (sp !== -1)
+                add(value.slice(sp + 1));
+        }
+    }
+    let query;
+    try {
+        query = new URL(req.url).searchParams;
+    }
+    catch {
+        query = new URLSearchParams();
+    }
+    for (const [key, value] of query.entries()) {
+        if (HAR_REDACT_PARAMS.has(key.toLowerCase()) &&
+            typeof value === "string" &&
+            value.length >= 8) {
+            secrets.push(value);
+        }
+    }
+    let out = text;
+    for (const secret of secrets)
+        out = out.split(secret).join(HAR_REDACT_MASK);
+    return out;
+}
+function redactHARBody(text, mimeType) {
+    if (!/json/i.test(mimeType))
+        return text;
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return text; // Not valid JSON despite the header; nothing safe to rewrite.
+    }
+    const walk = (node) => {
+        if (Array.isArray(node))
+            return node.map(walk);
+        if (node !== null && typeof node === "object") {
+            const out = {};
+            for (const [key, value] of Object.entries(node)) {
+                out[key] = HAR_REDACT_PARAMS.has(key.toLowerCase()) ? HAR_REDACT_MASK : walk(value);
+            }
+            return out;
+        }
+        return node;
+    };
+    try {
+        return JSON.stringify(walk(parsed));
+    }
+    catch {
+        return text;
+    }
+}
 /** 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. */
@@ -238,15 +336,57 @@ function redactHARUrl(url) {
     }
 }
 /** Redact a single header value for HAR output. */
+/**
+ * HAR entries carry their own mask ("***REDACTED***"), distinct from the
+ * logger's "***" and the logging interceptor's "**REDACTED**". A recorded HAR
+ * is a file a user reads and shares, so the string is part of its output; the
+ * shared helper takes it as an argument rather than the three being merged.
+ */
+const HAR_REDACT_MASK = "***REDACTED***";
 function redactHARHeader(name, value) {
-    return HAR_REDACT_HEADERS.has(name.toLowerCase())
-        ? { name, value: "***REDACTED***" }
-        : { name, value };
+    // A HAR stores headers as `{name, value}` pairs rather than a record, so it
+    // uses the shared case-insensitive predicate rather than the record helper.
+    return {
+        name,
+        value: isSensitiveHeader(name, HAR_REDACT_HEADERS) ? HAR_REDACT_MASK : 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
+    }
+    // Redact before truncating: truncating first could cut a redaction in half
+    // and leave the head of a secret in the export.
+    const redacted = scrubKnownSecrets(redactHARBody(text, mimeType), req);
+    return { postData: { mimeType, text: redacted.slice(0, HAR_MAX_BODY_CHARS) } };
+}
 class HARRecorder {
     /** Ring buffer of entries keyed by monotonic counter. */
     _buf = new Map();
@@ -338,6 +478,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,
@@ -350,7 +501,12 @@ class HARRecorder {
                     // 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) }
+                        ? {
+                            // Same reason as the request side: a `text/plain` body has no
+                            // field names to redact by, and a server that echoes the token
+                            // back would otherwise put it in the export verbatim.
+                            text: scrubKnownSecrets(res.data, req).slice(0, HAR_MAX_BODY_CHARS),
+                        }
                         : {}),
                 },
                 // The Location header can itself carry a signed URL — redact it too.
@@ -473,35 +629,6 @@ async function applyAuth(req, auth) {
 // ============================================================================
 // §5  URL BUILDING
 // ============================================================================
-/**
- * Headers the Fetch spec already drops when a redirect crosses origins.
- * Anything credential-bearing outside this set is forwarded by fetch() itself,
- * which is why those requests must be redirected manually.
- * See {@link CROSS_ORIGIN_STRIP_HEADERS}.
- */
-const FETCH_SPEC_STRIPPED_ON_REDIRECT = new Set(["authorization", "cookie", "proxy-authorization"]);
-/**
- * True when the request carries a credential-bearing header that fetch()
- * would forward across a cross-origin redirect. Drives the decision to follow
- * redirects manually even when no cookie jar is configured.
- *
- * Two sources are consulted: the well-known CREDENTIAL_HEADERS names, and a
- * declared `apikey` auth header, whose name is chosen by the application and so
- * cannot be known to the library.
- */
-function hasForwardedCredentials(headers, auth) {
-    if (auth && auth.type === "apikey")
-        return true;
-    if (!headers)
-        return false;
-    for (const name of Object.keys(headers)) {
-        const lower = name.toLowerCase();
-        if (CROSS_ORIGIN_STRIP_HEADERS.has(lower) && !FETCH_SPEC_STRIPPED_ON_REDIRECT.has(lower)) {
-            return true;
-        }
-    }
-    return false;
-}
 /**
  * Headers stripped when a redirect crosses origins (FIX H2).
  * These carry credentials and must never be forwarded to a different origin.
@@ -545,8 +672,49 @@ 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"], allowPrivateNetwork = false) {
     const MAX_QUERY_PARAM_COUNT = 100;
+    /**
+     * Walk query params once, enforcing the count limit, handing each surviving
+     * key/value pair to `emit`.
+     *
+     * `null` and `undefined` are dropped, and an array expands to one entry per
+     * non-null element. Both URL-assembly paths below did exactly this and each
+     * carried its own copy of the limit check — four copies of the same `throw`,
+     * inside two loops — so the two paths could drift and the cap could end up
+     * enforced in one spelling of the query but not the other.
+     *
+     * Encoding stays with the caller, and so does the array/scalar distinction:
+     * the primary path must `append` array elements (so `?a=1&a=2` survives) but
+     * `set` a scalar (so it replaces a value the URL already carried). The
+     * fallback appends to a list it is building and does not care. That
+     * difference is observable, so `emit` is told which case it is in.
+     */
+    const forEachQueryParam = (params, emit) => {
+        let paramCount = 0;
+        const count = () => {
+            paramCount++;
+            if (paramCount > MAX_QUERY_PARAM_COUNT) {
+                throw new KinetexError(`Query parameter count ${paramCount} exceeds limit of ${MAX_QUERY_PARAM_COUNT}`, "EVALIDATION");
+            }
+        };
+        for (const [key, value] of Object.entries(params)) {
+            if (value === null || value === undefined)
+                continue;
+            if (Array.isArray(value)) {
+                for (const v of value) {
+                    if (v === null || v === undefined)
+                        continue;
+                    count();
+                    emit(key, String(v), true);
+                }
+            }
+            else {
+                count();
+                emit(key, String(value), false);
+            }
+        }
+    };
     const MAX_URL_LENGTH = 8192;
     let full;
     if (/^https?:\/\//i.test(url)) {
@@ -574,44 +742,33 @@ function buildURL(base, url, params) {
         }
     }
     if (!params || Object.keys(params).length === 0) {
-        if (!isSafeURL(full)) {
+        if (!isSafeURL(full, allowedSchemes, { allowPrivateNetwork })) {
             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);
-        let paramCount = 0;
-        for (const [key, value] of Object.entries(params)) {
-            if (value === null || value === undefined)
-                continue;
-            const strValue = String(value);
-            if (Array.isArray(value)) {
-                for (const v of value) {
-                    if (v !== null && v !== undefined) {
-                        paramCount++;
-                        if (paramCount > MAX_QUERY_PARAM_COUNT) {
-                            throw new KinetexError(`Query parameter count ${paramCount} exceeds limit of ${MAX_QUERY_PARAM_COUNT}`, "EVALIDATION");
-                        }
-                        u.searchParams.append(key, String(v));
-                    }
-                }
-            }
-            else {
-                paramCount++;
-                if (paramCount > MAX_QUERY_PARAM_COUNT) {
-                    throw new KinetexError(`Query parameter count ${paramCount} exceeds limit of ${MAX_QUERY_PARAM_COUNT}`, "EVALIDATION");
-                }
-                u.searchParams.set(key, strValue);
-            }
+        // 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, { allowPrivateNetwork })) {
+            throw new KinetexError(`URL "${redactUserInfo(full)}" failed safety check — blocked private/loopback address or forbidden scheme`, "EVALIDATION");
         }
+        // An array element appends, so `?a=1&a=2` survives; a scalar sets, so it
+        // replaces a value the URL already carried under that name.
+        forEachQueryParam(params, (key, value, fromArray) => {
+            if (fromArray)
+                u.searchParams.append(key, value);
+            else
+                u.searchParams.set(key, value);
+        });
         const result = u.toString();
         // Check URL length limit
         if (result.length > MAX_URL_LENGTH) {
             throw new KinetexError(`URL length ${result.length} bytes exceeds limit of ${MAX_URL_LENGTH} bytes`, "EVALIDATION");
         }
         // Validate the final URL with params
-        if (!isSafeURL(result)) {
+        if (!isSafeURL(result, allowedSchemes, { allowPrivateNetwork })) {
             throw new KinetexError(`URL "${redactUserInfo(result)}" failed safety check — blocked private/loopback address or forbidden scheme`, "EVALIDATION");
         }
         return result;
@@ -627,29 +784,9 @@ function buildURL(base, url, params) {
             full += "?";
         }
         const paramParts = [];
-        let paramCount = 0;
-        for (const [key, value] of Object.entries(params ?? {})) {
-            if (value === null || value === undefined)
-                continue;
-            if (Array.isArray(value)) {
-                for (const v of value) {
-                    if (v !== null && v !== undefined) {
-                        paramCount++;
-                        if (paramCount > MAX_QUERY_PARAM_COUNT) {
-                            throw new KinetexError(`Query parameter count ${paramCount} exceeds limit of ${MAX_QUERY_PARAM_COUNT}`, "EVALIDATION");
-                        }
-                        paramParts.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(v))}`);
-                    }
-                }
-            }
-            else {
-                paramCount++;
-                if (paramCount > MAX_QUERY_PARAM_COUNT) {
-                    throw new KinetexError(`Query parameter count ${paramCount} exceeds limit of ${MAX_QUERY_PARAM_COUNT}`, "EVALIDATION");
-                }
-                paramParts.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
-            }
-        }
+        forEachQueryParam(params ?? {}, (key, value) => {
+            paramParts.push(`${encodeURIComponent(key)}=${encodeURIComponent(value)}`);
+        });
         const result = full + paramParts.join("&");
         // Check URL length limit
         if (result.length > MAX_URL_LENGTH) {
@@ -657,7 +794,7 @@ function buildURL(base, url, params) {
         }
         // FIX M4: the manual param-concat fallback previously returned WITHOUT a
         // safety check — validate the assembled URL like every other path.
-        if (!isSafeURL(result)) {
+        if (!isSafeURL(result, allowedSchemes, { allowPrivateNetwork })) {
             throw new KinetexError(`URL "${redactUserInfo(result)}" failed safety check — blocked private/loopback address or forbidden scheme`, "EVALIDATION");
         }
         return result;
@@ -713,11 +850,42 @@ function mergeHeaders(...sources) {
  * @param ctx - Current retry context (error, response, attempt count).
  * @returns Whether a retry should be attempted.
  */
+/**
+ * A request body rendered for a log entry, or `null` when it cannot be.
+ *
+ * A `ReadableStream` or a `FormData` is deliberately not consumed to log it:
+ * reading either would consume the payload the request is about to send, so
+ * logging would break the request it is describing.
+ */
+function loggableBody(body) {
+    if (body === null || body === undefined)
+        return null;
+    if (typeof body === "string")
+        return body;
+    if (body instanceof Uint8Array)
+        return body;
+    try {
+        return JSON.stringify(body);
+    }
+    catch {
+        // Cyclic, or otherwise not serialisable. The request still has to go out.
+        return null;
+    }
+}
 function shouldRetry(cfg, ctx) {
     if (ctx.attempt > cfg.maxRetries)
         return false;
-    if (!cfg.methods.includes(ctx.request.method))
+    // `Idempotency-Key` is a declaration that this exact request may be
+    // repeated: the whole point of the header is that the server collapses
+    // duplicates. Without this, POST is never retried, so a caller who attached
+    // a key — which kinetex generates for exactly this purpose — still lost the
+    // request to the first transient 503, and the changelog's claim that "every
+    // retry reuses it" described retries that could never happen. A caller opts
+    // in by sending the header, which is the same contract the header carries.
+    const hasIdempotencyKey = Object.keys(ctx.request.headers ?? {}).some((name) => name.toLowerCase() === "idempotency-key" && ctx.request.headers[name] !== "");
+    if (!hasIdempotencyKey && !cfg.methods.includes(ctx.request.method)) {
         return false;
+    }
     if (cfg.shouldRetry)
         return cfg.shouldRetry(ctx); // caller handles it
     if (ctx.error) {
@@ -745,6 +913,10 @@ function shouldRetry(cfg, ctx) {
                 return false;
             case "EREDIRECT":
                 return false;
+            // A blocked host is a permanent refusal, not a transport hiccup; retrying
+            // resolves the same name to the same blocked address.
+            case "EBLOCKEDHOST":
+                return false;
             case "EUNKNOWN":
                 return false;
             default: {
@@ -775,7 +947,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.
@@ -787,15 +965,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;
     }
-    const ms = Date.parse(ra);
-    return isNaN(ms) ? null : Math.max(0, Math.min(ms - Date.now(), 86_400_000));
+    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));
+    }
+    return null;
 }
 // ============================================================================
 // §8  MAIN KINETEX CLASS
@@ -850,6 +1034,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.
      */
@@ -868,10 +1060,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;
@@ -889,7 +1088,19 @@ 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 } : {}),
+            ...(config.allowPrivateNetwork !== undefined
+                ? { allowPrivateNetwork: config.allowPrivateNetwork }
+                : {}),
+            ...(config.ca !== undefined ? { ca: config.ca } : {}),
+        });
         // Register config-level interceptors
         if (config.interceptors) {
             config.interceptors.request?.forEach((fn) => this.interceptors.addRequest(fn));
@@ -992,7 +1203,7 @@ export class Kinetex {
                 status: ctx.response.status,
                 statusText: ctx.response.statusText,
                 headers: ctx.response.headers,
-                body: ctx.response.rawBody ?? null,
+                body: ctx.response.body ?? null,
                 request: {
                     url: ctx.request.url,
                     method: ctx.request.method,
@@ -1293,20 +1504,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 ────────────────────────────────────────────────
     /**
@@ -1382,7 +1592,15 @@ 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"], this.cfg.allowPrivateNetwork);
         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.
@@ -1415,7 +1633,11 @@ export class Kinetex {
         // Inject cookies from cookie jar into WS handshake
         const jar = await this.getCookieJar();
         if (jar) {
-            const cookieHeader = jar.getCookieHeader({ url: fullURL, http: false });
+            const cookieHeader = jar.getCookieHeader({
+                url: fullURL,
+                http: false,
+                sameSiteContext: "strict",
+            });
             if (cookieHeader)
                 headers["cookie"] = cookieHeader;
         }
@@ -1424,8 +1646,20 @@ export class Kinetex {
             const wsUrl = new URL(fullURL);
             if (this.cfg.baseURL) {
                 const baseUrl = new URL(this.cfg.baseURL);
-                const wsIsSecure = wsUrl.protocol === "wss:";
-                const httpIsSecure = baseUrl.protocol === "https:";
+                // `https:` counts as secure here, not just `wss:`. `fullURL` comes
+                // from `buildURL` against the same baseURL, so it carries the baseURL's
+                // own scheme — `https:` — and the WebSocket upgrade happens later, in
+                // the runtime's `WebSocket`. Testing for `wss:` alone therefore made
+                // `wsIsSecure` false for every https baseURL while `httpIsSecure` was
+                // true, so `client.ws()` rejected its own configuration and could not
+                // open a socket at all. The error even printed two identical origins.
+                const wsIsSecure = wsUrl.protocol === "wss:" || wsUrl.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");
                 }
@@ -1478,6 +1712,12 @@ export class Kinetex {
         this._wsClients.add(client);
         await client.connect().catch((err) => {
             this._wsClients.delete(client);
+            // Destroy, not just deregister. A handshake that fails before `open`
+            // rejects with the socket still referenced by the WSClient — its
+            // handlers, its buffer and the underlying handle — so dropping the
+            // registry entry alone left it alive and holding a socket for the life of
+            // the process. A caller that retried on failure leaked one per attempt.
+            client.destroy();
             throw err;
         });
         return client;
@@ -1501,7 +1741,23 @@ export class Kinetex {
         // ── Resolve timeout ────────────────────────────────────────────────────
         const timeoutMs = options.timeout !== undefined ? options.timeout : (this.cfg.timeout ?? 30_000);
         // ── Resolve retry ──────────────────────────────────────────────────────
-        const retryCfg = options.retry === false ? false : { ...this.retryConfig, ...(options.retry ?? {}) };
+        // `totalTimeoutMs` defaults to the request timeout, so `timeout` bounds the
+        // whole logical request rather than each attempt. It applied per attempt
+        // only, while the backoff between attempts was bounded by nothing: with
+        // `timeout: 1_000`, five retries and a growing `baseDelayMs`, an instantly
+        // failing endpoint held the caller for ~37s. Anyone who reads `timeout` as
+        // "this call must not take longer than this" — most people — was wrong.
+        // `timeout: 0` (no timeout) likewise yields no budget, and an explicit
+        // `totalTimeoutMs: 0` opts back out.
+        const retryCfg = options.retry === false
+            ? false
+            : {
+                ...this.retryConfig,
+                ...(options.retry ?? {}),
+                ...(options.retry?.totalTimeoutMs !== undefined
+                    ? {}
+                    : { totalTimeoutMs: options.totalTimeoutMs ?? this.cfg.totalTimeoutMs ?? timeoutMs }),
+            };
         // ── Validate HTTP method ────────────────────────────────────────────────
         const VALID_METHODS = [
             "GET",
@@ -1519,16 +1775,18 @@ export class Kinetex {
             throw new KinetexError(`Invalid HTTP method '${method}'. Valid methods: ${VALID_METHODS.join(", ")}`, "EVALIDATION");
         }
         // ── 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");
+        const fullUrl = buildURL(options.baseURL ?? this.cfg.baseURL, url, mergeParams(this.cfg.params, options.params), undefined, this.cfg.allowPrivateNetwork === true);
+        // 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) {
@@ -1544,6 +1802,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) {
@@ -1571,19 +1837,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 —
@@ -1630,6 +1890,25 @@ export class Kinetex {
             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" &&
@@ -1668,7 +1947,11 @@ export class Kinetex {
         // ── Cookie jar (outgoing cookies) ──────────────────────────────────────
         const jar = await this.getCookieJar();
         if (jar) {
-            const cookieHeader = jar.getCookieHeader({ url: req.url, http: true });
+            const cookieHeader = jar.getCookieHeader({
+                url: req.url,
+                http: true,
+                sameSiteContext: "strict",
+            });
             if (cookieHeader)
                 req = { ...req, headers: { ...req.headers, cookie: cookieHeader } };
         }
@@ -1684,6 +1967,7 @@ export class Kinetex {
         // 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;
+        let _dedupKey = "";
         try {
             if (this._otelTracer) {
                 _otelSpan = this._otelTracer.startSpan(`HTTP ${req.method}`, { kind: 3 /* CLIENT */ });
@@ -1712,6 +1996,24 @@ export class Kinetex {
                     meta: { ...req.meta, spanId },
                 };
             }
+            // Dedup key. Computed inside this try, not below it, so that a failure
+            // here ends the span instead of abandoning it. The auth fingerprint needs
+            // Web Crypto, so it can throw on a runtime without `crypto.subtle` — and
+            // because it is an `await`, the throw resumes here, outside the span's
+            // lifecycle when this block sat below the catch. The span was then never
+            // ended, never exported, and held its attributes in the tracer's memory.
+            if (this._dedup) {
+                // Fingerprint *every* header, not just the credential ones. Keying on
+                // `Authorization`/`Cookie` alone is what the comment above promised,
+                // and it held — for the two headers it covered. It did not cover the
+                // header a multi-tenant gateway actually partitions on: two concurrent
+                // GETs to one URL differing only in `X-Tenant` shared a single response,
+                // so one tenant was handed another's data. Hashing keeps the values out
+                // of the key itself, and the trace-id headers are excluded so they
+                // cannot silently disable coalescing.
+                const identity = await identityFingerprint(req.headers);
+                _dedupKey = dedupKeyFrom(req.method, req.url, identity);
+            }
         }
         catch (tracingErr) {
             if (_otelSpan) {
@@ -1752,16 +2054,12 @@ export class Kinetex {
         const _execFactory = () => this._executeWithRetry(req, retryCfg, timeoutMs, options, startMs, wallClockMs);
         // Dedup: coalesce identical concurrent GET/HEAD requests into one network
         // call. All callers share the same KinetexResponse object once resolved.
-        // 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.
-        // 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 : ""}`;
-        }
+        // SECURITY: the dedup key fingerprints every request header, so two
+        // requests are only ever coalesced when they would have received the same
+        // response — including when they differ only by tenant or session header.
+        // Fingerprinting hashes the header set with SHA-256, so credentials never
+        // sit in the key, and it is only paid when dedup is actually enabled. The
+        // key is computed inside the tracing try above, where a throw ends the span.
         const _dedupedFactory = this._dedup
             ? () => this._dedup
                 .execute(req.method, _dedupKey, _execFactory)
@@ -1801,6 +2099,82 @@ 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++;
@@ -1831,6 +2205,14 @@ export class Kinetex {
                         : shouldRetry(retryCfg, retryCtx);
                     if (doRetry) {
                         const delay = computeRetryDelay(retryCfg, attempt, getRetryAfterMs(res.headers));
+                        // Total budget: a backoff that would run past it is not worth
+                        // sleeping through. The caller gets the response they already have
+                        // (a retry-worthy status) instead of a manufactured timeout, which
+                        // keeps the real reason visible.
+                        if (retryCfg.totalTimeoutMs !== undefined && retryCfg.totalTimeoutMs > 0) {
+                            if (perfNow() - startMs + delay >= retryCfg.totalTimeoutMs)
+                                return res;
+                        }
                         await retryCfg.onRetry?.(retryCtx, delay);
                         await this.cfg.hooks?.onRetry?.reduce(async (p, fn) => {
                             await p;
@@ -1852,20 +2234,67 @@ export class Kinetex {
                         method: req.method,
                     });
                 }
-                if (retryCfg && attempt <= retryCfg.maxRetries) {
+                // 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);
+                        // Total budget, as above: do not sleep past the caller's ceiling.
+                        // Here there is no response to fall back on, so the original error
+                        // stands and is rethrown below.
+                        if (retryCfg.totalTimeoutMs !== undefined && retryCfg.totalTimeoutMs > 0) {
+                            if (perfNow() - startMs + delay >= retryCfg.totalTimeoutMs) {
+                                throw err;
+                            }
+                        }
                         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;
                     }
@@ -1971,9 +2400,7 @@ 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
@@ -1982,13 +2409,26 @@ export class Kinetex {
                 });
                 // `followRedirects: false` (or `maxRedirects: 0`) hands the 3xx back to
                 // the caller instead of chasing it — the same shape fetch() returns for
-                // `redirect: "manual"`.
+                // `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: true };
+                    return { ...raw, redirected: false };
                 if (hop === maxRedirects) {
-                    throw new KinetexError(`Too many redirects (exceeded ${maxRedirects})`, "ENETWORK", {
-                        request: req,
-                    });
+                    // `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) {
@@ -2016,7 +2456,9 @@ export class Kinetex {
                     // 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)) {
+                    if (!isSafeURL(nextUrl, undefined, {
+                        allowPrivateNetwork: this.cfg.allowPrivateNetwork === true,
+                    })) {
                         throw new KinetexError(`Unsafe redirect target blocked: ${redactUserInfo(location)}`, "EVALIDATION", { request: req });
                     }
                     // httpsOnly must hold for redirect legs too, otherwise a redirect is a
@@ -2039,6 +2481,15 @@ export class Kinetex {
                     ? "GET"
                     : currentReq.method;
                 const nextBody = nextMethod === "GET" || nextMethod === "HEAD" ? null : currentReq.body;
+                // A 307/308 keeps the method and the body, so the hop needs the body
+                // again — and a stream or Blob body is spent: the first attempt consumed
+                // and locked it. The retry loop already refuses this case with a clear
+                // EVALIDATION, but the follower had no equivalent check, so it handed
+                // the dead stream to the transport and the caller got an opaque ENETWORK
+                // "Response body object should not be disturbed or locked".
+                if (nextBody !== null && isNonReplayableBody(nextBody)) {
+                    throw new KinetexError("Cannot follow this redirect: a 307/308 preserves the method and body, and this request's body is a stream or Blob that the first attempt already consumed. Buffer it first, or disable redirects for this request.", "EVALIDATION", { request: currentReq });
+                }
                 const nextHeaders = { ...currentReq.headers };
                 // FIX H2: When the redirect crosses origins, strip credential-bearing
                 // headers (Authorization, Cookie, proxy auth, API keys) so secrets are
@@ -2070,7 +2521,13 @@ export class Kinetex {
                 // 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 });
+                    // Same context as the initial hop: a redirect followed to an origin the
+                    // client chose is still a same-site request for cookie purposes.
+                    const cookieHeader = jar.getCookieHeader({
+                        url: nextUrl,
+                        http: true,
+                        sameSiteContext: "strict",
+                    });
                     if (cookieHeader) {
                         nextHeaders["cookie"] = cookieHeader;
                     }
@@ -2100,7 +2557,7 @@ export class Kinetex {
             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 ──────────────────────────────────────────────────
     /**
@@ -2136,10 +2593,30 @@ export class Kinetex {
             }
         }
         this._trace(_traceId, "lifecycle_before", "end", startMs, attempt);
+        // ── Logger: request ────────────────────────────────────────────────────
+        // `HTTPLogger.logRequest` was fully implemented — it registers the id so
+        // the matching `logResponse` can recover the method, URL and duration —
+        // and the client never called it. Nothing had ever been registered, so
+        // every response entry came back with `url: ""`, `method: "GET"`,
+        // `durationMs: 0` and `requestId: "unknown"`: the request line was simply
+        // missing, and a structured log that cannot name the request it describes
+        // is not much use for diagnosing one. Registered here, before dispatch, so
+        // it covers the same span the response entry closes.
+        const _logger = await this.getLogger();
+        if (_logger) {
+            _logger.logRequest(_traceId, req.method, req.url, req.headers, loggableBody(req.body), 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) {
@@ -2310,22 +2787,34 @@ export class Kinetex {
             };
         }
         // ── Dispatch ───────────────────────────────────────────────────────────
-        // Redirects are followed by hand when EITHER:
-        //  - a cookie jar is active, so every intermediate Set-Cookie is captured
-        //    (fetch() silently drops them), or
-        //  - the request carries a credential header that fetch() would NOT strip on
-        //    a cross-origin redirect. Per the Fetch spec only `authorization`,
-        //    `cookie` and `proxy-authorization` are dropped, so a custom API-key
-        //    header would otherwise be forwarded verbatim to a foreign origin.
+        // 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;
-        const needsManualRedirects = dispatchJar !== null || hasForwardedCredentials(req.headers, effectiveAuth);
         this._trace(_traceId, "transport_send", "start", startMs, attempt);
         let raw;
         try {
-            raw = needsManualRedirects
-                ? await this._sendFollowingRedirects(req, timeout, dispatchJar ?? undefined, effectiveAuth)
-                : 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
@@ -2343,6 +2832,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();
@@ -2424,7 +2927,11 @@ export class Kinetex {
             });
         }
         // ── Read body with size limit ──────────────────────────────────────────
-        const maxSize = options.maxResponseSize ?? this.cfg.maxResponseSize ?? 0;
+        // 100 MB by default rather than unbounded: without a cap a hostile or
+        // simply broken server can drive this process out of memory, because the
+        // body is read in full before the caller sees a byte of it. An explicit
+        // `0` opts back out, which is what that value has always meant.
+        const maxSize = options.maxResponseSize ?? this.cfg.maxResponseSize ?? DEFAULT_MAX_RESPONSE_SIZE;
         const rawBody = await readRawBody(bodyStream, maxSize, raw.url, req.signal);
         // ── Cookie jar (incoming Set-Cookie) ──────────────────────────────────
         const jar = await this.getCookieJar();
@@ -2448,6 +2955,9 @@ export class Kinetex {
             // the real response object instead of the `{}` placeholder it used to get.
             data,
             rawBody,
+            // The same bytes in the shape an interceptor sees, so one response
+            // object satisfies both the public and the pipeline views.
+            body: rawBody,
             url: raw.url,
             cached: false,
             redirected: raw.redirected,
@@ -2472,9 +2982,9 @@ export class Kinetex {
             }
         }
         // ── Logger ─────────────────────────────────────────────────────────────
-        const logger = await this.getLogger();
+        const logger = _logger ?? (await this.getLogger());
         if (logger) {
-            const requestId = ctx.store.get("requestId") ?? req.meta["requestId"] ?? "unknown";
+            const requestId = ctx.store.get("requestId") ?? req.meta["requestId"] ?? _traceId;
             logger.logResponse(requestId, res.status, res.statusText, res.headers, rawBody, attempt, false);
         }
         // ── HAR recording ──────────────────────────────────────────────────────
@@ -2635,6 +3145,8 @@ export class Kinetex {
             status: raw.status,
             statusText: raw.statusText,
             headers: raw.headers,
+            // Present so the object satisfies both response views at once.
+            body: rawBody,
             data,
             rawBody,
             url: responseURL,
@@ -2753,7 +3265,7 @@ export class Kinetex {
     async sse(url, options = {}) {
         const { SSEClient } = await import("./sse.js");
         const headers = mergeHeaders(this.cfg.headers, options.headers);
-        const fullURL = buildURL(this.cfg.baseURL, url, this.cfg.params);
+        const fullURL = buildURL(this.cfg.baseURL, url, this.cfg.params, undefined, this.cfg.allowPrivateNetwork);
         // Route through the full kinetex pipeline (auth, interceptors, rate-limit, CB, etc.)
         // by providing a pipeline-aware fetch function.
         const pipeFetch = async (input, init) => {
@@ -2794,7 +3306,7 @@ export class Kinetex {
     async graphql(url, options = {}) {
         const { GraphQLClient } = await import("./graphql.js");
         const headers = mergeHeaders(this.cfg.headers, options.headers);
-        const fullURL = buildURL(this.cfg.baseURL, url, this.cfg.params);
+        const fullURL = buildURL(this.cfg.baseURL, url, this.cfg.params, undefined, this.cfg.allowPrivateNetwork);
         // Route through the full kinetex pipeline (auth, interceptors, rate-limit, CB, OTel, etc.)
         const pipeFetch = async (input, init) => {
             const reqUrl = typeof input === "string" ? input : input.url;
@@ -2833,7 +3345,7 @@ export class Kinetex {
      */
     async paginate(url, options) {
         const { createPagePaginator } = await import("./pagination.js");
-        const fullURL = buildURL(this.cfg.baseURL, url, this.cfg.params);
+        const fullURL = buildURL(this.cfg.baseURL, url, this.cfg.params, undefined, this.cfg.allowPrivateNetwork);
         // Route through the full kinetex pipeline
         const pipeFetch = async (input, init) => {
             const reqUrl = typeof input === "string" ? input : input.url;
@@ -2886,6 +3398,8 @@ export class Kinetex {
         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();
@@ -2940,6 +3454,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 = {
@@ -3225,10 +3767,6 @@ function isNonReplayableBody(body) {
         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();
-}
 // ============================================================================
 // §16  ENTERPRISE HELPERS
 // ============================================================================