@juspay/neurolink 9.88.2 → 9.88.3

package/dist/lib/types/file.d.ts

@@ -298,6 +298,16 @@ export type FileDetectorOptions = {
     maxSize?: number;
     timeout?: number;
     allowedTypes?: FileType[];
+    /**
+     * When set, local file paths must resolve inside this base directory;
+     * anything that escapes it (absolute path, `../` traversal, or a symlink
+     * pointing outside) is rejected. Containment is enforced on the real,
+     * symlink-resolved path of both the base dir and the target, so a symlink
+     * inside the base cannot be used to reach a file outside it. Servers that
+     * accept file paths from untrusted callers should set this to sandbox
+     * filesystem access; SDK callers loading their own files can omit it.
+     */
+    allowedBaseDir?: string;
     audioOptions?: AudioProcessorOptions;
     csvOptions?: CSVProcessorOptions;
     officeOptions?: OfficeProcessorOptions;

package/dist/lib/utils/fileDetector.js

@@ -3,7 +3,8 @@
  * Centralized file detection for all multimodal file types
  * Uses multi-strategy approach for reliable type identification
  */
-import { readFile, stat } from "fs/promises";
+import { open, readFile, realpath } from "fs/promises";
+import { isAbsolute as isAbsolutePath, relative as relativePath, resolve as resolvePath, sep, } from "path";
 import { getGlobalDispatcher, interceptors, request } from "undici";
 // Lazy-loaded processor singletons — avoids loading heavy media deps
 // (mediabunny, fluent-ffmpeg, music-metadata, adm-zip) on every generate() call.
@@ -585,7 +586,9 @@ export class FileDetector {
                 return result;
             }
         }
-        logger.warn(`[FileDetector] Low confidence: ${best?.type ?? "unknown"} (${best?.metadata.confidence ?? 0}%)`);
+        // Below-threshold detection is the common case for any file under the
+        // ContentHeuristic ceiling — a debug detail, not a warning-worthy anomaly.
+        logger.debug(`[FileDetector] Best-effort type below threshold: ${best?.type ?? "unknown"} (${best?.metadata.confidence ?? 0}%, threshold ${confidenceThreshold}%)`);
         return best;
     }
     /**
@@ -1342,7 +1345,7 @@ export class FileDetector {
                 bodyTimeout: timeout,
             });
             if (response.statusCode !== 200) {
-                throw new Error(`HTTP ${response.statusCode}`);
+                throw new Error(`HTTP ${response.statusCode} fetching ${url}`);
             }
             const chunks = [];
             let totalSize = 0;
@@ -1359,16 +1362,49 @@ export class FileDetector {
     /**
      * Load file from filesystem path
      */
-    static async loadFromPath(path, options) {
+    static async loadFromPath(filePath, options) {
         const maxSize = options?.maxSize || 200 * 1024 * 1024; // 200MB default (matches Curator memory-safety cap)
-        const statInfo = await stat(path);
-        if (!statInfo.isFile()) {
-            throw new Error("Not a file");
+        // Reject NUL-byte injection outright (a classic path-truncation vector).
+        if (filePath.includes("\0")) {
+            throw new Error("Invalid file path: contains a null byte");
+        }
+        // Optional sandbox: when a base dir is configured (servers accepting paths
+        // from untrusted callers), reject anything that resolves outside it. Real
+        // paths are resolved (symlinks followed) on BOTH sides so a symlink inside
+        // the base dir pointing outside cannot bypass containment. The
+        // path.relative check (not a string prefix) correctly handles the root dir
+        // ("/") and sibling-prefix ("/app" vs "/app-evil") edge cases.
+        if (options?.allowedBaseDir) {
+            let base;
+            let real;
+            try {
+                base = await realpath(resolvePath(options.allowedBaseDir));
+                real = await realpath(filePath);
+            }
+            catch {
+                throw new Error(`Access denied: "${filePath}" could not be resolved within the allowed base directory`);
+            }
+            const rel = relativePath(base, real);
+            if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolutePath(rel)) {
+                throw new Error(`Access denied: "${filePath}" resolves outside the allowed base directory`);
+            }
+        }
+        // Open a handle and stat/read through the SAME descriptor so a symlink
+        // swap between the size check and the read cannot occur (TOCTOU).
+        const handle = await open(filePath, "r");
+        try {
+            const statInfo = await handle.stat();
+            if (!statInfo.isFile()) {
+                throw new Error(`Not a file: ${filePath}`);
+            }
+            if (statInfo.size > maxSize) {
+                throw new Error(`File too large: ${filePath} is ${formatFileSize(statInfo.size)} (max: ${formatFileSize(maxSize)})`);
+            }
+            return await handle.readFile();
         }
-        if (statInfo.size > maxSize) {
-            throw new Error(`File too large: ${formatFileSize(statInfo.size)} (max: ${formatFileSize(maxSize)})`);
+        finally {
+            await handle.close();
         }
-        return await readFile(path);
     }
     /**
      * Load file from data URI
@@ -1376,7 +1412,7 @@ export class FileDetector {
     static loadFromDataURI(dataUri) {
         const match = dataUri.match(/^data:([^;]+);base64,(.+)$/);
         if (!match) {
-            throw new Error("Invalid data URI format");
+            throw new Error(`Invalid data URI format (expected "data:<mime>;base64,<data>"): "${dataUri.slice(0, 32)}…"`);
         }
         return Buffer.from(match[2], "base64");
     }

package/dist/types/file.d.ts

@@ -298,6 +298,16 @@ export type FileDetectorOptions = {
     maxSize?: number;
     timeout?: number;
     allowedTypes?: FileType[];
+    /**
+     * When set, local file paths must resolve inside this base directory;
+     * anything that escapes it (absolute path, `../` traversal, or a symlink
+     * pointing outside) is rejected. Containment is enforced on the real,
+     * symlink-resolved path of both the base dir and the target, so a symlink
+     * inside the base cannot be used to reach a file outside it. Servers that
+     * accept file paths from untrusted callers should set this to sandbox
+     * filesystem access; SDK callers loading their own files can omit it.
+     */
+    allowedBaseDir?: string;
     audioOptions?: AudioProcessorOptions;
     csvOptions?: CSVProcessorOptions;
     officeOptions?: OfficeProcessorOptions;

package/dist/utils/fileDetector.js

@@ -3,7 +3,8 @@
  * Centralized file detection for all multimodal file types
  * Uses multi-strategy approach for reliable type identification
  */
-import { readFile, stat } from "fs/promises";
+import { open, readFile, realpath } from "fs/promises";
+import { isAbsolute as isAbsolutePath, relative as relativePath, resolve as resolvePath, sep, } from "path";
 import { getGlobalDispatcher, interceptors, request } from "undici";
 // Lazy-loaded processor singletons — avoids loading heavy media deps
 // (mediabunny, fluent-ffmpeg, music-metadata, adm-zip) on every generate() call.
@@ -585,7 +586,9 @@ export class FileDetector {
                 return result;
             }
         }
-        logger.warn(`[FileDetector] Low confidence: ${best?.type ?? "unknown"} (${best?.metadata.confidence ?? 0}%)`);
+        // Below-threshold detection is the common case for any file under the
+        // ContentHeuristic ceiling — a debug detail, not a warning-worthy anomaly.
+        logger.debug(`[FileDetector] Best-effort type below threshold: ${best?.type ?? "unknown"} (${best?.metadata.confidence ?? 0}%, threshold ${confidenceThreshold}%)`);
         return best;
     }
     /**
@@ -1342,7 +1345,7 @@ export class FileDetector {
                 bodyTimeout: timeout,
             });
             if (response.statusCode !== 200) {
-                throw new Error(`HTTP ${response.statusCode}`);
+                throw new Error(`HTTP ${response.statusCode} fetching ${url}`);
             }
             const chunks = [];
             let totalSize = 0;
@@ -1359,16 +1362,49 @@ export class FileDetector {
     /**
      * Load file from filesystem path
      */
