@juspay/neurolink 1.10.0 → 1.11.0

package/dist/lib/mcp/security-manager.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Security Manager - Permission-Based Sandbox for MCP Operations
+ * Implements the research blueprint's security-by-design principles
+ */
+import type { ExecutionContext } from "./contracts/mcp-contract.js";
+/**
+ * Security levels for plugin execution
+ */
+export type SecurityLevel = "strict" | "moderate" | "permissive";
+/**
+ * Permission types supported by the security system
+ */
+export interface Permission {
+    type: "fs" | "net" | "process" | "env";
+    action: string;
+    resource: string;
+}
+/**
+ * Security Manager implementing permission-based sandbox
+ */
+export declare class SecurityManager {
+    private securityLevel;
+    private allowedBasePaths;
+    private deniedPaths;
+    constructor(securityLevel?: SecurityLevel);
+    /**
+     * Initialize default security boundaries based on level
+     */
+    private initializeSecurityBoundaries;
+    /**
+     * Validate permissions array from manifest
+     */
+    validatePermissions(permissions: string[]): boolean;
+    /**
+     * Parse permission string into structured format
+     */
+    private parsePermission;
+    /**
+     * Check if a permission is allowed based on security level
+     */
+    private isPermissionAllowed;
+    /**
+     * Validate filesystem permissions
+     */
+    private isFileSystemPermissionAllowed;
+    /**
+     * Check if filesystem action is allowed
+     */
+    private isFileSystemActionAllowed;
+    /**
+     * Validate network permissions
+     */
+    private isNetworkPermissionAllowed;
+    /**
+     * Validate process permissions
+     */
+    private isProcessPermissionAllowed;
+    /**
+     * Validate environment permissions
+     */
+    private isEnvironmentPermissionAllowed;
+    /**
+     * Create a secure filesystem interface for ExecutionContext
+     */
+    createSecureFS(grantedPermissions: string[], basePath?: string): {
+        readFile(filePath: string, encoding?: string): Promise<string | Buffer>;
+        writeFile(filePath: string, content: string | Buffer): Promise<void>;
+        readdir(dirPath: string): Promise<string[]>;
+        stat(filePath: string): Promise<any>;
+        mkdir(dirPath: string, options?: any): Promise<void>;
+        exists(filePath: string): Promise<boolean>;
+    };
+    /**
+     * Check filesystem permission against granted permissions
+     */
+    private checkFileSystemPermission;
+    /**
+     * Check if permission matches wildcard pattern
+     */
+    private matchesWildcardPermission;
+    /**
+     * Create execution context with security sandbox
+     */
+    createExecutionContext(sessionId: string, userId: string, grantedPermissions: string[], basePath?: string): ExecutionContext;
+}

package/dist/lib/mcp/security-manager.js

