@mondaydotcomorg/atp-protocol 0.17.14

package/src/types.ts

@@ -0,0 +1,547 @@
+import type { ProvenanceMode, SecurityPolicy } from '@mondaydotcomorg/atp-provenance';
+export { ProvenanceMode, type SecurityPolicy } from '@mondaydotcomorg/atp-provenance';
+
+/**
+ * Callback types that can pause execution
+ */
+export enum CallbackType {
+	LLM = 'llm',
+	APPROVAL = 'approval',
+	EMBEDDING = 'embedding',
+	TOOL = 'tool',
+}
+
+/**
+ * Tool callback operations
+ */
+export enum ToolOperation {
+	CALL = 'call',
+}
+
+export interface AgentToolProtocolRequest {
+	jsonrpc: '2.0';
+	id: string | number;
+	method: string;
+	params: Record<string, unknown>;
+}
+
+export interface AgentToolProtocolResponse {
+	jsonrpc: '2.0';
+	id: string | number;
+	result?: unknown;
+	error?: {
+		code: number;
+		message: string;
+		data?: unknown;
+	};
+}
+
+export interface AgentToolProtocolNotification {
+	jsonrpc: '2.0';
+	method: string;
+	params: Record<string, unknown>;
+}
+
+/**
+ * Client-provided service availability
+ */
+export interface ClientServices {
+	/** Whether client provides LLM implementation */
+	hasLLM: boolean;
+	/** Whether client provides approval handler */
+	hasApproval: boolean;
+	/** Whether client provides embedding model */
+	hasEmbedding: boolean;
+	/** Whether client provides custom tools */
+	hasTools: boolean;
+	/** Names of client-provided tools (for discovery) */
+	toolNames?: string[];
+}
+
+/**
+ * Client-provided LLM handler
+ */
+export interface ClientLLMHandler {
+	call: (
+		prompt: string,
+		options?: {
+			context?: Record<string, unknown>;
+			model?: string;
+			temperature?: number;
+			systemPrompt?: string;
+		}
+	) => Promise<string>;
+	extract?: <T>(
+		prompt: string,
+		schema: Record<string, unknown>,
+		options?: {
+			context?: Record<string, unknown>;
+		}
+	) => Promise<T>;
+	classify?: (
+		text: string,
+		categories: string[],
+		options?: {
+			context?: Record<string, unknown>;
+		}
+	) => Promise<string>;
+}
+
+/**
+ * Client-provided approval handler
+ */
+export interface ClientApprovalHandler {
+	request: (
+		message: string,
+		context?: Record<string, unknown>
+	) => Promise<{
+		approved: boolean;
+		response?: unknown;
+		timestamp: number;
+	}>;
+}
+
+/**
+ * Client-provided embedding handler
+ */
+export interface ClientEmbeddingHandler {
+	embed: (text: string) => Promise<number[]>;
+	similarity?: (text1: string, text2: string) => Promise<number>;
+}
+
+/**
+ * Client-provided tool handler
+ * Function that executes on the client side when a client tool is invoked
+ */
+export interface ClientToolHandler {
+	(input: unknown): Promise<unknown>;
+}
+
+/**
+ * Client tool definition (metadata sent to server)
+ * The actual handler function remains on the client side
+ */
+export interface ClientToolDefinition {
+	/** Tool name (unique per client session) */
+	name: string;
+	/** API namespace (e.g., 'playwright', 'browser'). Defaults to 'client' if not specified */
+	namespace?: string;
+	/** Human-readable description of what the tool does */
+	description: string;
+	/** JSON Schema for tool input validation */
+	inputSchema: JSONSchema;
+	/** JSON Schema for tool output (optional, for documentation) */
+	outputSchema?: JSONSchema;
+	/** Tool metadata for security and risk management */
+	metadata?: ToolMetadata;
+	/** Whether this tool supports parallel execution with other tools */
+	supportsConcurrency?: boolean;
+	/** Keywords for search/discovery (optional) */
+	keywords?: string[];
+}
+
+/**
+ * Client tool with handler (used client-side only)
+ * Extends ClientToolDefinition to include the actual handler function
+ */
+export interface ClientTool extends ClientToolDefinition {
+	/** Handler function that executes on client side */
+	handler: ClientToolHandler;
+}
+
+/**
+ * Tool operation type classification
+ */
+export enum ToolOperationType {
+	/** Safe read-only operations */
+	READ = 'read',
+	/** Operations that modify data */
+	WRITE = 'write',
+	/** Operations that delete or destroy data */
+	DESTRUCTIVE = 'destructive',
+}
+
+/**
+ * Tool sensitivity level
+ */
+export enum ToolSensitivityLevel {
+	/** Public data, no sensitivity concerns */
+	PUBLIC = 'public',
+	/** Internal data, requires authentication */
+	INTERNAL = 'internal',
+	/** Sensitive data (PII, financial data, etc.) */
+	SENSITIVE = 'sensitive',
+}
+
+/**
+ * Client-side tool execution rules
+ * Allows clients to control which tools can be executed and under what conditions
+ */
+export interface ClientToolRules {
+	/** Block all tools of specific operation types */
+	blockOperationTypes?: ToolOperationType[];
+	/** Block all tools with specific sensitivity levels */
+	blockSensitivityLevels?: ToolSensitivityLevel[];
+	/** Require approval for specific operation types */
+	requireApprovalForOperationTypes?: ToolOperationType[];
+	/** Require approval for specific sensitivity levels */
+	requireApprovalForSensitivityLevels?: ToolSensitivityLevel[];
+	/** Block specific tools by name (e.g., ['deleteDatabase', 'dropTable']) */
+	blockTools?: string[];
+	/** Allow only specific tools by name (whitelist mode) */
+	allowOnlyTools?: string[];
+	/** Block entire API groups (e.g., ['admin', 'system']) */
+	blockApiGroups?: string[];
+	/** Allow only specific API groups (whitelist mode) */
+	allowOnlyApiGroups?: string[];
+}
+
+/**
+ * Tool/API metadata for security and risk management
+ *
+ * What can clients do with these annotations?
+ *
+ * 1. **Block Execution**:
+ *    - Block all WRITE operations: blockOperationTypes: [ToolOperationType.WRITE]
+ *    - Block all DESTRUCTIVE operations: blockOperationTypes: [ToolOperationType.DESTRUCTIVE]
+ *    - Block SENSITIVE data access: blockSensitivityLevels: [ToolSensitivityLevel.SENSITIVE]
+ *
+ * 2. **Require Approval**:
+ *    - Require approval for WRITE: requireApprovalForOperationTypes: [ToolOperationType.WRITE]
+ *    - Require approval for DESTRUCTIVE: requireApprovalForOperationTypes: [ToolOperationType.DESTRUCTIVE]
+ *    - Require approval for SENSITIVE: requireApprovalForSensitivityLevels: [ToolSensitivityLevel.SENSITIVE]
+ *
+ * 3. **Whitelist/Blacklist**:
+ *    - Block specific tools: blockTools: ['deleteDatabase', 'dropTable']
+ *    - Allow only safe tools: allowOnlyTools: ['getUser', 'listItems']
+ *    - Block admin APIs: blockApiGroups: ['admin', 'system']
+ *
+ * 4. **Audit & Logging**:
+ *    - Log all DESTRUCTIVE operations
+ *    - Track access to SENSITIVE data
+ *    - Monitor WRITE operations
+ *
+ * Granularity levels:
+ * - Operation Type: READ, WRITE, DESTRUCTIVE (coarse-grained)
+ * - Sensitivity Level: PUBLIC, INTERNAL, SENSITIVE (data classification)
+ * - Tool Name: Specific function names (fine-grained)
+ * - API Group: Entire namespaces (medium-grained)
+ */
+export interface ToolMetadata {
+	/** Operation type classification */
+	operationType?: ToolOperationType;
+	/** Sensitivity level of data handled */
+	sensitivityLevel?: ToolSensitivityLevel;
+	/** Require explicit approval before execution (server-side enforcement) */
+	requiresApproval?: boolean;
+	/** Category for grouping/filtering (e.g., 'database', 'user-management') */
+	category?: string;
+	/** Additional tags for classification */
+	tags?: string[];
+	/** Human-readable description of potential impact */
+	impactDescription?: string;
+	/**
+	 * Required OAuth scopes to use this tool
+	 * Used for scope-based filtering when user credentials have limited permissions
+	 * @example ['repo', 'read:user'] for GitHub
+	 * @example ['https://www.googleapis.com/auth/calendar'] for Google
+	 */
+	requiredScopes?: string[];
+	/**
+	 * Generic permissions required (for non-OAuth providers)
+	 * @example ['admin', 'write:users']
+	 */
+	requiredPermissions?: string[];
+}
+
+/**
+ * Client service providers
+ */
+export interface ClientServiceProviders {
+	llm?: ClientLLMHandler;
+	approval?: ClientApprovalHandler;
+	embedding?: ClientEmbeddingHandler;
+	/** Client-provided tools that execute locally */
+	tools?: ClientTool[];
+}
+
+export interface ExecutionConfig {
+	timeout: number;
+	maxMemory: number;
+	maxLLMCalls: number;
+	allowedAPIs: string[];
+	allowLLMCalls: boolean;
+	progressCallback?: (message: string, fraction: number) => void;
+	customLLMHandler?: (prompt: string, options?: any) => Promise<string>;
+	clientServices?: ClientServices;
+	provenanceMode?: ProvenanceMode;
+	securityPolicies?: SecurityPolicy[];
+	provenanceHints?: string[];
+}
+
+/**
+ * Execution status codes for fine-grained error reporting
+ */
+export enum ExecutionStatus {
+	COMPLETED = 'completed',
+	FAILED = 'failed',
+	TIMEOUT = 'timeout',
+	CANCELLED = 'cancelled',
+	PAUSED = 'paused',
+	MEMORY_EXCEEDED = 'memory_exceeded',
+	LLM_CALLS_EXCEEDED = 'llm_calls_exceeded',
+	SECURITY_VIOLATION = 'security_violation',
+	VALIDATION_FAILED = 'validation_failed',
+	LOOP_DETECTED = 'loop_detected',
+	RATE_LIMITED = 'rate_limited',
+	NETWORK_ERROR = 'network_error',
+	PARSE_ERROR = 'parse_error',
+}
+
+/**
+ * Execution error codes for categorizing failures
+ */
+export enum ExecutionErrorCode {
+	UNKNOWN_ERROR = 'UNKNOWN_ERROR',
+	EXECUTION_FAILED = 'EXECUTION_FAILED',
+	TIMEOUT_ERROR = 'TIMEOUT_ERROR',
+
+	MEMORY_LIMIT_EXCEEDED = 'MEMORY_LIMIT_EXCEEDED',
+	LLM_CALL_LIMIT_EXCEEDED = 'LLM_CALL_LIMIT_EXCEEDED',
+	HTTP_CALL_LIMIT_EXCEEDED = 'HTTP_CALL_LIMIT_EXCEEDED',
+
+	SECURITY_VIOLATION = 'SECURITY_VIOLATION',
+	VALIDATION_FAILED = 'VALIDATION_FAILED',
+	FORBIDDEN_OPERATION = 'FORBIDDEN_OPERATION',
+
+	PARSE_ERROR = 'PARSE_ERROR',
+	SYNTAX_ERROR = 'SYNTAX_ERROR',
+	TYPE_ERROR = 'TYPE_ERROR',
+	REFERENCE_ERROR = 'REFERENCE_ERROR',
+
+	INFINITE_LOOP_DETECTED = 'INFINITE_LOOP_DETECTED',
+	LOOP_TIMEOUT = 'LOOP_TIMEOUT',
+
+	NETWORK_ERROR = 'NETWORK_ERROR',
+	HTTP_ERROR = 'HTTP_ERROR',
+	DNS_ERROR = 'DNS_ERROR',
+
+	RATE_LIMIT_EXCEEDED = 'RATE_LIMIT_EXCEEDED',
+	CONCURRENT_LIMIT_EXCEEDED = 'CONCURRENT_LIMIT_EXCEEDED',
+}
+
+export interface ExecutionResult {
+	executionId: string;
+	status: ExecutionStatus;
+	result?: unknown;
+	error?: {
+		message: string;
+		code?: ExecutionErrorCode;
+		stack?: string;
+		line?: number;
+		context?: Record<string, unknown>;
+		retryable?: boolean;
+		suggestion?: string;
+	};
+	stats: {
+		duration: number;
+		memoryUsed: number;
+		llmCallsCount: number;
+		approvalCallsCount: number;
+		statementsExecuted?: number;
+		statementsCached?: number;
+	};
+	needsCallback?: {
+		type: CallbackType;
+		operation: string;
+		payload: Record<string, unknown>;
+	};
+	needsCallbacks?: BatchCallbackRequest[];
+	callbackHistory?: Array<{
+		type: CallbackType;
+		operation: string;
+		payload: Record<string, unknown>;
+		result?: unknown;
+		timestamp: number;
+		sequenceNumber: number;
+	}>;
+	transformedCode?: string;
+	provenanceSnapshot?: unknown;
+	provenanceTokens?: Array<{
+		path: string;
+		token: string;
+	}>;
+}
+
+/**
+ * Batch callback request for parallel execution
+ */
+export interface BatchCallbackRequest {
+	/** Unique callback ID */
+	id: string;
+	/** Callback type */
+	type: CallbackType;
+	/** Operation name */
+	operation: string;
+	/** Operation payload */
+	payload: Record<string, unknown>;
+}
+
+/**
+ * Batch callback result from client
+ */
+export interface BatchCallbackResult {
+	/** Callback ID (matches BatchCallbackRequest.id) */
+	id: string;
+	/** Callback result */
+	result: unknown;
+}
+
+export interface SearchOptions {
+	query: string;
+	apiGroups?: string[];
+	maxResults?: number;
+	useEmbeddings?: boolean;
+	embeddingModel?: string;
+}
+
+export interface SearchResult {
+	apiGroup: string;
+	functionName: string;
+	description: string;
+	signature: string;
+	example?: string;
+	relevanceScore: number;
+}
+
+export interface ExploreRequest {
+	path: string;
+}
+
+export interface ExploreDirectoryResult {
+	type: 'directory';
+	path: string;
+	items: Array<{ name: string; type: 'directory' | 'function' }>;
+}
+
+export interface ExploreFunctionResult {
+	type: 'function';
+	path: string;
+	name: string;
+	description: string;
+	definition: string;
+	group: string;
+}
+
+export type ExploreResult = ExploreDirectoryResult | ExploreFunctionResult;
+
+export interface ValidationResult {
+	valid: boolean;
+	errors?: ValidationError[];
+	warnings?: ValidationError[];
+	securityIssues?: SecurityIssue[];
+}
+
+export interface ValidationError {
+	line: number;
+	message: string;
+	severity: 'error' | 'warning';
+}
+
+export interface SecurityIssue {
+	line: number;
+	issue: string;
+	risk: 'low' | 'medium' | 'high';
+}
+
+export interface APISource {
+	type: 'mcp' | 'openapi' | 'custom';
+	name: string;
+	url?: string;
+	spec?: unknown;
+}
+
+export interface ServerConfig {
+	apiGroups: APIGroupConfig[];
+	security: SecurityConfig;
+	execution: ExecutionLimits;
+	search: SearchConfig;
+	logging: LoggingConfig;
+}
+
+export interface APIGroupConfig {
+	name: string;
+	type: 'mcp' | 'openapi' | 'custom';
+	url?: string;
+	spec?: unknown;
+	functions?: CustomFunctionDef[];
+	/** Authentication configuration for this API group */
+	auth?: import('./auth.js').AuthConfig;
+}
+
+export interface SecurityConfig {
+	allowedOrigins: string[];
+	apiKeyRequired: boolean;
+	rateLimits: {
+		requestsPerMinute: number;
+		executionsPerHour: number;
+	};
+}
+
+export interface ExecutionLimits {
+	defaultTimeout: number;
+	maxTimeout: number;
+	defaultMemoryLimit: number;
+	maxMemoryLimit: number;
+	defaultLLMCallLimit: number;
+	maxLLMCallLimit: number;
+}
+
+export interface SearchConfig {
+	enableEmbeddings: boolean;
+	embeddingProvider?: 'openai' | 'cohere' | 'custom';
+	customSearcher?: (query: string) => Promise<SearchResult[]>;
+}
+
+export interface LoggingConfig {
+	level: 'debug' | 'info' | 'warn' | 'error';
+	destination: 'console' | 'file' | 'remote';
+	auditEnabled: boolean;
+}
+
+export interface CustomFunctionDef {
+	name: string;
+	description: string;
+	inputSchema: JSONSchema;
+	outputSchema?: JSONSchema;
+	handler: (params: unknown) => Promise<unknown>;
+	keywords?: string[];
+	metadata?: ToolMetadata; // NEW: Tool metadata for security
+	requiredScopes?: string[]; // OAuth scopes required to use this function
+	auth?: {
+		source?: 'server' | 'user';
+		oauthProvider?: string;
+	};
+}
+
+export interface JSONSchema {
+	type: string;
+	properties?: Record<string, unknown>;
+	required?: string[];
+	[key: string]: unknown;
+}
+
+export interface ClientConfig {
+	serverUrl: string;
+	apiKey: string;
+	timeout?: number;
+	llmProvider: 'anthropic' | 'openai' | 'custom';
+	llmModel?: string;
+	temperature?: number;
+	defaultExecutionConfig?: Partial<ExecutionConfig>;
+	searchPreferences?: {
+		useEmbeddings?: boolean;
+		embeddingModel?: string;
+		maxResults?: number;
+	};
+}

