@juspay/neurolink 9.1.1 → 9.2.0

package/dist/processors/data/YamlProcessor.js

@@ -0,0 +1,294 @@
+/**
+ * YAML Processing Utility
+ *
+ * Handles downloading, validating, and processing YAML files with security.
+ *
+ * Security Notes:
+ * ---------------
+ * YAML parsing can be vulnerable to various attacks if not configured securely:
+ *
+ * 1. **Code Execution via Custom Tags**: YAML supports custom tags like `!!python/object`,
+ *    `!!ruby/object`, or `!!js/function` that can execute arbitrary code when parsed.
+ *    We use the 'core' schema which only allows standard YAML types (strings, numbers,
+ *    booleans, null, arrays, and objects) and explicitly check for dangerous tag patterns.
+ *
+ * 2. **Billion Laughs Attack (Entity Expansion)**: YAML supports anchors (&) and aliases (*)
+ *    for referencing content. Malicious YAML can use nested aliases to create exponential
+ *    expansion (e.g., 10 levels of 10x expansion = 10^10 entities from a small file).
+ *    We limit `maxAliasCount` to 100 to prevent memory exhaustion.
+ *
+ * 3. **Denial of Service**: Large or deeply nested YAML files can exhaust memory/CPU.
+ *    Size limits are enforced by the base processor's maxSizeMB configuration.
+ *
+ * References:
+ * - https://en.wikipedia.org/wiki/Billion_laughs_attack
+ * - https://cwe.mitre.org/data/definitions/502.html (Deserialization of Untrusted Data)
+ *
+ * @module processors/data/YamlProcessor
+ *
+ * @example
+ * ```typescript
+ * import { yamlProcessor, isYamlFile, processYaml } from "./YamlProcessor.js";
+ *
+ * // Check if file is YAML
+ * if (isYamlFile("application/x-yaml", "config.yaml")) {
+ *   // Process the file
+ *   const result = await processYaml(fileInfo);
+ *   if (result.success && result.data) {
+ *     console.log("Parsed YAML:", result.data.parsed);
+ *     console.log("As JSON:", result.data.asJson);
+ *   }
+ * }
+ * ```
+ */
+import { createRequire } from "node:module";
+import { BaseFileProcessor } from "../base/BaseFileProcessor.js";
+import { SIZE_LIMITS_MB } from "../config/index.js";
+import { createFileError, FileErrorCode } from "../errors/index.js";
+const require = createRequire(import.meta.url);
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+/** Supported YAML MIME types */
+const SUPPORTED_YAML_TYPES = ["application/x-yaml", "text/yaml", "text/x-yaml"];
+/** Supported YAML file extensions */
+const SUPPORTED_YAML_EXTENSIONS = [".yaml", ".yml"];
+/**
+ * Dangerous YAML custom tags that can execute code.
+ * These patterns indicate potential security threats and should be rejected.
+ */
+const YAML_DANGEROUS_TAGS = [
+    // Python code execution
+    "!!python/object",
+    "!!python/object/apply",
+    "!!python/object/new",
+    "!!python/name",
+    "!!python/module",
+    // Ruby code execution
+    "!!ruby/object",
+    "!!ruby/hash",
+    "!!ruby/struct",
+    "!!ruby/sym",
+    // JavaScript code execution
+    "!!js/function",
+    "!!js/undefined",
+    // General dangerous patterns
+    "!!perl/",
+    "!!php/",
+    "!!java/",
+];
+// =============================================================================
+// YAML PROCESSOR CLASS
+// =============================================================================
+/**
+ * YAML file processor.
+ * Extends BaseFileProcessor with YAML-specific parsing and validation.
+ *
+ * Uses secure parsing configuration to prevent:
+ * - Code execution via custom tags (uses 'core' schema)
+ * - Billion laughs attack (limits alias count to 100)
+ * - Dangerous custom tag injection (explicit pattern checking)
+ *
+ * @example
+ * ```typescript
+ * const processor = new YamlProcessor();
+ *
+ * const result = await processor.processFile({
+ *   id: "file-123",
+ *   name: "config.yaml",
+ *   mimetype: "application/x-yaml",
+ *   size: 1024,
+ *   buffer: yamlBuffer,
+ * });
+ *
+ * if (result.success && result.data?.valid) {
+ *   console.log("As JSON:", result.data.asJson);
+ * }
+ * ```
+ */
+export class YamlProcessor extends BaseFileProcessor {
+    constructor() {
+        super({
+            maxSizeMB: SIZE_LIMITS_MB.YAML_MAX_MB,
+            timeoutMs: 30000,
+            supportedMimeTypes: SUPPORTED_YAML_TYPES,
+            supportedExtensions: SUPPORTED_YAML_EXTENSIONS,
+            fileTypeName: "YAML",
+            defaultFilename: "config.yaml",
+        });
+    }
+    /**
+     * Get detected dangerous tags in YAML content.
+     *
+     * @param content - Raw YAML content string
+     * @returns Array of detected dangerous tags (empty if none found)
+     */
+    getDetectedDangerousTags(content) {
+        return YAML_DANGEROUS_TAGS.filter((pattern) => content.includes(pattern));
+    }
+    /**
+     * Parse YAML content securely using strict schema.
+     *
+     * Security measures:
+     * - 'core' schema: Only allows standard YAML types (string, number, boolean, null, array, object)
+     * - maxAliasCount: Limits alias expansion to prevent billion laughs attack
+     *
+     * @param content - Raw YAML content string
+     * @returns Parsed YAML content
+     */
+    parseYamlSecurely(content) {
+        // Dynamically import js-yaml to parse YAML securely
+        const yaml = require("js-yaml");
+        return yaml.load(content, {
+            schema: yaml.CORE_SCHEMA, // Only allow standard YAML types, no custom tags
+            // Prevent billion laughs attack via alias expansion
+            // Note: js-yaml doesn't have maxAliasCount, but using CORE_SCHEMA + size limits provides protection
+        });
+    }
+    /**
+     * Validate downloaded YAML is parseable and safe with structured error result.
+     * Checks for dangerous custom tags and validates YAML syntax.
+     * Returns user-friendly error messages with actionable suggestions.
+     *
+     * @param buffer - Downloaded file content
+     * @param fileInfo - Original file information
+     * @returns Success result or error result
+     */
+    async validateDownloadedFileWithResult(buffer, fileInfo) {
+        try {
+            const content = buffer.toString("utf-8");
+            // Check for potentially dangerous YAML constructs before parsing
+            const detectedTags = this.getDetectedDangerousTags(content);
+            if (detectedTags.length > 0) {
+                const error = createFileError(FileErrorCode.CODE_EXECUTION_DETECTED, {
+                    fileType: "YAML",
+                    detectedTags: detectedTags.join(", "),
+                    filename: fileInfo.name,
+                });
+                return {
+                    success: false,
+                    error: {
+                        code: error.code,
+                        message: error.message,
+                        userMessage: error.userMessage,
+                        details: error.details,
+                    },
+                };
+            }
+            // Parse with secure configuration
+            this.parseYamlSecurely(content);
+            return { success: true, data: undefined };
+        }
+        catch (error) {
+            const fileError = createFileError(FileErrorCode.PARSING_FAILED, { fileType: "YAML" }, error instanceof Error ? error : undefined);
+            return {
+                success: false,
+                error: {
+                    code: fileError.code,
+                    message: fileError.message,
+                    userMessage: fileError.userMessage,
+                    details: fileError.details,
+                },
+            };
+        }
+    }
+    /**
+     * Build processed YAML result with parsed content.
+     * Uses secure parsing configuration to prevent code execution attacks.
+     *
+     * @param buffer - Downloaded file content
+     * @param fileInfo - Original file information
+     * @returns Processed YAML result
+     */
+    buildProcessedResult(buffer, fileInfo) {
+        const content = buffer.toString("utf-8");
+        let parsed = null;
+        let valid = true;
+        let errorMessage;
+        let asJson = null;
+        try {
+            // Use secure parsing - validation already passed, but maintain consistent security
+            parsed = this.parseYamlSecurely(content);
+            asJson = JSON.stringify(parsed, null, 2);
+        }
+        catch (error) {
+            // This shouldn't happen since we validate, but handle gracefully
+            valid = false;
+            errorMessage = error instanceof Error ? error.message : "Invalid YAML";
+        }
+        return {
+            content,
+            parsed,
+            valid,
+            errorMessage,
+            asJson,
+            buffer,
+            mimetype: fileInfo.mimetype || "application/x-yaml",
+            size: fileInfo.size,
+            filename: this.getFilename(fileInfo),
+        };
+    }
+}
+// =============================================================================
+// SINGLETON INSTANCE
+// =============================================================================
+/** Singleton YAML processor instance */
+export const yamlProcessor = new YamlProcessor();
+// =============================================================================
+// UTILITY FUNCTIONS
+// =============================================================================
+/**
+ * Check if a file is a YAML file based on MIME type or extension.
+ *
+ * @param mimetype - MIME type of the file
+ * @param filename - Filename (for extension-based detection)
+ * @returns true if the file is a YAML file
+ *
+ * @example
+ * ```typescript
+ * if (isYamlFile("application/x-yaml", "config.yaml")) {
+ *   // Process as YAML
+ * }
+ * ```
+ */
+export function isYamlFile(mimetype, filename) {
+    return yamlProcessor.isFileSupported(mimetype, filename);
+}
+/**
+ * Validate YAML file size against configured limit.
+ *
+ * @param sizeBytes - File size in bytes
+ * @returns true if size is within the limit
+ */
+export function validateYamlSize(sizeBytes) {
+    const maxBytes = SIZE_LIMITS_MB.YAML_MAX_MB * 1024 * 1024;
+    return sizeBytes <= maxBytes;
+}
+/**
+ * Process a single YAML file with security validation.
+ *
+ * @param fileInfo - File information (with URL or buffer)
+ * @param options - Optional processing options (auth headers, timeout, retry config)
+ * @returns Processing result with parsed YAML or error
+ *
+ * @example
+ * ```typescript
+ * const result = await processYaml({
+ *   id: "file-123",
+ *   name: "config.yaml",
+ *   mimetype: "application/x-yaml",
+ *   size: 2048,
+ *   url: "https://example.com/config.yaml",
+ * }, {
+ *   authHeaders: { "Authorization": "Bearer token" },
+ * });
+ *
+ * if (result.success && result.data) {
+ *   console.log("Parsed:", result.data.parsed);
+ *   console.log("As JSON:", result.data.asJson);
+ * }
+ * ```
+ */
+export function processYaml(fileInfo, options) {
+    return yamlProcessor.processFile(fileInfo, options);
+}