-    static async loadFromPath(path, options) {
+    static async loadFromPath(filePath, options) {
         const maxSize = options?.maxSize || 200 * 1024 * 1024; // 200MB default (matches Curator memory-safety cap)
-        const statInfo = await stat(path);
-        if (!statInfo.isFile()) {
-            throw new Error("Not a file");
+        // Reject NUL-byte injection outright (a classic path-truncation vector).
+        if (filePath.includes("\0")) {
+            throw new Error("Invalid file path: contains a null byte");
+        }
+        // Optional sandbox: when a base dir is configured (servers accepting paths
+        // from untrusted callers), reject anything that resolves outside it. Real
+        // paths are resolved (symlinks followed) on BOTH sides so a symlink inside
+        // the base dir pointing outside cannot bypass containment. The
+        // path.relative check (not a string prefix) correctly handles the root dir
+        // ("/") and sibling-prefix ("/app" vs "/app-evil") edge cases.
+        if (options?.allowedBaseDir) {
+            let base;
+            let real;
+            try {
+                base = await realpath(resolvePath(options.allowedBaseDir));
+                real = await realpath(filePath);
+            }
+            catch {
+                throw new Error(`Access denied: "${filePath}" could not be resolved within the allowed base directory`);
+            }
+            const rel = relativePath(base, real);
+            if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolutePath(rel)) {
+                throw new Error(`Access denied: "${filePath}" resolves outside the allowed base directory`);
+            }
+        }
+        // Open a handle and stat/read through the SAME descriptor so a symlink
+        // swap between the size check and the read cannot occur (TOCTOU).
+        const handle = await open(filePath, "r");
+        try {
+            const statInfo = await handle.stat();
+            if (!statInfo.isFile()) {
+                throw new Error(`Not a file: ${filePath}`);
+            }
+            if (statInfo.size > maxSize) {
+                throw new Error(`File too large: ${filePath} is ${formatFileSize(statInfo.size)} (max: ${formatFileSize(maxSize)})`);
+            }
+            return await handle.readFile();
         }
-        if (statInfo.size > maxSize) {
-            throw new Error(`File too large: ${formatFileSize(statInfo.size)} (max: ${formatFileSize(maxSize)})`);
+        finally {
+            await handle.close();
         }
-        return await readFile(path);
     }
     /**
      * Load file from data URI
@@ -1376,7 +1412,7 @@ export class FileDetector {
     static loadFromDataURI(dataUri) {
         const match = dataUri.match(/^data:([^;]+);base64,(.+)$/);
         if (!match) {
-            throw new Error("Invalid data URI format");
+            throw new Error(`Invalid data URI format (expected "data:<mime>;base64,<data>"): "${dataUri.slice(0, 32)}…"`);
         }
         return Buffer.from(match[2], "base64");
     }

package/package.json

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