@juspay/neurolink 9.88.2 → 9.88.4

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`);
+            }
         }
-        if (statInfo.size > maxSize) {
-            throw new Error(`File too large: ${formatFileSize(statInfo.size)} (max: ${formatFileSize(maxSize)})`);
+        // 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();
+        }
+        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");
     }
@@ -1405,20 +1441,34 @@ class MagicBytesStrategy {
         if (this.isPDF(input)) {
             return this.result("pdf", "application/pdf", 95);
         }
-        // MP4/MOV: "ftyp" at offset 4
+        // ISO-BMFF ("ftyp" at offset 4): MP4 video, QuickTime MOV, or M4A/M4B/M4P
+        // audio all share this box — disambiguate by the major brand at offset 8-11,
+        // otherwise an .m4a audio file is misrouted to the video pipeline.
         if (input.length >= 8 &&
             input[4] === 0x66 &&
             input[5] === 0x74 &&
             input[6] === 0x79 &&
             input[7] === 0x70) {
+            const brand = input.length >= 12 ? input.toString("latin1", 8, 12) : "";
+            if (/^(M4A|M4B|M4P|F4A|F4B)/.test(brand)) {
+                return this.result("audio", "audio/mp4", 95);
+            }
+            if (brand.startsWith("qt")) {
+                return this.result("video", "video/quicktime", 95);
+            }
             return this.result("video", "video/mp4", 95);
         }
-        // MKV/WebM: EBML header
+        // EBML container (MKV/WebM) — both share the 0x1A45DFA3 header; the DocType
+        // string in the header disambiguates WebM from generic Matroska.
         if (input.length >= 4 &&
             input[0] === 0x1a &&
             input[1] === 0x45 &&
             input[2] === 0xdf &&
             input[3] === 0xa3) {
+            const head = input.toString("latin1", 0, Math.min(input.length, 64));
+            if (head.includes("webm")) {
+                return this.result("video", "video/webm", 92);
+            }
             return this.result("video", "video/x-matroska", 90);
         }
         // AVI: "RIFF" + "AVI "
@@ -1452,7 +1502,13 @@ class MagicBytesStrategy {
             input[2] === 0x33) {
             return this.result("audio", "audio/mpeg", 95);
         }
-        // MP3: sync word
+        // AAC (ADTS): 12-bit syncword 0xFFF with the 2 layer bits == 00. This must be
+        // checked before the MP3 sync word below, because an ADTS header also satisfies
+        // the looser 11-bit MPEG sync mask and would otherwise be mislabeled audio/mpeg.
+        if (input.length >= 2 && input[0] === 0xff && (input[1] & 0xf6) === 0xf0) {
+            return this.result("audio", "audio/aac", 85);
+        }
+        // MP3: sync word (MPEG audio — layer bits are non-zero, unlike ADTS AAC above)
         if (input.length >= 2 && input[0] === 0xff && (input[1] & 0xe0) === 0xe0) {
             return this.result("audio", "audio/mpeg", 80);
         }

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`);
+            }
         }
-        if (statInfo.size > maxSize) {
-            throw new Error(`File too large: ${formatFileSize(statInfo.size)} (max: ${formatFileSize(maxSize)})`);
+        // 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();
+        }
+        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");
     }
@@ -1405,20 +1441,34 @@ class MagicBytesStrategy {
         if (this.isPDF(input)) {
             return this.result("pdf", "application/pdf", 95);
         }
-        // MP4/MOV: "ftyp" at offset 4
+        // ISO-BMFF ("ftyp" at offset 4): MP4 video, QuickTime MOV, or M4A/M4B/M4P
+        // audio all share this box — disambiguate by the major brand at offset 8-11,
+        // otherwise an .m4a audio file is misrouted to the video pipeline.
         if (input.length >= 8 &&
             input[4] === 0x66 &&
             input[5] === 0x74 &&
             input[6] === 0x79 &&
             input[7] === 0x70) {
+            const brand = input.length >= 12 ? input.toString("latin1", 8, 12) : "";
+            if (/^(M4A|M4B|M4P|F4A|F4B)/.test(brand)) {
+                return this.result("audio", "audio/mp4", 95);
+            }
+            if (brand.startsWith("qt")) {
+                return this.result("video", "video/quicktime", 95);
+            }
             return this.result("video", "video/mp4", 95);
         }
-        // MKV/WebM: EBML header
+        // EBML container (MKV/WebM) — both share the 0x1A45DFA3 header; the DocType
+        // string in the header disambiguates WebM from generic Matroska.
         if (input.length >= 4 &&
             input[0] === 0x1a &&
             input[1] === 0x45 &&
             input[2] === 0xdf &&
             input[3] === 0xa3) {
+            const head = input.toString("latin1", 0, Math.min(input.length, 64));
+            if (head.includes("webm")) {
+                return this.result("video", "video/webm", 92);
+            }
             return this.result("video", "video/x-matroska", 90);
         }
         // AVI: "RIFF" + "AVI "
@@ -1452,7 +1502,13 @@ class MagicBytesStrategy {
             input[2] === 0x33) {
             return this.result("audio", "audio/mpeg", 95);
         }
-        // MP3: sync word
+        // AAC (ADTS): 12-bit syncword 0xFFF with the 2 layer bits == 00. This must be
+        // checked before the MP3 sync word below, because an ADTS header also satisfies
+        // the looser 11-bit MPEG sync mask and would otherwise be mislabeled audio/mpeg.
+        if (input.length >= 2 && input[0] === 0xff && (input[1] & 0xf6) === 0xf0) {
+            return this.result("audio", "audio/aac", 85);
+        }
+        // MP3: sync word (MPEG audio — layer bits are non-zero, unlike ADTS AAC above)
         if (input.length >= 2 && input[0] === 0xff && (input[1] & 0xe0) === 0xe0) {
             return this.result("audio", "audio/mpeg", 80);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "9.88.2",
+  "version": "9.88.4",
   "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": {