package/src/validation.ts

@@ -0,0 +1,162 @@
+/**
+ * Input validation utilities for ExecutionConfig and other types
+ */
+
+import { z } from 'zod';
+import type { ExecutionConfig } from './types.js';
+
+/**
+ * Maximum allowed code size (1MB)
+ */
+export const MAX_CODE_SIZE = 1000000;
+
+export class ConfigValidationError extends Error {
+	constructor(
+		message: string,
+		public readonly field: string,
+		public readonly value: unknown
+	) {
+		super(message);
+		this.name = 'ConfigValidationError';
+	}
+}
+
+export class SecurityViolationError extends Error {
+	constructor(
+		message: string,
+		public readonly violations: string[]
+	) {
+		super(message);
+		this.name = 'SecurityViolationError';
+	}
+}
+
+/**
+ * Sanitizes input string by removing control characters and normalizing whitespace
+ */
+export function sanitizeInput(input: string, maxLength = MAX_CODE_SIZE): string {
+	if (typeof input !== 'string') {
+		return '';
+	}
+
+	let sanitized = input.replace(/[\x00-\x08\x0B-\x0C\x0E-\x1F\x7F]/g, '');
+
+	sanitized = sanitized.replace(/[\u200B-\u200D\uFEFF]/g, '');
+
+	sanitized = sanitized.replace(/\n{10,}/g, '\n\n\n');
+
+	if (sanitized.length > maxLength) {
+		sanitized = sanitized.substring(0, maxLength);
+	}
+
+	return sanitized;
+}
+
+/**
+ * Frames user code in a secure execution context to prevent injection attacks
+ * Similar to SQL parameterized queries - treats user code as data within a safe boundary
+ */
+export function frameCodeExecution(userCode: string): string {
+	const cleaned = sanitizeInput(userCode);
+
+	return `
+(async function __user_code_context__() {
+	"use strict";
+	${cleaned}
+})();
+`.trim();
+}
+
+/**
+ * Zod schema for ExecutionConfig validation
+ */
+export const executionConfigSchema = z.object({
+	timeout: z
+		.number({
+			invalid_type_error: 'timeout must be a number',
+		})
+		.positive('timeout must be positive')
+		.max(300000, 'timeout cannot exceed 300000ms (5 minutes)')
+		.optional(),
+
+	maxMemory: z
+		.number({
+			invalid_type_error: 'maxMemory must be a number',
+		})
+		.positive('maxMemory must be positive')
+		.max(512 * 1024 * 1024, 'maxMemory cannot exceed 512MB')
+		.optional(),
+
+	maxLLMCalls: z
+		.number({
+			invalid_type_error: 'maxLLMCalls must be a number',
+		})
+		.nonnegative('maxLLMCalls cannot be negative')
+		.max(1000, 'maxLLMCalls cannot exceed 1000')
+		.optional(),
+
+	allowedAPIs: z
+		.array(
+			z.string().refine((val) => val.trim().length > 0, {
+				message: 'allowedAPIs must contain non-empty strings',
+			})
+		)
+		.optional(),
+
+	allowLLMCalls: z
+		.boolean({
+			invalid_type_error: 'allowLLMCalls must be a boolean',
+		})
+		.optional(),
+
+	progressCallback: z.function().optional(),
+	customLLMHandler: z.function().optional(),
+	clientServices: z.any().optional(),
+	provenanceMode: z.any().optional(),
+	securityPolicies: z.array(z.any()).optional(),
+	provenanceHints: z.array(z.string()).optional(),
+});
+
+/**
+ * Validates ExecutionConfig parameters using Zod
+ */
+export function validateExecutionConfig(config: Partial<ExecutionConfig>): void {
+	try {
+		executionConfigSchema.parse(config);
+	} catch (error) {
+		if (error instanceof z.ZodError) {
+			const errors = error.errors.map((err) => err.message);
+			throw new ConfigValidationError(
+				`Invalid ExecutionConfig: ${errors.join(', ')}`,
+				'ExecutionConfig',
+				config
+			);
+		}
+		throw error;
+	}
+}
+
+/**
+ * Validates client ID format
+ */
+export function validateClientId(clientId: string): void {
+	if (typeof clientId !== 'string') {
+		throw new ConfigValidationError('clientId must be a string', 'clientId', clientId);
+	}
+
+	if (clientId.trim().length === 0) {
+		throw new ConfigValidationError('clientId cannot be empty', 'clientId', clientId);
+	}
+
+	if (clientId.length > 256) {
+		throw new ConfigValidationError('clientId cannot exceed 256 characters', 'clientId', clientId);
+	}
+
+	if (!/^[a-zA-Z0-9_-]+$/.test(clientId)) {
+		throw new ConfigValidationError(
+			'clientId can only contain alphanumeric characters, dashes, and underscores',
+			'clientId',
+			clientId
+		);
+	}
+}