@juspay/neurolink 9.95.1 → 9.95.2

package/dist/cli/factories/commandFactory.d.ts

@@ -22,6 +22,16 @@ export declare class CLICommandFactory {
     private static processCliImages;
     private static processCliCSVFiles;
     private static processCliPDFFiles;
+    /**
+     * Resolve the PDF decryption password, preferring the NEUROLINK_PDF_PASSWORD
+     * env var over the `--pdf-password` flag. A plaintext CLI flag leaks into
+     * shell history, `ps`/process listings, and CI logs — the env var avoids
+     * that, matching the project's existing "credentials via env vars, not
+     * flags" stance for the loop session. The flag stays supported (dropping it
+     * would be a breaking CLI change), but using it prints a one-line stderr
+     * warning recommending the env var instead.
+     */
+    private static resolvePdfPassword;
     private static processCliFiles;
     private static processCliVideoFiles;
     private static processOptions;

package/dist/cli/factories/commandFactory.js

@@ -156,6 +156,12 @@ export class CLICommandFactory {
             type: "string",
             description: "Add PDF file for analysis (can be used multiple times)",
         },
+        "pdf-password": {
+            type: "string",
+            description: "Password for an encrypted PDF (used on the image-conversion path). " +
+                "Visible in shell history/process listings — prefer the " +
+                "NEUROLINK_PDF_PASSWORD env var instead.",
+        },
         video: {
             type: "string",
             description: "Add video file for analysis (can be used multiple times) (MP4, WebM, MOV, AVI, MKV)",
@@ -793,6 +799,24 @@ export class CLICommandFactory {
         // URLs are preserved as-is by resolveFilePaths
         return resolveFilePaths(paths);
     }
+    /**
+     * Resolve the PDF decryption password, preferring the NEUROLINK_PDF_PASSWORD
+     * env var over the `--pdf-password` flag. A plaintext CLI flag leaks into
+     * shell history, `ps`/process listings, and CI logs — the env var avoids
+     * that, matching the project's existing "credentials via env vars, not
+     * flags" stance for the loop session. The flag stays supported (dropping it
+     * would be a breaking CLI change), but using it prints a one-line stderr
+     * warning recommending the env var instead.
+     */
+    static resolvePdfPassword(argv) {
+        const flagValue = argv.pdfPassword;
+        const envValue = process.env.NEUROLINK_PDF_PASSWORD;
+        if (flagValue) {
+            process.stderr.write(chalk.yellow("⚠️  --pdf-password is visible in shell history and process listings. " +
+                "Prefer the NEUROLINK_PDF_PASSWORD environment variable instead.\n"));
+        }
+        return flagValue || envValue;
+    }
     // Helper method to process CLI files with auto-detection
     static processCliFiles(files) {
         if (!files) {
@@ -2649,6 +2673,9 @@ export class CLICommandFactory {
             const inputAudioFormat = inferAudioFormatFromPath(inputAudioPath);
             const runGenerate = () => sdk.generate({
                 input: generateInput,
+                pdfOptions: {
+                    password: CLICommandFactory.resolvePdfPassword(argv),
+                },
                 csvOptions: CLICommandFactory.buildCsvOptionsFromArgv(argv),
                 videoOptions: {
                     frames: argv.videoFrames,
@@ -2901,6 +2928,9 @@ export class CLICommandFactory {
                 ...(videoFiles && { videoFiles }),
                 ...(files && { files }),
             },
+            pdfOptions: {
+                password: CLICommandFactory.resolvePdfPassword(argv),
+            },
             csvOptions: CLICommandFactory.buildCsvOptionsFromArgv(argv),
             videoOptions: {
                 frames: argv.videoFrames,

package/dist/cli/loop/optionsSchema.d.ts

@@ -4,4 +4,4 @@ import type { OptionSchema, TextGenerationOptions } from "../../lib/types/index.
  * This object provides metadata for validation and help text in the CLI loop.
  * It is derived from the main TextGenerationOptions interface to ensure consistency.
  */
-export declare const textGenerationOptionsSchema: Record<keyof Omit<TextGenerationOptions, "prompt" | "input" | "schema" | "tools" | "context" | "conversationHistory" | "conversationMessages" | "conversationMemoryConfig" | "originalPrompt" | "middleware" | "expectedOutcome" | "evaluationCriteria" | "region" | "csvOptions" | "tts" | "stt" | "thinkingConfig" | "requestId" | "fileRegistry" | "abortSignal" | "toolFilter" | "excludeTools" | "toolChoice" | "prepareStep" | "credentials" | "onFinish" | "onError" | "processors" | "piiDetection" | "responseValidation" | "inputValidation">, OptionSchema>;
+export declare const textGenerationOptionsSchema: Record<keyof Omit<TextGenerationOptions, "prompt" | "input" | "schema" | "tools" | "context" | "conversationHistory" | "conversationMessages" | "conversationMemoryConfig" | "originalPrompt" | "middleware" | "expectedOutcome" | "evaluationCriteria" | "region" | "csvOptions" | "pdfOptions" | "tts" | "stt" | "thinkingConfig" | "requestId" | "fileRegistry" | "abortSignal" | "toolFilter" | "excludeTools" | "toolChoice" | "prepareStep" | "credentials" | "onFinish" | "onError" | "processors" | "piiDetection" | "responseValidation" | "inputValidation">, OptionSchema>;

package/dist/core/baseProvider.js

@@ -420,6 +420,7 @@ export class BaseProvider {
                 toolUsageContext: options.toolUsageContext,
                 context: options.context,
                 csvOptions: options.csvOptions,
+                pdfOptions: options.pdfOptions,
                 // Forward abort, tool filtering, and timeout options to prevent
                 // silent bypass when falling back from real streaming to fake streaming
                 abortSignal: options.abortSignal,

package/dist/core/constants.d.ts

@@ -122,6 +122,8 @@ export declare const PDF_LIMITS: {
     MAX_SIZE_MB: number;
     DEFAULT_MAX_PAGES: number;
     MAX_SCALE: number;
+    DEFAULT_MAX_CANVAS_PIXELS: number;
+    MIN_EFFECTIVE_SCALE: number;
 };
 export declare const SYSTEM_LIMITS: {
     MAX_PROMPT_LENGTH: number;

package/dist/core/constants.js

@@ -220,6 +220,15 @@ export const PDF_LIMITS = {
     // Upper bound for the render scale factor. Above this, a single page can
     // allocate hundreds of MB; scale <= 0 produces a degenerate viewport.
     MAX_SCALE: 10,
+    // Default per-page pixel ceiling for image conversion (#260). 16.7M px ×
+    // 4 bytes RGBA ≈ 64 MB per page — safely bounded. A larger page is
+    // uniformly downscaled to stay under this instead of allocating gigabytes.
+    DEFAULT_MAX_CANVAS_PIXELS: 16_777_216,
+    // Floor for the downscaled render scale (#260 follow-up). A crafted/malformed
+    // MediaBox can drive the estimated pixel count toward Infinity, which would
+    // otherwise collapse `effectiveScale` to 0 and hand `pdf-to-img` a degenerate
+    // viewport. Never let the downscale branch go below this.
+    MIN_EFFECTIVE_SCALE: 0.1,
 };
 // Performance and System Limits
 export const SYSTEM_LIMITS = {

package/dist/core/modules/MessageBuilder.js

@@ -103,6 +103,7 @@ export class MessageBuilder {
                         files: input?.files,
                     },
                     csvOptions: options.csvOptions,
+                    pdfOptions: options.pdfOptions,
                     provider: options.provider,
                     model: options.model,
                     temperature: options.temperature,
@@ -224,6 +225,7 @@ export class MessageBuilder {
                         files: input?.files,
                     },
                     csvOptions: options.csvOptions,
+                    pdfOptions: options.pdfOptions,
                     provider: options.provider,
                     model: options.model,
                     temperature: options.temperature,

package/dist/lib/core/baseProvider.js

@@ -420,6 +420,7 @@ export class BaseProvider {
                 toolUsageContext: options.toolUsageContext,
                 context: options.context,
                 csvOptions: options.csvOptions,
+                pdfOptions: options.pdfOptions,
                 // Forward abort, tool filtering, and timeout options to prevent
                 // silent bypass when falling back from real streaming to fake streaming
                 abortSignal: options.abortSignal,

package/dist/lib/core/constants.d.ts

@@ -122,6 +122,8 @@ export declare const PDF_LIMITS: {
     MAX_SIZE_MB: number;
     DEFAULT_MAX_PAGES: number;
     MAX_SCALE: number;
+    DEFAULT_MAX_CANVAS_PIXELS: number;
+    MIN_EFFECTIVE_SCALE: number;
 };
 export declare const SYSTEM_LIMITS: {
     MAX_PROMPT_LENGTH: number;

package/dist/lib/core/constants.js

@@ -220,6 +220,15 @@ export const PDF_LIMITS = {
     // Upper bound for the render scale factor. Above this, a single page can
     // allocate hundreds of MB; scale <= 0 produces a degenerate viewport.
     MAX_SCALE: 10,
+    // Default per-page pixel ceiling for image conversion (#260). 16.7M px ×
+    // 4 bytes RGBA ≈ 64 MB per page — safely bounded. A larger page is
+    // uniformly downscaled to stay under this instead of allocating gigabytes.
+    DEFAULT_MAX_CANVAS_PIXELS: 16_777_216,
+    // Floor for the downscaled render scale (#260 follow-up). A crafted/malformed
+    // MediaBox can drive the estimated pixel count toward Infinity, which would
+    // otherwise collapse `effectiveScale` to 0 and hand `pdf-to-img` a degenerate
+    // viewport. Never let the downscale branch go below this.
+    MIN_EFFECTIVE_SCALE: 0.1,
 };
 // Performance and System Limits
 export const SYSTEM_LIMITS = {

package/dist/lib/core/modules/MessageBuilder.js

@@ -103,6 +103,7 @@ export class MessageBuilder {
                         files: input?.files,
                     },
                     csvOptions: options.csvOptions,
+                    pdfOptions: options.pdfOptions,
                     provider: options.provider,
                     model: options.model,
                     temperature: options.temperature,
@@ -224,6 +225,7 @@ export class MessageBuilder {
                         files: input?.files,
                     },
                     csvOptions: options.csvOptions,
+                    pdfOptions: options.pdfOptions,
                     provider: options.provider,
                     model: options.model,
                     temperature: options.temperature,

package/dist/lib/neurolink.js

@@ -3899,11 +3899,15 @@ Current user's request: ${currentInput}`;
             evaluationDomain: options.evaluationDomain,
             toolUsageContext: options.toolUsageContext,
             input: options.input,
-            // CSV processing options must survive the reconstruction into
-            // TextGenerationOptions — the message builder reads them (encoding,
-            // formatting, sanitization, parse timeout). Omitting them silently
-            // dropped every csvOptions field (incl. the CLI --csv-* flags).
+            // Multimodal file-processing options must survive the reconstruction
+            // into TextGenerationOptions — the message builder reads them downstream
+            // (csv encoding/formatting/sanitization/parse timeout, PDF
+            // password/decryption #258). Omitting them here silently dropped e.g.
+            // every csvOptions field (incl. the CLI --csv-* flags) or
+            // pdfOptions.password so the CLI --pdf-password / SDK pdfOptions never
+            // reached convertToImages.
             csvOptions: options.csvOptions,
+            pdfOptions: options.pdfOptions,
             region: options.region,
             tts: options.tts,
             stt: options.stt,

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

@@ -226,6 +226,8 @@ export type PDFProcessorOptions = {
      * Set to false to bypass limit enforcement (logs warning instead)
      */
     enforceLimits?: boolean;
+    /** Password for an encrypted PDF (used on the image-conversion path) (#258). */
+    password?: string;
 };
 /**
  * Audio provider configuration for transcription services
@@ -395,6 +397,14 @@ export type PDFImageConversionOptions = {
     maxPages?: number;
     /** Output format (default: png). Only PNG is currently implemented by PDFProcessor. */
     format?: "png";
+    /**
+     * Per-page pixel ceiling (#260). Any page whose width×height×scale² would
+     * exceed this is uniformly downscaled to stay under it, preventing a huge
+     * page from allocating gigabytes of canvas. Default: PDF_LIMITS.DEFAULT_MAX_CANVAS_PIXELS.
+     */
+    maxCanvasPixels?: number;
+    /** Password for an encrypted PDF (passed to the underlying renderer) (#258). */
+    password?: string;
 };
 /** Result of PDF to image conversion. */
 export type PDFImageConversionResult = {

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

@@ -125,6 +125,13 @@ export type GenerateOptions = {
         music?: MusicOptions;
     };
     csvOptions?: CSVProcessorOptions;
+    /** PDF processing options (#258). */
+    pdfOptions?: {
+        /** Password for an encrypted PDF (image-conversion fallback path). */
+        password?: string;
+        /** Max rendered-canvas pixels per page (#260 memory guard); oversized pages auto-downscale. */
+        maxCanvasPixels?: number;
+    };
     videoOptions?: {
         frames?: number;
         quality?: number;
@@ -1131,6 +1138,13 @@ export type TextGenerationOptions = {
     expectedOutcome?: string;
     evaluationCriteria?: string[];
     csvOptions?: CSVProcessorOptions;
+    /** PDF processing options (#258). */
+    pdfOptions?: {
+        /** Password for an encrypted PDF (image-conversion fallback path). */
+        password?: string;
+        /** Max rendered-canvas pixels per page (#260 memory guard); oversized pages auto-downscale. */
+        maxCanvasPixels?: number;
+    };
     enableSummarization?: boolean;
     /**
      * Skip injecting tool schemas into the system prompt.

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

@@ -207,6 +207,13 @@ export type StreamOptions = {
         };
     };
     csvOptions?: CSVProcessorOptions;
+    /** PDF processing options (#258). */
+    pdfOptions?: {
+        /** Password for an encrypted PDF (image-conversion fallback path). */
+        password?: string;
+        /** Max rendered-canvas pixels per page (#260 memory guard); oversized pages auto-downscale. */
+        maxCanvasPixels?: number;
+    };
     videoOptions?: {
         frames?: number;
         quality?: number;

package/dist/lib/utils/errorHandling.d.ts

@@ -39,6 +39,8 @@ export declare const ERROR_CODES: {
     readonly FILE_PROCESSING_FAILED: "FILE_PROCESSING_FAILED";
     readonly CSV_PROCESSING_FAILED: "CSV_PROCESSING_FAILED";
     readonly PDF_PAGE_LIMIT_EXCEEDED: "PDF_PAGE_LIMIT_EXCEEDED";
+    readonly PDF_PASSWORD_REQUIRED: "PDF_PASSWORD_REQUIRED";
+    readonly PDF_INCORRECT_PASSWORD: "PDF_INCORRECT_PASSWORD";
     readonly RATE_LIMITER_QUEUE_FULL: "RATE_LIMITER_QUEUE_FULL";
     readonly RATE_LIMITER_QUEUE_TIMEOUT: "RATE_LIMITER_QUEUE_TIMEOUT";
     readonly RATE_LIMITER_RESET: "RATE_LIMITER_RESET";
@@ -199,6 +201,14 @@ export declare class ErrorFactory {
      * Create a PDF page limit exceeded error
      */
     static pdfPageLimitExceeded(estimatedPages: number, maxPages: number, provider: string): NeuroLinkError;
+    /**
+     * The PDF is encrypted and no password was supplied (#258).
+     */
+    static pdfPasswordRequired(): NeuroLinkError;
+    /**
+     * A password was supplied for an encrypted PDF but it was incorrect (#258).
+     */
+    static pdfIncorrectPassword(): NeuroLinkError;
     /**
      * Create an image too large error
      */

package/dist/lib/utils/errorHandling.js

@@ -52,6 +52,8 @@ export const ERROR_CODES = {
     CSV_PROCESSING_FAILED: "CSV_PROCESSING_FAILED",
     // PDF validation errors
     PDF_PAGE_LIMIT_EXCEEDED: "PDF_PAGE_LIMIT_EXCEEDED",
+    PDF_PASSWORD_REQUIRED: "PDF_PASSWORD_REQUIRED",
+    PDF_INCORRECT_PASSWORD: "PDF_INCORRECT_PASSWORD",
     // Rate limiter errors
     RATE_LIMITER_QUEUE_FULL: "RATE_LIMITER_QUEUE_FULL",
     RATE_LIMITER_QUEUE_TIMEOUT: "RATE_LIMITER_QUEUE_TIMEOUT",
@@ -553,6 +555,32 @@ export class ErrorFactory {
             },
         });
     }
+    /**
+     * The PDF is encrypted and no password was supplied (#258).
+     */
+    static pdfPasswordRequired() {
+        return new NeuroLinkError({
+            code: ERROR_CODES.PDF_PASSWORD_REQUIRED,
+            message: "This PDF is password-protected. Supply the password via " +
+                "`pdfOptions: { password: '…' }` (SDK) or `--pdf-password` (CLI).",
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+        });
+    }
+    /**
+     * A password was supplied for an encrypted PDF but it was incorrect (#258).
+     */
+    static pdfIncorrectPassword() {
+        return new NeuroLinkError({
+            code: ERROR_CODES.PDF_INCORRECT_PASSWORD,
+            message: "The password supplied for this PDF is incorrect. Check the " +
+                "`pdfOptions.password` / `--pdf-password` value and try again.",
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+        });
+    }
     /**
      * Create an image too large error
      */

package/dist/lib/utils/messageBuilder.js

@@ -1011,6 +1011,12 @@ async function processExplicitPdfFiles(options, maxSize, provider) {
                     buffer: result.content,
                     filename,
                     pageCount: result.metadata?.estimatedPages ?? null,
+                    // #258: carry the password so the image-fallback conversion can
+                    // decrypt an encrypted PDF for providers without native PDF support.
+                    password: options.pdfOptions?.password,
+                    // #260: carry the per-page canvas-pixel ceiling so the caller can
+                    // raise (or lower) the memory guard for the image-fallback render.
+                    maxCanvasPixels: options.pdfOptions?.maxCanvasPixels,
                 });
                 logger.info(`[PDF] ✅ Queued for multimodal: ${filename} (${result.metadata?.estimatedPages ?? "unknown"} pages)`);
             }
@@ -1103,7 +1109,13 @@ export async function buildMultimodalMessagesArray(options, provider, model) {
     // Check if this is a multimodal request
     const hasImages = (inp.images && inp.images.length > 0) ||
         (inp.content && inp.content.some((c) => c.type === "image"));
-    const hasPDFs = pdfFiles.length > 0;
+    // A PDF supplied only via input.content (type: "pdf", no explicit
+    // input.pdfFiles and no image alongside it) must still route through the
+    // multimodal path below — otherwise it silently falls through to the
+    // text-only branch and the PDF (and any pdfOptions) never reaches
+    // convertContentToProviderFormat at all.
+    const hasPDFs = pdfFiles.length > 0 ||
+        !!(inp.content && inp.content.some((c) => c.type === "pdf"));
     // If no images or PDFs, use standard message building and convert to MultimodalChatMessage[]
     if (!hasImages && !hasPDFs) {
         // #289: CSV content[] items don't need vision, so they never reach the
@@ -1139,8 +1151,11 @@ export async function buildMultimodalMessagesArray(options, provider, model) {
             `Supported providers: ${ProviderImageAdapter.getVisionProviders().join(", ")}`);
     }
     const messages = [];
-    // Build enhanced system prompt
-    const systemPrompt = buildMultimodalSystemPrompt(options, pdfFiles.length > 0);
+    // Build enhanced system prompt. Gate on the same `hasPDFs` predicate used
+    // for routing above — a PDF supplied only via input.content (no explicit
+    // input.pdfFiles) must still get the "treat inlined content as an
+    // attachment" instruction, or the model can claim no files were attached.
+    const systemPrompt = buildMultimodalSystemPrompt(options, hasPDFs);
     if (systemPrompt.trim()) {
         messages.push({
             role: "system",
@@ -1206,7 +1221,7 @@ export async function buildMultimodalMessagesArray(options, provider, model) {
     try {
         let userContent;
         if (inp.content && inp.content.length > 0) {
-            userContent = await convertContentToProviderFormat(inp.content, provider, model);
+            userContent = await convertContentToProviderFormat(inp.content, provider, model, options.pdfOptions);
         }
         else if ((inp.images && inp.images.length > 0) || pdfFiles.length > 0) {
             userContent = await convertMultimodalToProviderFormat(inp.text ?? "", inp.images || [], pdfFiles, provider, model);
@@ -1285,7 +1300,7 @@ async function appendCsvContentToText(csvItems, baseText) {
 /**
  * Convert advanced content format to provider-specific format
  */
-async function convertContentToProviderFormat(content, provider, _model) {
+async function convertContentToProviderFormat(content, provider, _model, pdfOptions) {
     const textContent = content.find((c) => c.type === "text");
     const imageContent = content.filter((c) => c.type === "image");
     const pdfContent = content.filter((c) => c.type === "pdf");
@@ -1312,6 +1327,11 @@ async function convertContentToProviderFormat(content, provider, _model) {
         buffer: typeof pdf.data === "string" ? Buffer.from(pdf.data, "base64") : pdf.data,
         filename: pdf.metadata?.filename || "document.pdf",
         pageCount: pdf.metadata?.pages ?? null,
+        // #258/#260: carry password + canvas-pixel ceiling so a PDF supplied via
+        // the advanced `input.content` array gets the same decryption/memory
+        // guard as the `input.pdfFiles` path (see `processExplicitPdfFiles`).
+        password: pdfOptions?.password,
+        maxCanvasPixels: pdfOptions?.maxCanvasPixels,
     }));
     return await convertMultimodalToProviderFormat(text, images, pdfFiles, provider, _model);
 }
@@ -1694,6 +1714,10 @@ async function convertMultimodalToProviderFormat(text, images, pdfFiles, provide
                 const conversionResult = await PDFImageConverter.convertToImages(pdf.buffer, {
                     scale: 2.0, // High quality for OCR/analysis
                     maxPages: 20, // Limit pages to prevent token overflow
+                    ...(pdf.password ? { password: pdf.password } : {}), // #258
+                    ...(pdf.maxCanvasPixels
+                        ? { maxCanvasPixels: pdf.maxCanvasPixels }
+                        : {}), // #260
                 });
                 logger.info(`[PDF→Image] ✅ Converted ${pdf.filename}: ${conversionResult.pageCount} page(s) → images`);
                 // Add each page as an ImagePart (raw base64, not data: URI — see SSRF note above)
@@ -1715,6 +1739,13 @@ async function convertMultimodalToProviderFormat(text, images, pdfFiles, provide
             catch (error) {
                 const errorMessage = error instanceof Error ? error.message : String(error);
                 logger.error(`[PDF→Image] ❌ Failed to convert ${pdf.filename}: ${errorMessage}`);
+                // #258: password errors are already actionable typed errors — re-throw
+                // them unwrapped so the "supply a password" guidance isn't buried.
+                const code = error?.code;
+                if (code === "PDF_PASSWORD_REQUIRED" ||
+                    code === "PDF_INCORRECT_PASSWORD") {
+                    throw error;
+                }
                 // Re-throw so the user knows PDF processing failed
                 throw new Error(`PDF to image conversion failed for ${pdf.filename}: ${errorMessage}. ` +
                     `Provider ${provider} doesn't support native PDFs and image conversion failed.`, { cause: error });

package/dist/lib/utils/multimodalOptionsBuilder.d.ts

@@ -51,6 +51,10 @@ export declare function buildMultimodalOptions(options: StreamOptions, providerN
         pdfFiles: (string | Buffer<ArrayBufferLike>)[] | undefined;
     };
     csvOptions: import("../types/file.js").CSVProcessorOptions | undefined;
+    pdfOptions: {
+        password?: string;
+        maxCanvasPixels?: number;
+    } | undefined;
     systemPrompt: string | undefined;
     conversationHistory: import("../types/conversation.js").ChatMessage[] | undefined;
     provider: string;

package/dist/lib/utils/multimodalOptionsBuilder.js

@@ -51,6 +51,7 @@ export function buildMultimodalOptions(options, providerName, modelName) {
             pdfFiles: options.input?.pdfFiles,
         },
         csvOptions: options.csvOptions,
+        pdfOptions: options.pdfOptions,
         systemPrompt: options.systemPrompt,
         conversationHistory: options.conversationMessages,
         provider: providerName,

package/dist/lib/utils/pdfProcessor.d.ts

@@ -21,6 +21,21 @@ export declare class PDFProcessor {
     private static isValidPDF;
     private static extractBasicMetadata;
     static estimateTokens(pageCount: number, mode?: "text-only" | "visual"): number;
+    /**
+     * Estimate the largest page's rendered pixel count from the PDF's MediaBox
+     * entries, WITHOUT rendering (#260). Parses `/MediaBox [llx lly urx ury]`
+     * (dimensions in points); rendered pixels ≈ (width·scale)·(height·scale).
+     * Returns 0 when no plaintext MediaBox is found (e.g. compressed object
+     * streams) — the caller then skips downscaling, matching prior behavior.
+     *
+     * A crafted/malformed MediaBox can have finite but astronomically large
+     * width/height; `width * height * scale * scale` can then overflow past
+     * `Number.MAX_VALUE` to `Infinity`. Clamp the product to
+     * `Number.MAX_SAFE_INTEGER` so it stays finite — a large-but-finite pixel
+     * estimate still triggers downscaling, whereas `Infinity` would collapse
+     * the computed downscale factor to 0 (see `convertToImages`).
+     */
+    private static largestPagePixels;
     /**
      * Convert a PDF buffer to an array of base64 PNG images
      *

package/dist/lib/utils/pdfProcessor.js

@@ -231,6 +231,40 @@ export class PDFProcessor {
     // ============================================================================
     // PDF → Image Conversion (for providers without native PDF support)
     // ============================================================================
+    /**
+     * Estimate the largest page's rendered pixel count from the PDF's MediaBox
+     * entries, WITHOUT rendering (#260). Parses `/MediaBox [llx lly urx ury]`
+     * (dimensions in points); rendered pixels ≈ (width·scale)·(height·scale).
+     * Returns 0 when no plaintext MediaBox is found (e.g. compressed object
+     * streams) — the caller then skips downscaling, matching prior behavior.
+     *
+     * A crafted/malformed MediaBox can have finite but astronomically large
+     * width/height; `width * height * scale * scale` can then overflow past
+     * `Number.MAX_VALUE` to `Infinity`. Clamp the product to
+     * `Number.MAX_SAFE_INTEGER` so it stays finite — a large-but-finite pixel
+     * estimate still triggers downscaling, whereas `Infinity` would collapse
+     * the computed downscale factor to 0 (see `convertToImages`).
+     */
+    static largestPagePixels(pdfBuffer, scale) {
+        const text = pdfBuffer.toString("latin1");
+        const re = /\/MediaBox\s*\[\s*(-?[\d.]+)\s+(-?[\d.]+)\s+(-?[\d.]+)\s+(-?[\d.]+)\s*\]/g;
+        let max = 0;
+        let match;
+        while ((match = re.exec(text)) !== null) {
+            const width = Math.abs(parseFloat(match[3]) - parseFloat(match[1]));
+            const height = Math.abs(parseFloat(match[4]) - parseFloat(match[2]));
+            if (Number.isFinite(width) && Number.isFinite(height)) {
+                const pixels = width * height * scale * scale;
+                const boundedPixels = Number.isFinite(pixels)
+                    ? Math.min(pixels, Number.MAX_SAFE_INTEGER)
+                    : Number.MAX_SAFE_INTEGER;
+                if (boundedPixels > max) {
+                    max = boundedPixels;
+                }
+            }
+        }
+        return max;
+    }
     /**
      * Convert a PDF buffer to an array of base64 PNG images
      *
@@ -257,7 +291,7 @@ export class PDFProcessor {
      */
     static async convertToImages(pdfBuffer, options) {
         const startTime = Date.now();
-        const { scale = 2, maxPages = PDF_LIMITS.DEFAULT_MAX_PAGES, format = "png", } = options || {};
+        const { scale = 2, maxPages = PDF_LIMITS.DEFAULT_MAX_PAGES, format = "png", maxCanvasPixels = PDF_LIMITS.DEFAULT_MAX_CANVAS_PIXELS, password, } = options || {};
         const images = [];
         const warnings = [];
         // ============================================================================
@@ -273,6 +307,11 @@ export class PDFProcessor {
         if (!Number.isFinite(scale) || scale <= 0 || scale > PDF_LIMITS.MAX_SCALE) {
             throw new Error(`Invalid scale: ${scale}. Scale must be a finite number greater than 0 and at most ${PDF_LIMITS.MAX_SCALE}.`);
         }
+        // 0c. Validate the per-page pixel ceiling (#260). A non-finite or
+        // non-positive value would disable the guard or yield a NaN downscale.
+        if (!Number.isFinite(maxCanvasPixels) || maxCanvasPixels <= 0) {
+            throw new Error(`Invalid maxCanvasPixels: ${maxCanvasPixels}. Must be a finite number greater than 0.`);
+        }
         // 1. Validate buffer is not empty or too small
         if (!pdfBuffer || pdfBuffer.length < 5) {
             throw new Error("Invalid PDF: Buffer is too small or empty. " +
@@ -303,8 +342,38 @@ export class PDFProcessor {
                 scale,
                 maxPages: maxPages || "all",
             });
-            // Create PDF document iterator
-            const document = await pdf(pdfBuffer, { scale });
+            // #260: pre-flight page-size check WITHOUT rendering. pdf-to-img applies
+            // `scale` uniformly with no per-page hook and no pixel guard, so a very
+            // large page (e.g. an architectural drawing with a huge MediaBox) can
+            // allocate gigabytes of canvas. Read the largest MediaBox from the PDF
+            // bytes and, if that page at the requested scale would exceed
+            // maxCanvasPixels, downscale the whole render uniformly to stay under it.
+            let effectiveScale = scale;
+            const largestPixels = PDFProcessor.largestPagePixels(pdfBuffer, scale);
+            if (largestPixels > maxCanvasPixels) {
+                const downscale = Math.sqrt(maxCanvasPixels / largestPixels);
+                // Floor the result: an astronomically large (but now finite, see
+                // `largestPagePixels`) pixel estimate would otherwise push `downscale`
+                // — and therefore `effectiveScale` — toward 0, handing `pdf-to-img` a
+                // degenerate viewport instead of a small-but-renderable page.
+                effectiveScale = Math.max(PDF_LIMITS.MIN_EFFECTIVE_SCALE, scale * downscale);
+                // Recompute the ratio actually applied (may differ from `downscale`
+                // when the floor above kicks in) so the logged estimate stays honest.
+                const actualDownscale = effectiveScale / scale;
+                const beforeMB = (largestPixels * 4) / (1024 * 1024);
+                const afterMB = (largestPixels * actualDownscale * actualDownscale * 4) /
+                    (1024 * 1024);
+                const msg = `Downscaled render (scale ${scale} → ${effectiveScale.toFixed(3)}): ` +
+                    `the largest page would allocate ~${beforeMB.toFixed(0)}MB, above the ` +
+                    `maxCanvasPixels ceiling; reduced to ~${afterMB.toFixed(0)}MB per page.`;
+                logger.warn(`[PDF→Image] ⚠️ ${msg}`);
+                warnings.push(msg);
+            }
+            // Create PDF document iterator (password forwarded for encrypted PDFs, #258)
+            const document = await pdf(pdfBuffer, {
+                scale: effectiveScale,
+                ...(password ? { password } : {}),
+            });
             let pageIndex = 0;
             // Iterate through pages and convert to base64
             for await (const page of document) {
@@ -346,6 +415,17 @@ export class PDFProcessor {
                 error: errorMessage,
                 conversionTimeMs,
             });
+            // #258: map pdfjs's PasswordException to an actionable typed error so a
+            // caller learns to supply (or correct) the password instead of seeing a
+            // generic "conversion failed". pdfjs code 1 = NEED_PASSWORD, 2 = INCORRECT.
+            const pdfErr = error;
+            if (pdfErr?.name === "PasswordException" ||
+                /password/i.test(errorMessage)) {
+                const incorrect = pdfErr.code === 2 || /incorrect|invalid/i.test(errorMessage);
+                throw incorrect
+                    ? ErrorFactory.pdfIncorrectPassword()
+                    : ErrorFactory.pdfPasswordRequired();
+            }
             throw new Error(`PDF to image conversion failed: ${errorMessage}`, {
                 cause: error,
             });

package/dist/neurolink.js

@@ -3899,11 +3899,15 @@ Current user's request: ${currentInput}`;
             evaluationDomain: options.evaluationDomain,
             toolUsageContext: options.toolUsageContext,
             input: options.input,
-            // CSV processing options must survive the reconstruction into
-            // TextGenerationOptions — the message builder reads them (encoding,
-            // formatting, sanitization, parse timeout). Omitting them silently
-            // dropped every csvOptions field (incl. the CLI --csv-* flags).
+            // Multimodal file-processing options must survive the reconstruction
+            // into TextGenerationOptions — the message builder reads them downstream
+            // (csv encoding/formatting/sanitization/parse timeout, PDF
+            // password/decryption #258). Omitting them here silently dropped e.g.
+            // every csvOptions field (incl. the CLI --csv-* flags) or
+            // pdfOptions.password so the CLI --pdf-password / SDK pdfOptions never
+            // reached convertToImages.
             csvOptions: options.csvOptions,
+            pdfOptions: options.pdfOptions,
             region: options.region,
             tts: options.tts,
             stt: options.stt,