@juspay/neurolink 13.8.17 → 13.8.18

package/dist/music/providers/BeatovenMusic.js

@@ -10,8 +10,8 @@
 import { ErrorCategory, ErrorSeverity } from "../../constants/enums.js";
 import { logger } from "../../utils/logger.js";
 import { MUSIC_ERROR_CODES, MusicError } from "../../utils/musicProcessor.js";
-import { MAX_AUDIO_BYTES, readBoundedBuffer } from "../../utils/sizeGuard.js";
-import { assertSafeUrl } from "../../utils/ssrfGuard.js";
+import { MAX_AUDIO_BYTES } from "../../utils/sizeGuard.js";
+import { safeDownload } from "../../utils/safeFetch.js";
 const DEFAULT_BASE_URL = "https://public-api.beatoven.ai";
 const REQUEST_TIMEOUT_MS = 30_000;
 const POLL_INTERVAL_MS = 3_000;
@@ -263,26 +263,20 @@ export class BeatovenMusic {
         return (await response.json());
     }
     async downloadTrack(url) {
+        // `safeDownload` validates the provider-returned URL (HTTPS, public host),
+        // pins the connection to the vetted addresses, refuses redirects and
+        // bounds the body while it streams — where this was a one-off URL check
+        // followed by a plain `fetch`, which left redirects and a rebinding
+        // resolver uncovered.
         try {
-            await assertSafeUrl(url);
-        }
-        catch (err) {
-            throw new MusicError({
-                code: MUSIC_ERROR_CODES.GENERATION_FAILED,
-                message: `Beatoven track URL rejected: ${err instanceof Error ? err.message : String(err)}`,
-                category: ErrorCategory.VALIDATION,
-                severity: ErrorSeverity.HIGH,
-                retriable: false,
-                context: { url },
+            return await safeDownload(url, {
+                maxBytes: MAX_AUDIO_BYTES,
+                label: "Beatoven track",
+                timeoutMs: REQUEST_TIMEOUT_MS,
             });
         }
-        const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
-        let response;
-        try {
-            response = await fetch(url, { signal: controller.signal });
-        }
         catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
             if (err instanceof Error && err.name === "AbortError") {
                 throw new MusicError({
                     code: MUSIC_ERROR_CODES.GENERATION_FAILED,
@@ -293,41 +287,36 @@ export class BeatovenMusic {
                     originalError: err,
                 });
             }
+            if (/rejected|permitted|blocked range|redirect/i.test(message)) {
+                throw new MusicError({
+                    code: MUSIC_ERROR_CODES.GENERATION_FAILED,
+                    message: `Beatoven track URL rejected: ${message}`,
+                    category: ErrorCategory.VALIDATION,
+                    severity: ErrorSeverity.HIGH,
+                    retriable: false,
+                    context: { url },
+                });
+            }
+            if (/too large|size cap/i.test(message)) {
+                throw new MusicError({
+                    code: MUSIC_ERROR_CODES.GENERATION_FAILED,
+                    message: `Beatoven track download exceeded size limit: ${message}`,
+                    category: ErrorCategory.EXECUTION,
+                    severity: ErrorSeverity.HIGH,
+                    retriable: false,
+                    context: { url },
+                });
+            }
+            const status = /HTTP (\d{3})/.exec(message)?.[1];
             throw new MusicError({
                 code: MUSIC_ERROR_CODES.GENERATION_FAILED,
-                message: `Beatoven track download network error: ${err instanceof Error ? err.message : String(err)}`,
+                message: `Beatoven track download failed: ${message}`,
                 category: ErrorCategory.NETWORK,
                 severity: ErrorSeverity.MEDIUM,
-                retriable: true,
+                retriable: status === undefined || Number(status) >= 500,
                 originalError: err instanceof Error ? err : undefined,
                 context: { url },
             });
         }
-        finally {
-            clearTimeout(timeoutId);
-        }
-        if (!response.ok) {
-            throw new MusicError({
-                code: MUSIC_ERROR_CODES.GENERATION_FAILED,
-                message: `Beatoven track download failed: ${response.status}`,
-                category: ErrorCategory.NETWORK,
-                severity: ErrorSeverity.MEDIUM,
-                retriable: response.status >= 500,
-                context: { status: response.status, url },
-            });
-        }
-        try {
-            return await readBoundedBuffer(response, MAX_AUDIO_BYTES, "Beatoven track");
-        }
-        catch (err) {
-            throw new MusicError({
-                code: MUSIC_ERROR_CODES.GENERATION_FAILED,
-                message: `Beatoven track download exceeded size limit: ${err instanceof Error ? err.message : String(err)}`,
-                category: ErrorCategory.EXECUTION,
-                severity: ErrorSeverity.HIGH,
-                retriable: false,
-                context: { url },
-            });
-        }
     }
 }

package/dist/music/providers/ReplicateMusic.js

@@ -13,8 +13,8 @@ import { MUSIC_ERROR_CODES, MusicError } from "../../utils/musicProcessor.js";
 import { logger } from "../../utils/logger.js";
 import { getReplicateAuth } from "../../adapters/replicate/auth.js";
 import { downloadPredictionOutput, predict, } from "../../adapters/replicate/predictionLifecycle.js";
-import { MAX_AUDIO_BYTES, readBoundedBuffer } from "../../utils/sizeGuard.js";
-import { assertSafeUrl } from "../../utils/ssrfGuard.js";
+import { MAX_AUDIO_BYTES } from "../../utils/sizeGuard.js";
+import { safeDownload } from "../../utils/safeFetch.js";
 const DEFAULT_MODEL = "meta/musicgen:7be0f12c54a8d033a0fbd14418c9af98962da9a86f5ff7811f9b3423a1f0b7d7";
 export class ReplicateMusic {
     maxDurationSeconds = 30;
@@ -154,27 +154,18 @@ export class ReplicateMusic {
                 retriable: false,
             });
         }
