@juspay/neurolink 13.8.17 → 13.8.19

package/dist/utils/fileDetector.js

@@ -4,9 +4,8 @@
  * Uses multi-strategy approach for reliable type identification
  */
 import { open, readFile, realpath } from "fs/promises";
-import { STATUS_CODES } from "node:http";
 import { basename, isAbsolute as isAbsolutePath, relative as relativePath, resolve as resolvePath, sep, } from "path";
-import { redirectFollowingDispatcher } from "./redirectDispatcher.js";
+import { AttachmentRefusedError, downloadAttachment, getAttachmentPolicy, readAttachmentFile, } from "./attachmentPolicy.js";
 // Lazy-loaded processor singletons — avoids loading heavy media deps
 // (mediabunny, fluent-ffmpeg, music-metadata, adm-zip) on every generate() call.
 async function getVideoProcessor() {
@@ -33,7 +32,7 @@ import { detectIsoBmffImageMimeType, hasFtypBoxSignature } from "./isoBmff.js";
 import { logger } from "./logger.js";
 import { looksLikeSvgMarkup } from "./markupSniff.js";
 import { withTimeout } from "./errorHandling.js";
-import { normalizeUrlForCache, redactUrlForError, sanitizeErrorCause, } from "./logSanitize.js";
+import { normalizeUrlForCache, sanitizeErrorCause } from "./logSanitize.js";
 import { mimeHintToExtension, mimeHintToFileType, normalizeMimeHint, } from "./mimeTypeHints.js";
 import { PDFProcessor } from "./pdfProcessor.js";
 import { formatKeyframeTimestamp } from "./mediaDuration.js";
@@ -161,14 +160,58 @@ const RETRYABLE_STATUS_CODES = [429, 500, 502, 503, 504];
  * @param error - Error to check
  * @returns True if error is retryable (transient network issue)
  */
+/**
+ * The innermost `code` on an error's `cause` chain (bounded walk). Wrappers such
+ * as undici's "fetch failed" carry the Node transport code one level down.
+ */
+/** The deepest `Error` on a `cause` chain (bounded walk); the input when it has none. */
+function innermostError(error) {
+    let cursor = error;
+    for (let depth = 0; depth < 6; depth++) {
+        const next = cursor instanceof Error ? cursor.cause : undefined;
+        if (!(next instanceof Error)) {
+            return cursor;
+        }
+        cursor = next;
+    }
+    return cursor;
+}
+function innermostErrorCode(error) {
+    let found;
+    let cursor = error;
+    for (let depth = 0; depth < 6 && cursor instanceof Error; depth++) {
+        const code = cursor.code;
+        if (typeof code === "string") {
+            found = code;
+        }
+        cursor = cursor.cause;
+    }
+    return found;
+}
 function isRetryableNetworkError(error) {
     if (!(error instanceof Error)) {
         return false;
     }
-    const errorMessage = error.message.toLowerCase();
-    // Extract error code from various error shapes
-    const errorWithCode = error;
-    const errorCode = errorWithCode.code?.toUpperCase();
+    // `fetch()` (undici) reports a transport failure as a bare "fetch failed"
+    // TypeError and keeps the real reason — ECONNRESET, ETIMEDOUT, ... — on
+    // `cause`. The safe downloader wraps that again. Walk the chain (bounded) so
+    // the classification sees the innermost code and message, not the wrapper.
+    const chain = [];
+    let cursor = error;
+    while (cursor instanceof Error && chain.length < 6) {
+        chain.push(cursor);
+        cursor = cursor.cause;
+    }
+    const errorMessage = chain
+        .map((e) => e.message)
+        .join(" | ")
+        .toLowerCase();
+    // Extract error code from various error shapes, innermost first
+    const errorCode = chain
+        .map((e) => e.code)
+        .reverse()
+        .find((c) => typeof c === "string")
+        ?.toUpperCase();
     // Check for retryable network error codes
     if (errorCode && RETRYABLE_ERROR_CODES.includes(errorCode)) {
         return true;
@@ -669,7 +712,7 @@ export class FileDetector {
         const confidenceThreshold = options?.confidenceThreshold ?? 80;
         const strategies = [
             new MagicBytesStrategy(),
-            new MimeTypeStrategy(responseMimeType),
+            new MimeTypeStrategy(responseMimeType, getAttachmentPolicy(options)),
             new ExtensionStrategy(),
             new ContentHeuristicStrategy(),
         ];
@@ -1606,55 +1649,27 @@ export class FileDetector {
     static async loadUrl(url, options) {
         const maxSize = options?.maxSize || 200 * 1024 * 1024; // 200MB default (matches Curator memory-safety cap)
         const timeout = options?.timeout || FileDetector.DEFAULT_NETWORK_TIMEOUT;
+        const policy = getAttachmentPolicy(options);
         return withRetry(async () => {
             try {
-                // Dynamic import keeps undici off the package's static import
-                // graph — it is only needed once a URL-referenced attachment
-                // actually has to be fetched. See
-                // test/continuous-test-suite-import-cost.ts.
-                const { request } = await import("undici");
-                const response = await request(url, {
-                    dispatcher: await redirectFollowingDispatcher(5),
-                    method: "GET",
-                    headersTimeout: timeout,
-                    bodyTimeout: timeout,
+                // `downloadAttachment` applies the instance's URL policy (HTTPS and
+                // public hosts unless opened up), pins the connection to the vetted
+                // addresses, re-validates every redirect hop and bounds the body
+                // while it streams — a declared oversize response is refused at
+                // the headers, an undeclared one as soon as it passes the cap.
+                const downloaded = await downloadAttachment(url, {
+                    policy,
+                    maxBytes: maxSize,
+                    label: "attached URL",
+                    // One budget for headers and body, where the two undici timeouts
+                    // used to apply separately.
+                    timeoutMs: timeout * 2,
                 });
-                if (response.statusCode !== 200) {
-                    // #360: pair the code with its standard reason phrase (e.g. 404 →
-                    // "Not Found") so the message is readable rather than a bare
-                    // number. Sourced from Node's own `http.STATUS_CODES` table
-                    // rather than a hand-written map that could drift from it, and
-                    // falls back gracefully for a non-standard code that table
-                    // doesn't recognize. Query string / fragment stays stripped — a
-                    // presigned URL's token must not be echoed into a thrown error.
-                    const statusText = STATUS_CODES[response.statusCode];
-                    throw new Error(`HTTP ${response.statusCode}${statusText ? ` ${statusText}` : ""} fetching ${redactUrlForError(url)}`);
-                }
-                const contentType = response.headers["content-type"] || "";
-                const declaredLength = Number(response.headers["content-length"]);
-                if (Number.isFinite(declaredLength) && declaredLength > maxSize) {
-                    // `request()` resolves after response headers arrive. Close the
-                    // unread stream before throwing so a declared oversize response
-                    // never enters the body-reading loop or holds its connection.
-                    // Undici emits an abort error asynchronously when the stream is
-                    // destroyed, so consume that expected event before closing it.
-                    response.body.once("error", () => { });
-                    response.body.destroy();
-                    throw new Error(`File too large: ${formatFileSize(declaredLength)} (max: ${formatFileSize(maxSize)})`);
-                }
+                const contentType = downloaded.contentType;
                 // #323: cache the Content-Type from this GET so a subsequent detection
                 // of the same URL needs no HEAD.
                 setCachedUrlContentType(url, contentType, Date.now());
-                const chunks = [];
-                let totalSize = 0;
-                for await (const chunk of response.body) {
-                    totalSize += chunk.length;
-                    if (totalSize > maxSize) {
-                        throw new Error(`File too large: ${formatFileSize(totalSize)} (max: ${formatFileSize(maxSize)})`);
-                    }
-                    chunks.push(chunk);
-                }
-                return { content: Buffer.concat(chunks), contentType };
+                return { content: downloaded.buffer, contentType };
             }
             catch (error) {
                 // Node/undici DNS, TLS, and connect-timeout errors embed the full
@@ -1673,10 +1688,13 @@ export class FileDetector {
                 // string/object can just as easily carry the full URL), so there is
                 // no unconditional `throw error` fallback that would bypass
                 // redaction for that case.
-                const cause = sanitizeErrorCause(error);
+                // Read the transport code off the ORIGINAL chain before sanitizing:
+                // undici's "fetch failed" TypeError keeps ECONNRESET/ETIMEDOUT on
+                // `cause`, and the sanitized copy deliberately drops that chain.
+                const code = innermostErrorCode(error);
+                const cause = sanitizeErrorCause(innermostError(error));
                 const redacted = new Error(cause.message, { cause });
                 redacted.name = cause.name;
-                const code = cause.code;
                 if (code !== undefined) {
                     redacted.code = code;
                 }
@@ -1709,6 +1727,38 @@ export class FileDetector {
         // check and the open() call routes the read outside the sandbox even
         // though validation passed (TOCTOU). With no sandbox configured there's no
         // boundary to defend, so the original path is used as given.
+        //
+        // Without an `allowedBaseDir` the instance's attachment policy decides:
+        // its `allowedRoots` (when configured) bound the read the same way, and
+        // either way the file is opened O_NOFOLLOW on its real path, regular
+        // files only, under the size cap — see `readAttachmentFile`.
+        if (!options?.allowedBaseDir) {
+            try {
+                const read = await readAttachmentFile(filePath, {
+                    policy: getAttachmentPolicy(options),
+                    maxBytes: maxSize,
+                    label: "attached file",
+                });
+                return read.buffer;
+            }
+            catch (error) {
+                if (error instanceof AttachmentRefusedError) {
+                    throw error;
+                }
+                // A failed open/stat (ENOENT, EACCES, ELOOP, …) embeds the full path
+                // in its message. Throw a copy whose message and cause are redacted
+                // to the basename, keeping the code so callers can still classify it.
+                logger.debug("loadFromPath: read failed", { filePath, error });
+                const cause = sanitizeErrorCause(error, { filePath });
+                const failed = new Error(cause.message, { cause });
+                failed.name = cause.name;
+                const code = cause.code;
+                if (code !== undefined) {
+                    failed.code = code;
+                }
+                throw failed;
+            }
+        }
         let pathToOpen = filePath;
         if (options?.allowedBaseDir) {
             let base;
@@ -2352,8 +2402,10 @@ class MagicBytesStrategy {
  */
 class MimeTypeStrategy {
     responseMimeType;
-    constructor(responseMimeType) {
+    attachmentPolicy;
+    constructor(responseMimeType, attachmentPolicy) {
         this.responseMimeType = responseMimeType;
+        this.attachmentPolicy = attachmentPolicy;
     }
     async detect(input) {
         if (this.responseMimeType !== undefined) {
@@ -2378,20 +2430,18 @@ class MimeTypeStrategy {
             if (contentType === undefined) {
                 // Wrap the whole HEAD (request + body drain) in withTimeout so a stalled
                 // dump() can't hang detection, per the project's async-timeout guideline.
+                // The same guard as the GET: a HEAD to a private or loopback target
+                // is a request too, and the old pre-flight followed redirects to
+                // wherever they pointed.
                 contentType = await withTimeout((async () => {
-                    // Dynamic import keeps undici off the package's static import
-                    // graph — it is only needed once a URL-referenced attachment
-                    // actually has to be fetched. See
-                    // test/continuous-test-suite-import-cost.ts.
-                    const { request } = await import("undici");
-                    const response = await request(input, {
-                        dispatcher: await redirectFollowingDispatcher(5),
+                    const head = await downloadAttachment(input, {
+                        policy: this.attachmentPolicy,
+                        maxBytes: 0,
+                        label: "attached URL",
                         method: "HEAD",
-                        headersTimeout: FileDetector.DEFAULT_HEAD_TIMEOUT,
-                        bodyTimeout: FileDetector.DEFAULT_HEAD_TIMEOUT,
+                        timeoutMs: FileDetector.DEFAULT_HEAD_TIMEOUT,
                     });
-                    await response.body.dump();
-                    return response.headers["content-type"] || "";
+                    return head.contentType;
                 })(), FileDetector.DEFAULT_HEAD_TIMEOUT);
                 setCachedUrlContentType(input, contentType, now);
             }

package/dist/utils/json/coerce.js

@@ -181,7 +181,17 @@ function deepUnwrapJsonStrings(value, depth = 0) {
             if (r.changed) {
                 changed = true;
             }
-            out[k] = r.value;
+            // Define, never assign: `out[k] = …` with a model-supplied key of
+            // `__proto__` invokes the prototype setter and swaps `out`'s prototype
+            // for the model's object, so fields hidden from `Object.keys` read back
+            // through property access. `JSON.parse` creates such a key as an own
+            // data property, and this keeps it one.
+            Object.defineProperty(out, k, {
+                value: r.value,
+                enumerable: true,
+                writable: true,
+                configurable: true,
+            });
         }
         return { value: changed ? out : value, changed };
     }

package/dist/utils/logSanitize.d.ts

@@ -15,6 +15,11 @@
  *     jina_ (Jina), fish- (Fish Audio)
  *   - Generic key=value pairs: api_key=…, access_token: …, secret_key=…
  */
+/**
+ * Whether `key` names a value that must never appear in a log — the same list
+ * {@link sanitizeRecord} masks, matched case-insensitively.
+ */
+export declare function isSensitiveLogKey(key: string): boolean;
 /**
  * Truncate `text` to `maxLen` chars then replace embedded secrets with `***`.
  *

package/dist/utils/logSanitize.js

@@ -85,6 +85,14 @@ const SENSITIVE_OBJECT_KEYS = [
     // PII, not a secret — but it has no business in debug log dumps.
     "userEmail",
 ];
+/**
+ * Whether `key` names a value that must never appear in a log — the same list
+ * {@link sanitizeRecord} masks, matched case-insensitively.
+ */
+export function isSensitiveLogKey(key) {
+    const lower = key.toLowerCase();
+    return SENSITIVE_OBJECT_KEYS.some((name) => name.toLowerCase() === lower);
+}
 /**
  * Truncate `text` to `maxLen` chars then replace embedded secrets with `***`.
  *

package/dist/utils/logger.js

@@ -14,6 +14,7 @@
  * - Tabular data display
  */
 import { AsyncLocalStorage } from "node:async_hooks";
+import { isSensitiveLogKey, sanitizeForLog, sanitizeRecord, } from "./logSanitize.js";
 /**
  * Identifies which NeuroLink instance is emitting, for the async operation
  * currently on the stack. Populated by `runInInstanceScope()` — which the SDK
@@ -85,6 +86,69 @@ function cloneLogData(data) {
         return data;
     }
 }
+/**
+ * Per-string cap for central redaction. Deliberately far above anything a
+ * debug payload carries, so this pass redacts without truncating — the
+ * logger's "zero truncation" promise for debug data stands.
+ */
+const REDACTION_STRING_CAP = 1_000_000;
+/** Depth past which a payload is handed to `sanitizeRecord` wholesale. */
+const REDACTION_MAX_DEPTH = 32;
+function isPlainObject(value) {
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * Central redaction for `debug` / `info` payloads — the same key list and
+ * secret patterns as `sanitizeRecord`, applied to plain objects and arrays.
+ *
+ * `sanitizeRecord` itself is not used directly on the whole payload because
+ * its `Object.entries` walk flattens what debug data is full of: an `Error`
+ * becomes `{}` (message and stack gone), a `Buffer` becomes thousands of
+ * numeric keys, a `Date`/`Map`/`Set` becomes `{}`. Those are left as they are
+ * — `serializeData` and `structuredClone` already know how to carry them —
+ * and only plain containers are walked, with sensitive keys masked and
+ * string values scrubbed of bearer tokens and known key prefixes. An `Error`
+ * gets its message scrubbed in place of the instance.
+ *
+ * Cost: one recursive pass over objects a call site already chose to log,
+ * and only when `shouldLog(level)` was true. Nothing runs for the 99% of
+ * `logger.debug` calls that are filtered out.
+ */
+function redactLogData(data, depth = 0) {
+    if (data === null || data === undefined) {
+        return data;
+    }
+    if (typeof data === "string") {
+        return sanitizeForLog(data, REDACTION_STRING_CAP);
+    }
+    if (typeof data !== "object") {
+        return data;
+    }
+    if (data instanceof Error) {
+        const copy = new Error(sanitizeForLog(data.message, REDACTION_STRING_CAP));
+        copy.name = data.name;
+        copy.stack = data.stack
+            ? sanitizeForLog(data.stack, REDACTION_STRING_CAP)
+            : undefined;
+        return copy;
+    }
+    if (depth >= REDACTION_MAX_DEPTH) {
+        return sanitizeRecord(data, REDACTION_STRING_CAP);
+    }
+    if (Array.isArray(data)) {
+        return data.map((item) => redactLogData(item, depth + 1));
+    }
+    if (!isPlainObject(data)) {
+        // Buffer, Date, Map, Set, class instances: carried as they are.
+        return data;
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(data)) {
+        out[key] = isSensitiveLogKey(key) ? "***" : redactLogData(value, depth + 1);
+    }
+    return out;
+}
 class NeuroLinkLogger {
     logLevel = "info";
     logs = [];
@@ -379,10 +443,18 @@ class NeuroLinkLogger {
      * @param message - The message text to log
      * @param data - Optional additional context data to include
      */
-    log(level, message, data) {
+    log(level, message, rawData) {
         if (!this.shouldLog(level)) {
             return;
         }
+        // Central redaction: a `debug`/`info` payload is masked by key
+        // (`apiKey`, `authorization`, `credentials`, …) and scrubbed of
+        // bearer/known-prefix tokens before it is stored, emitted or printed, so
+        // the next `logger.debug("…", options)` cannot leak a credential into
+        // `getLogs()`, a `log-event` sink or the console. `warn`/`error` are
+        // left verbatim: they carry the diagnostics an operator is debugging
+        // with, and every credential-bearing path already redacts at source.
+        const data = level === "debug" || level === "info" ? redactLogData(rawData) : rawData;
         const entry = {
             level,
             message,

package/dist/utils/messageBuilder.d.ts

@@ -1,4 +1,4 @@
-import type { GenerateOptions, MultimodalChatMessage, StreamOptions, TextGenerationOptions, VisionImageOutputFormat } from "../types/index.js";
+import type { AttachmentPolicy, GenerateOptions, MultimodalChatMessage, StreamOptions, TextGenerationOptions, VisionImageOutputFormat } from "../types/index.js";
 import type { ModelMessage, ToolHistoryRow, ToolReplayMode } from "../types/index.js";
 /**
  * Type-safe conversion from MultimodalChatMessage[] to ModelMessage[]
@@ -100,4 +100,4 @@ export declare function buildMultimodalModelMessages(options: GenerateOptions, p
  * Entries that are `http(s)` URLs are left alone — they have no bytes yet, and
  * `processImageToBase64` converts them once they are downloaded.
  */
-export declare function normalizeVisionImageFormats(input: GenerateOptions["input"], outputFormat?: VisionImageOutputFormat): Promise<void>;
+export declare function normalizeVisionImageFormats(input: GenerateOptions["input"], outputFormat?: VisionImageOutputFormat, attachmentPolicy?: AttachmentPolicy): Promise<void>;