@juspay/neurolink 9.95.3 → 10.0.0

package/dist/cli/commands/proxy.d.ts

@@ -13,6 +13,32 @@ import type { CommandModule } from "yargs";
 import type { Hono } from "hono";
 import type { AccountAllowlist, LoadedProxyConfig, ModelRouterInterface, ProxyGuardArgs, ProxyNeurolinkRuntime, ProxyStartArgs, ProxyStartStrategy, ProxyStatusArgs, ProxyTelemetryArgs, ProxyReadinessState } from "../../lib/types/index.js";
 import { ProxyRuntimeConfigStore } from "../../lib/proxy/runtimeConfig.js";
+/**
+ * Best-effort check that a pid actually belongs to a neurolink proxy process,
+ * so a stale/recycled supervisor pid is never mistaken for a live supervisor
+ * and signalled. Returns false when the process cannot be confirmed as ours.
+ *
+ * @param expectedStartTimeIso - The `ProxySupervisorState.startTime` (ISO
+ *   string) recorded when the supervisor we expect at `pid` was launched.
+ *   When provided, this is cross-checked against `pid`'s actual OS-reported
+ *   start time (see {@link getProcessStartTime}) — the args match alone
+ *   ("neurolink" + "proxy" both present) is not airtight, since an
+ *   unrelated process (e.g. a shell running this very test suite, or a
+ *   coincidentally-named script) could match it too. A pid recycled by such
+ *   a process would have a start time far from the recorded supervisor
+ *   startTime, which this catches.
+ *
+ *   Deliberately fail-open on anything unparseable: `ps -o lstart=` output
+ *   parsing is inherently a little fragile (locale/format quirks), and the
+ *   cost of a false "can't confirm" is silently regressing to pre-hardening
+ *   behavior, while the cost of a false "confirmed mismatch" is leaving a
+ *   real supervisor running and orphaning its socket during uninstall — the
+ *   former is the safer failure mode. So this only ever returns false for
+ *   the startTime check when BOTH timestamps parsed successfully AND their
+ *   drift exceeds the tolerance; any parse failure is treated as "can't
+ *   confirm a mismatch" and falls through to the args-only result.
+ */
+export declare function processLooksLikeProxySupervisor(pid: number, expectedStartTimeIso?: string): Promise<boolean>;
 export declare function mapClaudeErrorTypeToStatus(errorType?: string): number;
 export declare function createProxyStartApp(params: {
     neurolink: ProxyNeurolinkRuntime["neurolink"];

package/dist/cli/commands/proxy.js

@@ -41,6 +41,14 @@ const _require = createRequire(import.meta.url);
 const PROXY_VERSION = packageJson.version;
 const PROXY_TELEMETRY_SCRIPT_PATH = fileURLToPath(new URL("../../../scripts/observability/manage-local-openobserve.sh", import.meta.url));
 const PROXY_LIFECYCLE_SHUTDOWN_TIMEOUT_MS = 5_000;
+// Allowed drift between a pid's OS-reported start time and the persisted
+// ProxySupervisorState.startTime before processLooksLikeProxySupervisor
+// treats it as a confident mismatch (recycled pid). Generous on purpose:
+// `supervisorStartedAt` is captured inside runLaunchdProxySupervisor, which
+// runs after Node has already booted and done setup, so it always lags the
+// OS-level fork/exec by a little — a tight tolerance would produce false
+// mismatches on a slow/cold-started machine.
+const PROXY_SUPERVISOR_START_TIME_TOLERANCE_MS = 10_000;
 const PROXY_UPDATE_CONTROL_TOKEN = process.env.NEUROLINK_PROXY_UPDATE_CONTROL_TOKEN?.trim() ||
     crypto.randomUUID();
 // =============================================================================
@@ -98,23 +106,131 @@ function getProcessStatus(pid) {
     }
 }
 /**
- * Best-effort check that a pid actually belongs to a neurolink proxy process,
- * so a stale/recycled supervisor pid is never mistaken for a live supervisor
- * and signalled. Returns false when the process cannot be confirmed as ours.
+ * Read a single `ps -o <field>=` field for `pid`, off the event loop (async
+ * `execFile`, not `execFileSync`) and bounded by a short timeout, so a
+ * hung/zombie `ps` invocation can never block the event loop or hang the
+ * (often uninstall-path) async caller. Shared by {@link getProcessStartTime}
+ * and {@link processLooksLikeProxySupervisor}, which both read a single
+ * `ps -o <field>=` column for the same pid.
+ *
+ * Returns null — never throws — on any error, timeout, or empty output, so
+ * callers uniformly treat "couldn't read" as "can't confirm either way"
+ * rather than distinguishing the failure mode.
  */
-async function processLooksLikeProxySupervisor(pid) {
+async function readPsField(pid, field) {
     try {
-        const { execFileSync } = await import("node:child_process");
-        const args = execFileSync("ps", ["-p", String(pid), "-o", "args="], {
+        const { execFile } = await import("node:child_process");
+        const { promisify } = await import("node:util");
+        const execFileAsync = promisify(execFile);
+        const { stdout } = await withTimeout(execFileAsync("ps", ["-p", String(pid), "-o", `${field}=`], {
             encoding: "utf-8",
-            stdio: ["ignore", "pipe", "ignore"],
-        });
-        return /neurolink/i.test(args);
+        }), 2000, `ps -o ${field}= timed out for pid ${pid}`);
+        const trimmed = stdout.trim();
+        return trimmed || null;
     }
     catch {
-        // `ps` unavailable or the pid vanished — do not signal an unverified pid.
+        return null;
+    }
+}
+/**
+ * Best-effort, macOS-only (uninstall is macOS-only) read of `pid`'s
+ * OS-reported start time via `ps -o lstart=`, which prints a fixed-width
+ * `Www Mmm dd hh:mm:ss yyyy` timestamp — the same shape `Date`'s parser
+ * already understands (it's the format `Date#toString()` itself produces
+ * modulo the trailing timezone). Returns null (never throws) when `ps`
+ * fails or its output doesn't parse, so callers can tell "confirmed
+ * mismatch" apart from "couldn't confirm either way".
+ */
+async function getProcessStartTime(pid) {
+    const out = await readPsField(pid, "lstart");
+    if (!out) {
+        return null;
+    }
+    // `ps -o lstart=` prints the OS start time in the machine's LOCAL timezone
+    // with no offset, e.g. "Sun Jul 19 20:12:41 2026". Parse the components and
+    // build the Date via the local-time constructor rather than relying on the
+    // engine's implementation-defined parsing of non-ISO date strings. The
+    // result is the same absolute instant the supervisor persisted as an
+    // ISO-UTC string, so the drift comparison against it is timezone-safe.
+    const m = out.match(/^\w{3}\s+(\w{3})\s+(\d{1,2})\s+(\d{2}):(\d{2}):(\d{2})\s+(\d{4})$/);
+    if (!m) {
+        return null;
+    }
+    const monthIndex = [
+        "Jan",
+        "Feb",
+        "Mar",
+        "Apr",
+        "May",
+        "Jun",
+        "Jul",
+        "Aug",
+        "Sep",
+        "Oct",
+        "Nov",
+        "Dec",
+    ].indexOf(m[1]);
+    if (monthIndex < 0) {
+        return null;
+    }
+    const parsed = new Date(Number(m[6]), monthIndex, Number(m[2]), Number(m[3]), Number(m[4]), Number(m[5]));
+    return Number.isNaN(parsed.getTime()) ? null : parsed;
+}
+/**
+ * Best-effort check that a pid actually belongs to a neurolink proxy process,
+ * so a stale/recycled supervisor pid is never mistaken for a live supervisor
+ * and signalled. Returns false when the process cannot be confirmed as ours.
+ *
+ * @param expectedStartTimeIso - The `ProxySupervisorState.startTime` (ISO
+ *   string) recorded when the supervisor we expect at `pid` was launched.
+ *   When provided, this is cross-checked against `pid`'s actual OS-reported
+ *   start time (see {@link getProcessStartTime}) — the args match alone
+ *   ("neurolink" + "proxy" both present) is not airtight, since an
+ *   unrelated process (e.g. a shell running this very test suite, or a
+ *   coincidentally-named script) could match it too. A pid recycled by such
+ *   a process would have a start time far from the recorded supervisor
+ *   startTime, which this catches.
+ *
+ *   Deliberately fail-open on anything unparseable: `ps -o lstart=` output
+ *   parsing is inherently a little fragile (locale/format quirks), and the
+ *   cost of a false "can't confirm" is silently regressing to pre-hardening
+ *   behavior, while the cost of a false "confirmed mismatch" is leaving a
+ *   real supervisor running and orphaning its socket during uninstall — the
+ *   former is the safer failure mode. So this only ever returns false for
+ *   the startTime check when BOTH timestamps parsed successfully AND their
+ *   drift exceeds the tolerance; any parse failure is treated as "can't
+ *   confirm a mismatch" and falls through to the args-only result.
+ */
+export async function processLooksLikeProxySupervisor(pid, expectedStartTimeIso) {
+    const args = await readPsField(pid, "args");
+    if (args === null) {
+        // `ps` unavailable, timed out, or the pid vanished — do not signal an
+        // unverified pid.
+        return false;
+    }
+    // `/neurolink/i` alone is too broad: any process whose args merely
+    // *mention* "neurolink" (e.g. a shell running in a directory named
+    // "neurolink", an editor with a neurolink file open) would match, and a
+    // stale/recycled pid running such a process could then be SIGTERM'd/
+    // SIGKILL'd by `ensureSupervisorStoppedBeforeClear` during uninstall.
+    // Require the actual proxy-supervisor invocation — both "neurolink" AND
+    // the "proxy" subcommand present in args.
+    if (!(/neurolink/i.test(args) && /\bproxy\b/i.test(args))) {
         return false;
     }
+    if (!expectedStartTimeIso) {
+        return true;
+    }
+    const expected = new Date(expectedStartTimeIso);
+    if (Number.isNaN(expected.getTime())) {
+        return true; // recorded startTime itself is unparseable — can't confirm a mismatch
+    }
+    const actual = await getProcessStartTime(pid);
+    if (!actual) {
+        return true; // ps -o lstart= unavailable/unparseable — can't confirm a mismatch
+    }
+    const driftMs = Math.abs(actual.getTime() - expected.getTime());
+    return driftMs <= PROXY_SUPERVISOR_START_TIME_TOLERANCE_MS;
 }
 /**
  * Ensure any supervisor recorded in state is actually stopped before its state
@@ -124,14 +240,17 @@ async function processLooksLikeProxySupervisor(pid) {
  * the uninstall instead of silently discarding the record.
  */
 async function ensureSupervisorStoppedBeforeClear() {
-    const pid = loadProxySupervisorState()?.pid;
+    const supervisorState = loadProxySupervisorState();
+    const pid = supervisorState?.pid;
     if (!pid || getProcessStatus(pid) === "not_running") {
         return true;
     }
     // Guard against a stale/recycled pid: only signal a process that still looks
     // like a neurolink proxy supervisor, so uninstall never terminates an
-    // unrelated, same-user process that inherited the recorded pid.
-    if (!(await processLooksLikeProxySupervisor(pid))) {
+    // unrelated, same-user process that inherited the recorded pid. Also cross-
+    // checks the pid's actual OS start time against the recorded
+    // supervisorState.startTime (see processLooksLikeProxySupervisor).
+    if (!(await processLooksLikeProxySupervisor(pid, supervisorState?.startTime))) {
         return true;
     }
     try {

package/dist/cli/factories/commandFactory.d.ts

@@ -192,6 +192,13 @@ export declare class CLICommandFactory {
      * objects independently.
      */
     private static buildCsvOptionsFromArgv;
+    /**
+     * Build video processor options from CLI argv. Shared by executeGenerate,
+     * executeStream and executeBatch, which previously built byte-for-byte
+     * identical `videoOptions` objects independently (mirrors
+     * {@link buildCsvOptionsFromArgv}).
+     */
+    private static buildVideoOptionsFromArgv;
     /**
      * Build output configuration for generate request
      */

package/dist/cli/factories/commandFactory.js

@@ -2438,6 +2438,20 @@ export class CLICommandFactory {
             parseTimeoutMs: argv.csvParseTimeoutMs,
         };
     }
+    /**
+     * Build video processor options from CLI argv. Shared by executeGenerate,
+     * executeStream and executeBatch, which previously built byte-for-byte
+     * identical `videoOptions` objects independently (mirrors
+     * {@link buildCsvOptionsFromArgv}).
+     */
+    static buildVideoOptionsFromArgv(argv) {
+        return {
+            frames: argv.videoFrames,
+            quality: argv.videoQuality,
+            format: argv.videoFormat,
+            transcribeAudio: argv.transcribeAudio,
+        };
+    }
     /**
      * Build output configuration for generate request
      */
@@ -2677,12 +2691,7 @@ export class CLICommandFactory {
                     password: CLICommandFactory.resolvePdfPassword(argv),
                 },
                 csvOptions: CLICommandFactory.buildCsvOptionsFromArgv(argv),
-                videoOptions: {
-                    frames: argv.videoFrames,
-                    quality: argv.videoQuality,
-                    format: argv.videoFormat,
-                    transcribeAudio: argv.transcribeAudio,
-                },
+                videoOptions: CLICommandFactory.buildVideoOptionsFromArgv(argv),
                 output: outputConfig,
                 provider: enhancedOptions.provider,
                 model: enhancedOptions.model,
@@ -2932,12 +2941,7 @@ export class CLICommandFactory {
                 password: CLICommandFactory.resolvePdfPassword(argv),
             },
             csvOptions: CLICommandFactory.buildCsvOptionsFromArgv(argv),
-            videoOptions: {
-                frames: argv.videoFrames,
-                quality: argv.videoQuality,
-                format: argv.videoFormat,
-                transcribeAudio: argv.transcribeAudio,
-            },
+            videoOptions: CLICommandFactory.buildVideoOptionsFromArgv(argv),
             provider: enhancedOptions.provider,
             model: enhancedOptions.model,
             temperature: enhancedOptions.temperature,
@@ -3411,6 +3415,7 @@ export class CLICommandFactory {
             // see createBatchCommand — so `argv.file` can never be set here; no
             // exclusion needed to protect the (differently-named) positional.
             validateCliInputFiles(argv);
+            validateCsvMaxRows(argv);
             const batchImages = CLICommandFactory.processCliImages(argv.image);
             const batchCsvFiles = CLICommandFactory.processCliCSVFiles(argv.csv);
             const batchPdfFiles = CLICommandFactory.processCliPDFFiles(argv.pdf);
@@ -3469,6 +3474,12 @@ export class CLICommandFactory {
                 logger.alwaysStderr(chalk.yellow("⚠️  Multimodal files (--image/--csv/--pdf/--video) are attached to ALL prompts in this batch."));
                 spinner?.start();
             }
+            // Resolve the PDF password once for the whole batch. resolvePdfPassword
+            // emits a "visible in shell history" stderr warning when the flag is set;
+            // it must fire once per run (like generate/stream), not once per prompt.
+            const batchPdfPassword = batchPdfFiles?.length
+                ? CLICommandFactory.resolvePdfPassword(argv)
+                : undefined;
             for (let i = 0; i < prompts.length; i++) {
                 if (spinner) {
                     spinner.text = `Processing ${i + 1}/${prompts.length}: ${prompts[i].substring(0, 30)}...`;
@@ -3518,18 +3529,15 @@ export class CLICommandFactory {
                         // unlike generate/stream, so an empty options object here is
                         // pure noise on every prompt of every batch run.
                         ...(batchCsvFiles?.length && {
-                            csvOptions: {
-                                maxRows: argv.csvMaxRows,
-                                formatStyle: argv.csvFormat,
+                            csvOptions: CLICommandFactory.buildCsvOptionsFromArgv(argv),
+                        }),
+                        ...(batchPdfFiles?.length && {
+                            pdfOptions: {
+                                password: batchPdfPassword,
                             },
                         }),
                         ...(batchVideoFiles?.length && {
-                            videoOptions: {
-                                frames: argv.videoFrames,
-                                quality: argv.videoQuality,
-                                format: argv.videoFormat,
-                                transcribeAudio: argv.transcribeAudio,
-                            },
+                            videoOptions: CLICommandFactory.buildVideoOptionsFromArgv(argv),
                         }),
                         provider: enhancedOptions.provider,
                         model: enhancedOptions.model,

package/dist/cli/utils/inputValidation.d.ts

@@ -21,6 +21,7 @@ export declare const CLI_SOFT_LIMITS_MB: {
     readonly IMAGE_MAX_MB: 10;
     readonly CSV_MAX_MB: 50;
     readonly PDF_MAX_MB: 100;
+    readonly PDF_SOFT_MAX_MB: 50;
     readonly VIDEO_MAX_MB: 500;
 };
 /**

package/dist/cli/utils/inputValidation.js

@@ -27,6 +27,11 @@ export const CLI_SOFT_LIMITS_MB = {
     IMAGE_MAX_MB: 10,
     CSV_MAX_MB: 50,
     PDF_MAX_MB: 100,
+    // Distinct from PDF_MAX_MB above (which mirrors the processor's true
+    // 100MB hard cap in lib/processors/config/sizeLimits.ts and is kept here
+    // for backward compatibility). Docs promise a 50MB *warning* threshold
+    // specifically for --pdf — wire warnAtMB to this value, not the hard cap.
+    PDF_SOFT_MAX_MB: 50,
     VIDEO_MAX_MB: 500,
 };
 // `file://` is intentionally excluded here: it addresses a local path, so it
@@ -165,7 +170,7 @@ export function validateCliInputFiles(argv) {
         {
             option: "--pdf",
             value: argv.pdf,
-            warnAtMB: CLI_SOFT_LIMITS_MB.PDF_MAX_MB,
+            warnAtMB: CLI_SOFT_LIMITS_MB.PDF_SOFT_MAX_MB,
         },
         {
             option: "--video",

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