@juspay/neurolink 9.29.1 → 9.31.0

package/dist/client/mcp/agentExposure.js

@@ -0,0 +1,356 @@
+/**
+ * Agent and Workflow Exposure as MCP Tools
+ *
+ * Enables exposing NeuroLink agents and workflows as MCP tools,
+ * allowing external MCP clients to invoke complex AI operations
+ * through the standardized MCP protocol.
+ *
+ * @module mcp/agentExposure
+ * @since 8.39.0
+ */
+import { logger } from "../utils/logger.js";
+import { withTimeout } from "../utils/async/withTimeout.js";
+import { ErrorFactory } from "../utils/errorHandling.js";
+/**
+ * Expose an agent as an MCP tool
+ */
+export function exposeAgentAsTool(agent, options = {}) {
+    const { prefix = "agent", defaultAnnotations = {}, includeMetadataInDescription = true, nameTransformer = (name) => name.toLowerCase().replace(/\s+/g, "_"), wrapWithContext = true, executionTimeout = 300000, // 5 minutes default
+    enableLogging = true, } = options;
+    // Generate tool name
+    const baseName = nameTransformer(agent.name);
+    const toolName = prefix ? `${prefix}_${baseName}` : baseName;
+    // Build description
+    let description = agent.description;
+    if (includeMetadataInDescription && agent.metadata) {
+        const metaParts = [];
+        if (agent.metadata.version) {
+            metaParts.push(`v${agent.metadata.version}`);
+        }
+        if (agent.metadata.category) {
+            metaParts.push(`category: ${agent.metadata.category}`);
+        }
+        if (agent.metadata.estimatedDuration) {
+            metaParts.push(`~${agent.metadata.estimatedDuration}ms`);
+        }
+        if (metaParts.length > 0) {
+            description += ` [${metaParts.join(", ")}]`;
+        }
+    }
+    // Build annotations
+    const annotations = {
+        ...defaultAnnotations,
+        complexity: defaultAnnotations.complexity ?? "complex",
+        estimatedDuration: agent.metadata?.estimatedDuration ?? defaultAnnotations.estimatedDuration,
+        costHint: agent.metadata?.costHint ?? defaultAnnotations.costHint,
+        tags: [
+            ...(defaultAnnotations.tags ?? []),
+            "agent",
+            ...(agent.metadata?.tags ?? []),
+        ],
+    };
+    // Build input schema with agent context
+    const inputSchema = agent.inputSchema ?? {
+        type: "object",
+        properties: {},
+    };
+    // Create execution wrapper
+    const execute = async (params, context) => {
+        const startTime = Date.now();
+        if (enableLogging) {
+            logger.debug(`[AgentExposure] Executing agent '${agent.id}' as tool '${toolName}'`);
+        }
+        try {
+            // Execute agent with context wrapper if enabled
+            const existingConfig = context?.config && typeof context.config === "object"
+                ? context.config
+                : {};
+            const executionContext = wrapWithContext
+                ? {
+                    ...context,
+                    config: {
+                        ...existingConfig,
+                        sourceType: "mcp-exposed-agent",
+                        agentId: agent.id,
+                        toolName,
+                    },
+                }
+                : (context ?? {});
+            const result = await withTimeout(agent.execute(params, executionContext), executionTimeout);
+            const duration = Date.now() - startTime;
+            if (enableLogging) {
+                logger.debug(`[AgentExposure] Agent '${agent.id}' completed in ${duration}ms`);
+            }
+            return {
+                success: true,
+                data: result,
+                metadata: {
+                    agentId: agent.id,
+                    toolName,
+                    executionTime: duration,
+                    sourceType: "agent",
+                },
+            };
+        }
+        catch (error) {
+            const duration = Date.now() - startTime;
+            const agentError = error instanceof Error
+                ? error
+                : ErrorFactory.toolExecutionFailed(toolName, new Error(String(error)));
+            if (enableLogging) {
+                logger.error(`[AgentExposure] Agent '${agent.id}' failed after ${duration}ms: ${agentError.message}`);
+            }
+            return {
+                success: false,
+                error: agentError.message,
+                metadata: {
+                    agentId: agent.id,
+                    toolName,
+                    executionTime: duration,
+                    sourceType: "agent",
+                },
+            };
+        }
+    };
+    const tool = {
+        name: toolName,
+        description,
+        inputSchema,
+        outputSchema: agent.outputSchema,
+        annotations,
+        execute,
+        metadata: {
+            sourceType: "agent",
+            sourceId: agent.id,
+            originalName: agent.name,
+            ...agent.metadata,
+        },
+    };
+    return {
+        tool,
+        sourceType: "agent",
+        sourceId: agent.id,
+        toolName,
+    };
+}
+/**
+ * Expose a workflow as an MCP tool
+ */
+export function exposeWorkflowAsTool(workflow, options = {}) {
+    const { prefix = "workflow", defaultAnnotations = {}, includeMetadataInDescription = true, nameTransformer = (name) => name.toLowerCase().replace(/\s+/g, "_"), wrapWithContext = true, executionTimeout = 600000, // 10 minutes default for workflows
+    enableLogging = true, } = options;
+    // Generate tool name
+    const baseName = nameTransformer(workflow.name);
+    const toolName = prefix ? `${prefix}_${baseName}` : baseName;
+    // Build description
+    let description = workflow.description;
+    if (includeMetadataInDescription) {
+        const metaParts = [];
+        if (workflow.metadata?.version) {
+            metaParts.push(`v${workflow.metadata.version}`);
+        }
+        if (workflow.steps?.length) {
+            metaParts.push(`${workflow.steps.length} steps`);
+        }
+        if (workflow.metadata?.estimatedDuration) {
+            metaParts.push(`~${workflow.metadata.estimatedDuration}ms`);
+        }
+        if (metaParts.length > 0) {
+            description += ` [${metaParts.join(", ")}]`;
+        }
+    }
+    // Build annotations
+    const annotations = {
+        ...defaultAnnotations,
+        complexity: defaultAnnotations.complexity ?? "complex",
+        estimatedDuration: workflow.metadata?.estimatedDuration ??
+            defaultAnnotations.estimatedDuration,
+        idempotentHint: workflow.metadata?.idempotent ?? defaultAnnotations.idempotentHint,
+        tags: [
+            ...(defaultAnnotations.tags ?? []),
+            "workflow",
+            ...(workflow.metadata?.tags ?? []),
+        ],
+    };
+    // Build input schema
+    const inputSchema = workflow.inputSchema ?? {
+        type: "object",
+        properties: {},
+    };
+    // Create execution wrapper
+    const execute = async (params, context) => {
+        const startTime = Date.now();
+        if (enableLogging) {
+            logger.debug(`[WorkflowExposure] Executing workflow '${workflow.id}' as tool '${toolName}'`);
+        }
+        try {
+            // Execute workflow with context wrapper if enabled
+            const existingConfig = context?.config && typeof context.config === "object"
+                ? context.config
+                : {};
+            const executionContext = wrapWithContext
+                ? {
+                    ...context,
+                    config: {
+                        ...existingConfig,
+                        sourceType: "mcp-exposed-workflow",
+                        workflowId: workflow.id,
+                        toolName,
+                    },
+                }
+                : (context ?? {});
+            const result = await withTimeout(workflow.execute(params, executionContext), executionTimeout);
+            const duration = Date.now() - startTime;
+            if (enableLogging) {
+                logger.debug(`[WorkflowExposure] Workflow '${workflow.id}' completed in ${duration}ms`);
+            }
+            return {
+                success: true,
+                data: result,
+                metadata: {
+                    workflowId: workflow.id,
+                    toolName,
+                    executionTime: duration,
+                    sourceType: "workflow",
+                    stepsCount: workflow.steps?.length,
+                },
+            };
+        }
+        catch (error) {
+            const duration = Date.now() - startTime;
+            const workflowError = error instanceof Error
+                ? error
+                : ErrorFactory.toolExecutionFailed(toolName, new Error(String(error)));
+            if (enableLogging) {
+                logger.error(`[WorkflowExposure] Workflow '${workflow.id}' failed after ${duration}ms: ${workflowError.message}`);
+            }
+            return {
+                success: false,
+                error: workflowError.message,
+                metadata: {
+                    workflowId: workflow.id,
+                    toolName,
+                    executionTime: duration,
+                    sourceType: "workflow",
+                },
+            };
+        }
+    };
+    const tool = {
+        name: toolName,
+        description,
+        inputSchema,
+        outputSchema: workflow.outputSchema,
+        annotations,
+        execute,
+        metadata: {
+            sourceType: "workflow",
+            sourceId: workflow.id,
+            originalName: workflow.name,
+            steps: workflow.steps,
+            ...workflow.metadata,
+        },
+    };
+    return {
+        tool,
+        sourceType: "workflow",
+        sourceId: workflow.id,
+        toolName,
+    };
+}
+/**
+ * Batch expose agents as MCP tools
+ */
+export function exposeAgentsAsTools(agents, options = {}) {
+    return agents.map((agent) => exposeAgentAsTool(agent, options));
+}
+/**
+ * Batch expose workflows as MCP tools
+ */
+export function exposeWorkflowsAsTools(workflows, options = {}) {
+    return workflows.map((workflow) => exposeWorkflowAsTool(workflow, options));
+}
+/**
+ * Agent Exposure Manager
+ *
+ * Manages the lifecycle of exposed agents and workflows,
+ * providing registration, lookup, and invocation capabilities.
+ */
+export class AgentExposureManager {
+    exposedTools = new Map();
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    /**
+     * Expose an agent and register it
+     */
+    exposeAgent(agent) {
+        const result = exposeAgentAsTool(agent, this.options);
+        this.exposedTools.set(result.toolName, result);
+        return result.tool;
+    }
+    /**
+     * Expose a workflow and register it
+     */
+    exposeWorkflow(workflow) {
+        const result = exposeWorkflowAsTool(workflow, this.options);
+        this.exposedTools.set(result.toolName, result);
+        return result.tool;
+    }
+    /**
+     * Get all exposed tools
+     */
+    getExposedTools() {
+        return Array.from(this.exposedTools.values()).map((r) => r.tool);
+    }
+    /**
+     * Get exposed tool by name
+     */
+    getExposedTool(toolName) {
+        return this.exposedTools.get(toolName)?.tool;
+    }
+    /**
+     * Get exposure result by tool name
+     */
+    getExposureResult(toolName) {
+        return this.exposedTools.get(toolName);
+    }
+    /**
+     * Get tools by source type
+     */
+    getToolsBySourceType(sourceType) {
+        return Array.from(this.exposedTools.values())
+            .filter((r) => r.sourceType === sourceType)
+            .map((r) => r.tool);
+    }
+    /**
+     * Remove exposed tool
+     */
+    unexpose(toolName) {
+        return this.exposedTools.delete(toolName);
+    }
+    /**
+     * Clear all exposed tools
+     */
+    clear() {
+        this.exposedTools.clear();
+    }
+    /**
+     * Get statistics
+     */
+    getStatistics() {
+        const results = Array.from(this.exposedTools.values());
+        return {
+            totalExposed: results.length,
+            exposedAgents: results.filter((r) => r.sourceType === "agent").length,
+            exposedWorkflows: results.filter((r) => r.sourceType === "workflow")
+                .length,
+            toolNames: results.map((r) => r.toolName),
+        };
+    }
+}
+/**
+ * Global agent exposure manager instance
+ */
+export const globalAgentExposureManager = new AgentExposureManager();