package/dist/processors/data/index.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Data Processors Module
+ *
+ * Provides processors for structured data formats (JSON, YAML, XML).
+ * All processors include security validation and provide parsed content
+ * for easy integration with AI models.
+ *
+ * @module processors/data
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   // JSON processing
+ *   jsonProcessor,
+ *   isJsonFile,
+ *   processJson,
+ *   type ProcessedJson,
+ *
+ *   // YAML processing (with security)
+ *   yamlProcessor,
+ *   isYamlFile,
+ *   processYaml,
+ *   type ProcessedYaml,
+ *
+ *   // XML processing (with XXE protection)
+ *   xmlProcessor,
+ *   isXmlFile,
+ *   processXml,
+ *   type ProcessedXml,
+ * } from "./data/index.js";
+ *
+ * // Auto-detect and process
+ * async function processDataFile(fileInfo: FileInfo) {
+ *   if (isJsonFile(fileInfo.mimetype, fileInfo.name)) {
+ *     return processJson(fileInfo);
+ *   }
+ *   if (isYamlFile(fileInfo.mimetype, fileInfo.name)) {
+ *     return processYaml(fileInfo);
+ *   }
+ *   if (isXmlFile(fileInfo.mimetype, fileInfo.name)) {
+ *     return processXml(fileInfo);
+ *   }
+ *   throw new Error("Unsupported data format");
+ * }
+ * ```
+ */
+export { isJsonFile, JsonProcessor, jsonProcessor, type ProcessedJson, processJson, validateJsonSize, } from "./JsonProcessor.js";
+export { isYamlFile, type ProcessedYaml, processYaml, validateYamlSize, YamlProcessor, yamlProcessor, } from "./YamlProcessor.js";
+export { isXmlFile, type ProcessedXml, processXml, validateXmlSize, XmlProcessor, xmlProcessor, } from "./XmlProcessor.js";

package/dist/processors/data/index.js

@@ -0,0 +1,76 @@
+/**
+ * Data Processors Module
+ *
+ * Provides processors for structured data formats (JSON, YAML, XML).
+ * All processors include security validation and provide parsed content
+ * for easy integration with AI models.
+ *
+ * @module processors/data
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   // JSON processing
+ *   jsonProcessor,
+ *   isJsonFile,
+ *   processJson,
+ *   type ProcessedJson,
+ *
+ *   // YAML processing (with security)
+ *   yamlProcessor,
+ *   isYamlFile,
+ *   processYaml,
+ *   type ProcessedYaml,
+ *
+ *   // XML processing (with XXE protection)
+ *   xmlProcessor,
+ *   isXmlFile,
+ *   processXml,
+ *   type ProcessedXml,
+ * } from "./data/index.js";
+ *
+ * // Auto-detect and process
+ * async function processDataFile(fileInfo: FileInfo) {
+ *   if (isJsonFile(fileInfo.mimetype, fileInfo.name)) {
+ *     return processJson(fileInfo);
+ *   }
+ *   if (isYamlFile(fileInfo.mimetype, fileInfo.name)) {
+ *     return processYaml(fileInfo);
+ *   }
+ *   if (isXmlFile(fileInfo.mimetype, fileInfo.name)) {
+ *     return processXml(fileInfo);
+ *   }
+ *   throw new Error("Unsupported data format");
+ * }
+ * ```
+ */
+// =============================================================================
+// JSON PROCESSOR
+// =============================================================================
+export { 
+// Utility functions
+isJsonFile, 
+// Class
+JsonProcessor, 
+// Singleton
+jsonProcessor, processJson, validateJsonSize, } from "./JsonProcessor.js";
+// =============================================================================
+// YAML PROCESSOR
+// =============================================================================
+export { 
+// Utility functions
+isYamlFile, processYaml, validateYamlSize, 
+// Class
+YamlProcessor, 
+// Singleton
+yamlProcessor, } from "./YamlProcessor.js";
+// =============================================================================
+// XML PROCESSOR
+// =============================================================================
+export { 
+// Utility functions
+isXmlFile, processXml, validateXmlSize, 
+// Class
+XmlProcessor, 
+// Singleton
+xmlProcessor, } from "./XmlProcessor.js";

