@inkeep/agents-core 0.41.2 → 0.43.0

package/dist/utils/internal-service-auth.js

@@ -0,0 +1,140 @@
+import { getLogger } from "./logger.js";
+import { extractBearerToken, hasIssuer, signJwt, verifyJwt } from "./jwt-helpers.js";
+
+//#region src/utils/internal-service-auth.ts
+const logger = getLogger("internal-service-auth");
+const ISSUER = "inkeep-agents-internal";
+/**
+* Known internal services that can authenticate
+*/
+const InternalServices = {
+	INKEEP_AGENTS_RUN_API: "inkeep-agents-run-api",
+	INKEEP_AGENTS_MANAGE_API: "inkeep-agents-manage-api",
+	INKEEP_AGENTS_EVAL_API: "inkeep-agents-eval-api"
+};
+/**
+* Generate an internal service token for service-to-service authentication
+*/
+async function generateInternalServiceToken(params) {
+	try {
+		const claims = {};
+		if (params.tenantId) claims.tenantId = params.tenantId;
+		if (params.projectId) claims.projectId = params.projectId;
+		if (params.userId) claims.userId = params.userId;
+		const token = await signJwt({
+			issuer: ISSUER,
+			subject: params.serviceId,
+			expiresIn: params.expiresIn || "5m",
+			claims
+		});
+		logger.debug({
+			serviceId: params.serviceId,
+			tenantId: params.tenantId,
+			projectId: params.projectId
+		}, "Generated internal service token");
+		return token;
+	} catch (error) {
+		logger.error({ error }, "Failed to generate internal service token");
+		throw new Error("Failed to generate internal service token");
+	}
+}
+/**
+* Verify and decode an internal service token
+*/
+async function verifyInternalServiceToken(token) {
+	const result = await verifyJwt(token, { issuer: ISSUER });
+	if (!result.valid || !result.payload) {
+		logger.warn({ error: result.error }, "Internal service token verification failed");
+		return {
+			valid: false,
+			error: result.error
+		};
+	}
+	const payload = result.payload;
+	if (typeof payload.sub !== "string") {
+		logger.warn({ payload }, "Invalid internal service token: missing subject");
+		return {
+			valid: false,
+			error: "Invalid token: missing service identifier"
+		};
+	}
+	if (!Object.values(InternalServices).includes(payload.sub)) {
+		logger.warn({ serviceId: payload.sub }, "Unknown service identifier in token");
+		return {
+			valid: false,
+			error: `Unknown service identifier: ${payload.sub}`
+		};
+	}
+	const validPayload = {
+		iss: payload.iss,
+		sub: payload.sub,
+		tenantId: payload.tenantId,
+		projectId: payload.projectId,
+		userId: payload.userId,
+		iat: payload.iat,
+		exp: payload.exp
+	};
+	logger.debug({
+		serviceId: validPayload.sub,
+		tenantId: validPayload.tenantId,
+		projectId: validPayload.projectId,
+		userId: validPayload.userId
+	}, "Successfully verified internal service token");
+	return {
+		valid: true,
+		payload: validPayload
+	};
+}
+/**
+* Extract and verify an internal service token from Authorization header
+*/
+async function verifyInternalServiceAuthHeader(authHeader) {
+	const extracted = extractBearerToken(authHeader);
+	if (!extracted.token) return {
+		valid: false,
+		error: extracted.error
+	};
+	return verifyInternalServiceToken(extracted.token);
+}
+/**
+* Check if a token is an internal service token (vs user/agent token)
+* by checking the issuer claim without full verification
+*/
+function isInternalServiceToken(token) {
+	return hasIssuer(token, ISSUER);
+}
+/**
+* Validate that the token has access to the specified tenant.
+* If token has no tenantId claim, it has access to all tenants (superuser service).
+*/
+function validateInternalServiceTenantAccess(payload, tenantId) {
+	if (!payload.tenantId) return true;
+	if (payload.tenantId !== tenantId) {
+		logger.warn({
+			tokenTenantId: payload.tenantId,
+			requestedTenantId: tenantId,
+			serviceId: payload.sub
+		}, "Internal service token tenant mismatch");
+		return false;
+	}
+	return true;
+}
+/**
+* Validate that the token has access to the specified project.
+* If token has no projectId claim, it has access to all projects in the allowed tenant(s).
+*/
+function validateInternalServiceProjectAccess(payload, projectId) {
+	if (!payload.projectId) return true;
+	if (payload.projectId !== projectId) {
+		logger.warn({
+			tokenProjectId: payload.projectId,
+			requestedProjectId: projectId,
+			serviceId: payload.sub
+		}, "Internal service token project mismatch");
+		return false;
+	}
+	return true;
+}
+
+//#endregion
+export { InternalServices, generateInternalServiceToken, isInternalServiceToken, validateInternalServiceProjectAccess, validateInternalServiceTenantAccess, verifyInternalServiceAuthHeader, verifyInternalServiceToken };

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/jwt-helpers.d.ts

