@anyshift/mcp-proxy 0.2.0

package/dist/jq/handler.js

@@ -0,0 +1,90 @@
+import { spawn } from 'child_process';
+import { existsSync } from 'fs';
+import path from 'path';
+import { validatePathWithinAllowedDirs } from '../utils/pathValidation.js';
+// Default timeout for JQ execution
+const DEFAULT_TIMEOUT_MS = 30000;
+/**
+ * Execute a JQ query on a JSON file
+ * @param config - JQ configuration
+ * @param jqQuery - The JQ query to execute
+ * @param filePath - Absolute path to the JSON file
+ * @returns Promise with the query result
+ */
+export async function executeJqQuery(config, jqQuery, filePath) {
+    // Input validation
+    if (!jqQuery || !filePath) {
+        throw new Error('jq_query and file_path are required');
+    }
+    // Sanitize jq query to prevent environment variable access
+    const dangerousPatterns = [
+        /\$ENV/i, // $ENV variable access
+        /env\./i, // env.VARIABLE access
+        /@env/i, // @env function
+        /\.env\[/i, // .env["VARIABLE"] access
+        /getenv/i, // getenv function
+        /\$__loc__/i, // location info that might leak paths
+        /input_filename/i, // input filename access
+    ];
+    const isDangerous = dangerousPatterns.some((pattern) => pattern.test(jqQuery));
+    if (isDangerous) {
+        throw new Error('The jq query contains patterns that could access environment variables or system information. Please use a different query.');
+    }
+    // Validate file path
+    if (!path.isAbsolute(filePath)) {
+        throw new Error(`File path must be an absolute path starting with "/": ${filePath}`);
+    }
+    if (!existsSync(filePath)) {
+        throw new Error(`File not found: ${filePath}`);
+    }
+    // Validate file extension
+    if (!filePath.toLowerCase().endsWith('.json')) {
+        throw new Error(`Only JSON files (.json) are supported for jq processing: ${filePath}`);
+    }
+    // Validate path is within allowed directories
+    validatePathWithinAllowedDirs(filePath, config.allowedPaths);
+    // Execute jq query
+    const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    return new Promise((resolve, reject) => {
+        const jqProcess = spawn('jq', [jqQuery, filePath], {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            timeout: timeoutMs,
+        });
+        let stdout = '';
+        let stderr = '';
+        jqProcess.stdout.on('data', (data) => {
+            stdout += data.toString();
+        });
+        jqProcess.stderr.on('data', (data) => {
+            stderr += data.toString();
+        });
+        jqProcess.on('close', (code) => {
+            if (code === 0) {
+                // Success - return clean response directly to AI
+                const responseText = stdout.trim();
+                resolve({
+                    content: [
+                        {
+                            type: 'text',
+                            text: responseText,
+                        },
+                    ],
+                });
+            }
+            else {
+                // Error
+                reject(new Error(`jq command failed with exit code ${code}: ${stderr.trim()}`));
+            }
+        });
+        jqProcess.on('error', (error) => {
+            reject(new Error(`Failed to execute jq command: ${error.message}`));
+        });
+        // Handle timeout
+        setTimeout(() => {
+            if (!jqProcess.killed) {
+                jqProcess.kill('SIGTERM');
+                reject(new Error(`jq command timed out after ${timeoutMs}ms`));
+            }
+        }, timeoutMs);
+    });
+}

package/dist/jq/index.d.ts

@@ -0,0 +1,51 @@
+import { JqConfig } from './types.js';
+/**
+ * Create a JQ tool instance with the given configuration
+ * @param config - JQ configuration
+ * @returns Object with handler and toolDefinition
+ */
+export declare function createJqTool(config: JqConfig): {
+    /**
+     * Tool definition for MCP server registration
+     */
+    toolDefinition: {
+        name: string;
+        description: string;
+        inputSchema: {
+            type: string;
+            properties: {
+                jq_query: {
+                    type: string;
+                    description: string;
+                };
+                file_path: {
+                    type: string;
+                    description: string;
+                };
+                description: {
+                    type: string;
+                    description: string;
+                };
+            };
+            required: string[];
+        };
+    };
+    /**
+     * Handler for JQ query execution requests
+     * @param request - MCP request containing jq_query and file_path
+     * @returns Promise with the query result
+     */
+    handler: (request: {
+        params: {
+            arguments: Record<string, unknown>;
+        };
+    }) => Promise<{
+        content: Array<{
+            type: "text";
+            text: string;
+        }>;
+    }>;
+};
+export type { JqConfig } from './types.js';
+export { ExecuteJqQuerySchema, JQ_TOOL_DEFINITION } from './tool.js';
+export { executeJqQuery } from './handler.js';

package/dist/jq/index.js

@@ -0,0 +1,26 @@
+import { executeJqQuery } from './handler.js';
+import { ExecuteJqQuerySchema, JQ_TOOL_DEFINITION } from './tool.js';
+/**
+ * Create a JQ tool instance with the given configuration
+ * @param config - JQ configuration
+ * @returns Object with handler and toolDefinition
+ */
+export function createJqTool(config) {
+    return {
+        /**
+         * Tool definition for MCP server registration
+         */
+        toolDefinition: JQ_TOOL_DEFINITION,
+        /**
+         * Handler for JQ query execution requests
+         * @param request - MCP request containing jq_query and file_path
+         * @returns Promise with the query result
+         */
+        handler: async (request) => {
+            const { jq_query, file_path } = ExecuteJqQuerySchema.parse(request.params.arguments);
+            return executeJqQuery(config, jq_query, file_path);
+        },
+    };
+}
+export { ExecuteJqQuerySchema, JQ_TOOL_DEFINITION } from './tool.js';
+export { executeJqQuery } from './handler.js';

package/dist/jq/tool.d.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+/**
+ * Zod schema for JQ query execution
+ */
+export declare const ExecuteJqQuerySchema: z.ZodObject<{
+    jq_query: z.ZodString;
+    file_path: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    jq_query: string;
+    file_path: string;
+    description?: string | undefined;
+}, {
+    jq_query: string;
+    file_path: string;
+    description?: string | undefined;
+}>;
+/**
+ * Tool definition for JQ query execution with enhanced prompts
+ * This includes schema-first development hints for better LLM usage
+ */
+export declare const JQ_TOOL_DEFINITION: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            jq_query: {
+                type: string;
+                description: string;
+            };
+            file_path: {
+                type: string;
+                description: string;
+            };
+            description: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};

