@juspay/neurolink 9.95.3 → 10.0.0

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "9.95.3",
+  "version": "10.0.0",
   "packageManager": "pnpm@10.15.1",
   "description": "TypeScript AI SDK with 24+ LLM providers behind one consistent API. MCP-native (connect any MCP server), voice TTS/STT/realtime, RAG, agents, memory, context compaction. OpenAI · Anthropic · Gemini · Bedrock · Azure · Ollama · DeepSeek · NVIDIA NIM and more.",
   "author": {