-        try {
-            await assertSafeUrl(input);
-        }
-        catch (err) {
-            throw new MusicError({
-                code: MUSIC_ERROR_CODES.INVALID_INPUT,
-                message: `Unsafe URL rejected: ${err instanceof Error ? err.message : String(err)}`,
-                category: ErrorCategory.VALIDATION,
-                severity: ErrorSeverity.HIGH,
-                retriable: false,
-                context: { url: input },
-            });
-        }
+        // `safeDownload`: URL vetted (HTTPS, public host), connection pinned to
+        // the vetted addresses, redirects refused, body bounded while streaming.
         const FETCH_TIMEOUT_MS = 60_000;
-        const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
-        let r;
         try {
-            r = await fetch(input, { signal: controller.signal });
+            return await safeDownload(input, {
+                maxBytes: MAX_AUDIO_BYTES,
+                label: "Replicate reference audio",
+                timeoutMs: FETCH_TIMEOUT_MS,
+            });
         }
         catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
             if (err instanceof Error && err.name === "AbortError") {
                 throw new MusicError({
                     code: MUSIC_ERROR_CODES.GENERATION_FAILED,
@@ -184,31 +175,33 @@ export class ReplicateMusic {
                     retriable: true,
                 });
             }
-            throw err;
-        }
-        finally {
-            clearTimeout(timeoutId);
-        }
-        if (!r.ok) {
+            if (/rejected|permitted|blocked range|redirect/i.test(message)) {
+                throw new MusicError({
+                    code: MUSIC_ERROR_CODES.INVALID_INPUT,
+                    message: `Unsafe URL rejected: ${message}`,
+                    category: ErrorCategory.VALIDATION,
+                    severity: ErrorSeverity.HIGH,
+                    retriable: false,
+                    context: { url: input },
+                });
+            }
+            if (/too large|size cap/i.test(message)) {
+                throw new MusicError({
+                    code: MUSIC_ERROR_CODES.INVALID_INPUT,
+                    message: `Replicate reference audio too large: ${message}`,
+                    category: ErrorCategory.VALIDATION,
+                    severity: ErrorSeverity.HIGH,
+                    retriable: false,
+                    context: { url: input },
+                });
+            }
+            const status = /HTTP (\d{3})/.exec(message)?.[1];
             throw new MusicError({
                 code: MUSIC_ERROR_CODES.GENERATION_FAILED,
-                message: `Failed to fetch reference audio: ${input}: ${r.status}`,
+                message: `Failed to fetch reference audio: ${input}: ${message}`,
                 category: ErrorCategory.NETWORK,
                 severity: ErrorSeverity.MEDIUM,
-                retriable: r.status >= 500,
-            });
-        }
-        try {
-            return await readBoundedBuffer(r, MAX_AUDIO_BYTES, "Replicate reference audio");
-        }
-        catch (err) {
-            throw new MusicError({
-                code: MUSIC_ERROR_CODES.INVALID_INPUT,
-                message: `Replicate reference audio too large: ${err instanceof Error ? err.message : String(err)}`,
-                category: ErrorCategory.VALIDATION,
-                severity: ErrorSeverity.HIGH,
-                retriable: false,
-                context: { url: input },
+                retriable: status === undefined || Number(status) >= 500,
             });
         }
     }