package/dist/jq/tool.js

@@ -0,0 +1,106 @@
+import { z } from 'zod';
+/**
+ * Zod schema for JQ query execution
+ */
+export const ExecuteJqQuerySchema = z.object({
+    jq_query: z
+        .string()
+        .describe('The jq query to execute on the JSON file. Query will be sanitized to prevent environment variable access.'),
+    file_path: z
+        .string()
+        .describe('Absolute path starting with "/" pointing to the JSON file to process. Must be a valid, existing file with .json extension. The file will be validated for existence and readability before processing.'),
+    description: z
+        .string()
+        .optional()
+        .describe('Optional description; a short explanation of the purpose of the query'),
+});
+/**
+ * Tool definition for JQ query execution with enhanced prompts
+ * This includes schema-first development hints for better LLM usage
+ */
+export const JQ_TOOL_DEFINITION = {
+    name: 'execute_jq_query',
+    description: 'Execute a jq query on a JSON file with comprehensive debugging and retry strategies.' +
+        'This tool processes JSON files using jq operations for data extraction, transformation, and filtering. ' +
+        '\n\n⚠️ **CRITICAL SYNTAX RULE**: The jq_query parameter is a STRING. Use PLAIN quotes like .["0"] - DO NOT ESCAPE them as .[\"0\"] or .[\\"0\\"]. The MCP framework handles escaping automatically.' +
+        '\n\n📋 **SCHEMA-FIRST WORKFLOW**: READ the schema from the file write response. For nullable fields use: select(.field != null) or .field // "default"' +
+        '\n\nCRITICAL: When queries fail or return null/empty results, DO NOT abandon the jq approach immediately. Instead, follow the debugging workflow below.' +
+        '\n\n## JQ SYNTAX REFERENCE (Fix Common Errors):' +
+        '\n**QUOTE SYNTAX (MOST COMMON ERROR):**' +
+        '\n- The jq_query is passed as a STRING to the jq binary' +
+        '\n- Use PLAIN quotes: .["key"] NOT .[\"key\"] or .[\\"key\\"]' +
+        '\n- DO NOT escape quotes - the parameter is already a string' +
+        '\n- ✅ CORRECT: .["0"], .["field"], .field' +
+        '\n- ❌ WRONG: .[\"0\"], .[\\"field\\"], .\\\"field\\\"' +
+        '\n\n**ARRAY SLICING (Not Shell Commands):**' +
+        '\n- First N items: .[:5] NOT head -5 or head(5)' +
+        '\n- Last N items: .[-5:] NOT tail -5' +
+        '\n- Skip first N: .[5:] NOT tail +6' +
+        '\n- With limit: limit(10; .) NOT head(10)' +
+        '\n- ✅ CORRECT: .[:10], limit(20; .), .[-5:]' +
+        '\n- ❌ WRONG: head -10, head(20), tail -5' +
+        '\n\n**COMMON FUNCTION MISTAKES:**' +
+        '\n- ❌ head, tail, wc, cut, grep, awk, sed → These are SHELL commands, not jq!' +
+        '\n- ✅ .[:N] → Take first N (array slice)' +
+        '\n- ✅ limit(N; .) → Limit to N items' +
+        '\n- ✅ length → Count items' +
+        '\n- ✅ sort_by(.field) → Sort by field' +
+        '\n- ✅ group_by(.field) → Group by field' +
+        '\n\n**STRING OPERATIONS:**' +
+        '\n- Regex: test("pattern") NOT test(\'pattern\')' +
+        '\n- Contains: contains("text") or test("text")' +
+        '\n- Split: split(",")' +
+        '\n- Join: join(",")' +
+        '\n\n**OBJECT CONSTRUCTION:** Arithmetic needs extra parens: {count: ((.items | length) + 1)} or use variables' +
+        '\n**TYPE SAFETY:** Check schema types. Error "Cannot index X with Y" = wrong type, use: type == "object"' +
+        '\n\n## DEBUGGING WORKFLOW (Use when queries fail or return unexpected results):' +
+        '\n1. **Structure Inspection**: Start with `keys`, `type`, `length` to understand the data structure' +
+        '\n2. **Single Record Access**: Test `.["0"]`, `.["1"]` to access specific items (for object with numeric string keys)' +
+        '\n3. **Field Exploration**: Check `.["0"].Values`, `.["0"].Keys` to understand nested structures' +
+        '\n4. **Build Incrementally**: Start with simple queries, add complexity step by step' +
+        '\n5. **Test Without Filters**: Remove `select()` clauses to see if data exists' +
+        '\n\n## CYPHER RESULT STRUCTURES (Common patterns from Neo4j/graph queries):' +
+        '\n- **Objects with numeric string keys**: {"0": {...}, "1": {...}, "2": {...}} - Use `.["0"]`, NOT `.[0]`' +
+        '\n- **Values/Keys arrays**: Each result has `.Values` and `.Keys` arrays with corresponding data' +
+        '\n- **Null handling**: Many Values arrays contain null - always check for null before processing' +
+        '\n\n## OBJECT vs ARRAY ACCESS PATTERNS:' +
+        '\n✅ **For objects with numeric keys**: `.["0"].Values`, `to_entries[] | .value`, `.[keys[0]]`' +
+        '\n❌ **Wrong**: `.[0].Values` (treats object as array - will fail)' +
+        '\n✅ **Iteration over objects**: `to_entries[] | .value | ...` or `.[] | ...`' +
+        '\n✅ **Safe null checking**: `select(.Values[0] != null)` or `select(.Values // [] | length > 0)`' +
+        '\n\n## RETRY STRATEGIES (Try multiple approaches):' +
+        '\n1. **Different iteration methods**: `.[]`, `to_entries[] | .value`, `.[keys[]]`' +
+        '\n2. **Incremental filtering**: Start with no filters, add conditions one by one' +
+        '\n3. **Alternative null handling**: Use `// empty`, `select(. != null)`, or `try ... catch`' +
+        '\n4. **Simplified queries**: Break complex queries into smaller, testable parts' +
+        '\n\n## COMPREHENSIVE EXAMPLES:' +
+        '\n**Debugging sequence for Cypher results**:' +
+        '\n- `keys` → ["0", "1", "2", ...] (shows object structure)' +
+        '\n- `.["0"]` → {"Values": [...], "Keys": [...]} (shows single result format)' +
+        '\n- `.["0"].Values` → [value1, value2, null, ...] (shows actual data)' +
+        '\n- `to_entries[] | .value | select(.Values[0] != null)` → final query' +
+        '\n\n**Common transformations**:' +
+        '\n- Extract non-null records: `to_entries[] | .value | select(.Values[0] != null)`' +
+        '\n- Build objects from Values/Keys: `.["0"] | {(.Keys[0]): .Values[0], (.Keys[1]): .Values[1]}`' +
+        '\n- Count results: `to_entries | length` or `keys | length`' +
+        '\n- Filter by position: `to_entries[] | select(.key | tonumber < 5) | .value`' +
+        '\n\n**IMPORTANT**: If a query returns null/empty, try simpler versions first to verify data exists before assuming the approach is wrong.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            jq_query: {
+                type: 'string',
+                description: 'The jq query to execute on the JSON file. Query will be sanitized to prevent environment variable access.',
+            },
+            file_path: {
+                type: 'string',
+                description: 'Absolute path starting with "/" pointing to the JSON file to process. Must be a valid, existing file with .json extension. The file will be validated for existence and readability before processing.',
+            },
+            description: {
+                type: 'string',
+                description: 'Optional description; a short explanation of the purpose of the query',
+            },
+        },
+        required: ['jq_query', 'file_path'],
+    },
+};

