@juspay/neurolink 13.8.17 → 13.8.18

package/dist/utils/messageBuilder.js

@@ -1,7 +1,7 @@
-import { existsSync, readFileSync, statSync } from "fs";
-import { open as openAsync, readFile as readFileAsync, stat as statAsync, } from "fs/promises";
+import { constants as fsConstants, existsSync, statSync } from "fs";
+import { open as openAsync, stat as statAsync } from "fs/promises";
 import pLimit from "p-limit";
-import { redirectFollowingDispatcher } from "./redirectDispatcher.js";
+import { downloadAttachment, getAttachmentPolicy, readAttachmentFile, resolveAttachmentPath, resolveAttachmentPolicy, } from "./attachmentPolicy.js";
 import { MultimodalLogger, ProviderImageAdapter, } from "../adapters/providerImageAdapter.js";
 import { CONVERSATION_INSTRUCTIONS, STRUCTURED_OUTPUT_INSTRUCTIONS, } from "../config/conversationMemory.js";
 import { getAvailableInputTokens } from "../constants/contextWindows.js";
@@ -18,6 +18,7 @@ import { needsAudioTranscode, supportsNativeAudio, toProviderCompatibleAudio, }
 import { supportsNativeVideo } from "../adapters/videoFormatSupport.js";
 import { getImageCache } from "./imageCache.js";
 import { ImageProcessor, imageUtils } from "./imageProcessor.js";
+import { SIZE_LIMITS_BYTES } from "../processors/config/sizeLimits.js";
 import { logger } from "./logger.js";
 import { looksLikeSvgMarkup } from "./markupSniff.js";
 import { redactUrlForError } from "./logSanitize.js";
@@ -914,6 +915,13 @@ const PREPROCESSED_FILES = new WeakMap();
  * page cache the read usually hits — detection has just read the same bytes.
  */
 const FILE_READ_TIMEOUT_MS = 30_000;
+/**
+ * Ceiling for a local attachment read by path on the unified `files` path and
+ * the lazy registry. Matches FileDetector's own 200 MB default, so a file the
+ * detector would have accepted is not refused here; `attachments.maxBytes`
+ * lowers it.
+ */
+const ATTACHED_FILE_READ_CAP_BYTES = 200 * 1024 * 1024;
 /**
  * How many files may be detected and processed at once.
  *
@@ -941,7 +949,7 @@ const FILE_PROCESSING_CONCURRENCY = 4;
  * materialised by the time detection runs, and re-fetching a remote URL here
  * would issue a second network request behind the caller's back.
  */
