kinetex 1.2.0 → 1.3.0

package/dist/cjs/cookie-parser.js

@@ -1735,10 +1735,13 @@ export function domainMatch(requestHost, cookieDomain) {
     if (isIPAddress(cd))
         return false;
     // RFC 6265 §5.3: cookie domain must not be a public suffix
-    // e.g., "com" or "co.uk" should not be allowed as cookie domain
-    const psl = getPublicSuffix(rh);
-    if (psl === rh)
-        return false; // requestHost is a public suffix
+    // The COOKIE DOMAIN must not be a public suffix: "com" or "co.uk" must
+    // never be accepted as a cookie domain. This check used to test the request
+    // host instead, so it could never fire and a Domain=com cookie was reported
+    // as matching every .com host. (HTTPCookieJar.setCookie guards it separately
+    // with isPublicSuffix(cd); this exported helper must be correct on its own.)
+    if (isPublicSuffix(cd))
+        return false;
     return true;
 }
 // ============================================================================

package/dist/cjs/cookie-store.js

@@ -180,7 +180,11 @@ export class CookieJar {
         let cookieDomain;
         let hostOnly;
         if (parsed.domain !== null && parsed.domain !== "") {
-            const cd = parsed.domain;
+            // Normalize the case: the Domain attribute is case-insensitive, but the
+            // value was stored verbatim while every lookup compares against a
+            // lower-cased request host. `Domain=Example.COM` therefore stored a cookie
+            // that could never be matched again — silently lost for the jar's lifetime.
+            const cd = parsed.domain.toLowerCase();
             // Must domain-match the request host (use custom matcher if provided)
             const matcher = this.domainMatcherFn ?? domainMatch;
             if (!matcher(reqHost, cd))
@@ -269,10 +273,9 @@ export class CookieJar {
      * @returns Array of matching Cookie objects (direct references into storage)
      */
     getCookies(options) {
-        // Lazy cleanup: 1% chance to clear expired cookies on each access
-        if (Math.random() < 0.01) {
-            this.clearExpired();
-        }
+        // Expired cookies are removed by the periodic cleanup timer (and by
+        // clearExpired()); the old 1%-per-access coin flip walked the whole store
+        // at random and made eviction timing non-deterministic.
         const url = safeParseUrl(options.url);
         if (!url)
             return [];
@@ -747,11 +750,16 @@ export class CookieJar {
         // For domain cookies: domain-match (subdomains allowed).
         // We can't know per-domain whether it's host-only without checking cookies,
         // so we do the broader domain-match here and filter host-only per cookie.
-        if (reqHost === cookieDomain)
+        // Lower-case both sides: cookie domains are stored from the (already
+        // normalized) Domain attribute, but a caller can also insert cookies
+        // directly via putCookie() with mixed-case input.
+        const host = reqHost.toLowerCase();
+        const domain = cookieDomain.toLowerCase();
+        if (host === domain)
             return true;
-        if (isIPAddress(reqHost))
+        if (isIPAddress(host))
             return false;
-        return reqHost.endsWith("." + cookieDomain);
+        return host.endsWith("." + domain);
     }
 }
 // ============================================================================

package/dist/cjs/core.js

@@ -103,6 +103,12 @@ function isProductionEnvironment() {
         return false;
     }
 }
+/**
+ * The accept-encoding value client.ts injects when the caller did not set
+ * one. FetchTransport removes exactly this string so fetch() negotiates its
+ * own encodings; any other value is treated as caller intent.
+ */
+export const DEFAULT_ACCEPT_ENCODING = "gzip, deflate, br";
 /**
  * Universal fetch-based transport.
  * Suitable for all runtimes where `fetch` is available.
@@ -160,10 +166,12 @@ export class FetchTransport {
             }
             sanitizedHeaders[name] = value;
         }
-        // Strip default accept-encoding injected by client.ts so fetch()
-        // can add its own. Preserve caller-explicit values (e.g. "identity").
+        // Strip the accept-encoding value INJECTED by client.ts so fetch() can add
+        // its own. The old check removed ANY value containing gzip+deflate+br,
+        // including one the caller set deliberately; matching the exact injected
+        // default keeps caller intent intact.
         const ae = sanitizedHeaders["accept-encoding"];
-        if (ae && ae.toLowerCase().includes("gzip") && ae.toLowerCase().includes("deflate") && ae.toLowerCase().includes("br")) {
+        if (ae && ae.toLowerCase().replace(/\s+/g, " ") === DEFAULT_ACCEPT_ENCODING) {
             delete sanitizedHeaders["accept-encoding"];
         }
         // Build fetch init
@@ -735,6 +743,13 @@ export function createTransport(fetchFn, preferHTTP2 = true, sessionOptions, tra
     // "Custom fetch implementation" behavior holds on every runtime.
     // Use NodeHTTP2Transport for Node.js when HTTP/2 is preferred and no custom
     // fetch is given. Falls back to FetchTransport otherwise.
+    if (IS_NODE && preferHTTP2 && fetchFn) {
+        if (!isProductionEnvironment()) {
+            console.warn('[kinetex] httpVersion: "HTTP/2" is ignored when a custom `fetch` is configured — ' +
+                "NodeHTTP2Transport cannot use a custom fetch, so the request goes through " +
+                "FetchTransport (HTTP/1.1 semantics). Drop the `fetch` option to use HTTP/2.");
+        }
+    }
     if (IS_NODE && preferHTTP2 && !fetchFn) {
         return new NodeHTTP2Transport({
             ...(sessionOptions?.sessionTTLMs !== undefined
@@ -1111,7 +1126,7 @@ async function writeChunkWithBackpressure(stream, chunk) {
 }
 /**
  * Write a request body to an HTTP/2 stream, respecting backpressure.
- * Handles ReadableStream, Uint8Array, ArrayBuffer, and string body types.
+ * Handles ReadableStream, Uint8Array, ArrayBuffer, string, URLSearchParams and Blob bodies.
  *
  * @param stream - HTTP/2 stream to write to
  * @param body   - Request body
@@ -1136,12 +1151,16 @@ async function attachBodyToH2Stream(stream, body) {
         stream.end(body);
     }
     else {
-        stream.end();
+        // The raw Node transports bypass fetch, so bodies fetch would normally
+        // serialize (URLSearchParams, Blob) must be encoded here. Skipping them
+        // silently sent an empty body to the server.
+        const bytes = await serializeRawBody(body);
+        stream.end(bytes);
     }
 }
 /**
  * Write a request body to a Node.js http.ClientRequest, respecting backpressure.
- * Handles ReadableStream, Uint8Array, ArrayBuffer, and string body types.
+ * Handles ReadableStream, Uint8Array, ArrayBuffer, string, URLSearchParams and Blob bodies.
  *
  * @param req  - Node.js ClientRequest
  * @param body - Request body
@@ -1166,8 +1185,28 @@ async function pipeBodyToNodeReq(req, body) {
         req.end(body);
     }
     else {
-        req.end();
+        // The raw Node transports bypass fetch, so bodies fetch would normally
+        // serialize (URLSearchParams, Blob) must be encoded here. Skipping them
+        // silently sent an empty body to the server.
+        const bytes = await serializeRawBody(body);
+        req.end(bytes);
+    }
+}
+/**
+ * Serialize body types that `fetch` would normally encode for us, so the raw
+ * Node HTTP/1.1 and HTTP/2 transports do not silently send an empty payload.
+ *
+ * @param body - Request body that is not a stream, byte array, or string
+ * @returns The encoded bytes to write (empty for unsupported types)
+ */
+async function serializeRawBody(body) {
+    if (typeof URLSearchParams !== "undefined" && body instanceof URLSearchParams) {
+        return new TextEncoder().encode(body.toString());
+    }
+    if (typeof Blob !== "undefined" && body instanceof Blob) {
+        return new Uint8Array(await body.arrayBuffer());
     }
+    return new Uint8Array(0);
 }
 // ============================================================================
 // §10  DECOMPRESSION

package/dist/cjs/dedup.js

@@ -136,6 +136,15 @@ export class DedupMap {
                 this.inflight.delete(key);
             }
             else {
+                // Clear any previous timer for this key first. Registering a new
+                // window without clearing the old one let the stale timer fire later
+                // and `inflight.delete(key)` — wiping the *new*, still-in-flight entry
+                // out from under callers that were sharing it.
+                const stale = this.timeouts.get(key);
+                if (stale !== undefined) {
+                    clearTimeout(stale);
+                    this.timeouts.delete(key);
+                }
                 const timeoutId = setTimeout(() => {
                     this.inflight.delete(key);
                     this.timeouts.delete(key);
@@ -177,13 +186,6 @@ export class DedupMap {
     get keys() {
         return [...this.inflight.keys()];
     }
-    /**
-     * Get comprehensive deduplication statistics.
-     * NOTE: inFlightCount and trackedKeys reflect snapshot time; entries may
-     * resolve asynchronously between sampling and return (non-blocking, acceptable).
-     *
-     * @returns Snapshot of hits, misses, hit rate, and tracked entries
-     */
     /**
      * Get comprehensive deduplication statistics.
      *

package/dist/cjs/digest.js

@@ -550,3 +550,29 @@ export async function createDigestAuthorization(wwwAuth, username, password, met
     const response = await computeDigestResponse(challenge, username, password, method, uri, cnonce, nc);
     return formatDigestAuth(challenge, username, response, uri, cnonce, nc);
 }
+/**
+ * Stateful Digest-auth authorizer.
+ *
+ * Keeps a per-nonce request counter and increments it on every call, as
+ * RFC 7616 §3.4.1 requires: `nc` is the hex request count for the current
+ * nonce and MUST increase for each request. The stateless
+ * {@link createDigestAuthorization} always sends 00000001, which replay-
+ * protecting servers (nginx, Apache with `AuthDigestNonceLifetime`) reject on
+ * the second request. A new nonce (challenge change) resets the counter to 1.
+ *
+ * Not safe to share across clients that authenticate as different users —
+ * create one per client.
+ */
+export function createDigestAuthorizer() {
+    const counters = new Map();
+    return async (wwwAuth, username, password, method, uri) => {
+        const challenge = parseDigestChallenge(wwwAuth);
+        const cnonce = randomBytes(5);
+        const scope = `${challenge.realm}\u0000${challenge.nonce}`;
+        const next = (counters.get(scope) ?? 0) + 1;
+        counters.set(scope, next);
+        const nc = next.toString(16).padStart(8, "0");
+        const response = await computeDigestResponse(challenge, username, password, method, uri, cnonce, nc);
+        return formatDigestAuth(challenge, username, response, uri, cnonce, nc);
+    };
+}

package/dist/cjs/headers.js

@@ -897,6 +897,31 @@ export function formatContentDisposition(cd) {
  * @param value - Raw `Cache-Control` header value
  * @returns Structured directives object with boolean flags and numeric values
  */
+/**
+ * Split a `Cache-Control` value on commas, ignoring commas inside a quoted
+ * string. RFC 7234 §5.2 allows quoted-string values that contain commas, e.g.
+ * `private="field1, field2"`, so a plain `split(",")` corrupts them.
+ *
+ * @param value - Raw `Cache-Control` header value
+ * @returns Each directive as its own (untrimmed) string
+ */
+function splitCacheControlDirectives(value) {
+    const parts = [];
+    let current = "";
+    let inQuotes = false;
+    for (const ch of value) {
+        if (ch === '"')
+            inQuotes = !inQuotes;
+        if (ch === "," && !inQuotes) {
+            parts.push(current);
+            current = "";
+            continue;
+        }
+        current += ch;
+    }
+    parts.push(current);
+    return parts;
+}
 export function parseCacheControl(value) {
     const d = {
         noCache: false,
@@ -917,7 +942,7 @@ export function parseCacheControl(value) {
         staleWhileRevalidate: null,
         unknown: new Map(),
     };
-    for (const part of value.split(",")) {
+    for (const part of splitCacheControlDirectives(value)) {
         const t = part.trim();
         const eq = t.indexOf("=");
         const k = (eq === -1 ? t : t.slice(0, eq)).trim().toLowerCase();
@@ -1379,17 +1404,48 @@ export function normalizeForwardedHeaders(headers) {
     };
 }
 /**
- * Extract the real client IP from Forwarded, X-Forwarded-For, or X-Real-IP
- * headers (in priority order).
+ * Extract the client IP from Forwarded, X-Forwarded-For, or X-Real-IP.
+ *
+ * ⚠️ SECURITY: the value is derived from client-supplied headers and must NOT be
+ * used for access control, rate limiting or audit trails unless `trustedHops` is
+ * set to the real number of proxies in front of the server. The returned string
+ * is also not validated as an IP address.
  *
  * @param headers - Source headers object
- * @returns First client IP found, or `null` if none present
+ * @param options - Trust configuration
+ * @returns The selected client IP, or `null` if none present
  */
-export function getClientIP(headers) {
+export function getClientIP(headers, options = {}) {
+    const trustedHops = Math.max(0, Math.trunc(options.trustedHops ?? 0));
     const fwd = normalizeForwardedHeaders(headers);
-    if (fwd.for.length > 0)
-        return fwd.for[0];
-    return headers.get(HeaderName.XRealIP);
+    if (fwd.for.length > 0) {
+        const list = fwd.for;
+        // Right-most entry is the closest hop. trustedHops = 1 → the entry the
+        // nearest trusted proxy appended; index = length - trustedHops.
+        const index = trustedHops === 0 ? 0 : list.length - trustedHops;
+        const value = list[index] ?? list[0];
+        return stripIPPortAndBrackets(value);
+    }
+    return stripIPPortAndBrackets(headers.get(HeaderName.XRealIP) ?? "") || null;
+}
+/**
+ * Normalize a Forwarded/XFF entry to a bare host: strip `for="…"` quoting,
+ * `[ipv6]:port`, and a bare `:port` suffix.
+ */
+function stripIPPortAndBrackets(value) {
+    let v = value.trim();
+    if (v.startsWith('"') && v.endsWith('"') && v.length >= 2)
+        v = v.slice(1, -1);
+    if (v.startsWith("[")) {
+        const end = v.indexOf("]");
+        if (end !== -1)
+            return v.slice(1, end);
+    }
+    // Only strip a trailing :digits (never the colons inside an IPv6 literal).
+    const m = /^(.*):\d+$/.exec(v);
+    if (m && (m[1] ?? "").includes("."))
+        return m[1];
+    return v;
 }
 /**
  * Parse a Retry-After header which may be either delta-seconds or an

package/dist/cjs/interceptors.js

@@ -27,6 +27,7 @@
  *  - Metrics interceptor   (timing, status buckets, error rates)
  *  - No dependencies, no runtime globals beyond Promise/Map/Set
  */
+import { getAuthFingerprint } from "./cache.js";
 // ============================================================================
 // §3  INTERCEPTOR MANAGER
 // ============================================================================
@@ -34,8 +35,18 @@ let _idSeq = 0;
 function nextId() {
     return `interceptor_${++_idSeq}`;
 }
-function sortByPriority(arr) {
-    return [...arr].sort((a, b) => a.priority - b.priority);
+/**
+ * Insert keeping ascending priority order. Sorting at registration (once)
+ * instead of on every request avoids copying the whole array three times per
+ * request, and Array#sort is stable so equal priorities keep registration
+ * order — the same result the old per-request sort produced.
+ */
+function insertByPriority(arr, entry) {
+    const at = arr.findIndex((x) => x.priority > entry.priority);
+    if (at === -1)
+        arr.push(entry);
+    else
+        arr.splice(at, 0, entry);
 }
 /**
  * Manages registration, ejection, and pipeline execution of interceptors.
@@ -57,7 +68,7 @@ export class InterceptorManager {
      */
     useRequest(fn, opts = {}) {
         const id = opts.id ?? nextId();
-        this.requestInterceptors.push({
+        insertByPriority(this.requestInterceptors, {
             id,
             priority: opts.priority ?? 0,
             once: opts.once ?? false,
@@ -75,7 +86,7 @@ export class InterceptorManager {
      */
     useResponse(fn, opts = {}) {
         const id = opts.id ?? nextId();
-        this.responseInterceptors.push({
+        insertByPriority(this.responseInterceptors, {
             id,
             priority: opts.priority ?? 0,
             once: opts.once ?? false,
@@ -93,7 +104,7 @@ export class InterceptorManager {
      */
     useError(fn, opts = {}) {
         const id = opts.id ?? nextId();
-        this.errorInterceptors.push({
+        insertByPriority(this.errorInterceptors, {
             id,
             priority: opts.priority ?? 0,
             once: opts.once ?? false,
@@ -178,7 +189,7 @@ export class InterceptorManager {
         // Collect IDs to eject after iteration (avoids modifying array during for-of)
         const toEject = new Set();
         // ── Request phase ──────────────────────────────────────────────────────
-        for (const interceptor of sortByPriority(this.requestInterceptors)) {
+        for (const interceptor of this.requestInterceptors) {
             if (ctx.aborted)
                 break;
             if (interceptor.condition && !interceptor.condition(ctx))
@@ -225,7 +236,7 @@ export class InterceptorManager {
     async _runResponsePhase(ctx, dispatcher) {
         // Collect IDs to eject after iteration
         const toEject = new Set();
-        for (const interceptor of sortByPriority(this.responseInterceptors)) {
+        for (const interceptor of this.responseInterceptors) {
             if (ctx.aborted)
                 break;
             if (interceptor.condition && !interceptor.condition(ctx))
@@ -268,7 +279,7 @@ export class InterceptorManager {
     async _runErrorPhase(ctx, dispatcher) {
         // Collect IDs to eject after iteration
         const toEject = new Set();
-        for (const interceptor of sortByPriority(this.errorInterceptors)) {
+        for (const interceptor of this.errorInterceptors) {
             if (interceptor.condition && !interceptor.condition(ctx))
                 continue;
             let result;
@@ -758,13 +769,22 @@ const CACHE_STALE_KEY = Symbol("cacheStale");
  */
 export function createDedupeInterceptor() {
     const inflight = new Map();
-    function key(req) {
-        return `${req.method.toUpperCase()}:${req.url}`;
+    /**
+     * Dedupe key. SECURITY: the auth fingerprint is part of the key. Without it,
+     * two callers with different Authorization / Cookie / API-key headers for the
+     * same URL were coalesced and one user received the other user's response.
+     */
+    async function key(req) {
+        const authFp = await getAuthFingerprint((req.headers ?? {}));
+        return `${req.method.toUpperCase()}:${req.url}${authFp ? ":" + authFp : ""}`;
     }
-    const requestInterceptor = (ctx) => {
+    const requestInterceptor = async (ctx) => {
         if (ctx.request.method.toUpperCase() !== "GET" && ctx.request.method.toUpperCase() !== "HEAD")
             return;
-        const k = key(ctx.request);
+        const k = await key(ctx.request);
+        // Stash the key on the context so the response/error phases can find this
+        // request' slot without re-deriving it.
+        ctx.store.set(DEDUPE_KEY, k);
         const slot = inflight.get(k);
         if (!slot) {
             // First request for this key — create in-flight entry
@@ -774,39 +794,61 @@ export function createDedupeInterceptor() {
             });
             return;
         }
-        // A request is already in flight — queue up
-        ctx.store.set(DEDUPE_QUEUED_KEY, k);
-        // Return a Promise that resolves to InterceptorResponse (which is a valid RequestInterceptorResult)
+        // A request is already in flight — queue up. A queued caller must never be
+        // left hanging if its own signal aborts while it waits for the leader.
         return new Promise((resolve, reject) => {
-            slot.waiters.push({
+            const signal = ctx.request.signal;
+            const waiter = {
                 resolve: (res) => resolve(res),
                 reject: (err) => reject(err), // Properly reject instead of throwing
-            });
+                cleanup: () => signal?.removeEventListener("abort", onQueuedAbort),
+            };
+            const onQueuedAbort = () => {
+                const at = slot.waiters.indexOf(waiter);
+                if (at !== -1)
+                    slot.waiters.splice(at, 1);
+                reject(new Error("Request aborted while queued for deduplication"));
+            };
+            if (signal?.aborted) {
+                onQueuedAbort();
+                return;
+            }
+            signal?.addEventListener("abort", onQueuedAbort, { once: true });
+            slot.waiters.push(waiter);
         });
     };
     const responseInterceptor = (ctx) => {
         if (!ctx.response)
             return;
-        const k = key(ctx.request);
+        const k = ctx.store.get(DEDUPE_KEY);
+        if (!k)
+            return;
         const slot = inflight.get(k);
         if (!slot)
             return;
         inflight.delete(k);
-        for (const w of slot.waiters)
+        for (const w of slot.waiters.splice(0)) {
+            w.cleanup();
             w.resolve(ctx.response);
+        }
     };
     const errorInterceptor = (ctx) => {
-        const k = key(ctx.request);
+        const k = ctx.store.get(DEDUPE_KEY);
+        if (!k)
+            return;
         const slot = inflight.get(k);
         if (!slot)
             return;
         inflight.delete(k);
-        for (const w of slot.waiters)
+        for (const w of slot.waiters.splice(0)) {
+            w.cleanup();
             w.reject(ctx.error);
+        }
     };
     return { requestInterceptor, responseInterceptor, errorInterceptor };
 }
-const DEDUPE_QUEUED_KEY = Symbol("dedupeQueued");
+/** ctx.store key holding this request's dedupe key. */
+const DEDUPE_KEY = Symbol("dedupeKey");
 const RATE_LIMIT_DEFAULTS = {
     limit: 60,
     windowMs: 60_000,

package/dist/cjs/logging.js

@@ -723,7 +723,7 @@ export class HTTPLogger {
      * ```ts
      * const logger = createProductionLogger();
      * const child = logger.child({ requestId: "req-123", userId: "user-456" });
-     * child.logRequest(...); // Logs will include both requestId and userId
+     * child.logRequest("req-123", "GET", "/users", {}, null, 1); // Logs include both requestId and userId
      * ```
      */
     child(context) {

package/dist/cjs/pagination.js

@@ -478,12 +478,20 @@ function sleep(ms, signal) {
             r();
             return;
         }
-        const timer = setTimeout(r, ms);
-        if (signal)
-            signal.addEventListener("abort", () => {
-                clearTimeout(timer);
-                r();
-            }, { once: true });
+        // The listener is removed on the timer path too. With `{ once: true }` it
+        // only self-removes when it FIRES, so a long-lived signal shared by many
+        // paginated requests accumulated one dead listener per completed sleep
+        // (MaxListeners warning + retained closures).
+        const onAbort = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+            r();
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            r();
+        }, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
     });
 }
 /**