@@ -0,0 +1,344 @@
+/**
+ * Security Manager - Permission-Based Sandbox for MCP Operations
+ * Implements the research blueprint's security-by-design principles
+ */
+import * as fs from "fs/promises";
+import * as path from "path";
+import { mcpLogger } from "./logging.js";
+/**
+ * Security Manager implementing permission-based sandbox
+ */
+export class SecurityManager {
+    securityLevel;
+    allowedBasePaths;
+    deniedPaths;
+    constructor(securityLevel = "moderate") {
+        this.securityLevel = securityLevel;
+        this.allowedBasePaths = new Set();
+        this.deniedPaths = new Set();
+        // Initialize default security boundaries
+        this.initializeSecurityBoundaries();
+    }
+    /**
+     * Initialize default security boundaries based on level
+     */
+    initializeSecurityBoundaries() {
+        const cwd = process.cwd();
+        switch (this.securityLevel) {
+            case "strict":
+                // Only allow current working directory
+                this.allowedBasePaths.add(cwd);
+                this.deniedPaths.add(path.join(cwd, "node_modules"));
+                this.deniedPaths.add("/etc");
+                this.deniedPaths.add("/usr");
+                this.deniedPaths.add("/var");
+                break;
+            case "moderate":
+                // Allow project directory and some system reads
+                this.allowedBasePaths.add(cwd);
+                this.allowedBasePaths.add(path.join(process.env.HOME || "/", "Downloads"));
+                this.deniedPaths.add("/etc/passwd");
+                this.deniedPaths.add("/etc/shadow");
+                break;
+            case "permissive":
+                // Allow broader access with minimal restrictions
+                this.allowedBasePaths.add("/");
+                this.deniedPaths.add("/etc/passwd");
+                this.deniedPaths.add("/etc/shadow");
+                break;
+        }
+    }
+    /**
+     * Validate permissions array from manifest
+     */
+    validatePermissions(permissions) {
+        try {
+            for (const permission of permissions) {
+                const parsed = this.parsePermission(permission);
+                if (!this.isPermissionAllowed(parsed)) {
+                    mcpLogger.warn(`[SecurityManager] Permission denied: ${permission}`);
+                    return false;
+                }
+            }
+            return true;
+        }
+        catch (error) {
+            mcpLogger.error("[SecurityManager] Permission validation failed:", error);
+            return false;
+        }
+    }
+    /**
+     * Parse permission string into structured format
+     */
+    parsePermission(permission) {
+        const parts = permission.split(":");
+        if (parts.length !== 3) {
+            throw new Error(`Invalid permission format: ${permission}`);
+        }
+        return {
+            type: parts[0],
+            action: parts[1],
+            resource: parts[2],
+        };
+    }
+    /**
+     * Check if a permission is allowed based on security level
+     */
+    isPermissionAllowed(permission) {
+        switch (permission.type) {
+            case "fs":
+                return this.isFileSystemPermissionAllowed(permission);
+            case "net":
+                return this.isNetworkPermissionAllowed(permission);
+            case "process":
+                return this.isProcessPermissionAllowed(permission);
+            case "env":
+                return this.isEnvironmentPermissionAllowed(permission);
+            default:
+                return false;
+        }
+    }
+    /**
+     * Validate filesystem permissions
+     */
+    isFileSystemPermissionAllowed(permission) {
+        const { action, resource } = permission;
+        const resolvedPath = path.resolve(resource);
+        // Check if path is explicitly denied
+        for (const deniedPath of this.deniedPaths) {
+            if (resolvedPath.startsWith(deniedPath)) {
+                return false;
+            }
+        }
+        // Check if path is within allowed base paths
+        for (const basePath of this.allowedBasePaths) {
+            if (resolvedPath.startsWith(basePath)) {
+                return this.isFileSystemActionAllowed(action);
+            }
+        }
+        return false;
+    }
+    /**
+     * Check if filesystem action is allowed
+     */
+    isFileSystemActionAllowed(action) {
+        const allowedActions = {
+            strict: ["read"],
+            moderate: ["read", "write"],
+            permissive: ["read", "write", "delete", "execute"],
+        };
+        return allowedActions[this.securityLevel].includes(action);
+    }
+    /**
+     * Validate network permissions
+     */
+    isNetworkPermissionAllowed(permission) {
+        if (this.securityLevel === "strict") {
+            return false; // No network access in strict mode
+        }
+        const { resource } = permission;
+        // Only allow HTTPS in moderate mode
+        if (this.securityLevel === "moderate") {
+            return resource.startsWith("https://");
+        }
+        // Permissive allows both HTTP and HTTPS
+        return resource.startsWith("http://") || resource.startsWith("https://");
+    }
+    /**
+     * Validate process permissions
+     */
+    isProcessPermissionAllowed(permission) {
+        // Only permissive mode allows process operations
+        return this.securityLevel === "permissive";
+    }
+    /**
+     * Validate environment permissions
+     */
+    isEnvironmentPermissionAllowed(permission) {
+        const { action, resource } = permission;
+        // Reading environment variables is generally safe
+        if (action === "read") {
+            return true;
+        }
+        // Writing environment variables requires higher permissions
+        return this.securityLevel === "permissive";
+    }
+    /**
+     * Create a secure filesystem interface for ExecutionContext
+     */
+    createSecureFS(grantedPermissions, basePath) {
+        const self = this;
+        const CWD = process.cwd();
+        const resolveSecurePath = (p) => {
+            // Resolve the path. If basePath is provided, use it, otherwise use the current working directory.
+            const resolved = path.resolve(basePath || CWD, p);
+            // If a basePath is specified, ensure the resolved path is within that base path.
+            // This is a security measure to prevent path traversal attacks (e.g., using '../').
+            if (basePath) {
+                const relative = path.relative(path.resolve(basePath), resolved);
+                if (relative.startsWith("..") || path.isAbsolute(relative)) {
+                    throw new Error(`Path traversal detected. Attempted to access ${resolved} which is outside of the allowed base path ${basePath}`);
+                }
+            }
+            return resolved;
+        };
+        return {
+            async readFile(filePath, encoding) {
+                const resolvedPath = resolveSecurePath(filePath);
+                self.checkFileSystemPermission("read", resolvedPath, grantedPermissions, basePath);
+                try {
+                    return await fs.readFile(resolvedPath, encoding);
+                }
+                catch (error) {
+                    mcpLogger.error(`[SecurityManager] Failed to read file ${filePath}:`, error);
+                    throw error;
+                }
+            },
+            async writeFile(filePath, content) {
+                const resolvedPath = resolveSecurePath(filePath);
+                self.checkFileSystemPermission("write", resolvedPath, grantedPermissions, basePath);
+                try {
+                    // Ensure directory exists
+                    await fs.mkdir(path.dirname(resolvedPath), { recursive: true });
+                    await fs.writeFile(resolvedPath, content);
+                }
+                catch (error) {
+                    mcpLogger.error(`[SecurityManager] Failed to write file ${filePath}:`, error);
+                    throw error;
+                }
+            },
+            async readdir(dirPath) {
+                const resolvedPath = resolveSecurePath(dirPath);
+                self.checkFileSystemPermission("read", resolvedPath, grantedPermissions, basePath);
+                try {
+                    return await fs.readdir(resolvedPath);
+                }
+                catch (error) {
+                    mcpLogger.error(`[SecurityManager] Failed to read directory ${dirPath}:`, error);
+                    throw error;
+                }
+            },
+            async stat(filePath) {
+                const resolvedPath = resolveSecurePath(filePath);
+                self.checkFileSystemPermission("read", resolvedPath, grantedPermissions, basePath);
+                try {
+                    return await fs.stat(resolvedPath);
+                }
+                catch (error) {
+                    mcpLogger.error(`[SecurityManager] Failed to stat ${filePath}:`, error);
+                    throw error;
+                }
+            },
+            async mkdir(dirPath, options) {
+                const resolvedPath = resolveSecurePath(dirPath);
+                self.checkFileSystemPermission("write", resolvedPath, grantedPermissions, basePath);
+                try {
+                    await fs.mkdir(resolvedPath, options);
+                }
+                catch (error) {
+                    mcpLogger.error(`[SecurityManager] Failed to create directory ${dirPath}:`, error);
+                    throw error;
+                }
+            },
+            async exists(filePath) {
+                const resolvedPath = resolveSecurePath(filePath);
+                self.checkFileSystemPermission("read", resolvedPath, grantedPermissions, basePath);
+                try {
+                    await fs.access(resolvedPath);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            },
+        };
+    }
+    /**
+     * Check filesystem permission against granted permissions
+     */
+    checkFileSystemPermission(action, filePath, grantedPermissions, basePath) {
+        const requiredPermission = `fs:${action}:${filePath}`;
+        for (const permissionString of grantedPermissions) {
+            const parsedPermission = this.parsePermission(permissionString);
+            if (parsedPermission.type === "fs" &&
+                (parsedPermission.action === action ||
+                    parsedPermission.action === "read-write")) {
+                // Handle relative paths with wildcards properly
+                let grantedPath;
+                if (!path.isAbsolute(parsedPermission.resource)) {
+                    // For relative paths, resolve them relative to basePath if provided
+                    if (basePath) {
+                        // Handle wildcard patterns specially
+                        if (parsedPermission.resource.includes("*")) {
+                            // For patterns like './**/*', convert to absolute pattern
+                            const resolvedBase = path.resolve(basePath);
+                            if (parsedPermission.resource.startsWith("./")) {
+                                grantedPath = path.join(resolvedBase, parsedPermission.resource.substring(2));
+                            }
+                            else {
+                                grantedPath = path.join(resolvedBase, parsedPermission.resource);
+                            }
+                        }
+                        else {
+                            grantedPath = path.resolve(basePath, parsedPermission.resource);
+                        }
+                    }
+                    else {
+                        grantedPath = path.resolve(parsedPermission.resource);
+                    }
+                }
+                else {
+                    grantedPath = parsedPermission.resource;
+                }
+                if (this.matchesWildcardPermission(filePath, grantedPath)) {
+                    return; // Permission granted
+                }
+            }
+        }
+        throw new Error(`Permission denied: ${requiredPermission}`);
+    }
+    /**
+     * Check if permission matches wildcard pattern
+     */
+    matchesWildcardPermission(required, granted) {
+        // Handle patterns that end with /** or /**/* (recursive directory access)
+        if (granted.endsWith("/**") || granted.endsWith("/**/*")) {
+            const basePath = granted.endsWith("/**/*")
+                ? granted.slice(0, -5) // Remove /**/*
+                : granted.slice(0, -3); // Remove /**
+            // Check if required path is the base path itself or a subdirectory/file within it.
+            return required === basePath || required.startsWith(basePath + "/");
+        }
+        if (!granted.includes("*")) {
+            return required === granted;
+        }
+        // Convert wildcard to regex for other cases
+        const regexPattern = granted
+            .replace(/[.+?^${}()|[\]\\]/g, "\\$&") // Escape special regex characters
+            .replace(/\*\*/g, ".*") // This is a greedy match, use with caution
+            .replace(/\*/g, "[^/]*"); // Handle single wildcard (any characters except slashes)
+        const regex = new RegExp(`^${regexPattern}$`);
+        return regex.test(required);
+    }
+    /**
+     * Create execution context with security sandbox
+     */
+    createExecutionContext(sessionId, userId, grantedPermissions, basePath) {
+        return {
+            sessionId,
+            userId,
+            grantedPermissions,
+            secureFS: this.createSecureFS(grantedPermissions, basePath),
+            path: {
+                join: path.join,
+                resolve: path.resolve,
+                relative: path.relative,
+                dirname: path.dirname,
+                basename: path.basename,
+            },
+            log: (level, message, data) => {
+                mcpLogger[level](`[ExecutionContext:${sessionId}] ${message}`, data);
+            },
+        };
+    }
+}

package/dist/lib/mcp/servers/ai-providers/ai-workflow-tools.d.ts

@@ -30,13 +30,13 @@ export declare const workflowToolSchemas: {
         includeAsyncTests: z.ZodDefault<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
         codeFunction: string;
-        testTypes: ("unit" | "integration" | "edge-cases" | "performance" | "security")[];
+        testTypes: ("integration" | "unit" | "edge-cases" | "performance" | "security")[];
         framework: "jest" | "mocha" | "vitest" | "pytest" | "unittest" | "rspec";
         coverageTarget: number;
         includeAsyncTests: boolean;
     }, {
         codeFunction: string;
-        testTypes?: ("unit" | "integration" | "edge-cases" | "performance" | "security")[] | undefined;
+        testTypes?: ("integration" | "unit" | "edge-cases" | "performance" | "security")[] | undefined;
         framework?: "jest" | "mocha" | "vitest" | "pytest" | "unittest" | "rspec" | undefined;
         coverageTarget?: number | undefined;
         includeAsyncTests?: boolean | undefined;

package/dist/lib/mcp/tool-integration.d.ts

@@ -18,26 +18,16 @@ export declare class MCPToolIntegration {
     /**
      * Get all available tools
      */
-    getAvailableTools(): {
-        name: string;
-        qualifiedName: string;
-        description: string;
-        server: string;
-        serverTitle: string;
-        category?: string;
-        serverCategory?: string;
-        permissions?: string[];
-        isImplemented?: boolean;
-    }[];
+    getAvailableTools(): Promise<import("./tool-registry.js").ToolInfo[]>;
     /**
      * Find tools that match a query
      */
-    findTools(query: string): Array<{
+    findTools(query: string): Promise<Array<{
         name: string;
         description: string;
         serverId: string;
         relevance: number;
-    }>;
+    }>>;
     /**
      * Execute a tool by name
      */
@@ -45,7 +35,7 @@ export declare class MCPToolIntegration {
     /**
      * Enhance AI prompt with tool context
      */
-    createToolAwarePrompt(userPrompt: string): string;
+    createToolAwarePrompt(userPrompt: string): Promise<string>;
     /**
      * Analyze AI response for tool usage requests
      */

package/dist/lib/mcp/tool-integration.js

@@ -4,7 +4,7 @@
  */
 import { mcpConfig } from "./config.js";
 import { logger } from "../utils/logger.js";
-import { MCPToolRegistry } from "./registry.js";
+import { MCPToolRegistry } from "./tool-registry.js";
 /**
  * Tool Integration System
  * Provides natural language tool discovery and execution
@@ -16,9 +16,34 @@ export class MCPToolIntegration {
         this.registry = new MCPToolRegistry();
         this.context = {
             sessionId: context?.sessionId || `session-${Date.now()}`,
-            userId: context?.userId,
-            aiProvider: context?.aiProvider,
+            userId: context?.userId || "anonymous",
+            aiProvider: context?.aiProvider || "unknown",
             ...context,
+            // Ensure secureFS is properly typed
+            secureFS: context?.secureFS || {
+                readFile: async () => {
+                    throw new Error("secureFS not configured");
+                },
+                writeFile: async () => {
+                    throw new Error("secureFS not configured");
+                },
+                readdir: async () => {
+                    throw new Error("secureFS not configured");
+                },
+                stat: async () => {
+                    throw new Error("secureFS not configured");
+                },
+                mkdir: async () => {
+                    throw new Error("secureFS not configured");
+                },
+                exists: async () => false,
+                rmdir: async () => {
+                    throw new Error("secureFS not configured");
+                },
+                unlink: async () => {
+                    throw new Error("secureFS not configured");
+                },
+            },
         };
         // Initialize with all active servers
         this.initializeTools();
@@ -29,11 +54,12 @@ export class MCPToolIntegration {
     async initializeTools() {
         const servers = await mcpConfig.getServers();
         for (const server of servers) {
-            await this.registry.registerServer(server);
+            await this.registry.registerServer(server.id || server.name || "unknown", server);
         }
+        const tools = await this.registry.listTools();
         logger.debug("[Tool Integration] Initialized with servers:", {
             serverCount: servers.length,
-            toolCount: this.registry.listTools().length,
+            toolCount: tools.length,
         });
     }
     /**
@@ -45,8 +71,8 @@ export class MCPToolIntegration {
     /**
      * Find tools that match a query
      */
-    findTools(query) {
-        const allTools = this.registry.listTools();
+    async findTools(query) {
+        const allTools = await this.registry.listTools();
         const queryLower = query.toLowerCase();
         const results = [];
         for (const toolInfo of allTools) {
@@ -56,18 +82,18 @@ export class MCPToolIntegration {
                 relevance += 10;
             }
             // Check tool description
-            if (toolInfo.description.toLowerCase().includes(queryLower)) {
+            if (toolInfo.description?.toLowerCase().includes(queryLower)) {
                 relevance += 5;
             }
-            // Check category if present
-            if (toolInfo.category?.toLowerCase().includes(queryLower)) {
-                relevance += 3;
-            }
+            // Check category if present (category might not exist on ToolInfo)
+            // if (toolInfo.category?.toLowerCase().includes(queryLower)) {
+            //   relevance += 3;
+            // }
             if (relevance > 0) {
                 results.push({
                     name: toolInfo.name,
-                    description: toolInfo.description,
-                    serverId: toolInfo.server,
+                    description: toolInfo.description || "No description available",
+                    serverId: toolInfo.server || "unknown",
                     relevance,
                 });
             }
@@ -82,11 +108,7 @@ export class MCPToolIntegration {
         try {
             // If serverId is provided, use qualified name
             const qualifiedName = serverId ? `${serverId}.${toolName}` : toolName;
-            const result = await this.registry.executeTool(qualifiedName, params, this.context, {
-                validateInput: true,
-                validatePermissions: true,
-                trackMetrics: true,
-            });
+            const result = await this.registry.executeTool(qualifiedName, params, this.context);
             return result;
         }
         catch (error) {
@@ -105,8 +127,8 @@ export class MCPToolIntegration {
     /**
      * Enhance AI prompt with tool context
      */
-    createToolAwarePrompt(userPrompt) {
-        const tools = this.getAvailableTools();
+    async createToolAwarePrompt(userPrompt) {
+        const tools = await this.getAvailableTools();
         const toolDescriptions = tools
             .map((t) => `- ${t.name}: ${t.description}`)
             .join("\n");

package/dist/lib/mcp/tool-registry.d.ts

@@ -0,0 +1,66 @@
+/**
+ * MCP Tool Registry - Extended Registry with Tool Management
+ */
+import type { ExecutionContext } from "./contracts/mcp-contract.js";
+import type { ToolResult } from "./factory.js";
+import { MCPRegistry } from "./registry.js";
+export interface ToolInfo {
+    id: string;
+    name: string;
+    description?: string;
+    inputSchema?: any;
+    outputSchema?: any;
+    serverId: string;
+    source: "manual" | "auto" | "default";
+    isImplemented?: boolean;
+    server?: string;
+}
+export type ToolExecutionResult = ToolResult;
+export declare class MCPToolRegistry extends MCPRegistry {
+    private tools;
+    private toolExecutionStats;
+    /**
+     * Register a server with its tools
+     */
+    registerServer(serverId: string, serverInfo: any): Promise<void>;
+    /**
+     * Unregister a server and its tools
+     */
+    unregisterServer(serverId: string): Promise<void>;
+    /**
+     * Execute a tool
+     */
+    executeTool(toolName: string, args: any, context: ExecutionContext): Promise<ToolExecutionResult>;
+    /**
+     * List all available tools
+     */
+    listTools(): Promise<ToolInfo[]>;
+    /**
+     * Get tool information
+     */
+    getToolInfo(toolName: string): ToolInfo | undefined;
+    /**
+     * Update execution statistics
+     */
+    private updateStats;
+    /**
+     * Get tool execution statistics
+     */
+    getToolStats(toolName?: string): any;
+    /**
+     * Get tool execution statistics
+     */
+    getStats(): Promise<any>;
+    /**
+     * Clear all tools and stats
+     */
+    clear(): void;
+}
+export declare const toolRegistry: MCPToolRegistry;
+export declare const defaultToolRegistry: MCPToolRegistry;
+export interface ToolExecutionOptions {
+    preferredSource?: string;
+    fallbackEnabled?: boolean;
+    validateBeforeExecution?: boolean;
+    timeoutMs?: number;
+}