package/dist/jq/types.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Re-export JqConfig from the main types module
+ */
+export type { JqConfig } from '../types/index.js';

package/dist/jq/types.js

@@ -0,0 +1 @@
+export {};

package/dist/truncation/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Truncation module for MCP response size limiting
+ *
+ * Provides token-based truncation to prevent context overflow in LLM responses.
+ * Supports configurable limits, optional detailed logging, and helper functions.
+ */
+export { truncateResponseIfNeeded, estimateTokens, wouldBeTruncated, } from './truncate.js';
+export type { TruncationConfig } from './types.js';

package/dist/truncation/index.js

@@ -0,0 +1,7 @@
+/**
+ * Truncation module for MCP response size limiting
+ *
+ * Provides token-based truncation to prevent context overflow in LLM responses.
+ * Supports configurable limits, optional detailed logging, and helper functions.
+ */
+export { truncateResponseIfNeeded, estimateTokens, wouldBeTruncated, } from './truncate.js';

package/dist/truncation/truncate.d.ts

@@ -0,0 +1,28 @@
+import { TruncationConfig } from './types.js';
+/**
+ * Estimate token count using chars/token ratio
+ * Uses a simple approximation where 1 token ≈ 4 characters
+ *
+ * @param text - The text to estimate tokens for
+ * @param charsPerToken - Characters per token ratio (default: 4)
+ * @returns Estimated token count
+ */
+export declare function estimateTokens(text: string, charsPerToken?: number): number;
+/**
+ * Check if content would be truncated without actually truncating
+ *
+ * @param content - The content to check
+ * @param maxTokens - Maximum token limit
+ * @param charsPerToken - Characters per token ratio (default: 4)
+ * @returns True if content exceeds token limit
+ */
+export declare function wouldBeTruncated(content: string, maxTokens: number, charsPerToken?: number): boolean;
+/**
+ * Truncate response content if it exceeds token limit
+ * Optionally logs detailed metrics to stderr for monitoring
+ *
+ * @param config - Truncation configuration
+ * @param content - The content to potentially truncate
+ * @returns Original content if under limit, or truncated content with notice
+ */
+export declare function truncateResponseIfNeeded(config: TruncationConfig, content: string): string;

