@juspay/neurolink
Version:
Universal AI Development Platform with working MCP integration, multi-provider support, voice (TTS/STT/realtime), and professional CLI. 58+ external MCP servers discoverable, multimodal file processing, RAG pipelines. Build, test, and deploy AI applicatio
162 lines (161 loc) • 5.9 kB
TypeScript
/**
* 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 { BaseFileProcessor } from "../base/BaseFileProcessor.js";
import type { FileInfo, ProcessorFileProcessingResult, ProcessorOperationResult, ProcessOptions, ProcessedYaml } from "../../types/index.js";
/**
* 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 declare class YamlProcessor extends BaseFileProcessor<ProcessedYaml> {
constructor();
/**
* Get detected dangerous tags in YAML content.
*
* @param content - Raw YAML content string
* @returns Array of detected dangerous tags (empty if none found)
*/
private getDetectedDangerousTags;
/**
* 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
*/
private parseYamlSecurely;
/**
* 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
*/
protected validateDownloadedFileWithResult(buffer: Buffer, fileInfo: FileInfo): Promise<ProcessorOperationResult<void>>;
/**
* 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
*/
protected buildProcessedResult(buffer: Buffer, fileInfo: FileInfo): ProcessedYaml;
}
/** Singleton YAML processor instance */
export declare const yamlProcessor: YamlProcessor;
/**
* 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 declare function isYamlFile(mimetype: string, filename: string): boolean;
/**
* Validate YAML file size against configured limit.
*
* @param sizeBytes - File size in bytes
* @returns true if size is within the limit
*/
export declare function validateYamlSize(sizeBytes: number): boolean;
/**
* 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 declare function processYaml(fileInfo: FileInfo, options?: ProcessOptions): Promise<ProcessorFileProcessingResult<ProcessedYaml>>;