@inkeep/agents-core 0.42.0 → 0.44.0

package/dist/utils/JsonTransformer.js

@@ -1,32 +1,23 @@
+import { DANGEROUS_PATTERNS, MAX_EXPRESSION_LENGTH, compileJMESPath, validateJMESPathSecure } from "./jmespath-utils.js";
 import { getLogger } from "./logger.js";
-import * as jmespath$1 from "jmespath";
+import * as jmespath from "jmespath";
 
 //#region src/utils/JsonTransformer.ts
-const jmespathExt = jmespath$1;
 const logger = getLogger("JsonTransformer");
 var JsonTransformer = class JsonTransformer {
 	static DEFAULT_TIMEOUT = 5e3;
-	static MAX_EXPRESSION_LENGTH = 1e3;
-	static DANGEROUS_PATTERNS = [
-		/\$\{.*\}/,
-		/eval\s*\(/,
-		/function\s*\(/,
-		/constructor/,
-		/prototype/,
-		/__proto__/
-	];
 	/**
 	* Validate JMESPath expression for security and correctness
 	*/
-	static validateJMESPath(expression, _allowedFunctions) {
+	static validateExpression(expression, _allowedFunctions) {
 		if (!expression || typeof expression !== "string") throw new Error("JMESPath expression must be a non-empty string");
-		if (expression.length > JsonTransformer.MAX_EXPRESSION_LENGTH) throw new Error(`JMESPath expression too long (max ${JsonTransformer.MAX_EXPRESSION_LENGTH} characters)`);
-		for (const pattern of JsonTransformer.DANGEROUS_PATTERNS) if (pattern.test(expression)) throw new Error(`JMESPath expression contains dangerous pattern: ${pattern.source}`);
-		try {
-			jmespathExt.compile(expression);
-		} catch (error) {
-			throw new Error(`Invalid JMESPath syntax: ${error instanceof Error ? error.message : String(error)}`);
-		}
+		if (expression.length > MAX_EXPRESSION_LENGTH) throw new Error(`JMESPath expression too long (max ${MAX_EXPRESSION_LENGTH} characters)`);
+		for (const pattern of DANGEROUS_PATTERNS) if (pattern.test(expression)) throw new Error(`JMESPath expression contains dangerous pattern: ${pattern.source}`);
+		const result = validateJMESPathSecure(expression, {
+			maxLength: MAX_EXPRESSION_LENGTH + 1,
+			dangerousPatterns: []
+		});
+		if (!result.valid) throw new Error(`Invalid JMESPath syntax: ${result.error}`);
 		logger.debug("JMESPath expression validated", `${expression.substring(0, 100)}...`);
 	}
 	/**
@@ -38,7 +29,7 @@ var JsonTransformer = class JsonTransformer {
 				reject(/* @__PURE__ */ new Error(`JMESPath transformation timed out after ${timeoutMs}ms`));
 			}, timeoutMs);
 			try {
-				const result = jmespath$1.search(input, expression);
+				const result = jmespath.search(input, expression);
 				clearTimeout(timeout);
 				resolve(result);
 			} catch (error) {
@@ -52,7 +43,7 @@ var JsonTransformer = class JsonTransformer {
 	*/
 	static async transform(input, jmesPathExpression, options = {}) {
 		const { timeout = JsonTransformer.DEFAULT_TIMEOUT, allowedFunctions } = options;
-		JsonTransformer.validateJMESPath(jmesPathExpression, allowedFunctions);
+		JsonTransformer.validateExpression(jmesPathExpression, allowedFunctions);
 		try {
 			logger.debug("Executing JMESPath transformation", `inputType: ${typeof input}, expression: ${jmesPathExpression.substring(0, 100)}..., timeout: ${timeout}`);
 			const result = await JsonTransformer.executeWithTimeout(input, jmesPathExpression, timeout);
@@ -74,7 +65,7 @@ var JsonTransformer = class JsonTransformer {
 			if (!key || typeof key !== "string") throw new Error("Object transformation keys must be non-empty strings");
 			if (!path || typeof path !== "string") throw new Error("Object transformation values must be non-empty strings");
 			try {
-				jmespathExt.compile(path);
+				compileJMESPath(path);
 			} catch (error) {
 				throw new Error(`Invalid JMESPath in object transformation value "${path}": ${error instanceof Error ? error.message : String(error)}`);
 			}
@@ -101,7 +92,7 @@ var JsonTransformer = class JsonTransformer {
 	static transformSync(input, jmesPathExpression) {
 		logger.warn("Using deprecated synchronous transform method - security validation bypassed", "");
 		try {
-			return jmespath$1.search(input, jmesPathExpression);
+			return jmespath.search(input, jmesPathExpression);
 		} catch (error) {
 			throw new Error(`JMESPath transformation failed: ${error instanceof Error ? error.message : String(error)}`);
 		}

package/dist/utils/index.d.ts

@@ -16,9 +16,9 @@ import { convertZodToJsonSchema, convertZodToJsonSchemaWithPreview, extractPrevi
 import { GenerateServiceTokenParams, ServiceTokenPayload, VerifyServiceTokenResult, generateServiceToken, validateTargetAgent, validateTenantId, verifyAuthorizationHeader, verifyServiceToken } from "./service-token-auth.js";
 import { SignedTempToken, TempTokenPayload, signTempToken, verifyTempToken } from "./temp-jwt.js";
 import { interpolateTemplate } from "./template-interpolation.js";
-import { CredentialScope, extractComposioServerId, fetchComposioServers, fetchSingleComposioServer, getComposioOAuthRedirectUrl, getComposioUserId, isComposioMCPServerAuthenticated } from "./third-party-mcp-servers/composio-client.js";
+import { CredentialScope, buildComposioMCPUrl, extractComposioServerId, fetchComposioServers, fetchSingleComposioServer, getComposioOAuthRedirectUrl, getComposioUserId, isComposioMCPServerAuthenticated } from "./third-party-mcp-servers/composio-client.js";
 import { isThirdPartyMCPServerAuthenticated } from "./third-party-mcp-servers/third-party-check.js";
 import "./third-party-mcp-servers/index.js";
 import { getTracer, setSpanWithError } from "./tracer-factory.js";
-import { HashedHeaderValue, TriggerAuthResult, hashAuthenticationHeaders, hashTriggerHeaderValue, validateTriggerHeaderValue, verifySigningSecret, verifyTriggerAuth } from "./trigger-auth.js";
-export { ApiKeyGenerationResult, CommonCreateErrorResponses, CommonDeleteErrorResponses, CommonGetErrorResponses, CommonUpdateErrorResponses, CredentialScope, ERROR_DOCS_BASE_URL, ErrorCode, ErrorCodes, ErrorResponse, GenerateInternalServiceTokenParams, GenerateServiceTokenParams, HashedHeaderValue, InternalServiceId, InternalServiceTokenPayload, InternalServices, JsonTransformer, JwtVerifyResult, LLMMessage, LoggerFactoryConfig, McpClient, McpClientOptions, McpOAuthFlowResult, McpSSEConfig, McpServerConfig, McpStreamableHttpConfig, McpTokenExchangeResult, ModelFactory, OAuthConfig, PinoLogger, PinoLoggerConfig, ProblemDetails, ServiceTokenPayload, SignJwtOptions, SignedTempToken, TempTokenPayload, TriggerAuthResult, VerifyInternalServiceTokenResult, VerifyJwtOptions, VerifyServiceTokenResult, commonCreateErrorResponses, commonDeleteErrorResponses, commonGetErrorResponses, commonUpdateErrorResponses, convertZodToJsonSchema, convertZodToJsonSchemaWithPreview, createApiError, decodeJwtPayload, detectAuthenticationRequired, errorResponseSchema, errorSchemaFactory, exchangeMcpAuthorizationCode, extractBearerToken, extractComposioServerId, extractPreviewFields, extractPublicId, fetchComposioServers, fetchSingleComposioServer, formatMessagesForLLM, formatMessagesForLLMContext, generateApiKey, generateId, generateInternalServiceToken, generateServiceToken, getComposioOAuthRedirectUrl, getComposioUserId, getConversationId, getCredentialStoreLookupKeyFromRetrievalParams, getJwtSecret, getLogger, getMetadataFromApiKey, getTracer, handleApiError, hasIssuer, hashApiKey, hashAuthenticationHeaders, hashTriggerHeaderValue, initiateMcpOAuthFlow, interpolateTemplate, isApiKeyExpired, isComposioMCPServerAuthenticated, isInternalServiceToken, isThirdPartyMCPServerAuthenticated, isZodSchema, jsonSchemaToZod, loggerFactory, maskApiKey, normalizeDateString, parseEmbeddedJson, preview, problemDetailsSchema, setSpanWithError, signJwt, signTempToken, toISODateString, validateApiKey, validateInternalServiceProjectAccess, validateInternalServiceTenantAccess, validateTargetAgent, validateTenantId, validateTriggerHeaderValue, verifyAuthorizationHeader, verifyInternalServiceAuthHeader, verifyInternalServiceToken, verifyJwt, verifyServiceToken, verifySigningSecret, verifyTempToken, verifyTriggerAuth };
+import { HashedHeaderValue, SignatureVerificationErrorCode, SignatureVerificationResult, TriggerAuthResult, hashAuthenticationHeaders, hashTriggerHeaderValue, validateTriggerHeaderValue, verifySignatureWithConfig, verifyTriggerAuth } from "./trigger-auth.js";
+export { ApiKeyGenerationResult, CommonCreateErrorResponses, CommonDeleteErrorResponses, CommonGetErrorResponses, CommonUpdateErrorResponses, CredentialScope, ERROR_DOCS_BASE_URL, ErrorCode, ErrorCodes, ErrorResponse, GenerateInternalServiceTokenParams, GenerateServiceTokenParams, HashedHeaderValue, InternalServiceId, InternalServiceTokenPayload, InternalServices, JsonTransformer, JwtVerifyResult, LLMMessage, LoggerFactoryConfig, McpClient, McpClientOptions, McpOAuthFlowResult, McpSSEConfig, McpServerConfig, McpStreamableHttpConfig, McpTokenExchangeResult, ModelFactory, OAuthConfig, PinoLogger, PinoLoggerConfig, ProblemDetails, ServiceTokenPayload, SignJwtOptions, SignatureVerificationErrorCode, SignatureVerificationResult, SignedTempToken, TempTokenPayload, TriggerAuthResult, VerifyInternalServiceTokenResult, VerifyJwtOptions, VerifyServiceTokenResult, buildComposioMCPUrl, commonCreateErrorResponses, commonDeleteErrorResponses, commonGetErrorResponses, commonUpdateErrorResponses, convertZodToJsonSchema, convertZodToJsonSchemaWithPreview, createApiError, decodeJwtPayload, detectAuthenticationRequired, errorResponseSchema, errorSchemaFactory, exchangeMcpAuthorizationCode, extractBearerToken, extractComposioServerId, extractPreviewFields, extractPublicId, fetchComposioServers, fetchSingleComposioServer, formatMessagesForLLM, formatMessagesForLLMContext, generateApiKey, generateId, generateInternalServiceToken, generateServiceToken, getComposioOAuthRedirectUrl, getComposioUserId, getConversationId, getCredentialStoreLookupKeyFromRetrievalParams, getJwtSecret, getLogger, getMetadataFromApiKey, getTracer, handleApiError, hasIssuer, hashApiKey, hashAuthenticationHeaders, hashTriggerHeaderValue, initiateMcpOAuthFlow, interpolateTemplate, isApiKeyExpired, isComposioMCPServerAuthenticated, isInternalServiceToken, isThirdPartyMCPServerAuthenticated, isZodSchema, jsonSchemaToZod, loggerFactory, maskApiKey, normalizeDateString, parseEmbeddedJson, preview, problemDetailsSchema, setSpanWithError, signJwt, signTempToken, toISODateString, validateApiKey, validateInternalServiceProjectAccess, validateInternalServiceTenantAccess, validateTargetAgent, validateTenantId, validateTriggerHeaderValue, verifyAuthorizationHeader, verifyInternalServiceAuthHeader, verifyInternalServiceToken, verifyJwt, verifyServiceToken, verifySignatureWithConfig, verifyTempToken, verifyTriggerAuth };

package/dist/utils/index.js

@@ -16,10 +16,10 @@ import { ModelFactory } from "./model-factory.js";
 import { generateServiceToken, validateTargetAgent, validateTenantId, verifyAuthorizationHeader, verifyServiceToken } from "./service-token-auth.js";
 import { signTempToken, verifyTempToken } from "./temp-jwt.js";
 import { interpolateTemplate } from "./template-interpolation.js";
-import { extractComposioServerId, fetchComposioServers, fetchSingleComposioServer, getComposioOAuthRedirectUrl, getComposioUserId, isComposioMCPServerAuthenticated } from "./third-party-mcp-servers/composio-client.js";
+import { buildComposioMCPUrl, extractComposioServerId, fetchComposioServers, fetchSingleComposioServer, getComposioOAuthRedirectUrl, getComposioUserId, isComposioMCPServerAuthenticated } from "./third-party-mcp-servers/composio-client.js";
 import { isThirdPartyMCPServerAuthenticated } from "./third-party-mcp-servers/third-party-check.js";
 import "./third-party-mcp-servers/index.js";
 import { getTracer, setSpanWithError } from "./tracer-factory.js";
-import { hashAuthenticationHeaders, hashTriggerHeaderValue, validateTriggerHeaderValue, verifySigningSecret, verifyTriggerAuth } from "./trigger-auth.js";
+import { hashAuthenticationHeaders, hashTriggerHeaderValue, validateTriggerHeaderValue, verifySignatureWithConfig, verifyTriggerAuth } from "./trigger-auth.js";
 
-export { ERROR_DOCS_BASE_URL, ErrorCode, InternalServices, JsonTransformer, McpClient, ModelFactory, PinoLogger, commonCreateErrorResponses, commonDeleteErrorResponses, commonGetErrorResponses, commonUpdateErrorResponses, convertZodToJsonSchema, convertZodToJsonSchemaWithPreview, createApiError, decodeJwtPayload, detectAuthenticationRequired, errorResponseSchema, errorSchemaFactory, exchangeMcpAuthorizationCode, extractBearerToken, extractComposioServerId, extractPreviewFields, extractPublicId, fetchComposioServers, fetchSingleComposioServer, formatMessagesForLLM, formatMessagesForLLMContext, generateApiKey, generateId, generateInternalServiceToken, generateServiceToken, getComposioOAuthRedirectUrl, getComposioUserId, getConversationId, getCredentialStoreLookupKeyFromRetrievalParams, getJwtSecret, getLogger, getMetadataFromApiKey, getTracer, handleApiError, hasIssuer, hashApiKey, hashAuthenticationHeaders, hashTriggerHeaderValue, initiateMcpOAuthFlow, interpolateTemplate, isApiKeyExpired, isComposioMCPServerAuthenticated, isInternalServiceToken, isThirdPartyMCPServerAuthenticated, isZodSchema, jsonSchemaToZod, loggerFactory, maskApiKey, normalizeDateString, parseEmbeddedJson, preview, problemDetailsSchema, setSpanWithError, signJwt, signTempToken, toISODateString, validateApiKey, validateInternalServiceProjectAccess, validateInternalServiceTenantAccess, validateTargetAgent, validateTenantId, validateTriggerHeaderValue, verifyAuthorizationHeader, verifyInternalServiceAuthHeader, verifyInternalServiceToken, verifyJwt, verifyServiceToken, verifySigningSecret, verifyTempToken, verifyTriggerAuth };
+export { ERROR_DOCS_BASE_URL, ErrorCode, InternalServices, JsonTransformer, McpClient, ModelFactory, PinoLogger, buildComposioMCPUrl, commonCreateErrorResponses, commonDeleteErrorResponses, commonGetErrorResponses, commonUpdateErrorResponses, convertZodToJsonSchema, convertZodToJsonSchemaWithPreview, createApiError, decodeJwtPayload, detectAuthenticationRequired, errorResponseSchema, errorSchemaFactory, exchangeMcpAuthorizationCode, extractBearerToken, extractComposioServerId, extractPreviewFields, extractPublicId, fetchComposioServers, fetchSingleComposioServer, formatMessagesForLLM, formatMessagesForLLMContext, generateApiKey, generateId, generateInternalServiceToken, generateServiceToken, getComposioOAuthRedirectUrl, getComposioUserId, getConversationId, getCredentialStoreLookupKeyFromRetrievalParams, getJwtSecret, getLogger, getMetadataFromApiKey, getTracer, handleApiError, hasIssuer, hashApiKey, hashAuthenticationHeaders, hashTriggerHeaderValue, initiateMcpOAuthFlow, interpolateTemplate, isApiKeyExpired, isComposioMCPServerAuthenticated, isInternalServiceToken, isThirdPartyMCPServerAuthenticated, isZodSchema, jsonSchemaToZod, loggerFactory, maskApiKey, normalizeDateString, parseEmbeddedJson, preview, problemDetailsSchema, setSpanWithError, signJwt, signTempToken, toISODateString, validateApiKey, validateInternalServiceProjectAccess, validateInternalServiceTenantAccess, validateTargetAgent, validateTenantId, validateTriggerHeaderValue, verifyAuthorizationHeader, verifyInternalServiceAuthHeader, verifyInternalServiceToken, verifyJwt, verifyServiceToken, verifySignatureWithConfig, verifyTempToken, verifyTriggerAuth };

package/dist/utils/jmespath-utils.d.ts

@@ -0,0 +1,152 @@
+import { z } from "@hono/zod-openapi";
+
+//#region src/utils/jmespath-utils.d.ts
+
+/**
+ * Result of validating a JMESPath expression or regex pattern.
+ */
+interface ValidationResult {
+  valid: boolean;
+  error?: string;
+}
+/**
+ * Maximum allowed length for JMESPath expressions.
+ */
+declare const MAX_EXPRESSION_LENGTH = 1000;
+/**
+ * Validates a JMESPath expression by attempting to compile it.
+ * Uses the jmespath package which is already available in the codebase.
+ *
+ * @param expression - The JMESPath expression to validate
+ * @returns ValidationResult with valid flag and optional error message
+ *
+ * @example
+ * ```typescript
+ * const result = validateJMESPath('body.user.id');
+ * if (!result.valid) {
+ *   console.error(result.error);
+ * }
+ * ```
+ */
+declare function validateJMESPath(expression: string): ValidationResult;
+/**
+ * Validates a regex pattern by attempting to construct a RegExp object.
+ * Returns clear error messages for common regex issues.
+ *
+ * @param pattern - The regex pattern to validate (without delimiters)
+ * @returns ValidationResult with valid flag and optional error message
+ *
+ * @example
+ * ```typescript
+ * const result = validateRegex('v\\d+,(.+)');
+ * if (!result.valid) {
+ *   console.error(result.error);
+ * }
+ * ```
+ */
+declare function validateRegex(pattern: string): ValidationResult;
+/**
+ * Compiles a JMESPath expression.
+ * Wrapper around jmespath.compile() with proper typing.
+ *
+ * @param expression - The JMESPath expression to compile
+ * @returns The compiled expression object
+ * @throws Error if the expression is invalid
+ */
+declare function compileJMESPath(expression: string): unknown;
+/**
+ * Safely searches data using a JMESPath expression.
+ * Wrapper around jmespath.search() with proper typing.
+ *
+ * @param data - The object to search (e.g., template context, webhook body, tool result)
+ * @param expression - The JMESPath expression
+ * @returns The search result
+ *
+ * @example
+ * ```typescript
+ * const data = { users: [{ name: 'Alice' }] };
+ * const name = searchJMESPath<string>(data, 'users[0].name');
+ * // name is 'Alice'
+ *
+ * // Common use cases:
+ * // - Template contexts: { headers: {...}, body: {...} }
+ * // - Webhook payloads: { event: "...", data: {...} }
+ * // - Tool results: { status: "success", result: {...} }
+ * ```
+ */
+declare function searchJMESPath<T = unknown>(data: Record<string, unknown>, expression: string): T;
+/**
+ * Normalize a JMESPath expression by wrapping property names with dashes in quotes.
+ * JMESPath requires identifiers with special characters (like dashes) to be quoted.
+ *
+ * @param path - The JMESPath expression to normalize
+ * @returns The normalized JMESPath expression
+ *
+ * @example
+ * ```typescript
+ * normalizeJMESPath('headers.x-tenant-id');
+ * // Returns: 'headers."x-tenant-id"'
+ *
+ * normalizeJMESPath('api-responses[0].response-code');
+ * // Returns: '"api-responses"[0]."response-code"'
+ *
+ * normalizeJMESPath('simple.path');
+ * // Returns: 'simple.path' (unchanged)
+ * ```
+ */
+declare function normalizeJMESPath(path: string): string;
+/**
+ * Dangerous patterns that should not appear in JMESPath expressions.
+ * These patterns are checked during secure validation to prevent injection attacks.
+ */
+declare const DANGEROUS_PATTERNS: RegExp[];
+/**
+ * Options for secure JMESPath validation.
+ */
+interface SecurityOptions {
+  maxLength?: number;
+  dangerousPatterns?: RegExp[];
+}
+/**
+ * Validates a JMESPath expression with security checks.
+ * Performs checks in order of cost: length (O(1)), patterns (O(n)), compile (expensive).
+ *
+ * @param expression - The JMESPath expression to validate
+ * @param options - Optional security options
+ * @returns ValidationResult with valid flag and optional error message
+ *
+ * @example
+ * ```typescript
+ * const result = validateJMESPathSecure('body.user.id');
+ * if (!result.valid) {
+ *   console.error(result.error);
+ * }
+ *
+ * // With custom options
+ * const result2 = validateJMESPathSecure('expression', { maxLength: 500 });
+ * ```
+ */
+declare function validateJMESPathSecure(expression: string, options?: SecurityOptions): ValidationResult;
+/**
+ * Options for jmespathString Zod schema factory.
+ */
+interface JMESPathStringOptions {
+  maxLength?: number;
+}
+/**
+ * Creates a Zod string schema for JMESPath expressions with OpenAPI-visible constraints.
+ * Includes maxLength constraint and a description with valid/invalid examples.
+ *
+ * @param options - Optional configuration for the schema
+ * @returns A Zod string schema with maxLength and description
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({
+ *   transform: jmespathString().optional(),
+ * });
+ * ```
+ */
+declare function jmespathString(options?: JMESPathStringOptions): z.ZodString;
+//#endregion
+export { DANGEROUS_PATTERNS, JMESPathStringOptions, MAX_EXPRESSION_LENGTH, SecurityOptions, ValidationResult, compileJMESPath, jmespathString, normalizeJMESPath, searchJMESPath, validateJMESPath, validateJMESPathSecure, validateRegex };

package/dist/utils/jmespath-utils.js

@@ -0,0 +1,213 @@
+import { z } from "@hono/zod-openapi";
+import * as jmespath from "jmespath";
+
+//#region src/utils/jmespath-utils.ts
+const jmespathExt = jmespath;
+/**
+* Maximum allowed length for JMESPath expressions.
+*/
+const MAX_EXPRESSION_LENGTH = 1e3;
+/**
+* Validates a JMESPath expression by attempting to compile it.
+* Uses the jmespath package which is already available in the codebase.
+*
+* @param expression - The JMESPath expression to validate
+* @returns ValidationResult with valid flag and optional error message
+*
+* @example
+* ```typescript
+* const result = validateJMESPath('body.user.id');
+* if (!result.valid) {
+*   console.error(result.error);
+* }
+* ```
+*/
+function validateJMESPath(expression) {
+	if (!expression || typeof expression !== "string") return {
+		valid: false,
+		error: "JMESPath expression must be a non-empty string"
+	};
+	try {
+		jmespathExt.compile(expression);
+		return { valid: true };
+	} catch (error) {
+		return {
+			valid: false,
+			error: `Invalid JMESPath expression: ${error instanceof Error ? error.message : String(error)}`
+		};
+	}
+}
+/**
+* Validates a regex pattern by attempting to construct a RegExp object.
+* Returns clear error messages for common regex issues.
+*
+* @param pattern - The regex pattern to validate (without delimiters)
+* @returns ValidationResult with valid flag and optional error message
+*
+* @example
+* ```typescript
+* const result = validateRegex('v\\d+,(.+)');
+* if (!result.valid) {
+*   console.error(result.error);
+* }
+* ```
+*/
+function validateRegex(pattern) {
+	if (pattern === null || pattern === void 0) return {
+		valid: false,
+		error: "Regex pattern must be provided"
+	};
+	if (typeof pattern !== "string") return {
+		valid: false,
+		error: "Regex pattern must be a string"
+	};
+	if (pattern === "") return { valid: true };
+	try {
+		new RegExp(pattern);
+		return { valid: true };
+	} catch (error) {
+		return {
+			valid: false,
+			error: `Invalid regex pattern: ${error instanceof Error ? error.message : String(error)}`
+		};
+	}
+}
+/**
+* Compiles a JMESPath expression.
+* Wrapper around jmespath.compile() with proper typing.
+*
+* @param expression - The JMESPath expression to compile
+* @returns The compiled expression object
+* @throws Error if the expression is invalid
+*/
+function compileJMESPath(expression) {
+	return jmespathExt.compile(expression);
+}
+/**
+* Safely searches data using a JMESPath expression.
+* Wrapper around jmespath.search() with proper typing.
+*
+* @param data - The object to search (e.g., template context, webhook body, tool result)
+* @param expression - The JMESPath expression
+* @returns The search result
+*
+* @example
+* ```typescript
+* const data = { users: [{ name: 'Alice' }] };
+* const name = searchJMESPath<string>(data, 'users[0].name');
+* // name is 'Alice'
+*
+* // Common use cases:
+* // - Template contexts: { headers: {...}, body: {...} }
+* // - Webhook payloads: { event: "...", data: {...} }
+* // - Tool results: { status: "success", result: {...} }
+* ```
+*/
+function searchJMESPath(data, expression) {
+	return jmespath.search(data, expression);
+}
+/**
+* Normalize a JMESPath expression by wrapping property names with dashes in quotes.
+* JMESPath requires identifiers with special characters (like dashes) to be quoted.
+*
+* @param path - The JMESPath expression to normalize
+* @returns The normalized JMESPath expression
+*
+* @example
+* ```typescript
+* normalizeJMESPath('headers.x-tenant-id');
+* // Returns: 'headers."x-tenant-id"'
+*
+* normalizeJMESPath('api-responses[0].response-code');
+* // Returns: '"api-responses"[0]."response-code"'
+*
+* normalizeJMESPath('simple.path');
+* // Returns: 'simple.path' (unchanged)
+* ```
+*/
+function normalizeJMESPath(path) {
+	return path.split(".").map((segment) => {
+		if (!segment.includes("-")) return segment;
+		if (segment.startsWith("\"") && segment.includes("\"")) return segment;
+		const bracketIndex = segment.indexOf("[");
+		if (bracketIndex !== -1) return `"${segment.substring(0, bracketIndex)}"${segment.substring(bracketIndex)}`;
+		return `"${segment}"`;
+	}).join(".");
+}
+/**
+* Dangerous patterns that should not appear in JMESPath expressions.
+* These patterns are checked during secure validation to prevent injection attacks.
+*/
+const DANGEROUS_PATTERNS = [
+	/\$\{.*\}/,
+	/eval\s*\(/,
+	/function\s*\(/,
+	/constructor/,
+	/prototype/,
+	/__proto__/
+];
+/**
+* Validates a JMESPath expression with security checks.
+* Performs checks in order of cost: length (O(1)), patterns (O(n)), compile (expensive).
+*
+* @param expression - The JMESPath expression to validate
+* @param options - Optional security options
+* @returns ValidationResult with valid flag and optional error message
+*
+* @example
+* ```typescript
+* const result = validateJMESPathSecure('body.user.id');
+* if (!result.valid) {
+*   console.error(result.error);
+* }
+*
+* // With custom options
+* const result2 = validateJMESPathSecure('expression', { maxLength: 500 });
+* ```
+*/
+function validateJMESPathSecure(expression, options) {
+	if (!expression || typeof expression !== "string") return {
+		valid: false,
+		error: "JMESPath expression must be a non-empty string"
+	};
+	const maxLength = options?.maxLength ?? MAX_EXPRESSION_LENGTH;
+	const patterns = options?.dangerousPatterns ?? DANGEROUS_PATTERNS;
+	if (expression.length > maxLength) return {
+		valid: false,
+		error: `JMESPath expression exceeds maximum length of ${maxLength} characters`
+	};
+	for (const pattern of patterns) if (pattern.test(expression)) return {
+		valid: false,
+		error: `JMESPath expression contains dangerous pattern: ${pattern.source}`
+	};
+	try {
+		jmespathExt.compile(expression);
+		return { valid: true };
+	} catch (error) {
+		return {
+			valid: false,
+			error: `Invalid JMESPath expression: ${error instanceof Error ? error.message : String(error)}`
+		};
+	}
+}
+/**
+* Creates a Zod string schema for JMESPath expressions with OpenAPI-visible constraints.
+* Includes maxLength constraint and a description with valid/invalid examples.
+*
+* @param options - Optional configuration for the schema
+* @returns A Zod string schema with maxLength and description
+*
+* @example
+* ```typescript
+* const schema = z.object({
+*   transform: jmespathString().optional(),
+* });
+* ```
+*/
+function jmespathString(options) {
+	const maxLen = options?.maxLength ?? MAX_EXPRESSION_LENGTH;
+	return z.string().max(maxLen).describe(`JMESPath expression (max ${maxLen} chars). Valid: "data.items[0].name", "results[?status=='active']", "keys(@)". Invalid: "\${...}" (template injection), "eval" calls, "constructor", "__proto__".`);
+}
+
+//#endregion
+export { DANGEROUS_PATTERNS, MAX_EXPRESSION_LENGTH, compileJMESPath, jmespathString, normalizeJMESPath, searchJMESPath, validateJMESPath, validateJMESPathSecure, validateRegex };

package/dist/utils/mcp-client.d.ts

@@ -1,7 +1,7 @@
 import { MCPTransportType } from "../types/utility.js";
+import { ClientCapabilities } from "@modelcontextprotocol/sdk/types.js";
 import { SSEClientTransportOptions } from "@modelcontextprotocol/sdk/client/sse.js";
 import { StreamableHTTPClientTransportOptions } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import { ClientCapabilities } from "@modelcontextprotocol/sdk/types.js";
 
 //#region src/utils/mcp-client.d.ts
 interface SharedServerConfig {

package/dist/utils/mcp-client.js

@@ -1,11 +1,11 @@
 import { MCPTransportType } from "../types/utility.js";
 import { MCP_TOOL_CONNECTION_TIMEOUT_MS, MCP_TOOL_INITIAL_RECONNECTION_DELAY_MS, MCP_TOOL_MAX_RECONNECTION_DELAY_MS, MCP_TOOL_MAX_RETRIES, MCP_TOOL_RECONNECTION_DELAY_GROWTH_FACTOR } from "../constants/execution-limits-shared/index.js";
 import { z } from "@hono/zod-openapi";
+import { CallToolResultSchema } from "@modelcontextprotocol/sdk/types.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { DEFAULT_REQUEST_TIMEOUT_MSEC } from "@modelcontextprotocol/sdk/shared/protocol.js";
-import { CallToolResultSchema } from "@modelcontextprotocol/sdk/types.js";
 import { tool } from "ai";
 import { asyncExitHook, gracefulExit } from "exit-hook";
 import { match } from "ts-pattern";

package/dist/utils/signature-validation.d.ts

@@ -0,0 +1,2 @@
+import { ValidationResult, validateJMESPath, validateRegex } from "./jmespath-utils.js";
+export { type ValidationResult, validateJMESPath, validateRegex };

package/dist/utils/signature-validation.js

@@ -0,0 +1,3 @@
+import { validateJMESPath, validateRegex } from "./jmespath-utils.js";
+
+export { validateJMESPath, validateRegex };

package/dist/utils/third-party-mcp-servers/composio-client.d.ts

@@ -14,6 +14,18 @@ type CredentialScope = 'project' | 'user';
  * - For user-scoped: uses the actual user ID (per-user credentials)
  */
 declare function getComposioUserId(tenantId: string, projectId: string, credentialScope: CredentialScope, userId?: string): string;
+/**
+ * Build a Composio MCP URL with the appropriate user_id parameter
+ * Consolidates user_id injection logic used across the codebase
+ *
+ * @param baseUrl - The base MCP server URL
+ * @param tenantId - The tenant ID
+ * @param projectId - The project ID
+ * @param credentialScope - Whether credentials are 'project' or 'user' scoped
+ * @param userId - Optional user ID (required for user-scoped credentials)
+ * @returns The URL with user_id parameter set, or original URL if not a Composio URL
+ */
+declare function buildComposioMCPUrl(baseUrl: string, tenantId: string, projectId: string, credentialScope: CredentialScope, userId?: string): string;
 /**
  * Extract server ID from a Composio MCP URL
  * Example: https://backend.composio.dev/v3/mcp/1234-1234-1234?user_id=... -> 1234-1234-1234
@@ -44,4 +56,4 @@ declare function fetchComposioServers(): Promise<PrebuiltMCPServer[]>;
  */
 declare function fetchSingleComposioServer(tenantId: string, projectId: string, mcpServerUrl: string, credentialScope?: CredentialScope, userId?: string): Promise<PrebuiltMCPServer | null>;
 //#endregion
-export { CredentialScope, extractComposioServerId, fetchComposioServers, fetchSingleComposioServer, getComposioOAuthRedirectUrl, getComposioUserId, isComposioMCPServerAuthenticated };
+export { CredentialScope, buildComposioMCPUrl, extractComposioServerId, fetchComposioServers, fetchSingleComposioServer, getComposioOAuthRedirectUrl, getComposioUserId, isComposioMCPServerAuthenticated };

package/dist/utils/third-party-mcp-servers/composio-client.js

@@ -67,6 +67,25 @@ function getComposioUserId(tenantId, projectId, credentialScope, userId) {
 	return deriveComposioUserId(tenantId, projectId);
 }
 /**
+* Build a Composio MCP URL with the appropriate user_id parameter
+* Consolidates user_id injection logic used across the codebase
+*
+* @param baseUrl - The base MCP server URL
+* @param tenantId - The tenant ID
+* @param projectId - The project ID
+* @param credentialScope - Whether credentials are 'project' or 'user' scoped
+* @param userId - Optional user ID (required for user-scoped credentials)
+* @returns The URL with user_id parameter set, or original URL if not a Composio URL
+*/
+function buildComposioMCPUrl(baseUrl, tenantId, projectId, credentialScope, userId) {
+	if (!baseUrl.includes("composio.dev")) return baseUrl;
+	const urlObj = new URL(baseUrl);
+	if (urlObj.searchParams.has("user_id")) return baseUrl;
+	const composioUserId = getComposioUserId(tenantId, projectId, credentialScope, userId);
+	urlObj.searchParams.set("user_id", composioUserId);
+	return urlObj.toString();
+}
+/**
 * Extract server ID from a Composio MCP URL
 * Example: https://backend.composio.dev/v3/mcp/1234-1234-1234?user_id=... -> 1234-1234-1234
 */
@@ -142,12 +161,11 @@ async function isComposioMCPServerAuthenticated(tenantId, projectId, mcpServerUr
 		return false;
 	}
 	try {
-		const composioMcpServer = await composioInstance.mcp.get(serverId);
-		const firstAuthConfigId = composioMcpServer.authConfigIds.length > 0 ? composioMcpServer.authConfigIds[0] : null;
-		if (!firstAuthConfigId) return false;
-		const connectedAccounts = await fetchComposioConnectedAccounts(composioUserId);
+		const [composioMcpServer, connectedAccounts] = await Promise.all([composioInstance.mcp.get(serverId), fetchComposioConnectedAccounts(composioUserId)]);
+		if (!(composioMcpServer.authConfigIds.length > 0 ? composioMcpServer.authConfigIds[0] : null)) return false;
 		if (!connectedAccounts) return false;
-		return !!connectedAccounts.items.find((account) => account.authConfig.id === firstAuthConfigId && account.status === "ACTIVE");
+		const activeAuthConfigIds = new Set(connectedAccounts.items.filter((account) => account.status === "ACTIVE").map((account) => account.authConfig.id));
+		return composioMcpServer.authConfigIds.some((authConfigId) => activeAuthConfigIds.has(authConfigId));
 	} catch (error) {
 		logger$1.error({
 			error,
@@ -316,4 +334,4 @@ async function fetchSingleComposioServer(tenantId, projectId, mcpServerUrl, cred
 }
 
 //#endregion
-export { extractComposioServerId, fetchComposioServers, fetchSingleComposioServer, getComposioOAuthRedirectUrl, getComposioUserId, isComposioMCPServerAuthenticated };
+export { buildComposioMCPUrl, extractComposioServerId, fetchComposioServers, fetchSingleComposioServer, getComposioOAuthRedirectUrl, getComposioUserId, isComposioMCPServerAuthenticated };

package/dist/utils/third-party-mcp-servers/index.d.ts

@@ -1,3 +1,3 @@
-import { CredentialScope, extractComposioServerId, fetchComposioServers, fetchSingleComposioServer, getComposioOAuthRedirectUrl, getComposioUserId, isComposioMCPServerAuthenticated } from "./composio-client.js";
+import { CredentialScope, buildComposioMCPUrl, extractComposioServerId, fetchComposioServers, fetchSingleComposioServer, getComposioOAuthRedirectUrl, getComposioUserId, isComposioMCPServerAuthenticated } from "./composio-client.js";
 import { isThirdPartyMCPServerAuthenticated } from "./third-party-check.js";
-export { CredentialScope, extractComposioServerId, fetchComposioServers, fetchSingleComposioServer, getComposioOAuthRedirectUrl, getComposioUserId, isComposioMCPServerAuthenticated, isThirdPartyMCPServerAuthenticated };
+export { CredentialScope, buildComposioMCPUrl, extractComposioServerId, fetchComposioServers, fetchSingleComposioServer, getComposioOAuthRedirectUrl, getComposioUserId, isComposioMCPServerAuthenticated, isThirdPartyMCPServerAuthenticated };

package/dist/utils/third-party-mcp-servers/index.js

@@ -1,4 +1,4 @@
-import { extractComposioServerId, fetchComposioServers, fetchSingleComposioServer, getComposioOAuthRedirectUrl, getComposioUserId, isComposioMCPServerAuthenticated } from "./composio-client.js";
+import { buildComposioMCPUrl, extractComposioServerId, fetchComposioServers, fetchSingleComposioServer, getComposioOAuthRedirectUrl, getComposioUserId, isComposioMCPServerAuthenticated } from "./composio-client.js";
 import { isThirdPartyMCPServerAuthenticated } from "./third-party-check.js";
 
-export { extractComposioServerId, fetchComposioServers, fetchSingleComposioServer, getComposioOAuthRedirectUrl, getComposioUserId, isComposioMCPServerAuthenticated, isThirdPartyMCPServerAuthenticated };
+export { buildComposioMCPUrl, extractComposioServerId, fetchComposioServers, fetchSingleComposioServer, getComposioOAuthRedirectUrl, getComposioUserId, isComposioMCPServerAuthenticated, isThirdPartyMCPServerAuthenticated };