package/dist/truncation/truncate.js

@@ -0,0 +1,80 @@
+const DEFAULT_CHARS_PER_TOKEN = 4;
+/**
+ * Estimate token count using chars/token ratio
+ * Uses a simple approximation where 1 token ≈ 4 characters
+ *
+ * @param text - The text to estimate tokens for
+ * @param charsPerToken - Characters per token ratio (default: 4)
+ * @returns Estimated token count
+ */
+export function estimateTokens(text, charsPerToken = DEFAULT_CHARS_PER_TOKEN) {
+    return Math.ceil(text.length / charsPerToken);
+}
+/**
+ * Check if content would be truncated without actually truncating
+ *
+ * @param content - The content to check
+ * @param maxTokens - Maximum token limit
+ * @param charsPerToken - Characters per token ratio (default: 4)
+ * @returns True if content exceeds token limit
+ */
+export function wouldBeTruncated(content, maxTokens, charsPerToken = DEFAULT_CHARS_PER_TOKEN) {
+    return estimateTokens(content, charsPerToken) > maxTokens;
+}
+/**
+ * Truncate response content if it exceeds token limit
+ * Optionally logs detailed metrics to stderr for monitoring
+ *
+ * @param config - Truncation configuration
+ * @param content - The content to potentially truncate
+ * @returns Original content if under limit, or truncated content with notice
+ */
+export function truncateResponseIfNeeded(config, content) {
+    const charsPerToken = config.charsPerToken || DEFAULT_CHARS_PER_TOKEN;
+    const estimatedTokens = estimateTokens(content, charsPerToken);
+    const contentLength = content.length;
+    const maxChars = config.maxTokens * charsPerToken;
+    // Optional detailed logging to stderr (doesn't interfere with stdio protocol)
+    if (config.enableLogging) {
+        process.stderr.write(JSON.stringify({
+            event: 'truncation_check',
+            content_length: contentLength,
+            estimated_tokens: estimatedTokens,
+            max_token_limit: config.maxTokens,
+            max_chars: maxChars,
+            will_truncate: estimatedTokens > config.maxTokens,
+        }) + '\n');
+    }
+    // No truncation needed
+    if (estimatedTokens <= config.maxTokens) {
+        if (config.enableLogging) {
+            process.stderr.write(JSON.stringify({
+                event: 'no_truncation_needed',
+                estimated_tokens: estimatedTokens,
+                limit: config.maxTokens,
+            }) + '\n');
+        }
+        return content;
+    }
+    // Truncate to max characters
+    const truncated = content.substring(0, maxChars);
+    const truncatedTokens = estimateTokens(truncated, charsPerToken);
+    if (config.enableLogging) {
+        process.stderr.write(JSON.stringify({
+            event: 'content_truncated',
+            original_length: contentLength,
+            original_tokens: estimatedTokens,
+            truncated_length: truncated.length,
+            truncated_tokens: truncatedTokens,
+            limit: config.maxTokens,
+        }) + '\n');
+    }
+    const messagePrefix = config.messagePrefix || 'RESPONSE TRUNCATED';
+    return `=== ${messagePrefix} ===
+Estimated tokens: ${estimatedTokens} (limit: ${config.maxTokens})
+Response truncated to prevent context overflow.
+Please refine your query to be more specific and fetch less data.
+=== END TRUNCATION NOTICE ===
+
+${truncated}`;
+}

