@juspay/neurolink 9.95.2 → 10.0.0

package/dist/lib/utils/pdfProcessor.js

@@ -150,6 +150,13 @@ export class PDFProcessor {
             throw new Error(`PDF size ${sizeMB.toFixed(2)}MB exceeds ${config.maxSizeMB}MB limit for ${provider}`);
         }
         const metadata = PDFProcessor.extractBasicMetadata(content);
+        // #287: prefer an accurate page count (pdf-parse/pdfjs) over the unreliable
+        // header regex for both limit enforcement and returned metadata; fall back
+        // to the regex estimate when the accurate probe times out or fails.
+        const accuratePages = await PDFProcessor.getAccuratePageCount(content);
+        if (accuratePages !== null) {
+            metadata.estimatedPages = accuratePages;
+        }
         if (metadata.estimatedPages && metadata.estimatedPages > config.maxPages) {
             const enforceLimits = options?.enforceLimits !== false;
             if (enforceLimits) {
@@ -185,6 +192,10 @@ export class PDFProcessor {
                 ...metadata,
                 provider,
                 apiType: config.apiType,
+                // #349: surface the provider's citations requirement so downstream
+                // provider adapters (e.g. Bedrock Converse document blocks) can act on
+                // it, instead of the config field being read nowhere.
+                requiresCitations: config.requiresCitations,
             },
         };
     }
@@ -220,6 +231,53 @@ export class PDFProcessor {
             filename: undefined,
         };
     }