package/dist/client/mcp/auth/index.js

@@ -0,0 +1,11 @@
+/**
+ * MCP Authentication Module
+ * OAuth 2.1 authentication support for MCP HTTP transport
+ */
+// Note: OAuth types (OAuthTokens, TokenStorage, MCPOAuthConfig, etc.)
+// should be imported directly from the types folder: src/lib/types/mcpTypes.ts
+// Consumers should use: import type { MCPOAuthConfig } from "@juspay/neurolink"
+// Token storage implementations
+export { InMemoryTokenStorage, FileTokenStorage, isTokenExpired, calculateExpiresAt, } from "./tokenStorage.js";
+// OAuth client provider
+export { NeuroLinkOAuthProvider, createOAuthProviderFromConfig, } from "./oauthClientProvider.js";

package/dist/client/mcp/auth/oauthClientProvider.js

@@ -0,0 +1,325 @@
+/**
+ * OAuth 2.1 Client Provider for MCP HTTP Transport
+ * Implements OAuth 2.1 authentication with PKCE support
+ */
+import { randomBytes, createHash } from "crypto";
+import { InMemoryTokenStorage, isTokenExpired, calculateExpiresAt, } from "./tokenStorage.js";
+import { logger } from "../../utils/logger.js";
+/**
+ * NeuroLink OAuth Provider for MCP HTTP Transport
+ * Handles OAuth 2.1 authentication flow with optional PKCE support
+ */
+export class NeuroLinkOAuthProvider {
+    config;
+    storage;
+    pendingChallenges = new Map();
+    pendingStates = new Set();
+    constructor(config, storage) {
+        this.config = {
+            ...config,
+            usePKCE: config.usePKCE ?? true, // PKCE enabled by default for OAuth 2.1
+        };
+        this.storage = storage ?? new InMemoryTokenStorage();
+    }
+    /**
+     * Get stored tokens for a server
+     * Returns null if tokens are not available or expired (without refresh token)
+     */
+    async tokens(serverId) {
+        const tokens = await this.storage.getTokens(serverId);
+        if (!tokens) {
+            return null;
+        }
+        // Check if tokens are expired
+        if (isTokenExpired(tokens)) {
+            // Try to refresh if refresh token is available
+            if (tokens.refreshToken) {
+                try {
+                    const refreshedTokens = await this.refreshTokens(serverId, tokens.refreshToken);
+                    return refreshedTokens;
+                }
+                catch (error) {
+                    logger.warn(`[NeuroLinkOAuthProvider] Token refresh failed: ${error instanceof Error ? error.message : String(error)}`);
+                    // Delete expired tokens if refresh fails
+                    await this.storage.deleteTokens(serverId);
+                    return null;
+                }
+            }
+            // No refresh token, delete expired tokens
+            await this.storage.deleteTokens(serverId);
+            return null;
+        }
+        return tokens;
+    }
+    /**
+     * Save tokens for a server
+     */
+    async saveTokens(serverId, tokens) {
+        await this.storage.saveTokens(serverId, tokens);
+    }
+    /**
+     * Delete tokens for a server
+     */
+    async deleteTokens(serverId) {
+        await this.storage.deleteTokens(serverId);
+    }
+    /**
+     * Get client information for MCP SDK
+     */
+    clientInformation() {
+        return {
+            clientId: this.config.clientId,
+            clientSecret: this.config.clientSecret,
+            redirectUri: this.config.redirectUrl,
+        };
+    }
+    /**
+     * Generate authorization URL for OAuth flow
+     * Returns the URL to redirect the user to for authorization
+     * @param _serverId - Server ID (reserved for future use in state management)
+     */
+    redirectToAuthorization(_serverId) {
+        // Generate state parameter for CSRF protection
+        const state = this.generateState();
+        this.pendingStates.add(state);
+        // Build authorization URL
+        const url = new URL(this.config.authorizationUrl);
+        // Required OAuth 2.1 parameters
+        url.searchParams.set("response_type", "code");
+        url.searchParams.set("client_id", this.config.clientId);
+        url.searchParams.set("redirect_uri", this.config.redirectUrl);
+        url.searchParams.set("state", state);
+        // Optional scope
+        if (this.config.scope) {
+            url.searchParams.set("scope", this.config.scope);
+        }
+        // PKCE support
+        let codeVerifier;
+        if (this.config.usePKCE) {
+            const pkce = this.generatePKCE();
+            codeVerifier = pkce.codeVerifier;
+            // Store PKCE challenge for later verification
+            this.pendingChallenges.set(state, pkce);
+            url.searchParams.set("code_challenge", pkce.codeChallenge);
+            url.searchParams.set("code_challenge_method", pkce.codeChallengeMethod);
+        }
+        // Additional custom parameters
+        if (this.config.additionalParams) {
+            for (const [key, value] of Object.entries(this.config.additionalParams)) {
+                url.searchParams.set(key, value);
+            }
+        }
+        return {
+            url: url.toString(),
+            state,
+            codeVerifier,
+        };
+    }
+    /**
+     * Exchange authorization code for tokens
+     */
+    async exchangeCode(serverId, request) {
+        // Validate state
+        if (!this.pendingStates.has(request.state)) {
+            throw new Error("Invalid or expired state parameter");
+        }
+        this.pendingStates.delete(request.state);
+        // Get PKCE verifier if applicable
+        let codeVerifier = request.codeVerifier;
+        if (this.config.usePKCE && !codeVerifier) {
+            const pkce = this.pendingChallenges.get(request.state);
+            if (pkce) {
+                codeVerifier = pkce.codeVerifier;
+                this.pendingChallenges.delete(request.state);
+            }
+        }
+        // Build token request
+        const body = new URLSearchParams();
+        body.set("grant_type", "authorization_code");
+        body.set("code", request.code);
+        body.set("redirect_uri", this.config.redirectUrl);
+        body.set("client_id", this.config.clientId);
+        // Include client secret if available (confidential clients)
+        if (this.config.clientSecret) {
+            body.set("client_secret", this.config.clientSecret);
+        }
+        // Include PKCE verifier if applicable
+        if (codeVerifier) {
+            body.set("code_verifier", codeVerifier);
+        }
+        // Request tokens
+        const response = await fetch(this.config.tokenUrl, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+                Accept: "application/json",
+            },
+            body: body.toString(),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Token exchange failed: ${response.status} ${response.statusText} - ${errorText}`);
+        }
+        const tokenResponse = (await response.json());
+        // Convert to OAuthTokens format
+        const tokens = {
+            accessToken: tokenResponse.access_token,
+            refreshToken: tokenResponse.refresh_token,
+            expiresAt: tokenResponse.expires_in
+                ? calculateExpiresAt(tokenResponse.expires_in)
+                : undefined,
+            tokenType: tokenResponse.token_type ?? "Bearer",
+            scope: tokenResponse.scope,
+        };
+        // Save tokens
+        await this.saveTokens(serverId, tokens);
+        return tokens;
+    }
+    /**
+     * Refresh tokens using refresh token
+     */
+    async refreshTokens(serverId, refreshToken) {
+        const body = new URLSearchParams();
+        body.set("grant_type", "refresh_token");
+        body.set("refresh_token", refreshToken);
+        body.set("client_id", this.config.clientId);
+        if (this.config.clientSecret) {
+            body.set("client_secret", this.config.clientSecret);
+        }
+        const response = await fetch(this.config.tokenUrl, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+                Accept: "application/json",
+            },
+            body: body.toString(),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Token refresh failed: ${response.status} ${response.statusText} - ${errorText}`);
+        }
+        const tokenResponse = (await response.json());
+        const tokens = {
+            accessToken: tokenResponse.access_token,
+            // Keep old refresh token if new one not provided
+            refreshToken: tokenResponse.refresh_token ?? refreshToken,
+            expiresAt: tokenResponse.expires_in
+                ? calculateExpiresAt(tokenResponse.expires_in)
+                : undefined,
+            tokenType: tokenResponse.token_type ?? "Bearer",
+            scope: tokenResponse.scope,
+        };
+        await this.saveTokens(serverId, tokens);
+        return tokens;
+    }
+    /**
+     * Revoke tokens (if supported by the OAuth server)
+     */
+    async revokeTokens(serverId, revocationUrl) {
+        const tokens = await this.storage.getTokens(serverId);
+        if (!tokens) {
+            return;
+        }
+        const body = new URLSearchParams();
+        body.set("token", tokens.accessToken);
+        body.set("client_id", this.config.clientId);
+        if (this.config.clientSecret) {
+            body.set("client_secret", this.config.clientSecret);
+        }
+        try {
+            await fetch(revocationUrl, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/x-www-form-urlencoded",
+                },
+                body: body.toString(),
+            });
+        }
+        catch (error) {
+            logger.warn(`[NeuroLinkOAuthProvider] Token revocation failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        // Always delete local tokens
+        await this.storage.deleteTokens(serverId);
+    }
+    /**
+     * Get authorization header value for API requests
+     */
+    async getAuthorizationHeader(serverId) {
+        const tokens = await this.tokens(serverId);
+        if (!tokens) {
+            return null;
+        }
+        return `${tokens.tokenType} ${tokens.accessToken}`;
+    }
+    /**
+     * Check if a server has valid (non-expired) tokens
+     */
+    async hasValidTokens(serverId) {
+        const tokens = await this.tokens(serverId);
+        return tokens !== null;
+    }
+    /**
+     * Generate a cryptographically secure state parameter
+     */
+    generateState() {
+        return randomBytes(32).toString("base64url");
+    }
+    /**
+     * Generate PKCE code verifier and challenge
+     * Uses SHA-256 for code challenge method (required by OAuth 2.1)
+     */
+    generatePKCE() {
+        // Generate code verifier (43-128 characters, URL-safe)
+        const codeVerifier = randomBytes(32).toString("base64url");
+        // Generate code challenge using SHA-256
+        const codeChallenge = createHash("sha256")
+            .update(codeVerifier)
+            .digest("base64url");
+        return {
+            codeVerifier,
+            codeChallenge,
+            codeChallengeMethod: "S256",
+        };
+    }
+    /**
+     * Get the OAuth configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Get the token storage instance
+     */
+    getStorage() {
+        return this.storage;
+    }
+    /**
+     * Clean up expired pending states and challenges
+     * Should be called periodically to prevent memory leaks
+     */
+    cleanupPendingRequests() {
+        // Clear old pending states (older than 10 minutes)
+        // Note: In a production system, you'd want to track timestamps
+        // For now, we just clear all if there are too many
+        if (this.pendingStates.size > 100) {
+            this.pendingStates.clear();
+        }
+        if (this.pendingChallenges.size > 100) {
+            this.pendingChallenges.clear();
+        }
+    }
+}
+/**
+ * Create an OAuth provider from MCP server auth configuration
+ */
+export function createOAuthProviderFromConfig(authConfig, storage) {
+    return new NeuroLinkOAuthProvider({
+        clientId: authConfig.clientId,
+        clientSecret: authConfig.clientSecret,
+        authorizationUrl: authConfig.authorizationUrl,
+        tokenUrl: authConfig.tokenUrl,
+        redirectUrl: authConfig.redirectUrl,
+        scope: authConfig.scope,
+        usePKCE: authConfig.usePKCE ?? true,
+    }, storage);
+}