package/dist/truncation/types.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Configuration for response truncation
+ */
+export interface TruncationConfig {
+    /**
+     * Maximum number of tokens allowed in response
+     * Common values: 10000 (Datadog), 15000 (Anyshift)
+     */
+    maxTokens: number;
+    /**
+     * Enable detailed JSON logging to stderr
+     * Useful for debugging and monitoring truncation behavior
+     * Default: false
+     */
+    enableLogging?: boolean;
+    /**
+     * Custom prefix for truncation notice message
+     * Default: "RESPONSE TRUNCATED"
+     */
+    messagePrefix?: string;
+    /**
+     * Characters per token ratio for estimation
+     * Default: 4 (standard approximation)
+     */
+    charsPerToken?: number;
+}

package/dist/truncation/types.js

@@ -0,0 +1 @@
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Configuration for the file writer module
+ */
+export interface FileWriterConfig {
+    /** Whether file writing is enabled */
+    enabled: boolean;
+    /** Directory where files should be written */
+    outputPath: string;
+    /** Minimum character count to trigger file writing (default: 1000) */
+    minCharsForWrite?: number;
+    /** Custom abbreviations for tool names in filenames */
+    toolAbbreviations?: Record<string, string>;
+}
+/**
+ * Configuration for the JQ tool
+ */
+export interface JqConfig {
+    /** Paths where JQ is allowed to read files */
+    allowedPaths: string[];
+    /** Timeout for JQ query execution in milliseconds (default: 30000) */
+    timeoutMs?: number;
+}
+/**
+ * Result from file writer operations
+ */
+export interface FileWriterResult {
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+}
+/**
+ * Schema analysis result for a JSON structure
+ */
+export interface JsonSchema {
+    type: string;
+    properties?: Record<string, unknown>;
+    items?: unknown;
+    length?: number;
+    _hasNulls?: boolean;
+    _keysAreNumeric?: boolean;
+    _accessPattern?: string;
+}
+/**
+ * Nullable fields extracted from schema
+ */
+export interface NullableFields {
+    /** Fields that are always null */
+    alwaysNull: string[];
+    /** Fields that can be null (mixed types) */
+    nullable: string[];
+}

package/dist/types/index.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/filename.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Generate LLM-friendly compact filename
+ * @param toolName - Name of the tool that generated the data
+ * @param args - Arguments passed to the tool
+ * @param toolAbbreviations - Optional custom abbreviations for tool names
+ * @returns Compact filename like "1697834567123_met_qry_a3b4c5.json"
+ */
+export declare const generateCompactFilename: (toolName: string, args: Record<string, unknown>, toolAbbreviations?: Record<string, string>) => string;