package/dist/processors/document/ExcelProcessor.d.ts

@@ -0,0 +1,238 @@
+/**
+ * Excel Processor
+ *
+ * Handles downloading, validating, and processing Excel files (.xlsx, .xls).
+ * Uses exceljs library for parsing with streaming support for large files.
+ *
+ * Key features:
+ * - Supports both .xlsx and legacy .xls formats
+ * - Extracts worksheet data with headers
+ * - Handles complex cell types (formulas, rich text, dates)
+ * - Respects configurable row and sheet limits
+ * - Provides truncation metadata when limits are exceeded
+ *
+ * @module processors/document/ExcelProcessor
+ *
+ * @example
+ * ```typescript
+ * import { excelProcessor, processExcel, isExcelFile } from "./ExcelProcessor.js";
+ *
+ * // Check if a file is an Excel file
+ * if (isExcelFile(fileInfo.mimetype, fileInfo.name)) {
+ *   // Process the Excel file
+ *   const result = await processExcel(fileInfo, {
+ *     authHeaders: { Authorization: "Bearer token" },
+ *   });
+ *
+ *   if (result.success) {
+ *     console.log(`Processed ${result.data.sheetCount} sheets`);
+ *     console.log(`Total rows: ${result.data.totalRows}`);
+ *
+ *     for (const sheet of result.data.worksheets) {
+ *       console.log(`Sheet: ${sheet.name}, Rows: ${sheet.rowCount}`);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+import { BaseFileProcessor } from "../base/BaseFileProcessor.js";
+import type { FileInfo, FileProcessingResult, ProcessOptions } from "../base/types.js";
+export type { ExcelWorksheet, ProcessedExcel } from "../base/types.js";
+import type { ProcessedExcel } from "../base/types.js";
+/**
+ * Excel Processor - handles .xlsx and .xls files.
+ * Uses exceljs library for parsing with support for large files.
+ *
+ * Features:
+ * - ZIP format validation (XLSX files are ZIP archives)
+ * - Sheet count limiting (MAX_EXCEL_SHEETS)
+ * - Row count limiting per sheet (MAX_EXCEL_ROWS)
+ * - Cell type handling (text, numbers, formulas, dates, rich text)
+ *
+ * @example
+ * ```typescript
+ * const processor = new ExcelProcessor();
+ *
+ * // Process a file
+ * const result = await processor.processFile(fileInfo, {
+ *   authHeaders: { Authorization: "Bearer token" },
+ * });
+ *
+ * if (result.success) {
+ *   console.log(`Sheets: ${result.data.sheetCount}`);
+ *   console.log(`Truncated: ${result.data.truncated}`);
+ * }
+ * ```
+ */
+export declare class ExcelProcessor extends BaseFileProcessor<ProcessedExcel> {
+    constructor();
+    /**
+     * Validate downloaded Excel file has correct format.
+     * XLSX files are ZIP archives starting with PK signature.
+     *
+     * @param buffer - Downloaded file content
+     * @param _fileInfo - Original file information (unused but required by interface)
+     * @returns null if valid, error message if invalid
+     */
+    protected validateDownloadedFile(buffer: Buffer, _fileInfo: FileInfo): Promise<string | null>;
+    /**
+     * Build processed result stub.
+     * Note: This is a synchronous stub - actual parsing happens in processFile override.
+     *
+     * @param buffer - Downloaded file content
+     * @param fileInfo - Original file information
+     * @returns Empty ProcessedExcel structure (populated by processFile)
+     */
+    protected buildProcessedResult(buffer: Buffer, fileInfo: FileInfo): ProcessedExcel;
+    /**
+     * Override processFile for async Excel parsing with exceljs.
+     * This override is necessary because exceljs uses async parsing.
+     *
+     * @param fileInfo - File information (can include URL or buffer)
+     * @param options - Optional processing options (auth headers, timeout, etc.)
+     * @returns Processing result with parsed Excel data or error
+     */
+    processFile(fileInfo: FileInfo, options?: ProcessOptions): Promise<FileProcessingResult<ProcessedExcel>>;
+    /**
+     * Parse Excel buffer into workbook using exceljs.
+     *
+     * @param buffer - Excel file content
+     * @returns Parsed ExcelJS Workbook
+     */
+    private parseWorkbook;
+    /**
+     * Extract worksheet data from workbook with row and sheet limits.
+     *
+     * @param workbook - Parsed ExcelJS Workbook
+     * @returns Extracted worksheets with truncation metadata
+     */
+    private extractWorksheets;
+    /**
+     * Convert an Excel cell value to a primitive type.
+     * Handles various cell types including formulas, rich text, and dates.
+     *
+     * @param cell - ExcelJS cell value (can be various types)
+     * @returns Primitive value (string, number, boolean, or null)
+     */
+    private getCellValue;
+    /**
+     * Extract text from rich text cell format.
+     * Rich text cells contain an array of text fragments with formatting.
+     *
+     * @param richText - Array of rich text fragments
+     * @returns Concatenated plain text
+     */
+    private extractRichText;
+}
+/**
+ * Singleton Excel processor instance.
+ * Use this for standard Excel processing operations.
+ *
+ * @example
+ * ```typescript
+ * import { excelProcessor } from "./ExcelProcessor.js";
+ *
+ * const result = await excelProcessor.processFile(fileInfo);
+ * ```
+ */
+export declare const excelProcessor: ExcelProcessor;
+/**
+ * Check if a file is an Excel file.
+ * Matches by MIME type or file extension.
+ *
+ * @param mimetype - MIME type of the file
+ * @param filename - Filename (for extension-based detection)
+ * @returns true if the file is an Excel file
+ *
+ * @example
+ * ```typescript
+ * if (isExcelFile("application/vnd.ms-excel", "data.xls")) {
+ *   // Process as Excel
+ * }
+ *
+ * if (isExcelFile("", "report.xlsx")) {
+ *   // Also matches by extension
+ * }
+ * ```
+ */
+export declare function isExcelFile(mimetype: string, filename: string): boolean;
+/**
+ * Validate Excel file size against configured limit.
+ *
+ * @param sizeBytes - File size in bytes
+ * @returns true if size is within the Excel file limit
+ *
+ * @example
+ * ```typescript
+ * if (!validateExcelSize(fileInfo.size)) {
+ *   console.error(`File too large: max ${SIZE_LIMITS.EXCEL_MAX_MB}MB`);
+ * }
+ * ```
+ */
+export declare function validateExcelSize(sizeBytes: number): boolean;
+/**
+ * Process a single Excel file.
+ * Convenience function that uses the singleton processor.
+ *
+ * @param fileInfo - File information (can include URL or buffer)
+ * @param options - Optional processing options (auth headers, timeout, etc.)
+ * @returns Processing result with parsed Excel data or error
+ *
+ * @example
+ * ```typescript
+ * import { processExcel } from "./ExcelProcessor.js";
+ *
+ * const result = await processExcel(fileInfo, {
+ *   authHeaders: { Authorization: "Bearer token" },
+ *   timeout: 120000, // 2 minutes for large files
+ * });
+ *
+ * if (result.success) {
+ *   const { worksheets, totalRows, truncated } = result.data;
+ *   console.log(`Extracted ${totalRows} rows from ${worksheets.length} sheets`);
+ *
+ *   if (truncated) {
+ *     console.warn("Some data was truncated due to size limits");
+ *   }
+ * } else {
+ *   console.error(`Processing failed: ${result.error?.userMessage}`);
+ * }
+ * ```
+ */
+export declare function processExcel(fileInfo: FileInfo, options?: ProcessOptions): Promise<FileProcessingResult<ProcessedExcel>>;
+/**
+ * Get Excel max size in MB.
+ *
+ * @returns Maximum Excel file size in megabytes
+ *
+ * @example
+ * ```typescript
+ * const maxSize = getExcelMaxSizeMB(); // 10
+ * console.log(`Maximum Excel file size: ${maxSize}MB`);
+ * ```
+ */
+export declare function getExcelMaxSizeMB(): number;
+/**
+ * Get Excel max rows per sheet.
+ *
+ * @returns Maximum rows to process per worksheet
+ *
+ * @example
+ * ```typescript
+ * const maxRows = getExcelMaxRows(); // 5000
+ * console.log(`Maximum rows per sheet: ${maxRows}`);
+ * ```
+ */
+export declare function getExcelMaxRows(): number;
+/**
+ * Get Excel max sheets to process.
+ *
+ * @returns Maximum number of worksheets to process
+ *
+ * @example
+ * ```typescript
+ * const maxSheets = getExcelMaxSheets(); // 10
+ * console.log(`Maximum sheets to process: ${maxSheets}`);
+ * ```
+ */
+export declare function getExcelMaxSheets(): number;