@juspay/neurolink 9.95.3 → 10.0.1

package/dist/lib/utils/fileDetector.js

@@ -25,7 +25,7 @@ import { CSVProcessor } from "./csvProcessor.js";
 import { ImageProcessor } from "./imageProcessor.js";
 import { logger } from "./logger.js";
 import { withTimeout } from "./errorHandling.js";
-import { redactUrlForError, sanitizeErrorCause } from "./logSanitize.js";
+import { normalizeUrlForCache, redactUrlForError, sanitizeErrorCause, } from "./logSanitize.js";
 import { mimeHintToExtension, mimeHintToFileType, normalizeMimeHint, } from "./mimeTypeHints.js";
 import { PDFProcessor } from "./pdfProcessor.js";
 /**
@@ -54,22 +54,40 @@ const DEFAULT_RETRY_DELAY = 1000; // milliseconds
 const URL_CONTENT_TYPE_TTL_MS = 60_000;
 const URL_CONTENT_TYPE_CACHE_MAX_SIZE = 512;
 const urlContentTypeCache = new Map();
+/**
+ * Build the Map key for `urlContentTypeCache`. Delegates to the shared
+ * {@link normalizeUrlForCache} — this is a module-level, process-lifetime
+ * cache, so it must strip presigned-URL auth/signature query params (see
+ * `SENSITIVE_URL_QUERY_PARAM_DENYLIST`) the same way `ImageCache.normalizeUrl`
+ * does, folding a short hash of the stripped params into the key whenever any
+ * were present so two different presigned URLs for the same path don't
+ * collide and serve each other's cached content-type across auth contexts.
+ * Also strips tracking/analytics params first, so two URLs differing only by
+ * tracking noise (e.g. `utm_source`) still hit the same cache entry instead
+ * of missing each other. Falls back to the raw URL if it isn't a parseable
+ * absolute URL. Shared by both `getCachedUrlContentType` and
+ * `setCachedUrlContentType` so lookups and writes always agree on the key.
+ */
+function cacheKeyForUrl(url) {
+    return normalizeUrlForCache(url);
+}
 function getCachedUrlContentType(url, now) {
-    const hit = urlContentTypeCache.get(url);
+    const key = cacheKeyForUrl(url);
+    const hit = urlContentTypeCache.get(key);
     if (hit && hit.expiresAt > now) {
         // Bump recency: Map iteration order follows insertion order, and the
         // eviction below deletes the *first* key, so a plain `get` on a hot
         // entry would leave it first in line for eviction despite being the
         // most recently used. Re-inserting turns the size-bounded FIFO below
         // into an actual LRU.
-        urlContentTypeCache.delete(url);
-        urlContentTypeCache.set(url, hit);
+        urlContentTypeCache.delete(key);
+        urlContentTypeCache.set(key, hit);
         return hit.contentType;
     }
     if (hit) {
         // Entry exists but its TTL has passed — treat as a miss and evict it
         // immediately rather than serving (or retaining) stale data.
-        urlContentTypeCache.delete(url);
+        urlContentTypeCache.delete(key);
     }
     return undefined;
 }