package/dist/utils/filename.js

@@ -0,0 +1,42 @@
+import crypto from 'crypto';
+/**
+ * Generate compact timestamp using epoch + milliseconds
+ */
+const generateCompactTimestamp = () => {
+    const now = new Date();
+    const epoch = Math.floor(now.getTime() / 1000);
+    const ms = now.getMilliseconds().toString().padStart(3, '0');
+    return `${epoch}${ms}`;
+};
+/**
+ * Generate short hash from arguments for collision resistance
+ */
+const hashArgs = (args) => {
+    const argsString = Object.entries(args)
+        .filter(([key, value]) => 
+    // Filter out sensitive or irrelevant keys
+    !['api_key', 'app_key', 'token', 'api_token'].includes(key.toLowerCase()) &&
+        value !== undefined)
+        .map(([key, value]) => `${key}=${value}`)
+        .join('_');
+    if (!argsString)
+        return 'noargs';
+    return crypto
+        .createHash('md5')
+        .update(argsString)
+        .digest('hex')
+        .substring(0, 6);
+};
+/**
+ * Generate LLM-friendly compact filename
+ * @param toolName - Name of the tool that generated the data
+ * @param args - Arguments passed to the tool
+ * @param toolAbbreviations - Optional custom abbreviations for tool names
+ * @returns Compact filename like "1697834567123_met_qry_a3b4c5.json"
+ */
+export const generateCompactFilename = (toolName, args, toolAbbreviations) => {
+    const timestamp = generateCompactTimestamp();
+    const toolAbbrev = toolAbbreviations?.[toolName] || toolName.substring(0, 6);
+    const argsHash = hashArgs(args);
+    return `${timestamp}_${toolAbbrev}_${argsHash}.json`;
+};

package/dist/utils/pathValidation.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Validate that a file path is within allowed directories
+ * @param filePath - The file path to validate
+ * @param allowedPaths - Array of allowed directory paths
+ * @returns The validated real path (with symlinks resolved)
+ * @throws Error if path is invalid, doesn't exist, or is outside allowed directories
+ */
+export declare const validatePathWithinAllowedDirs: (filePath: string, allowedPaths: string[]) => string;

package/dist/utils/pathValidation.js

@@ -0,0 +1,42 @@
+import { existsSync, realpathSync } from 'fs';
+import path from 'path';
+/**
+ * Validate that a file path is within allowed directories
+ * @param filePath - The file path to validate
+ * @param allowedPaths - Array of allowed directory paths
+ * @returns The validated real path (with symlinks resolved)
+ * @throws Error if path is invalid, doesn't exist, or is outside allowed directories
+ */
+export const validatePathWithinAllowedDirs = (filePath, allowedPaths) => {
+    // Require absolute paths for security and clarity
+    if (!path.isAbsolute(filePath)) {
+        throw new Error(`Absolute path required. Received: ${filePath}. Paths must start with "/" to prevent ambiguity.`);
+    }
+    // Resolve the absolute path (for normalization and symlink handling)
+    const absolutePath = path.resolve(filePath);
+    // Check if file exists before resolving real path (to handle symlinks)
+    if (!existsSync(absolutePath)) {
+        throw new Error(`File does not exist: ${filePath}`);
+    }
+    // Get the real path (resolves symlinks)
+    let realPath;
+    try {
+        realPath = realpathSync(absolutePath);
+    }
+    catch (error) {
+        throw new Error(`Cannot resolve path: ${filePath}`);
+    }
+    // Check if path is within any of the allowed directories
+    for (const allowedPath of allowedPaths) {
+        // Resolve and normalize the allowed path
+        const allowedPathReal = realpathSync(path.resolve(allowedPath));
+        // Check if the real path is within this allowed directory
+        if (realPath.startsWith(allowedPathReal + path.sep) || realPath === allowedPathReal) {
+            console.error(`[validatePathWithinAllowedDirs] Path allowed (within ${allowedPathReal}): ${realPath}`);
+            return realPath;
+        }
+    }
+    // Path is not within any allowed directories
+    const allowedPathsList = allowedPaths.join(', ');
+    throw new Error(`Access denied: File path must be within allowed directories (${allowedPathsList}). Attempted path: ${realPath}`);
+};