-async function readFileInputBytes(file) {
+async function readFileInputBytes(file, policy) {
     try {
         if (isFileWithMetadata(file)) {
             return file.buffer;
@@ -950,35 +958,18 @@ async function readFileInputBytes(file) {
             return file;
         }
         if (typeof file === "string") {
-            const { readFile, stat } = await import("node:fs/promises");
-            // Two different hangs live here, and they need different guards.
-            //
-            // A FIFO or device node blocks inside the read syscall, where neither a
-            // timeout nor an abort can reach it — measured: with a signal attached,
-            // a blocked FIFO read stays pending through both open and mid-read. The
-            // timeout would return while that read sat there forever. So refuse
-            // anything that is not a regular file up front; that is the only thing
-            // that actually prevents this case.
-            //
-            // A regular file on a slow or hung mount does return control between
-            // chunks, so there the signal works (measured: rejects with AbortError
-            // in flight) — and it matters, because racing the promise alone leaves
-            // the read filling a buffer nobody will collect. Aborting in `finally`
-            // covers both exits; after a resolved read it is a no-op.
-            //
-            // stat-then-read is a TOCTOU window, but a narrow one, and it is strictly
-            // better than the unbounded read it replaces.
-            const stats = await withTimeout(stat(file), FILE_READ_TIMEOUT_MS);
-            if (!stats.isFile()) {
-                return null;
-            }
-            const controller = new AbortController();
-            try {
-                return await withTimeout(readFile(file, { signal: controller.signal }), FILE_READ_TIMEOUT_MS);
-            }
-            finally {
-                controller.abort();
-            }
+            // `readAttachmentFile` applies the instance's roots, opens the real path
+            // O_NOFOLLOW|O_NONBLOCK (so a FIFO cannot park a worker inside the read
+            // syscall — the hang a timeout alone can never reach), refuses anything
+            // that is not a regular file, and drains under the size cap through the
+            // same descriptor it stat'd. The timeout still bounds a slow or hung
+            // mount, where control does return between chunks.
+            const read = await withTimeout(readAttachmentFile(file, {
+                policy,
+                maxBytes: ATTACHED_FILE_READ_CAP_BYTES,
+                label: "attached file",
+            }), FILE_READ_TIMEOUT_MS);
+            return read.buffer;
         }
     }
     catch {
@@ -1046,7 +1037,7 @@ async function appendDetectedFileResult(result, file, options) {
         // and is no worse off than before. This matters most where the frames are
         // absent — ffmpeg is optional, and without it the summary was everything
         // the model saw.
-        const videoBytes = await readFileInputBytes(file);
+        const videoBytes = await readFileInputBytes(file, getAttachmentPolicy(options));
         if (videoBytes) {
             options.input.nativeVideoFiles = [
                 ...(options.input.nativeVideoFiles || []),
@@ -1069,7 +1060,7 @@ async function appendDetectedFileResult(result, file, options) {
         // Carry the bytes forward as well as the summary. Whether they are used is
         // decided later, per provider: one that can listen receives the audio, one
         // that cannot still gets the summary above and is no worse off than before.
-        const audioBytes = await readFileInputBytes(file);
+        const audioBytes = await readFileInputBytes(file, getAttachmentPolicy(options));
         if (audioBytes) {
             options.input.nativeAudioFiles = [
                 ...(options.input.nativeAudioFiles || []),
@@ -1267,6 +1258,9 @@ async function detectFileForUnifiedArray(file, options, provider, genericFileMax
         provider: provider,
         mimetypeHint: fileMimetypeHint,
         filenameHint: fileFilenameHint,
+        // The instance's roots / URL rules / size cap, so a path or URL named in
+        // `files` is read under the same policy as every other attachment.
+        attachmentPolicy: getAttachmentPolicy(options),
     });
 }
 /**
@@ -1379,7 +1373,7 @@ export async function processUnifiedFilesArray(options, maxSize, provider) {
                 // ─── Lazy file registration path ──────────────────────────────
                 const fileSize = fileRegistry ? getFileSize(file) : 0;
                 if (fileRegistry && isLazyCandidate[fileIdx]) {
-                    const registered = await tryRegisterFileReference(file, fileSize, fileRegistry, fileIdx);
+                    const registered = await tryRegisterFileReference(file, fileSize, fileRegistry, fileIdx, getAttachmentPolicy(options));
                     if (registered) {
                         logger.info(`[NEUROLINK] File lazily registered: ${filename} (${fileSize} bytes) — deferred processing`);
                         includedCount++;
@@ -1486,6 +1480,7 @@ async function processExplicitCsvFiles(options) {
     const settled = await Promise.allSettled(csvFiles.map((csvFile) => limit(() => FileDetector.detectAndProcess(csvFile, {
         allowedTypes: ["csv"],
         csvOptions: options.csvOptions,
+        attachmentPolicy: getAttachmentPolicy(options),
     }))));
     for (let i = 0; i < csvFiles.length; i++) {
         const csvFile = csvFiles[i];
@@ -1652,6 +1647,7 @@ async function processExplicitPdfFiles(options, maxSize, provider) {
                 maxSize,
                 allowedTypes: ["pdf"],
                 provider: provider,
+                attachmentPolicy: getAttachmentPolicy(options),
             });
             if (Buffer.isBuffer(result.content)) {
                 pdfFiles.push({
@@ -1782,7 +1778,7 @@ export async function buildMultimodalModelMessages(options, provider, model, rep
     await processUnifiedFilesArray(options, maxSize, provider);
     // Detection can append images (PDF page renders, video keyframes, a HEIC
     // photo), so compatibility conversion has to run after it, not before.
-    await normalizeVisionImageFormats(inp, options.imageOptions?.outputFormat);
+    await normalizeVisionImageFormats(inp, options.imageOptions?.outputFormat, getAttachmentPolicy(options));
     // Process explicit CSV files array
     await processExplicitCsvFiles(options);
     // Post-processing budget enforcement and token usage logging
@@ -1957,7 +1953,11 @@ export async function buildMultimodalModelMessages(options, provider, model, rep
             // the multimodal converter below, so the bytes were dropped and only the
             // metadata summary folded into `text` survived. Exactly the failure this
             // change exists to remove, reintroduced through the other door.
-            userContent = await convertContentToProviderFormat(inp.content, provider, model, options.pdfOptions, inp.nativeAudioFiles ?? [], options.imageOptions?.outputFormat);
+            userContent = await convertContentToProviderFormat(inp.content, provider, model, options.pdfOptions, {
+                audioFiles: inp.nativeAudioFiles ?? [],
+                outputFormat: options.imageOptions?.outputFormat,
+                attachmentPolicy: getAttachmentPolicy(options),
+            });
         }
         else if ((inp.images && inp.images.length > 0) ||
             pdfFiles.length > 0 ||
@@ -1973,6 +1973,7 @@ export async function buildMultimodalModelMessages(options, provider, model, rep
             userContent = await convertMultimodalToProviderFormat(inp.text ?? "", inp.images || [], pdfFiles, provider, model, {
                 audioFiles: inp.nativeAudioFiles ?? [],
                 outputFormat: options.imageOptions?.outputFormat,
+                attachmentPolicy: getAttachmentPolicy(options),
             });
         }
         else {
@@ -2066,7 +2067,8 @@ async function appendCsvContentToText(csvItems, baseText) {
 /**
  * Convert advanced content format to provider-specific format
  */
-async function convertContentToProviderFormat(content, provider, model, pdfOptions, audioFiles = [], outputFormat) {
+async function convertContentToProviderFormat(content, provider, model, pdfOptions, mediaOptions = {}) {
+    const { audioFiles = [], outputFormat, attachmentPolicy } = mediaOptions;
     const textContent = content.find((c) => c.type === "text");
     const imageContent = content.filter((c) => c.type === "image");
     const pdfContent = content.filter((c) => c.type === "pdf");
@@ -2129,6 +2131,7 @@ async function convertContentToProviderFormat(content, provider, model, pdfOptio
     return await convertMultimodalToProviderFormat(text, images, pdfFiles, provider, model, {
         audioFiles,
         outputFormat,
+        attachmentPolicy,
     });
 }
 /**
@@ -2144,8 +2147,12 @@ function isInternetUrl(input) {
  * Download image from URL and convert to base64 data URI
  * Rate-limited to 10 downloads per second to prevent DoS
  * Uses LRU cache to avoid redundant downloads of the same URL
+ *
+ * The fetch goes through `downloadAttachment`: HTTPS to a public host unless
+ * the instance's policy says otherwise, the connection pinned to the vetted
+ * addresses, redirects re-validated per hop, body bounded while streaming.
  */
-async function downloadImageFromUrl(url) {
+async function downloadImageFromUrl(url, policy) {
     // Check cache first (before rate limiting)
     const cache = getImageCache();
     const cached = cache.get(url);
@@ -2156,40 +2163,19 @@ async function downloadImageFromUrl(url) {
     // Apply rate limiting only if cache missed
     await urlDownloadRateLimiter.acquire();
     try {
-        // Dynamic import keeps undici off the package's static import graph —
-        // it is only needed once a URL-referenced image 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: 10000, // 10 second timeout for headers
-            bodyTimeout: 30000, // 30 second timeout for body,
+        const downloaded = await downloadAttachment(url, {
+            policy,
+            maxBytes: IMAGE_URL_MAX_BYTES,
+            label: "image URL",
+            timeoutMs: IMAGE_URL_TIMEOUT_MS,
         });
-        if (response.statusCode !== 200) {
-            throw new Error(`HTTP ${response.statusCode}: Failed to download image from ${url}`);
-        }
         // Get content type from headers
-        const contentType = response.headers["content-type"] || "image/jpeg";
+        const contentType = downloaded.contentType || "image/jpeg";
         // Validate it's an image
         if (!contentType.startsWith("image/")) {
             throw new Error(`URL does not point to an image. Content-Type: ${contentType}`);
         }
-        // Read the response body, enforcing the size cap INCREMENTALLY: a
-        // misbehaving/malicious server on a user-supplied URL must not be able to
-        // force unbounded memory growth by streaming gigabytes before we ever
-        // check the total (the previous code concat'd everything first).
-        const maxSize = 10 * 1024 * 1024; // 10MB
-        const chunks = [];
-        let totalSize = 0;
-        for await (const chunk of response.body) {
-            totalSize += chunk.length;
-            if (totalSize > maxSize) {
-                throw new Error(`Image too large: exceeds ${maxSize} bytes while downloading from ${url}`);
-            }
-            chunks.push(chunk);
-        }
-        const buffer = Buffer.concat(chunks);
+        const buffer = downloaded.buffer;
         // Convert to base64 data URI
         const base64 = buffer.toString("base64");
         const dataUri = `data:${contentType};base64,${base64}`;
@@ -2199,9 +2185,13 @@ async function downloadImageFromUrl(url) {
     }
     catch (error) {
         MultimodalLogger.logError("URL_DOWNLOAD_FAILED", error, { url });
-        throw new Error(`Failed to download image from ${url}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        throw new Error(`Failed to download image from ${redactUrlForError(url)}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
     }
 }
+/** 10 MB — the cap `downloadImageFromUrl` has always applied. */
+const IMAGE_URL_MAX_BYTES = 10 * 1024 * 1024;
+/** Headers plus body for an image URL; the previous 10 s + 30 s budgets, combined. */
+const IMAGE_URL_TIMEOUT_MS = 40_000;
 /**
  * Get MIME type from an image file extension.
  *
@@ -2338,34 +2328,41 @@ function detectMimeTypeFromBuffer(buffer) {
  * Uses async fs so a large/slow-filesystem image never blocks the event loop
  * while the size guard (below) or the read itself is in flight.
  */
-async function convertFilePathToBase64(filePath) {
-    let stats;
+async function convertFilePathToBase64(filePath, policy) {
+    const context = `image file "${filePath}"`;
+    let buffer;
     try {
-        stats = await statAsync(filePath);
+        // Roots containment, O_NOFOLLOW open of the real path, regular files
+        // only, and a read bounded at the image cap through the same descriptor
+        // that was stat'd — so neither a symlink swap nor a file growing under
+        // the read gets past the size guard (#257).
+        ({ buffer } = await readAttachmentFile(filePath, {
+            policy,
+            maxBytes: SIZE_LIMITS_BYTES.IMAGE_MAX,
+            label: "image file",
+        }));
     }
     catch (error) {
+        if (error instanceof NeuroLinkError) {
+            throw error;
+        }
+        const code = error instanceof Error ? error.code : undefined;
         // Only ENOENT means "not found" — EACCES/ELOOP/etc. are real access or
         // filesystem problems that must not be misreported as a missing file.
-        const code = error instanceof Error
-            ? error.code
-            : undefined;
         if (code === "ENOENT") {
             throw new Error(`Image file not found: ${filePath}`, { cause: error });
         }
+        if (code === "ATTACHMENT_NOT_A_FILE") {
+            throw new Error(`Image path is not a file: ${filePath}`, {
+                cause: error,
+            });
+        }
+        if (code === "ATTACHMENT_TOO_LARGE") {
+            // Preserve the typed IMAGE_TOO_LARGE error callers already match on.
+            ImageProcessor.validateSize(Number.MAX_SAFE_INTEGER, context);
+        }
         throw new Error(`Cannot access image file ${filePath}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
     }
-    if (!stats.isFile()) {
-        throw new Error(`Image path is not a file: ${filePath}`);
-    }
-    // #257: check the file size via stat BEFORE reading it into memory, so a
-    // huge image path never triggers an unbounded read + base64 allocation.
-    // Delegates to ImageProcessor's shared guard (no local reimplementation).
-    const context = `image file "${filePath}"`;
-    ImageProcessor.validateSize(stats.size, context);
-    const buffer = await readFileAsync(filePath);
-    // TOCTOU: the file can grow, or a symlink can be swapped, between the stat
-    // above and this read completing. Re-validate the bytes actually read
-    // (not just the pre-read stat) before the base64 allocation.
     return ImageProcessor.safeBase64Convert(buffer, context);
 }
 /**
@@ -2377,7 +2374,7 @@ async function convertFilePathToBase64(filePath) {
  * Passing raw base64 avoids this because `new URL(base64string)` throws and
  * the SDK treats the string as inline base64 data instead.
  */
-async function processImageToBase64(image, index, outputFormat) {
+async function processImageToBase64(image, index, outputFormat, policy = resolveAttachmentPolicy()) {
     let imageData;
     let mimeType = "image/jpeg"; // Default mime type
     if (typeof image === "string") {
@@ -2412,7 +2409,7 @@ async function processImageToBase64(image, index, outputFormat) {
         else {
             // File path string - convert to raw base64
             try {
-                imageData = await convertFilePathToBase64(image);
+                imageData = await convertFilePathToBase64(image, policy);
                 mimeType = getMimeTypeFromExtension(image);
             }
             catch (error) {
@@ -2508,7 +2505,7 @@ async function processImageToBase64(image, index, outputFormat) {
  * Entries that are `http(s)` URLs are left alone — they have no bytes yet, and
  * `processImageToBase64` converts them once they are downloaded.
  */
-export async function normalizeVisionImageFormats(input, outputFormat) {
+export async function normalizeVisionImageFormats(input, outputFormat, attachmentPolicy = resolveAttachmentPolicy()) {
     const images = input?.images;
     if (!images || images.length === 0) {
         return;
@@ -2521,7 +2518,7 @@ export async function normalizeVisionImageFormats(input, outputFormat) {
         const payload = isWrapped
             ? entry.data
             : entry;
-        const source = await readImageSourceForConversion(payload);
+        const source = await readImageSourceForConversion(payload, attachmentPolicy);
         if (!source ||
             (!needsVisionTranscode(source.mimeType) &&
                 !mayCarryExifOrientation(source.mimeType))) {
@@ -2679,7 +2676,9 @@ async function probeFileExifOrientation(path, mimeType, size) {
     }
     let handle;
     try {
-        handle = await openAsync(path, "r");
+        // `path` is the symlink-resolved real path from `resolveAttachmentPath`;
+        // O_NOFOLLOW refuses a link swapped in since.
+        handle = await openAsync(path, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0));
         const prefix = Buffer.alloc(window);
         const { bytesRead } = await handle.read(prefix, 0, prefix.length, 0);
         return probeExifOrientation(prefix.subarray(0, bytesRead), mimeType);
@@ -2691,7 +2690,7 @@ async function probeFileExifOrientation(path, mimeType, size) {
         await handle?.close().catch(() => undefined);
     }
 }
-async function readImageSourceForConversion(payload) {
+async function readImageSourceForConversion(payload, policy) {
     // Both in-memory shapes are size-checked before they can reach a decoder,
     // the same way the file-path branch below is. `withinConversionLimit`
     // reports rather than throws, because this whole pass is best-effort: an
@@ -2732,7 +2731,11 @@ async function readImageSourceForConversion(payload) {
         // without this a large local HEIC/TIFF/BMP was read fully into memory and
         // then re-encoded, with no limit applied at either step. The same applies
         // to a local JPEG read only for its EXIF tag: still bounded before the read.
-        const { size } = await statAsync(payload);
+        // Containment first: a path outside the instance's roots is refused
+        // before anything about it is read, and everything below opens the real
+        // path this returned.
+        const real = await resolveAttachmentPath(payload, policy, "image file");
+        const { size } = await statAsync(real);
         ImageProcessor.validateSize(size, `image at ${safeBasename(payload)}`);
         // A file whose only reason to be here is the orientation question gets
         // that question answered from its header, and is not read at all when the
@@ -2740,10 +2743,14 @@ async function readImageSourceForConversion(payload) {
         // whatever the orientation turns out to be, so a probe would be pure
         // overhead.
         if (!transcodable &&
-            (await probeFileExifOrientation(payload, mimeType, size)) === "absent") {
+            (await probeFileExifOrientation(real, mimeType, size)) === "absent") {
             return undefined;
         }
-        const buffer = await readFileAsync(payload);
+        const { buffer } = await readAttachmentFile(real, {
+            policy,
+            maxBytes: SIZE_LIMITS_BYTES.IMAGE_MAX,
+            label: "image file",
+        });
         ImageProcessor.validateBufferSize(buffer, `image at ${safeBasename(payload)}`);
         return { buffer, mimeType };
     }
@@ -2762,7 +2769,7 @@ async function readImageSourceForConversion(payload) {
  * - Buffers/Data URIs: Processed normally
  * - Supports alt text for accessibility (included as context in text parts)
  */
-async function convertSimpleImagesToProviderFormat(text, images, provider, _model, outputFormat) {
+async function convertSimpleImagesToProviderFormat(text, images, provider, _model, outputFormat, attachmentPolicy = resolveAttachmentPolicy()) {
     // Validate image count against provider-specific limits before processing
     ProviderImageAdapter.validateImageCount(images.length, provider, _model);
     // For Vercel AI SDK, we need to return the content in the standard format
@@ -2801,7 +2808,7 @@ async function convertSimpleImagesToProviderFormat(text, images, provider, _mode
     // Download URL images and add to actual images
     for (const { url, altText } of urlImages) {
         try {
-            const downloadedDataUri = await downloadImageFromUrl(url);
+            const downloadedDataUri = await downloadImageFromUrl(url, attachmentPolicy);
             actualImages.push({ data: downloadedDataUri, altText });
         }
         catch (error) {
@@ -2819,7 +2826,7 @@ async function convertSimpleImagesToProviderFormat(text, images, provider, _mode
     for (const [index, { data: image }] of actualImages.entries()) {
         try {
             // Use helper function to process image and reduce nesting depth
-            const { imageData, mimeType } = await processImageToBase64(image, index, outputFormat);
+            const { imageData, mimeType } = await processImageToBase64(image, index, outputFormat, attachmentPolicy);
             content.push({
                 type: "image",
                 image: imageData,
@@ -2847,12 +2854,13 @@ pdfFiles, provider, model,
 // repo's `max-params` ceiling of 6.
 mediaOptions = {}) {
     const { audioFiles = [], outputFormat } = mediaOptions;
+    const attachmentPolicy = mediaOptions.attachmentPolicy ?? resolveAttachmentPolicy();
     const content = [
         { type: "text", text },
     ];
     // Add images if present
     if (images.length > 0) {
-        const imageContent = await convertSimpleImagesToProviderFormat("", images, provider, model, outputFormat);
+        const imageContent = await convertSimpleImagesToProviderFormat("", images, provider, model, outputFormat, attachmentPolicy);
         if (Array.isArray(imageContent)) {
             imageContent.forEach((item) => {
                 if (item.type !== "text") {
@@ -3165,16 +3173,21 @@ function getFileSize(file) {
  * For file paths: reads the file.
  * For URLs/data URIs: returns null (not supported for lazy registration).
  */
-async function getFileBuffer(file) {
+async function getFileBuffer(file, policy) {
     if (isFileWithMetadata(file)) {
         return file.buffer;
     }
     if (Buffer.isBuffer(file)) {
         return file;
     }
-    if (typeof file === "string" && existsSync(file)) {
+    if (typeof file === "string" && getFileSource(file) === "path") {
         try {
-            return readFileSync(file);
+            const read = await readAttachmentFile(file, {
+                policy,
+                maxBytes: ATTACHED_FILE_READ_CAP_BYTES,
+                label: "attached file",
+            });
+            return read.buffer;
         }
         catch {
             return null;
@@ -3349,9 +3362,9 @@ function inferFileTypeFromMimetype(mimetype) {
  * Returns true if registration succeeded, false if it failed (caller should
  * fall through to full processing).
  */
-async function tryRegisterFileReference(file, fileSize, registry, index = 0) {
+async function tryRegisterFileReference(file, fileSize, registry, index = 0, policy = resolveAttachmentPolicy()) {
     try {
-        const buffer = await getFileBuffer(file);
+        const buffer = await getFileBuffer(file, policy);
         if (!buffer) {
             return false;
         }

package/dist/utils/multimodalOptionsBuilder.d.ts

@@ -80,4 +80,5 @@ export declare function buildMultimodalOptions(options: StreamOptions, providerN
     enableEvaluation: boolean | undefined;
     context: import("../index.js").UnknownRecord | undefined;
     fileRegistry: unknown;
+    attachmentPolicy: import("../index.js").AttachmentPolicy;
 };

package/dist/utils/multimodalOptionsBuilder.js

@@ -1,3 +1,4 @@
+import { getAttachmentPolicy } from "./attachmentPolicy.js";
 /**
  * Builds a normalized multimodal options payload for streaming providers.
  *
@@ -84,5 +85,6 @@ export function buildMultimodalOptions(options, providerName, modelName) {
         enableEvaluation: options.enableEvaluation,
         context: options.context,
         fileRegistry: options.fileRegistry,
+        attachmentPolicy: getAttachmentPolicy(options),
     };
 }

package/dist/utils/redis.d.ts

@@ -3,6 +3,18 @@
  * Helper functions for Redis storage operations
  */
 import type { ChatMessage, RedisClient, RedisConversationObject, RedisStorageConfig } from "../types/index.js";
+/**
+ * Why an id is not usable as a key segment, or `null` when it is.
+ */
+export declare function describeRedisIdProblem(value: string, kind?: "sessionId" | "userId"): string | null;
+/**
+ * Refuse an id that would alias another key or break a SCAN pattern.
+ *
+ * @throws {Error} with `code: "INVALID_REDIS_ID"` unless the legacy switch is
+ *   set, in which case the problem is logged once per id shape and the id
+ *   is used as given.
+ */
+export declare function assertSafeRedisId(value: string, label: "sessionId" | "userId"): void;
 /**
  * Redact the userinfo of every `scheme://user:pass@host` in `text`.
  *

package/dist/utils/redis.js

@@ -5,6 +5,73 @@
 import { randomUUID } from "crypto";
 import { logger } from "./logger.js";
 const SESSION_ONLY_PREFIX = "session-only:";
+/**
+ * Longest id that may become part of a key. Redis itself allows far more, but
+ * a session or user id past this length is not an id.
+ */
+const MAX_REDIS_ID_LENGTH = 512;
+/**
+ * Characters an id may not contain: `:` is the key-segment separator (so
+ * `user "a:b"` + session `"c"` would alias `user "a"` + session `"b:c"`), and
+ * `*`, `?`, `[` are glob metacharacters for SCAN/KEYS patterns; line breaks
+ * never belong in a key.
+ */
+const FORBIDDEN_REDIS_ID_CHARS = /[:*?[\r\n]/;
+// userId may carry ':' (multi-tenant ids such as `cust:merchant:shop` are established
+// usage); the key `${prefix}${userId}:${sessionId}` still splits unambiguously at the
+// last colon because sessionId may not contain one. Glob characters and line breaks
+// stay forbidden so an id can never widen a SCAN pattern or break a log line.
+const FORBIDDEN_REDIS_USER_ID_CHARS = /[*?[\r\n]/;
+/**
+ * Set `NEUROLINK_REDIS_ALLOW_LEGACY_IDS=1` to accept ids that fail the check
+ * with a warning instead of an error, for a deployment whose stored sessions
+ * already carry `:` in their ids and needs time to migrate.
+ */
+const ENV_ALLOW_LEGACY_IDS = "NEUROLINK_REDIS_ALLOW_LEGACY_IDS";
+/**
+ * Why an id is not usable as a key segment, or `null` when it is.
+ */
+export function describeRedisIdProblem(value, kind = "sessionId") {
+    if (value.length === 0) {
+        return "is empty";
+    }
+    if (value.length > MAX_REDIS_ID_LENGTH) {
+        return `is longer than ${MAX_REDIS_ID_LENGTH} characters`;
+    }
+    if (kind === "userId") {
+        if (FORBIDDEN_REDIS_USER_ID_CHARS.test(value)) {
+            return "contains a reserved character ('*', '?', '[' or a line break)";
+        }
+    }
+    else if (FORBIDDEN_REDIS_ID_CHARS.test(value)) {
+        return "contains a reserved character (':', '*', '?', '[' or a line break)";
+    }
+    if (value === SESSION_ONLY_PREFIX.slice(0, -1)) {
+        return "is the reserved no-user namespace";
+    }
+    return null;
+}
+/**
+ * Refuse an id that would alias another key or break a SCAN pattern.
+ *
+ * @throws {Error} with `code: "INVALID_REDIS_ID"` unless the legacy switch is
+ *   set, in which case the problem is logged once per id shape and the id
+ *   is used as given.
+ */
+export function assertSafeRedisId(value, label) {
+    const problem = describeRedisIdProblem(value, label);
+    if (problem === null) {
+        return;
+    }
+    const message = `[REDIS] ${label} ${problem}; it cannot be used in a Redis key`;
+    if (process.env[ENV_ALLOW_LEGACY_IDS] === "1") {
+        logger.warn(`${message} (allowed by ${ENV_ALLOW_LEGACY_IDS})`);
+        return;
+    }
+    const error = new Error(`${message}. Set ${ENV_ALLOW_LEGACY_IDS}=1 to accept legacy ids while migrating.`);
+    error.code = "INVALID_REDIS_ID";
+    throw error;
+}
 /** Characters that end the authority (`user:pass@host:port`) of a URL in text. */
 const AUTHORITY_TERMINATORS = new Set(["/", "?", "#", " ", "\t", "\n", "\r"]);
 /**
@@ -222,6 +289,10 @@ export async function createRedisClient(config) {
  * Generates a Redis key for session messages
  */
 export function getSessionKey(config, sessionId, userId) {
+    assertSafeRedisId(sessionId, "sessionId");
+    if (userId !== undefined && userId !== "") {
+        assertSafeRedisId(userId, "userId");
+    }
     if (!userId) {
         logger.warn("[REDIS] getSessionKey called without userId", { sessionId });
         return `${config.keyPrefix}${SESSION_ONLY_PREFIX}${sessionId}`;
@@ -239,6 +310,7 @@ export function getSessionKey(config, sessionId, userId) {
  * Generates a Redis key for user sessions mapping
  */
 export function getUserSessionsKey(config, userId) {
+    assertSafeRedisId(userId, "userId");
     return `${config.userSessionsKeyPrefix}${userId}`;
 }
 /**

package/dist/utils/safeFetch.d.ts

@@ -14,6 +14,13 @@
  * Use this for **every** download of an external (caller-supplied or
  * third-party-returned) URL. Direct `fetch(url)` of such URLs is unsafe.
  *
+ * Redirects are refused by default. A caller that opts in (`maxRedirects`)
+ * gets each hop validated and pinned exactly like the first request, and the
+ * caller's `headers` are sent to the first host only — a credential meant for
+ * one origin is never replayed to the one it redirects to. `allowInsecure`
+ * and `allowPrivateNetwork` relax the URL policy for SDK callers that have
+ * said so explicitly; the server path never passes them.
+ *
  * When the environment configures a proxy for the URL (HTTPS_PROXY / ALL_PROXY,
  * and the host is not in NO_PROXY) the download goes through that proxy and
  * nowhere else: there is no fallback to a direct connection. The proxy resolves
@@ -22,7 +29,19 @@
  *
  * @module utils/safeFetch
  */
-import type { SafeDownloadOptions } from "../types/index.js";
+import type { SafeDownloadOptions, SafeDownloadResult } from "../types/index.js";
+/**
+ * Safely download an external URL and report what came back.
+ *
+ * Same guarantees as {@link safeDownload}; additionally returns the final
+ * response's `Content-Type`/`Content-Encoding`, the URL that produced the body
+ * and how many redirect hops were taken.
+ *
+ * @throws {Error} if any URL on the way is unsafe, the response is too large,
+ *   a redirect is encountered beyond what `maxRedirects` allows, or the HTTP
+ *   status indicates failure.
+ */
+export declare function safeDownloadWithMeta(url: string, options: SafeDownloadOptions): Promise<SafeDownloadResult>;
 /**
  * Safely download a binary asset from an external URL.
  *
@@ -30,3 +49,5 @@ import type { SafeDownloadOptions } from "../types/index.js";
  *   is encountered, or the HTTP status indicates failure.
  */
 export declare function safeDownload(url: string, options: SafeDownloadOptions): Promise<Buffer>;
+/** Hop count applied when a caller opts into redirects without naming one. */
+export declare function defaultRedirectHops(follow: boolean): number;