@@ -0,0 +1,56 @@
+//#region src/utils/jwt-helpers.d.ts
+/**
+ * Get the JWT signing secret from environment variables.
+ * Falls back to an insecure default in non-production environments.
+ */
+declare function getJwtSecret(): Uint8Array;
+/**
+ * Common verification result structure
+ */
+interface JwtVerifyResult<T> {
+  valid: boolean;
+  payload?: T;
+  error?: string;
+}
+/**
+ * Options for signing a JWT
+ */
+interface SignJwtOptions {
+  issuer: string;
+  subject: string;
+  audience?: string;
+  expiresIn?: string;
+  claims?: Record<string, unknown>;
+}
+/**
+ * Sign a JWT with the shared secret
+ */
+declare function signJwt(options: SignJwtOptions): Promise<string>;
+/**
+ * Options for verifying a JWT
+ */
+interface VerifyJwtOptions {
+  issuer: string;
+  audience?: string;
+}
+/**
+ * Verify a JWT and return the raw payload
+ */
+declare function verifyJwt(token: string, options: VerifyJwtOptions): Promise<JwtVerifyResult<Record<string, unknown>>>;
+/**
+ * Extract bearer token from Authorization header
+ */
+declare function extractBearerToken(authHeader: string | undefined): {
+  token?: string;
+  error?: string;
+};
+/**
+ * Decode JWT payload without verification (for checking issuer before full verify)
+ */
+declare function decodeJwtPayload(token: string): Record<string, unknown> | null;
+/**
+ * Check if a token has a specific issuer (without full verification)
+ */
+declare function hasIssuer(token: string, issuer: string): boolean;
+//#endregion
+export { JwtVerifyResult, SignJwtOptions, VerifyJwtOptions, decodeJwtPayload, extractBearerToken, getJwtSecret, hasIssuer, signJwt, verifyJwt };

package/dist/utils/jwt-helpers.js

@@ -0,0 +1,90 @@
+import { env } from "../env.js";
+import { getLogger } from "./logger.js";
+import { SignJWT, jwtVerify } from "jose";
+
+//#region src/utils/jwt-helpers.ts
+const logger = getLogger("jwt-helpers");
+const DEV_SECRET = "insecure-dev-secret-change-in-production-min-32-chars";
+/**
+* Get the JWT signing secret from environment variables.
+* Falls back to an insecure default in non-production environments.
+*/
+function getJwtSecret() {
+	const secret = env.INKEEP_AGENTS_JWT_SIGNING_SECRET;
+	if (!secret) {
+		if (env.ENVIRONMENT === "production") throw new Error("INKEEP_AGENTS_JWT_SIGNING_SECRET environment variable is required in production");
+		logger.warn({}, "INKEEP_AGENTS_JWT_SIGNING_SECRET not set, using insecure default. DO NOT USE IN PRODUCTION!");
+		return new TextEncoder().encode(DEV_SECRET);
+	}
+	return new TextEncoder().encode(secret);
+}
+/**
+* Sign a JWT with the shared secret
+*/
+async function signJwt(options) {
+	const secret = getJwtSecret();
+	const builder = new SignJWT(options.claims || {}).setProtectedHeader({
+		alg: "HS256",
+		typ: "JWT"
+	}).setIssuer(options.issuer).setSubject(options.subject).setIssuedAt().setExpirationTime(options.expiresIn || "5m");
+	if (options.audience) builder.setAudience(options.audience);
+	return builder.sign(secret);
+}
+/**
+* Verify a JWT and return the raw payload
+*/
+async function verifyJwt(token, options) {
+	const secret = getJwtSecret();
+	try {
+		const verifyOptions = {
+			issuer: options.issuer,
+			algorithms: ["HS256"]
+		};
+		if (options.audience) verifyOptions.audience = options.audience;
+		const { payload } = await jwtVerify(token, secret, verifyOptions);
+		return {
+			valid: true,
+			payload
+		};
+	} catch (error) {
+		if (error instanceof Error) return {
+			valid: false,
+			error: error.message
+		};
+		return {
+			valid: false,
+			error: "Token verification failed"
+		};
+	}
+}
+/**
+* Extract bearer token from Authorization header
+*/
+function extractBearerToken(authHeader) {
+	if (!authHeader) return { error: "Missing Authorization header" };
+	if (!authHeader.startsWith("Bearer ")) return { error: "Invalid Authorization header format. Expected: Bearer <token>" };
+	const token = authHeader.substring(7);
+	if (!token) return { error: "Empty token in Authorization header" };
+	return { token };
+}
+/**
+* Decode JWT payload without verification (for checking issuer before full verify)
+*/
+function decodeJwtPayload(token) {
+	try {
+		const parts = token.split(".");
+		if (parts.length !== 3) return null;
+		return JSON.parse(Buffer.from(parts[1], "base64url").toString());
+	} catch {
+		return null;
+	}
+}
+/**
+* Check if a token has a specific issuer (without full verification)
+*/
+function hasIssuer(token, issuer) {
+	return decodeJwtPayload(token)?.iss === issuer;
+}
+
+//#endregion
+export { decodeJwtPayload, extractBearerToken, getJwtSecret, hasIssuer, signJwt, verifyJwt };

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";