package/dist/neurolink.d.ts

@@ -194,6 +194,13 @@ export declare class NeuroLink {
     private hitlManager?;
     private _sessionCostUsd;
     private fileRegistry;
+    /**
+     * What this instance may read or fetch when a call names a file path or a
+     * URL: resolved once from `config.attachments` and the
+     * `NEUROLINK_ATTACHMENT_*` variables, stamped onto every call's options so
+     * the loaders see the same answer. See `utils/attachmentPolicy.ts`.
+     */
+    private readonly attachmentPolicy;
     private cachedFileTools;
     private memoryInstance?;
     private memorySDKConfig?;
@@ -591,7 +598,15 @@ export declare class NeuroLink {
      */
     private registerDirectToolsServerInternal;
     /**
-     * Load MCP configuration from .mcp-config.json with parallel loading for improved performance
+     * Load the project MCP configuration, if this instance is allowed one.
+     *
+     * The working directory is not searched on its own. A file is loaded only
+     * when `mcp.configPath` names it, `mcp.trustProjectConfig` opts into
+     * `<cwd>/.mcp-config.json`, the CLI has registered its hash-pinned trust
+     * decision, or a host set `ProviderRegistry.setOptions({ enableManualMCP:
+     * true })` after construction (the constructor resets it to `false`, the
+     * SDK default). Otherwise this is a no-op and only servers added through
+     * `addExternalMCPServer` / `addInMemoryMCPServer` exist.
      */
     private loadMCPConfigurationInternal;
     /**

package/dist/neurolink.js

@@ -6,12 +6,18 @@ import { beginOllamaDiagnostic, captureOllamaDiagnosticContext, completeOllamaDi
  * Enhanced AI provider system with natural MCP tool access.
  * Uses real MCP infrastructure for tool discovery and execution.
  */
-// Load environment variables from .env file (critical for SDK usage).
-// Shared with the CLI so the two implicit loads cannot drift apart again.
-// Neither honoured DOTENV_CONFIG_PATH, and they had already drifted in how
-// each suppressed dotenv's banner — one conditional, one unconditional.
-import { loadProcessDotenv } from "./utils/dotenvBootstrap.js";
-await loadProcessDotenv();
+// The SDK no longer reads `<cwd>/.env` as a side effect of being imported:
+// a library loaded inside an untrusted checkout would pick up that
+// checkout's `*_BASE_URL` overrides and send the host's real keys wherever
+// they pointed. The CLI still loads `.env` at startup (it is interactive and
+// the directory is the user's); an SDK host that wants the same calls
+// `loadDotenv()` from the package root, or starts the process with
+// `NEUROLINK_DOTENV=1` in the real environment, which is honoured here.
+import { isSdkDotenvOptIn, loadProcessDotenv, } from "./utils/dotenvBootstrap.js";
+import { resolveProjectMcpConfigPath } from "./mcp/projectConfigTrust.js";
+if (isSdkDotenvOptIn()) {
+    await loadProcessDotenv({ caller: "sdk" });
+}
 import { SpanKind, SpanStatusCode, context, trace, } from "@opentelemetry/api";
 import { getPropagatedAttributesFromContext } from "@langfuse/core";
 import { LangfuseOtelSpanAttributes } from "@langfuse/tracing";
@@ -43,6 +49,7 @@ import { createToolEventPayload } from "./core/toolEvents.js";
 import { ProviderFactory } from "./factories/providerFactory.js";
 import { ProviderRegistry } from "./factories/providerRegistry.js";
 import { FileReferenceRegistry } from "./files/fileReferenceRegistry.js";
+import { resolveAttachmentPolicy } from "./utils/attachmentPolicy.js";
 import { createFileTools } from "./files/fileTools.js";
 import { HITLManager, DEFAULT_ALLOW_MODIFICATION } from "./hitl/hitlManager.js";
 import { ToolCallBatcher } from "./mcp/batching/index.js";
@@ -796,6 +803,13 @@ export class NeuroLink {
     _sessionCostUsd = 0;
     // File Reference Registry for lazy on-demand file processing
     fileRegistry;
+    /**
+     * What this instance may read or fetch when a call names a file path or a
+     * URL: resolved once from `config.attachments` and the
+     * `NEUROLINK_ATTACHMENT_*` variables, stamped onto every call's options so
+     * the loaders see the same answer. See `utils/attachmentPolicy.ts`.
+     */
+    attachmentPolicy;
     // Cached file tools to avoid redundant createFileTools() calls per generate/stream
     cachedFileTools = null;
     // Memory instance and config
@@ -1294,6 +1308,7 @@ export class NeuroLink {
             this.toolRegistry.setFileToolRootResolver(() => this.resolveFileToolRoots(undefined));
         }
         this.fileRegistry = new FileReferenceRegistry();
+        this.attachmentPolicy = resolveAttachmentPolicy(config?.attachments);
         this.observabilityConfig = config?.observability;
         if (this.observabilityConfig) {
             ensureTelemetry(this.observabilityConfig);
@@ -2743,12 +2758,32 @@ Current user's request: ${currentInput}`;
         }
     }
     /**
-     * Load MCP configuration from .mcp-config.json with parallel loading for improved performance
+     * Load the project MCP configuration, if this instance is allowed one.
+     *
+     * The working directory is not searched on its own. A file is loaded only
+     * when `mcp.configPath` names it, `mcp.trustProjectConfig` opts into
+     * `<cwd>/.mcp-config.json`, the CLI has registered its hash-pinned trust
+     * decision, or a host set `ProviderRegistry.setOptions({ enableManualMCP:
+     * true })` after construction (the constructor resets it to `false`, the
+     * SDK default). Otherwise this is a no-op and only servers added through
+     * `addExternalMCPServer` / `addInMemoryMCPServer` exist.
      */
     async loadMCPConfigurationInternal() {
         try {
-            const configResult = await this.externalServerManager.loadMCPConfiguration(undefined, // Use default config path
-            { parallel: true });
+            const resolution = await resolveProjectMcpConfigPath({
+                configPath: this.mcpEnhancementsConfig?.configPath,
+                trustProjectConfig: this.mcpEnhancementsConfig?.trustProjectConfig,
+                enableManualMCP: ProviderRegistry.getOptions().enableManualMCP,
+            });
+            if (!resolution) {
+                mcpLogger.debug("[NeuroLink] No project MCP configuration to load: the working directory is not searched unless mcp.configPath, mcp.trustProjectConfig or a CLI trust decision names a file");
+                return;
+            }
+            mcpLogger.debug("[NeuroLink] Loading project MCP configuration", {
+                path: resolution.path,
+                source: resolution.source,
+            });
+            const configResult = await this.externalServerManager.loadMCPConfiguration(resolution.path, { parallel: true });
             mcpLogger.debug("[NeuroLink] MCP configuration loaded successfully", {
                 serversLoaded: configResult.serversLoaded,
                 errors: configResult.errors.length,
@@ -3339,6 +3374,14 @@ Current user's request: ${currentInput}`;
             catch (error) {
                 logger.warn("[NeuroLink] Memory condenser shutdown failed:", error);
             }
+            // Persisted attachments live under a private tmpdir; remove them with
+            // the instance instead of leaving uploads behind for the exit sweep.
+            try {
+                await this.fileRegistry.clear();
+            }
+            catch (error) {
+                logger.warn("[NeuroLink] File registry cleanup failed:", error);
+            }
             try {
                 await this.releaseTelemetryHold();
                 logger.debug("[NeuroLink] OpenTelemetry shutdown completed");
@@ -4709,7 +4752,7 @@ Current user's request: ${currentInput}`;
         if (options.rag?.files?.length) {
             try {
                 const { prepareRAGTool } = await import("./rag/ragIntegration.js");
-                const ragResult = await prepareRAGTool(options.rag, options.provider);
+                const ragResult = await prepareRAGTool(options.rag, options.provider, this.attachmentPolicy);
                 if (!options.tools) {
                     options.tools = {};
                 }
@@ -4822,6 +4865,7 @@ Current user's request: ${currentInput}`;
             tts: options.tts,
             stt: options.stt,
             fileRegistry: this.fileRegistry,
+            attachmentPolicy: this.attachmentPolicy,
             timeout: options.timeout,
             turnTimeoutMs: options.turnTimeoutMs,
             stallTimeoutMs: options.stallTimeoutMs,
@@ -7779,6 +7823,7 @@ Current user's request: ${currentInput}`;
             }
             const originalPrompt = options.input?.text ?? "";
             options.fileRegistry = this.fileRegistry;
+            options.attachmentPolicy = this.attachmentPolicy;
             await this.validateStreamRequestOptions(options, startTime);
             const workflowResult = await this.maybeHandleWorkflowStreamRequest({
                 options,
@@ -9053,7 +9098,7 @@ Current user's request: ${currentInput}`;
         if (options.rag?.files?.length) {
             try {
                 const { prepareRAGTool } = await import("./rag/ragIntegration.js");
-                const ragResult = await prepareRAGTool(options.rag, options.provider);
+                const ragResult = await prepareRAGTool(options.rag, options.provider, this.attachmentPolicy);
                 // Inject the RAG tool into the tools record
                 if (!options.tools) {
                     options.tools = {};
@@ -14661,6 +14706,7 @@ Current user's request: ${currentInput}`;
             transcribe: (audio, provider, options) => STTProcessor.transcribe(audio, provider, options, credentials),
             resolveProvider,
             getHandler,
+            attachmentPolicy: this.attachmentPolicy,
         };
     }
     /**
@@ -15888,6 +15934,13 @@ Current user's request: ${currentInput}`;
             catch (error) {
                 cleanupErrors.push(error instanceof Error ? error : new Error(String(error)));
             }
+            // 0c. Persisted attachments go with the instance (private tmpdir).
+            try {
+                await this.fileRegistry.clear();
+            }
+            catch (error) {
+                logger.warn("[NeuroLink] File registry cleanup failed:", error);
+            }
             // 1. Flush and shutdown OpenTelemetry
             try {
                 logger.debug("[NeuroLink] Flushing and shutting down OpenTelemetry...");

package/dist/processors/archive/ArchiveProcessor.js

@@ -38,6 +38,7 @@
 import * as path from "path";
 import { BaseFileProcessor } from "../base/BaseFileProcessor.js";
 import { isDecompressionBoundExceeded, readZipEntryWithinLimit, } from "./zipEntryReader.js";
+import { indexZipEntriesByName } from "./zipEntryIndex.js";
 import { SIZE_LIMITS_MB } from "../config/index.js";
 import { FileErrorCode } from "../errors/index.js";
 // =============================================================================
@@ -641,8 +642,17 @@ export class ArchiveProcessor extends BaseFileProcessor {
                 };
             }
             let cumulativeUncompressedSize = 0;
+            // A name that appears twice is one listing with two possible contents:
+            // the first occurrence is what every reader here opens, and the
+            // repeat is reported rather than listed as if it were a second file.
+            const seenNames = new Set();
             for (const entry of zipEntries) {
                 const entryName = entry.entryName;
+                if (seenNames.has(entryName)) {
+                    securityWarnings.push(`Duplicate entry name "${entryName}" - only the first occurrence is read; the repeat is skipped`);
+                    continue;
+                }
+                seenNames.add(entryName);
                 // Security: path traversal check
                 if (this.hasPathTraversal(entryName)) {
                     securityWarnings.push(`Path traversal detected in entry: "${entryName}" - entry skipped`);
@@ -1337,6 +1347,10 @@ export class ArchiveProcessor extends BaseFileProcessor {
         try {
             const AdmZip = (await import("adm-zip")).default;
             const zip = new AdmZip(buffer);
+            // Read from the iterated entries, first occurrence per name — the same
+            // entry the listing described. `zip.getEntry(name)` resolves the LAST
+            // duplicate and would open a different member than the one listed.
+            const { byName } = indexZipEntriesByName(zip.getEntries());
             // Filter to extractable text-based entries within size limits
             const candidates = entries
                 .filter((e) => {
@@ -1364,7 +1378,7 @@ export class ArchiveProcessor extends BaseFileProcessor {
                     break;
                 }
                 try {
-                    const zipEntry = zip.getEntry(entry.name);
+                    const zipEntry = byName.get(entry.name);
                     if (!zipEntry) {
                         continue;
                     }

package/dist/processors/archive/zipEntryIndex.d.ts

@@ -0,0 +1,22 @@
+/**
+ * First-wins lookup over a ZIP's central directory.
+ *
+ * A ZIP may carry two entries with the same name. adm-zip's `getEntry(name)`
+ * resolves the LAST one, while `getEntries()` lists them in directory order,
+ * so a processor that lists with one call and reads with the other can show
+ * the user a listing of one file and the contents of another. Every reader
+ * here indexes the iterated entries once and reads from that index, so the
+ * entry it describes is the entry it opens; a repeated name is reported to
+ * the caller rather than silently resolved either way.
+ *
+ * @module processors/archive/zipEntryIndex
+ */
+import type { NamedZipEntry } from "../../types/index.js";
+/**
+ * Index `entries` by name, keeping the FIRST occurrence of each. Returns the
+ * index and the names that occurred more than once, in first-seen order.
+ */
+export declare function indexZipEntriesByName<T extends NamedZipEntry>(entries: readonly T[]): {
+    byName: Map<string, T>;
+    duplicates: string[];
+};

package/dist/processors/archive/zipEntryIndex.js

@@ -0,0 +1,33 @@
+/**
+ * First-wins lookup over a ZIP's central directory.
+ *
+ * A ZIP may carry two entries with the same name. adm-zip's `getEntry(name)`
+ * resolves the LAST one, while `getEntries()` lists them in directory order,
+ * so a processor that lists with one call and reads with the other can show
+ * the user a listing of one file and the contents of another. Every reader
+ * here indexes the iterated entries once and reads from that index, so the
+ * entry it describes is the entry it opens; a repeated name is reported to
+ * the caller rather than silently resolved either way.
+ *
+ * @module processors/archive/zipEntryIndex
+ */
+/**
+ * Index `entries` by name, keeping the FIRST occurrence of each. Returns the
+ * index and the names that occurred more than once, in first-seen order.
+ */
+export function indexZipEntriesByName(entries) {
+    const byName = new Map();
+    const duplicates = [];
+    const flagged = new Set();
+    for (const entry of entries) {
+        if (byName.has(entry.entryName)) {
+            if (!flagged.has(entry.entryName)) {
+                flagged.add(entry.entryName);
+                duplicates.push(entry.entryName);
+            }
+            continue;
+        }
+        byName.set(entry.entryName, entry);
+    }
+    return { byName, duplicates };
+}

package/dist/processors/base/BaseFileProcessor.d.ts

@@ -45,7 +45,7 @@
  */
 import "../../services/server/ai/observability/instrumentation.js";
 import { FileErrorCode } from "../errors/index.js";
-import type { BatchProcessingSummary, FileInfo, FileProcessingError, ProcessorFileProcessingResult, FileProcessorConfig, ProcessorOperationResult, ProcessedFileBase, ProcessOptions } from "../../types/index.js";
+import type { AttachmentPolicy, BatchProcessingSummary, FileInfo, FileProcessingError, ProcessorFileProcessingResult, FileProcessorConfig, ProcessorOperationResult, ProcessedFileBase, ProcessOptions } from "../../types/index.js";
 /**
  * Marker on the error raised when a processor refuses content for exceeding
  * the size limit *after* the download — a ZIP entry that expands past the
@@ -192,32 +192,20 @@ export declare abstract class BaseFileProcessor<T extends ProcessedFileBase> {
     /**
      * Download file from URL with authentication.
      *
+     * Goes through `downloadAttachment`, which applies the attachment policy
+     * (HTTPS and public hosts unless the instance says otherwise), pins the
+     * connection to the vetted addresses, re-validates every redirect hop and
+     * bounds the body while it streams. `authHeaders` ride on the first request
+     * only — they are never replayed to a redirect target.
+     *
      * @param url - URL to download from
      * @param authHeaders - Optional authentication headers
      * @param timeout - Optional timeout override
+     * @param attachmentPolicy - Policy for the fetch; the environment default when omitted
      * @returns Downloaded file content as Buffer
      * @throws Error if download fails
      */
-    protected downloadFile(url: string, authHeaders?: Record<string, string>, timeout?: number): Promise<Buffer>;
-    /**
-     * Read a response body, refusing it the moment it passes `maxBytes`.
-     *
-     * `response.arrayBuffer()` buffers whatever the server sends before anyone
-     * can object, so the size check further up only ever ran against a body that
-     * had already been paid for in full. Metering the stream makes the ceiling
-     * the configured limit instead of the server's choice, and cancelling the
-     * reader stops the transfer rather than merely stopping our interest in it.
-     *
-     * Content-Length is deliberately not trusted as the bound — it is a hint that
-     * can be absent or a lie — but it is worth honouring when present, because it
-     * refuses the honest oversized case without reading a byte.
-     *
-     * @param response - Fetch response whose body should be read
-     * @param maxBytes - Ceiling for the body, in bytes
-     * @returns The body as a Buffer
-     * @throws When the body exceeds `maxBytes`
-     */
-    private readBodyWithinLimit;
+    protected downloadFile(url: string, authHeaders?: Record<string, string>, timeout?: number, attachmentPolicy?: AttachmentPolicy): Promise<Buffer>;
     /**
      * Download file with retry logic for transient failures.
      *