@@ -89,7 +107,8 @@ function setCachedUrlContentType(url, contentType, now) {
     if (!contentType) {
         return;
     }
-    urlContentTypeCache.set(url, {
+    const key = cacheKeyForUrl(url);
+    urlContentTypeCache.set(key, {
         contentType,
         expiresAt: now + URL_CONTENT_TYPE_TTL_MS,
     });
@@ -1436,16 +1455,25 @@ export class FileDetector {
                 });
                 // Drain/close the (empty) HEAD body so the connection can be reused.
                 await head.body.dump();
-                const declaredLength = Number(head.headers["content-length"]);
-                if (Number.isFinite(declaredLength) && declaredLength > maxSize) {
-                    throw new Error(`File too large: ${formatFileSize(declaredLength)} (max: ${formatFileSize(maxSize)})`);
+                // Only trust `content-length` on a genuine 2xx response. A non-2xx
+                // HEAD (redirect the dispatcher didn't follow, 403/404/405 "HEAD not
+                // allowed", 5xx, …) can still carry a stale/irrelevant
+                // `content-length` header — enforcing size off of that would reject
+                // (or silently pass) based on the wrong body. Treat any non-2xx HEAD
+                // as if the header were missing and fall through to the streaming
+                // GET guard below, which enforces maxSize independently either way.
+                if (head.statusCode >= 200 && head.statusCode < 300) {
+                    const declaredLength = Number(head.headers["content-length"]);
+                    if (Number.isFinite(declaredLength) && declaredLength > maxSize) {
+                        throw new Error(`File too large: ${formatFileSize(declaredLength)} (max: ${formatFileSize(maxSize)})`);
+                    }
                 }
             }
             catch (error) {
                 if (error instanceof Error && /File too large/.test(error.message)) {
                     throw error;
                 }
-                logger.debug(`[FileDetector] HEAD pre-flight skipped for ${url}: ${error instanceof Error ? error.message : String(error)}`);
+                logger.debug(`[FileDetector] HEAD pre-flight skipped for ${redactUrlForError(url)}: ${sanitizeErrorCause(error).message}`);
             }
         }
         return withRetry(async () => {

package/dist/lib/utils/imageCache.d.ts

@@ -33,8 +33,16 @@ export declare class ImageCache {
      */
     private parseConfigValue;
     /**
-     * Normalize URL for consistent cache key generation
-     * Removes tracking parameters and normalizes the URL
+     * Normalize URL for consistent cache key generation.
+     *
+     * Delegates to the shared {@link normalizeUrlForCache} — this normalized
+     * URL is used as the in-memory Map key (see `get`/`set` below), which lives
+     * for the process lifetime, so both tracking-param noise and presigned-URL
+     * auth/signature secrets must be stripped consistently with
+     * `fileDetector.cacheKeyForUrl`'s identical requirement. See
+     * `stripSensitiveUrlParamsForCacheKey`'s doc comment for why a naive
+     * strip-only approach (no hash suffix) would be a correctness bug, not just
+     * a hygiene one.
      */
     private normalizeUrl;
     /**

package/dist/lib/utils/imageCache.js

@@ -14,7 +14,7 @@
  */
 import { createHash } from "crypto";
 import { logger } from "./logger.js";
-import { redactUrlForError } from "./logSanitize.js";
+import { normalizeUrlForCache, redactUrlForError } from "./logSanitize.js";
 /**
  * LRU Cache for downloaded images
  *
@@ -85,30 +85,19 @@ export class ImageCache {
         return value;
     }
     /**
-     * Normalize URL for consistent cache key generation
-     * Removes tracking parameters and normalizes the URL
+     * Normalize URL for consistent cache key generation.
+     *
+     * Delegates to the shared {@link normalizeUrlForCache} — this normalized
+     * URL is used as the in-memory Map key (see `get`/`set` below), which lives
+     * for the process lifetime, so both tracking-param noise and presigned-URL
+     * auth/signature secrets must be stripped consistently with
+     * `fileDetector.cacheKeyForUrl`'s identical requirement. See
+     * `stripSensitiveUrlParamsForCacheKey`'s doc comment for why a naive
+     * strip-only approach (no hash suffix) would be a correctness bug, not just
+     * a hygiene one.
      */
     normalizeUrl(url) {
-        try {
-            const parsed = new URL(url);
-            // Remove common tracking parameters that don't affect content
-            const trackingParams = [
-                "utm_source",
-                "utm_medium",
-                "utm_campaign",
-                "utm_term",
-                "utm_content",
-                "fbclid",
-                "gclid",
-                "_ga",
-            ];
-            trackingParams.forEach((param) => parsed.searchParams.delete(param));
-            return parsed.toString();
-        }
-        catch {
-            // If URL parsing fails, use the original URL
-            return url;
-        }
+        return normalizeUrlForCache(url);
     }
     /**
      * Generate content hash from image data

package/dist/lib/utils/imageProcessor.d.ts

@@ -13,6 +13,31 @@ export declare const MIN_IMAGE_SIZE = 12;
  * buffer that carries a format's magic bytes but is smaller than this is
  * truncated/corrupt and would fail (or render blank) downstream — reject early
  * with a clear message instead.
+ *
+ * Each threshold approximates the smallest byte count that format's
+ * container can structurally be while still holding the mandatory
+ * header/chunk skeleton for a minimal (e.g. 1×1 pixel) image — not an exact
+ * spec minimum, but close enough that anything smaller is unambiguously
+ * truncated:
+ *  - **PNG (67)**: 8-byte signature + IHDR chunk (4 len + 4 type + 13 data +
+ *    4 CRC = 25) + a minimal IDAT chunk carrying one zlib-compressed
+ *    scanline (~22 bytes) + IEND chunk (4 len + 4 type + 0 data + 4 CRC =
+ *    12) — matches the commonly-cited size of the smallest possible valid
+ *    PNG (a 1×1 transparent pixel).
+ *  - **JPEG (125)**: SOI + APP0/JFIF marker (18) + at least one DQT
+ *    quantization table (~69 for one 8-bit luma table) + SOF0 + DHT + SOS
+ *    headers + a minimal entropy-coded scan + EOI — the smallest legal
+ *    baseline-JPEG skeleton for a 1×1 image.
+ *  - **GIF (43)**: 6-byte GIF87a/89a header + 7-byte Logical Screen
+ *    Descriptor + a 2-color (6-byte) color table + 10-byte Image
+ *    Descriptor + minimal LZW-coded image sub-blocks + 1-byte trailer.
+ *  - **WEBP (20)**: RIFF container header ("RIFF" + size + "WEBP" = 12
+ *    bytes) + the first chunk's fourCC + size (8 bytes) — enough to confirm
+ *    a well-formed RIFF/WEBP container and its first chunk, before any
+ *    actual VP8/VP8L bitstream payload.
+ *  - **AVIF (100)**: ISOBMFF `ftyp` box plus the mandatory `meta` box
+ *    skeleton (`hdlr`/`pitm`/`iloc`/`iinf` sub-boxes) — roughly the minimum
+ *    to hold AVIF's required box structure before any AV1 image item data.
  */
 export declare const MIN_VALID_IMAGE_SIZE: Record<string, number>;
 /**

package/dist/lib/utils/imageProcessor.js

@@ -20,6 +20,31 @@ export const MIN_IMAGE_SIZE = 12;
  * buffer that carries a format's magic bytes but is smaller than this is
  * truncated/corrupt and would fail (or render blank) downstream — reject early
  * with a clear message instead.
+ *
+ * Each threshold approximates the smallest byte count that format's
+ * container can structurally be while still holding the mandatory
+ * header/chunk skeleton for a minimal (e.g. 1×1 pixel) image — not an exact
+ * spec minimum, but close enough that anything smaller is unambiguously
+ * truncated:
+ *  - **PNG (67)**: 8-byte signature + IHDR chunk (4 len + 4 type + 13 data +
+ *    4 CRC = 25) + a minimal IDAT chunk carrying one zlib-compressed
+ *    scanline (~22 bytes) + IEND chunk (4 len + 4 type + 0 data + 4 CRC =
+ *    12) — matches the commonly-cited size of the smallest possible valid
+ *    PNG (a 1×1 transparent pixel).
+ *  - **JPEG (125)**: SOI + APP0/JFIF marker (18) + at least one DQT
+ *    quantization table (~69 for one 8-bit luma table) + SOF0 + DHT + SOS
+ *    headers + a minimal entropy-coded scan + EOI — the smallest legal
+ *    baseline-JPEG skeleton for a 1×1 image.
+ *  - **GIF (43)**: 6-byte GIF87a/89a header + 7-byte Logical Screen
+ *    Descriptor + a 2-color (6-byte) color table + 10-byte Image
+ *    Descriptor + minimal LZW-coded image sub-blocks + 1-byte trailer.
+ *  - **WEBP (20)**: RIFF container header ("RIFF" + size + "WEBP" = 12
+ *    bytes) + the first chunk's fourCC + size (8 bytes) — enough to confirm
+ *    a well-formed RIFF/WEBP container and its first chunk, before any
+ *    actual VP8/VP8L bitstream payload.
+ *  - **AVIF (100)**: ISOBMFF `ftyp` box plus the mandatory `meta` box
+ *    skeleton (`hdlr`/`pitm`/`iloc`/`iinf` sub-boxes) — roughly the minimum
+ *    to hold AVIF's required box structure before any AV1 image item data.
  */
 export const MIN_VALID_IMAGE_SIZE = {
     "image/png": 67,
@@ -932,7 +957,9 @@ export const imageUtils = {
         const cache = getImageCache();
         const cached = cache.get(url);
         if (cached) {
-            logger.debug("Using cached image for URL", { url: url.substring(0, 50) });
+            logger.debug("Using cached image for URL", {
+                url: redactUrlForError(url),
+            });
             return cached.dataUri;
         }
         // Apply rate limiting before download

package/dist/lib/utils/logSanitize.d.ts

@@ -110,6 +110,103 @@ export declare function redactUrlCredentials(url: string): string;
  * @param url - The URL (or URL-shaped string) to redact.
  */
 export declare function redactUrlForError(url: string): string;
+/**
+ * Query-parameter names that commonly carry authentication/signature
+ * secrets in presigned URLs, matched case-insensitively: generic
+ * `token`/`signature`, AWS SigV4 (`X-Amz-Signature`, `X-Amz-Credential`,
+ * `X-Amz-Security-Token`, and the legacy `AWSAccessKeyId`/`Signature`/
+ * `Expires` query-auth params), Azure SAS (`sig`/`se`/`sp`/`sr`/`sv`), and
+ * GCS V4 signed URLs (`X-Goog-Signature`, `X-Goog-Credential`,
+ * `X-Goog-Algorithm`, `X-Goog-Date`, `X-Goog-Expires`,
+ * `X-Goog-SignedHeaders`).
+ *
+ * Unlike {@link redactUrlForError} (which drops the *entire* query string
+ * for a one-off error message), this is used where a URL is normalized
+ * into a long-lived in-memory cache key — content-varying query params
+ * must survive so distinct resources still get distinct keys, but a
+ * presigned URL's secret must never persist as a Map key for the process
+ * lifetime.
+ */
+export declare const SENSITIVE_URL_QUERY_PARAM_DENYLIST: readonly string[];
+/**
+ * Strip common tracking/analytics query params (`utm_*`, `fbclid`, `gclid`,
+ * `_ga`) from `parsed` in place, so callers that build a cache key from a
+ * URL don't miss a cache hit solely because two otherwise-identical URLs
+ * carry different tracking noise.
+ *
+ * Shared by `ImageCache.normalizeUrl` and `fileDetector.cacheKeyForUrl` —
+ * both build a long-lived in-memory cache key from a URL and should
+ * normalize tracking params the same way. Call this before
+ * {@link stripSensitiveUrlParamsForCacheKey} so both normalizations apply
+ * consistently regardless of caller.
+ *
+ * @param parsed - A `URL` instance to strip tracking params from in place.
+ */
+export declare function stripTrackingParams(parsed: URL): void;
+/**
+ * Build a secret-free, but still auth-context-distinct, cache key from a
+ * URL that may carry presigned-URL secrets in its query string.
+ *
+ * Naively stripping {@link SENSITIVE_URL_QUERY_PARAM_DENYLIST} params before
+ * using a URL as a long-lived cache key (an earlier version of this code did
+ * exactly that) creates a correctness bug, not just a hygiene one: two
+ * *different* presigned URLs for the same underlying object — e.g. one
+ * whose signature has since expired or been revoked, and a fresh one —
+ * strip down to the *same* key and collide. A cache populated under the
+ * first would silently serve its bytes back for the second, without ever
+ * revalidating against the origin.
+ *
+ * Fix: still remove the sensitive params from `parsed` in place (so the
+ * plaintext key never retains a raw secret — the original goal), but fold a
+ * short, non-reversible hash of the *removed* key=value pairs into the
+ * returned suffix whenever any were present, so distinct auth contexts keep
+ * distinct cache keys. Two requests presenting the exact same secret value
+ * still collide (correct — that's genuinely the same authorized request);
+ * two different secret values for the same object no longer do.
+ *
+ * Callers combine the return value with the now-stripped `parsed.toString()`
+ * to form the final cache key (see `ImageCache.normalizeUrl` and
+ * `fileDetector.cacheKeyForUrl`), rather than this function returning the
+ * full key itself, so each caller can apply its own additional
+ * normalization (e.g. tracking-param removal) in between.
+ *
+ * Matching against {@link SENSITIVE_URL_QUERY_PARAM_DENYLIST} is
+ * case-insensitive (both the denylist lookup and the value folded into the
+ * hash lower-case the param name), so the original casing of a sensitive
+ * param's name is not preserved anywhere in the returned key. That's fine
+ * here — this produces a cache key, not a user-facing URL, and the same
+ * lower-cased name always hashes to the same suffix for the same value
+ * regardless of how the caller happened to case it (`Token=` vs `token=`).
+ * Non-sensitive params left on `parsed` keep their original casing untouched.
+ *
+ * @param parsed - A `URL` instance to strip sensitive params from in place.
+ * @returns "" when no sensitive params were present; otherwise a short hex
+ *   suffix — prefixed with `\0` (a byte `URL#toString()` never emits, since
+ *   every URL component is percent-encoded, so it can't collide with real
+ *   URL content) — to append to the caller's cache key.
+ */
+export declare function stripSensitiveUrlParamsForCacheKey(parsed: URL): string;
+/**
+ * Build a secret-free, auth-context-distinct cache key from a URL, for any
+ * caller that needs a long-lived in-memory Map key derived from a URL.
+ *
+ * Centralizes the exact sequence both existing callers used independently:
+ * parse via `new URL()`, strip tracking noise ({@link stripTrackingParams}),
+ * then strip and hash-suffix sensitive auth params
+ * ({@link stripSensitiveUrlParamsForCacheKey}) so distinct presigned URLs for
+ * the same object don't collide (see that function's doc comment for why a
+ * naive strip-only approach is a correctness bug, not just a hygiene one).
+ *
+ * Shared by `ImageCache.normalizeUrl` and `fileDetector.cacheKeyForUrl` — both
+ * build a cache key from a URL and must normalize it identically, or the same
+ * URL could hash to two different keys depending on which cache looked it up.
+ *
+ * Falls back to the raw `url` string unchanged when it isn't a parseable
+ * absolute URL (mirrors both callers' pre-existing catch behavior).
+ *
+ * @param url - The URL (or URL-shaped string) to normalize into a cache key.
+ */
+export declare function normalizeUrlForCache(url: string): string;
 /**
  * Scrub any embedded absolute URLs out of free-form text — typically the
  * `.message` of an underlying network/DNS/TLS error thrown by `fetch`,

package/dist/lib/utils/logSanitize.js

@@ -15,6 +15,7 @@
  *     jina_ (Jina), fish- (Fish Audio)
  *   - Generic key=value pairs: api_key=…, access_token: …, secret_key=…
  */
+import { createHash } from "crypto";
 import { basename, resolve as resolvePath } from "path";
 const TOKEN_PREFIXES = [
     "sk",
@@ -227,6 +228,168 @@ export function redactUrlForError(url) {
         return truncate(redactUrlCredentials(withoutQueryOrFragment));
     }
 }
+/**
+ * Query-parameter names that commonly carry authentication/signature
+ * secrets in presigned URLs, matched case-insensitively: generic
+ * `token`/`signature`, AWS SigV4 (`X-Amz-Signature`, `X-Amz-Credential`,
+ * `X-Amz-Security-Token`, and the legacy `AWSAccessKeyId`/`Signature`/
+ * `Expires` query-auth params), Azure SAS (`sig`/`se`/`sp`/`sr`/`sv`), and
+ * GCS V4 signed URLs (`X-Goog-Signature`, `X-Goog-Credential`,
+ * `X-Goog-Algorithm`, `X-Goog-Date`, `X-Goog-Expires`,
+ * `X-Goog-SignedHeaders`).
+ *
+ * Unlike {@link redactUrlForError} (which drops the *entire* query string
+ * for a one-off error message), this is used where a URL is normalized
+ * into a long-lived in-memory cache key — content-varying query params
+ * must survive so distinct resources still get distinct keys, but a
+ * presigned URL's secret must never persist as a Map key for the process
+ * lifetime.
+ */
+export const SENSITIVE_URL_QUERY_PARAM_DENYLIST = [
+    "token",
+    "signature",
+    "x-amz-signature",
+    "x-amz-credential",
+    "x-amz-security-token",
+    "awsaccesskeyid",
+    "expires",
+    "sig",
+    "se",
+    "sp",
+    "sr",
+    "sv",
+    "x-goog-signature",
+    "x-goog-credential",
+    "x-goog-algorithm",
+    "x-goog-date",
+    "x-goog-expires",
+    "x-goog-signedheaders",
+];
+/** Common tracking/analytics query params that don't affect the fetched
+ * content, so two URLs differing only by these should map to the same
+ * cache key rather than missing each other. */
+const TRACKING_URL_QUERY_PARAMS = [
+    "utm_source",
+    "utm_medium",
+    "utm_campaign",
+    "utm_term",
+    "utm_content",
+    "fbclid",
+    "gclid",
+    "_ga",
+];
+/**
+ * Strip common tracking/analytics query params (`utm_*`, `fbclid`, `gclid`,
+ * `_ga`) from `parsed` in place, so callers that build a cache key from a
+ * URL don't miss a cache hit solely because two otherwise-identical URLs
+ * carry different tracking noise.
+ *
+ * Shared by `ImageCache.normalizeUrl` and `fileDetector.cacheKeyForUrl` —
+ * both build a long-lived in-memory cache key from a URL and should
+ * normalize tracking params the same way. Call this before
+ * {@link stripSensitiveUrlParamsForCacheKey} so both normalizations apply
+ * consistently regardless of caller.
+ *
+ * @param parsed - A `URL` instance to strip tracking params from in place.
+ */
+export function stripTrackingParams(parsed) {
+    TRACKING_URL_QUERY_PARAMS.forEach((param) => parsed.searchParams.delete(param));
+}
+/**
+ * Build a secret-free, but still auth-context-distinct, cache key from a
+ * URL that may carry presigned-URL secrets in its query string.
+ *
+ * Naively stripping {@link SENSITIVE_URL_QUERY_PARAM_DENYLIST} params before
+ * using a URL as a long-lived cache key (an earlier version of this code did
+ * exactly that) creates a correctness bug, not just a hygiene one: two
+ * *different* presigned URLs for the same underlying object — e.g. one
+ * whose signature has since expired or been revoked, and a fresh one —
+ * strip down to the *same* key and collide. A cache populated under the
+ * first would silently serve its bytes back for the second, without ever
+ * revalidating against the origin.
+ *
+ * Fix: still remove the sensitive params from `parsed` in place (so the
+ * plaintext key never retains a raw secret — the original goal), but fold a
+ * short, non-reversible hash of the *removed* key=value pairs into the
+ * returned suffix whenever any were present, so distinct auth contexts keep
+ * distinct cache keys. Two requests presenting the exact same secret value
+ * still collide (correct — that's genuinely the same authorized request);
+ * two different secret values for the same object no longer do.
+ *
+ * Callers combine the return value with the now-stripped `parsed.toString()`
+ * to form the final cache key (see `ImageCache.normalizeUrl` and
+ * `fileDetector.cacheKeyForUrl`), rather than this function returning the
+ * full key itself, so each caller can apply its own additional
+ * normalization (e.g. tracking-param removal) in between.
+ *
+ * Matching against {@link SENSITIVE_URL_QUERY_PARAM_DENYLIST} is
+ * case-insensitive (both the denylist lookup and the value folded into the
+ * hash lower-case the param name), so the original casing of a sensitive
+ * param's name is not preserved anywhere in the returned key. That's fine
+ * here — this produces a cache key, not a user-facing URL, and the same
+ * lower-cased name always hashes to the same suffix for the same value
+ * regardless of how the caller happened to case it (`Token=` vs `token=`).
+ * Non-sensitive params left on `parsed` keep their original casing untouched.
+ *
+ * @param parsed - A `URL` instance to strip sensitive params from in place.
+ * @returns "" when no sensitive params were present; otherwise a short hex
+ *   suffix — prefixed with `\0` (a byte `URL#toString()` never emits, since
+ *   every URL component is percent-encoded, so it can't collide with real
+ *   URL content) — to append to the caller's cache key.
+ */
+export function stripSensitiveUrlParamsForCacheKey(parsed) {
+    const strippedPairs = [];
+    const keysToDelete = [];
+    for (const [key, value] of parsed.searchParams.entries()) {
+        if (SENSITIVE_URL_QUERY_PARAM_DENYLIST.includes(key.toLowerCase())) {
+            strippedPairs.push(`${key.toLowerCase()}=${value}`);
+            keysToDelete.push(key);
+        }
+    }
+    if (strippedPairs.length === 0) {
+        return "";
+    }
+    keysToDelete.forEach((key) => parsed.searchParams.delete(key));
+    // Sort so key order in the original URL doesn't affect the hash — the
+    // same *set* of secret values must always hash to the same suffix.
+    strippedPairs.sort();
+    const hash = createHash("sha256")
+        .update(strippedPairs.join("&"))
+        .digest("hex")
+        .slice(0, 16);
+    return `\0auth=${hash}`;
+}
+/**
+ * Build a secret-free, auth-context-distinct cache key from a URL, for any
+ * caller that needs a long-lived in-memory Map key derived from a URL.
+ *
+ * Centralizes the exact sequence both existing callers used independently:
+ * parse via `new URL()`, strip tracking noise ({@link stripTrackingParams}),
+ * then strip and hash-suffix sensitive auth params
+ * ({@link stripSensitiveUrlParamsForCacheKey}) so distinct presigned URLs for
+ * the same object don't collide (see that function's doc comment for why a
+ * naive strip-only approach is a correctness bug, not just a hygiene one).
+ *
+ * Shared by `ImageCache.normalizeUrl` and `fileDetector.cacheKeyForUrl` — both
+ * build a cache key from a URL and must normalize it identically, or the same
+ * URL could hash to two different keys depending on which cache looked it up.
+ *
+ * Falls back to the raw `url` string unchanged when it isn't a parseable
+ * absolute URL (mirrors both callers' pre-existing catch behavior).
+ *
+ * @param url - The URL (or URL-shaped string) to normalize into a cache key.
+ */
+export function normalizeUrlForCache(url) {
+    try {
+        const parsed = new URL(url);
+        stripTrackingParams(parsed);
+        const authSuffix = stripSensitiveUrlParamsForCacheKey(parsed);
+        return parsed.toString() + authSuffix;
+    }
+    catch {
+        return url;
+    }
+}
 /**
  * Scrub any embedded absolute URLs out of free-form text — typically the
  * `.message` of an underlying network/DNS/TLS error thrown by `fetch`,

package/dist/lib/utils/messageBuilder.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, statSync } from "fs";
 import { readFile as readFileAsync, stat as statAsync } from "fs/promises";
+import { basename } from "path";
 import { getGlobalDispatcher, interceptors, request } from "undici";
 import { MultimodalLogger, ProviderImageAdapter, } from "../adapters/providerImageAdapter.js";
 import { CONVERSATION_INSTRUCTIONS, STRUCTURED_OUTPUT_INSTRUCTIONS, } from "../config/conversationMemory.js";
@@ -1031,8 +1032,26 @@ async function processExplicitPdfFiles(options, maxSize, provider) {
     // it in aggregate (e.g. three 40-page PDFs → 120 pages for a 100-page API).
     const aggregateConfig = PDFProcessor.getProviderConfig(provider);
     if (aggregateConfig && pdfFiles.length > 1) {
+        // A null pageCount (accurate count unavailable — see
+        // PDFProcessor.getAccuratePageCount) is treated as 0 in the sum below,
+        // which can undercount the aggregate and let a combined request over
+        // the provider's page limit slip through silently. Enforcement still
+        // runs against the known sum — a PDF with an unknown count must not
+        // fail the request outright — but the gap itself must not be silent.
+        const unknownPageCountFiles = pdfFiles.filter((f) => f.pageCount === null || f.pageCount === undefined);
         const totalPages = pdfFiles.reduce((sum, f) => sum + (f.pageCount ?? 0), 0);
         const totalMB = pdfFiles.reduce((sum, f) => sum + f.buffer.length, 0) / (1024 * 1024);
+        if (unknownPageCountFiles.length > 0) {
+            // Filenames are caller-controlled and may be full paths carrying
+            // PII/internal directory segments — log only the basename.
+            const unknownFileNames = unknownPageCountFiles
+                .map((f) => (f.filename ? basename(f.filename) : "<unnamed file>"))
+                .join(", ");
+            logger.warn(`[PDF] Aggregate page-limit check across ${pdfFiles.length} PDFs could only be ` +
+                `partially verified: ${unknownPageCountFiles.length} file(s) have an unknown ` +
+                `page count (${unknownFileNames}), so the known total (${totalPages}) may ` +
+                `undercount the true combined page count.`);
+        }
         if (totalPages > aggregateConfig.maxPages) {
             throw new Error(`[PDF] Combined page count across ${pdfFiles.length} PDFs (${totalPages}) exceeds the ` +
                 `${aggregateConfig.maxPages}-page limit for ${provider}. ` +

package/dist/lib/utils/pdfProcessor.d.ts

@@ -81,7 +81,13 @@ export declare class PDFProcessor {
      * base64 PNG as soon as it renders instead of buffering the whole document,
      * and reports progress via `options.onProgress`. A page that fails to render
      * is yielded with `error` set (per-page isolation, #294) rather than aborting
-     * the stream. `convertToImages` is the batch wrapper over this contract.
+     * the stream.
+     *
+     * NOT a wrapper of/over {@link convertToImages}, despite the similar
+     * contract — the two are independent, parallel implementations (each does
+     * its own `pdf-to-img` import, downscale calculation, and page loop)
+     * rather than one delegating to the other. Keep behavior changes (page
+     * isolation, downscale, password handling) in sync across both by hand.
      */
     static convertToImagesStream(pdfBuffer: Buffer, options?: PDFImageConversionOptions): AsyncGenerator<PDFImagePage, void, void>;
     /**

package/dist/lib/utils/pdfProcessor.js

@@ -243,16 +243,34 @@ export class PDFProcessor {
         try {
             const { PDFParse } = await import("pdf-parse");
             const pdf = new PDFParse({ data: new Uint8Array(buffer) });
+            // Captured outside the try so the `finally` below can always clear it
+            // — otherwise a `getInfo()` that wins the race leaves this timer
+            // running until PAGE_COUNT_TIMEOUT_MS fires for nothing. `.unref()`
+            // so it can never itself hold the process open in the meantime.
+            let timeoutHandle;
             try {
                 const info = await Promise.race([
                     pdf.getInfo(),
-                    new Promise((_, reject) => setTimeout(() => reject(new Error("page-count timeout")), PDF_LIMITS.PAGE_COUNT_TIMEOUT_MS)),
+                    new Promise((_, reject) => {
+                        timeoutHandle = setTimeout(() => reject(new Error("page-count timeout")), PDF_LIMITS.PAGE_COUNT_TIMEOUT_MS);
+                        timeoutHandle.unref?.();
+                    }),
                 ]);
                 const total = info.total;
                 return typeof total === "number" && total > 0 ? total : null;
             }
             finally {
-                await pdf.destroy?.();
+                if (timeoutHandle !== undefined) {
+                    clearTimeout(timeoutHandle);
+                }
+                try {
+                    await pdf.destroy?.();
+                }
+                catch {
+                    // A throwing destroy() must not discard an otherwise-valid page
+                    // count returned above (matches fileReferenceRegistry.ts's
+                    // pdf.destroy() cleanup pattern) — swallow it.
+                }
             }
         }
         catch (error) {
@@ -518,7 +536,13 @@ export class PDFProcessor {
      * base64 PNG as soon as it renders instead of buffering the whole document,
      * and reports progress via `options.onProgress`. A page that fails to render
      * is yielded with `error` set (per-page isolation, #294) rather than aborting
-     * the stream. `convertToImages` is the batch wrapper over this contract.
+     * the stream.
+     *
+     * NOT a wrapper of/over {@link convertToImages}, despite the similar
+     * contract — the two are independent, parallel implementations (each does
+     * its own `pdf-to-img` import, downscale calculation, and page loop)
+     * rather than one delegating to the other. Keep behavior changes (page
+     * isolation, downscale, password handling) in sync across both by hand.
      */
     static async *convertToImagesStream(pdfBuffer, options) {
         const startTime = Date.now();