+    /**
+     * Accurate page count via pdf-parse (pdfjs) (#287). The header regex in
+     * `extractBasicMetadata` only sees plaintext `/Type /Page` markers and misses
+     * compressed/object-stream PDFs (and miscounts when a page dict spans a chunk
+     * boundary). This parses the document properly, bounded by a timeout so a
+     * pathological PDF can't block; returns null on timeout/failure so the caller
+     * falls back to the regex estimate.
+     */
+    static async getAccuratePageCount(buffer) {
+        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) => {
+                        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 {
+                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) {
+            logger.debug(`[PDF] Accurate page count unavailable; using regex estimate: ${error instanceof Error ? error.message : String(error)}`);
+            return null;
+        }
+    }
     static estimateTokens(pageCount, mode = "visual") {
         if (mode === "text-only") {
             return Math.ceil((pageCount / 3) * 1000);
@@ -291,48 +349,32 @@ export class PDFProcessor {
      */
     static async convertToImages(pdfBuffer, options) {
         const startTime = Date.now();
-        const { scale = 2, maxPages = PDF_LIMITS.DEFAULT_MAX_PAGES, format = "png", maxCanvasPixels = PDF_LIMITS.DEFAULT_MAX_CANVAS_PIXELS, password, } = options || {};
+        const { scale = PDF_LIMITS.DEFAULT_SCALE, maxPages = PDF_LIMITS.DEFAULT_MAX_PAGES, format = "png", maxCanvasPixels = PDF_LIMITS.DEFAULT_MAX_CANVAS_PIXELS, password, onProgress, } = options || {};
         const images = [];
         const warnings = [];
-        // ============================================================================
-        // INPUT VALIDATION (Security: Prevent malformed/malicious PDF processing)
-        // ============================================================================
-        // 0. Validate format is supported and case-sensitive
-        if (format !== "png") {
-            throw new Error(`Invalid format: "${format}". Only "png" format is currently supported.`);
-        }
-        // 0b. Validate the render scale. A non-finite or non-positive scale yields a
-        // degenerate viewport (blank/zero-dimension render), and an excessive scale
-        // can allocate hundreds of MB per page — reject both with a clear message.
-        if (!Number.isFinite(scale) || scale <= 0 || scale > PDF_LIMITS.MAX_SCALE) {
-            throw new Error(`Invalid scale: ${scale}. Scale must be a finite number greater than 0 and at most ${PDF_LIMITS.MAX_SCALE}.`);
-        }
-        // 0c. Validate the per-page pixel ceiling (#260). A non-finite or
-        // non-positive value would disable the guard or yield a NaN downscale.
-        if (!Number.isFinite(maxCanvasPixels) || maxCanvasPixels <= 0) {
-            throw new Error(`Invalid maxCanvasPixels: ${maxCanvasPixels}. Must be a finite number greater than 0.`);
-        }
-        // 1. Validate buffer is not empty or too small
-        if (!pdfBuffer || pdfBuffer.length < 5) {
-            throw new Error("Invalid PDF: Buffer is too small or empty. " +
-                "A valid PDF must be at least 5 bytes (PDF header).");
-        }
-        // 2. Validate PDF magic bytes (%PDF-)
-        if (!PDFProcessor.isValidPDF(pdfBuffer)) {
-            throw new Error("Invalid PDF: File must start with %PDF- header. " +
-                "The provided buffer does not appear to be a valid PDF file.");
-        }
-        // 3. Validate maximum buffer size to prevent memory exhaustion
-        const sizeMB = pdfBuffer.length / (1024 * 1024);
-        if (sizeMB > PDF_LIMITS.MAX_SIZE_MB) {
-            throw new Error(`PDF too large for image conversion: ${sizeMB.toFixed(2)}MB exceeds ${PDF_LIMITS.MAX_SIZE_MB}MB limit. ` +
-                "Consider splitting the PDF or using a provider with native PDF support.");
-        }
+        const pageErrors = [];
+        // Validation shared with convertToImagesStream (#302).
+        const sizeMB = PDFProcessor.validateImageConversionInput(pdfBuffer, {
+            format,
+            scale,
+            maxCanvasPixels,
+        });
         logger.debug("[PDF→Image] ✅ PDF validation passed", {
             bufferSize: pdfBuffer.length,
             sizeMB: sizeMB.toFixed(2),
             maxPages,
         });
+        // #297: surface an up-front memory estimate so an operator can spot a
+        // conversion that will allocate a lot before it runs. Uses the cheap regex
+        // page estimate (the accurate pdf-parse count runs in process(), not here).
+        const estimatedPages = Math.max(1, PDFProcessor.extractBasicMetadata(pdfBuffer).estimatedPages ?? 1);
+        const estimatedMemoryMB = PDFProcessor.estimateConversionMemoryUsage(pdfBuffer.length, estimatedPages, scale);
+        logger.info("[PDF→Image] Estimated memory usage before conversion", {
+            scale,
+            estimatedPages,
+            estimatedMemoryMB,
+            sizeMB: Number(sizeMB.toFixed(2)),
+        });
         try {
             // Dynamic import to avoid loading MuPDF binaries until needed
             const pdfToImgModule = await import("pdf-to-img");
@@ -369,35 +411,60 @@ export class PDFProcessor {
                 logger.warn(`[PDF→Image] ⚠️ ${msg}`);
                 warnings.push(msg);
             }
-            // Create PDF document iterator (password forwarded for encrypted PDFs, #258)
+            // Create PDF document (password forwarded for encrypted PDFs, #258).
+            // pdf-to-img resolves `.length` (numPages) synchronously here and exposes
+            // `.getPage(n)`, so we drive an indexed loop rather than the async
+            // iterator — that lets one bad page be isolated instead of aborting all.
             const document = await pdf(pdfBuffer, {
                 scale: effectiveScale,
                 ...(password ? { password } : {}),
             });
-            let pageIndex = 0;
-            // Iterate through pages and convert to base64
-            for await (const page of document) {
-                // Check if we've reached the max pages limit
-                if (maxPages !== undefined && pageIndex >= maxPages) {
-                    warnings.push(`Stopped at page ${pageIndex} (maxPages limit: ${maxPages})`);
+            const totalPages = document.length;
+            // #294: convert page-by-page with per-page isolation. A single page whose
+            // canvas render throws (e.g. a degenerate MediaBox) no longer discards
+            // every already-converted page — it is recorded in `errors` and the rest
+            // continue.
+            for (let pageNum = 1; pageNum <= totalPages; pageNum++) {
+                if (maxPages !== undefined && pageNum - 1 >= maxPages) {
+                    warnings.push(`Stopped at page ${pageNum - 1} (maxPages limit: ${maxPages})`);
                     break;
                 }
-                // Convert PNG buffer to base64
-                const base64Image = page.toString("base64");
-                images.push(base64Image);
-                pageIndex++;
-                logger.debug(`[PDF→Image] Converted page ${pageIndex}`, {
-                    imageSizeBytes: page.length,
-                    base64Length: base64Image.length,
-                });
+                try {
+                    const page = await document.getPage(pageNum);
+                    const base64Image = page.toString("base64");
+                    images.push(base64Image);
+                    logger.debug(`[PDF→Image] Converted page ${pageNum}`, {
+                        imageSizeBytes: page.length,
+                        base64Length: base64Image.length,
+                    });
+                    // #302: report progress after each successfully converted page.
+                    if (onProgress) {
+                        await onProgress({
+                            pagesConverted: images.length,
+                            totalPages,
+                            elapsedMs: Date.now() - startTime,
+                        });
+                    }
+                }
+                catch (pageError) {
+                    const msg = pageError instanceof Error ? pageError.message : String(pageError);
+                    logger.warn(`[PDF→Image] ⚠️ page ${pageNum} failed to render: ${msg}`);
+                    pageErrors.push({ page: pageNum, error: msg });
+                }
             }
-            // Check for empty PDF (0 pages)
+            // Empty PDF (0 pages) or every page failed → treat as a conversion
+            // failure (kept inside the try so the password/format mapping below still
+            // applies), otherwise return the pages that did convert.
             if (images.length === 0) {
+                if (pageErrors.length > 0) {
+                    throw new Error(`All ${pageErrors.length} page(s) failed to render. First error: ${pageErrors[0].error}`);
+                }
                 throw new Error("PDF has 0 pages. Cannot convert empty PDF to images.");
             }
             const conversionTimeMs = Date.now() - startTime;
             logger.info("[PDF→Image] ✅ PDF conversion completed", {
                 pageCount: images.length,
+                failedPages: pageErrors.length,
                 conversionTimeMs,
                 totalImageBytes: images.reduce((sum, img) => sum + img.length, 0),
             });
@@ -406,6 +473,7 @@ export class PDFProcessor {
                 pageCount: images.length,
                 conversionTimeMs,
                 warnings: warnings.length > 0 ? warnings : undefined,
+                errors: pageErrors.length > 0 ? pageErrors : undefined,
             };
         }
         catch (error) {
@@ -431,6 +499,101 @@ export class PDFProcessor {
             });
         }
     }
+    /**
+     * Shared input validation for the image-conversion paths. Returns the PDF
+     * size in MB (needed by the memory-estimate log). Throws on any invalid input
+     * with the same messages the batch path has always used.
+     */
+    static validateImageConversionInput(pdfBuffer, opts) {
+        if (opts.format !== "png") {
+            throw new Error(`Invalid format: "${opts.format}". Only "png" format is currently supported.`);
+        }
+        if (!Number.isFinite(opts.scale) ||
+            opts.scale < PDF_LIMITS.MIN_SCALE ||
+            opts.scale > PDF_LIMITS.MAX_SCALE) {
+            throw new Error(`Invalid scale: ${opts.scale}. Scale must be a finite number between ${PDF_LIMITS.MIN_SCALE} and ${PDF_LIMITS.MAX_SCALE}.`);
+        }
+        if (!Number.isFinite(opts.maxCanvasPixels) || opts.maxCanvasPixels <= 0) {
+            throw new Error(`Invalid maxCanvasPixels: ${opts.maxCanvasPixels}. Must be a finite number greater than 0.`);
+        }
+        if (!pdfBuffer || pdfBuffer.length < 5) {
+            throw new Error("Invalid PDF: Buffer is too small or empty. " +
+                "A valid PDF must be at least 5 bytes (PDF header).");
+        }
+        if (!PDFProcessor.isValidPDF(pdfBuffer)) {
+            throw new Error("Invalid PDF: File must start with %PDF- header. " +
+                "The provided buffer does not appear to be a valid PDF file.");
+        }
+        const sizeMB = pdfBuffer.length / (1024 * 1024);
+        if (sizeMB > PDF_LIMITS.MAX_SIZE_MB) {
+            throw new Error(`PDF too large for image conversion: ${sizeMB.toFixed(2)}MB exceeds ${PDF_LIMITS.MAX_SIZE_MB}MB limit. ` +
+                "Consider splitting the PDF or using a provider with native PDF support.");
+        }
+        return sizeMB;
+    }
+    /**
+     * Streaming variant of {@link convertToImages} (#302): yields each page's
+     * 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.
+     *
+     * 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();
+        const { scale = PDF_LIMITS.DEFAULT_SCALE, maxPages = PDF_LIMITS.DEFAULT_MAX_PAGES, format = "png", maxCanvasPixels = PDF_LIMITS.DEFAULT_MAX_CANVAS_PIXELS, password, onProgress, } = options || {};
+        PDFProcessor.validateImageConversionInput(pdfBuffer, {
+            format,
+            scale,
+            maxCanvasPixels,
+        });
+        const pdfToImgModule = await import("pdf-to-img");
+        const pdf = pdfToImgModule.pdf;
+        // #260: uniform downscale so the largest page stays under maxCanvasPixels.
+        let effectiveScale = scale;
+        const largestPixels = PDFProcessor.largestPagePixels(pdfBuffer, scale);
+        if (largestPixels > maxCanvasPixels) {
+            effectiveScale = scale * Math.sqrt(maxCanvasPixels / largestPixels);
+        }
+        const document = await pdf(pdfBuffer, {
+            scale: effectiveScale,
+            ...(password ? { password } : {}),
+        });
+        const totalPages = document.length;
+        let converted = 0;
+        for (let pageNum = 1; pageNum <= totalPages; pageNum++) {
+            if (maxPages !== undefined && pageNum - 1 >= maxPages) {
+                break;
+            }
+            try {
+                const page = await document.getPage(pageNum);
+                const base64Image = page.toString("base64");
+                converted++;
+                if (onProgress) {
+                    await onProgress({
+                        pagesConverted: converted,
+                        totalPages,
+                        elapsedMs: Date.now() - startTime,
+                    });
+                }
+                yield {
+                    pageIndex: pageNum,
+                    image: base64Image,
+                    imageSizeBytes: page.length,
+                };
+            }
+            catch (pageError) {
+                const msg = pageError instanceof Error ? pageError.message : String(pageError);
+                logger.warn(`[PDF→Image] ⚠️ page ${pageNum} failed to render (stream): ${msg}`);
+                yield { pageIndex: pageNum, image: "", imageSizeBytes: 0, error: msg };
+            }
+        }
+    }
     /**
      * Convert a PDF file path to an array of base64 PNG images
      *
@@ -466,7 +629,7 @@ export class PDFProcessor {
      * @param scale - Scale factor
      * @returns Estimated memory usage in MB
      */
-    static estimateConversionMemoryUsage(pdfSizeBytes, pageCount, scale = 2) {
+    static estimateConversionMemoryUsage(pdfSizeBytes, pageCount, scale = PDF_LIMITS.DEFAULT_SCALE) {
         // Rough estimation:
         // - Each page at scale 2 produces ~1-3MB PNG
         // - MuPDF needs ~2x PDF size for processing

package/dist/types/file.d.ts

@@ -95,6 +95,8 @@ export type FileProcessingResult = {
         estimatedPages?: number | null;
         provider?: string;
         apiType?: PDFAPIType;
+        /** Provider's citations requirement for visual PDF analysis (#349). */
+        requiresCitations?: boolean | "auto";
         officeFormat?: OfficeDocumentType;
         pageCount?: number;
         slideCount?: number;
@@ -210,6 +212,14 @@ export type PDFProviderConfig = {
     maxSizeMB: number;
     maxPages: number;
     supportsNative: boolean;
+    /**
+     * Whether this provider needs source citations enabled for visual PDF
+     * analysis (#349). `"auto"` = enable when the request requires visual
+     * grounding (currently Bedrock's Converse document blocks); `false` = the
+     * provider handles PDFs without an explicit citations flag. Surfaced on
+     * `FileProcessingResult.metadata.requiresCitations` so downstream provider
+     * adapters can act on it instead of the value being dead config.
+     */
     requiresCitations: boolean | "auto";
     apiType: PDFAPIType;
 };
@@ -405,10 +415,32 @@ export type PDFImageConversionOptions = {
     maxCanvasPixels?: number;
     /** Password for an encrypted PDF (passed to the underlying renderer) (#258). */
     password?: string;
+    /** Per-page progress callback invoked as each page is rendered (#302). */
+    onProgress?: (progress: PDFImageConversionProgress) => void | Promise<void>;
+};
+/** Progress reported per page during streaming conversion (#302). */
+export type PDFImageConversionProgress = {
+    /** Number of pages successfully converted so far. */
+    pagesConverted: number;
+    /** Total pages in the document (known up-front from the renderer). */
+    totalPages: number;
+    /** Elapsed time since conversion started, in milliseconds. */
+    elapsedMs: number;
+};
+/** A single streamed page result (#302). `error` is set when that page failed. */
+export type PDFImagePage = {
+    /** 1-based page index. */
+    pageIndex: number;
+    /** Base64-encoded PNG for the page (empty string when `error` is set). */
+    image: string;
+    /** Byte size of the rendered PNG (0 when `error` is set). */
+    imageSizeBytes: number;
+    /** Populated when this page failed to render (#294). */
+    error?: string;
 };
 /** Result of PDF to image conversion. */
 export type PDFImageConversionResult = {
-    /** Array of base64-encoded PNG images (one per page) */
+    /** Array of base64-encoded PNG images (one per successfully converted page) */
     images: string[];
     /** Number of pages converted */
     pageCount: number;
@@ -416,6 +448,11 @@ export type PDFImageConversionResult = {
     conversionTimeMs: number;
     /** Any warnings during conversion */
     warnings?: string[];
+    /** Per-page failures — present only when some pages failed to render (#294). */
+    errors?: Array<{
+        page: number;
+        error: string;
+    }>;
 };
 /** Options for filename sanitization. */
 export type SanitizeFileNameOptions = {

package/dist/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,
     });
@@ -1413,6 +1432,50 @@ export class FileDetector {
         const timeout = options?.timeout || FileDetector.DEFAULT_NETWORK_TIMEOUT;
         const maxRetries = options?.maxRetries ?? DEFAULT_MAX_RETRIES;
         const retryDelay = options?.retryDelay ?? DEFAULT_RETRY_DELAY;
+        // #317: pre-flight HEAD to reject an oversized file BEFORE downloading any
+        // body. content-length is advisory (chunked responses omit it), so a
+        // missing/invalid header — or a server that refuses HEAD — falls through to
+        // the streaming byte guard below; only a genuine oversize rejection stops
+        // the GET from ever running.
+        //
+        // #323: skip the pre-flight entirely when this exact URL was recently seen
+        // (its Content-Type is still cached, whether from a prior loadFromURL GET
+        // or a MimeTypeStrategy HEAD) — issuing a fresh HEAD here would defeat the
+        // whole point of that cache. The streaming byte guard in the GET below
+        // still enforces maxSize even without a pre-flight, so this doesn't remove
+        // the oversize protection — it only skips the redundant round-trip for a
+        // URL we've already been talking to within the last 60s.
+        if (getCachedUrlContentType(url, Date.now()) === undefined) {
+            try {
+                const head = await request(url, {
+                    dispatcher: getGlobalDispatcher().compose(interceptors.redirect({ maxRedirections: 5 })),
+                    method: "HEAD",
+                    headersTimeout: FileDetector.DEFAULT_HEAD_TIMEOUT,
+                    bodyTimeout: FileDetector.DEFAULT_HEAD_TIMEOUT,
+                });
+                // Drain/close the (empty) HEAD body so the connection can be reused.
+                await head.body.dump();
+                // 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 ${redactUrlForError(url)}: ${sanitizeErrorCause(error).message}`);
+            }
+        }
         return withRetry(async () => {
             try {
                 const response = await request(url, {

package/dist/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/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/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>;
 /**