@mondaydotcomorg/atp-server 0.17.14

package/dist/validator/index.js

@@ -0,0 +1,224 @@
+import { sanitizeInput, MAX_CODE_SIZE } from '@mondaydotcomorg/atp-protocol';
+import * as acorn from 'acorn';
+/**
+ * CodeValidator validates user code before execution using a whitelist approach.
+ * Only explicitly allowed operations and patterns are permitted.
+ */
+export class CodeValidator {
+    allowedGlobalObjects = new Set([
+        'Array',
+        'Object',
+        'String',
+        'Number',
+        'Boolean',
+        'Date',
+        'Math',
+        'JSON',
+        'Promise',
+        'Map',
+        'Set',
+        'WeakMap',
+        'WeakSet',
+        'Error',
+        'TypeError',
+        'RangeError',
+        'console',
+    ]);
+    forbiddenPatterns = [
+        /\beval\s*\(/,
+        /\bnew\s+Function\s*\(/,
+        /\bnew\s+AsyncFunction\s*\(/,
+        /\bnew\s+GeneratorFunction\s*\(/,
+        /\brequire\s*\(/,
+        /\bprocess\b/,
+        /\bglobal\b/,
+        /\bglobalThis\.process\b/,
+        /\bglobalThis\.global\b/,
+        /\b__dirname\b/,
+        /\b__filename\b/,
+        /\bmodule\b/,
+        /\bexports\b/,
+        /\bBuffer\b/,
+        // Constructor chain exploits - CRITICAL security issue
+        /constructor\s*\[\s*['"`]constructor['"`]\s*\]/,
+        /constructor\.constructor/,
+        /\['constructor'\]\s*\[\s*['"`]constructor['"`]\s*\]/,
+        /\["constructor"\]\s*\[\s*['"`]constructor['"`]\s*\]/,
+        /\[`constructor`\]\s*\[\s*['"`]constructor['"`]\s*\]/,
+        // Prototype chain manipulation - sandbox escape vectors
+        /__proto__/,
+        /Object\.getPrototypeOf/,
+        /Object\.setPrototypeOf/,
+        /Reflect\.construct/,
+        /Reflect\.get/,
+        /Reflect\.set/,
+        // Indirect eval patterns
+        /\['eval'\]/,
+        /\["eval"\]/,
+        /\[`eval`\]/,
+        /window\['eval'\]/,
+        /this\['eval'\]/,
+    ];
+    /**
+     * Validates code for security and syntax issues.
+     * @param code - The code to validate
+     * @param config - Execution configuration
+     * @returns Validation result with any errors or security issues
+     */
+    async validate(code, config) {
+        const errors = [];
+        const warnings = [];
+        const securityIssues = [];
+        code = sanitizeInput(code, MAX_CODE_SIZE);
+        for (const pattern of this.forbiddenPatterns) {
+            if (pattern.test(code)) {
+                securityIssues.push({
+                    line: 0,
+                    issue: `Forbidden pattern detected: ${pattern.source}`,
+                    risk: 'high',
+                });
+            }
+        }
+        this.checkGlobalAccess(code, securityIssues);
+        this.validateImports(code, securityIssues);
+        this.validateSyntax(code, errors);
+        const hasHighRiskIssues = securityIssues.some((issue) => issue.risk === 'high');
+        return {
+            valid: errors.length === 0 && !hasHighRiskIssues,
+            errors: errors.length > 0 ? errors : undefined,
+            warnings: warnings.length > 0 ? warnings : undefined,
+            securityIssues: securityIssues.length > 0 ? securityIssues : undefined,
+        };
+    }
+    /**
+     * Validates JavaScript syntax using acorn parser.
+     * @param code - Code to validate
+     * @param errors - Array to append syntax errors to
+     */
+    validateSyntax(code, errors) {
+        try {
+            acorn.parse(code, {
+                ecmaVersion: 2022,
+                sourceType: 'script',
+                allowAwaitOutsideFunction: true,
+                allowReturnOutsideFunction: true,
+            });
+        }
+        catch (scriptError) {
+            try {
+                acorn.parse(code, {
+                    ecmaVersion: 2022,
+                    sourceType: 'module',
+                    allowAwaitOutsideFunction: true,
+                    allowReturnOutsideFunction: false,
+                });
+            }
+            catch (moduleError) {
+                errors.push({
+                    line: moduleError.loc?.line ?? 0,
+                    message: `Syntax error: ${moduleError.message}`,
+                    severity: 'error',
+                });
+            }
+        }
+    }
+    /**
+     * Checks for unauthorized global object access.
+     * @param code - Code to check
+     * @param securityIssues - Array to append issues to
+     */
+    checkGlobalAccess(code, securityIssues) {
+        const globalAccessPattern = /\b([A-Z][a-zA-Z0-9]*)\./g;
+        let match;
+        while ((match = globalAccessPattern.exec(code)) !== null) {
+            const globalName = match[1];
+            if (globalName &&
+                !this.allowedGlobalObjects.has(globalName) &&
+                globalName !== 'atp' &&
+                globalName !== 'api') {
+                securityIssues.push({
+                    line: 0,
+                    issue: `Unauthorized global access: ${globalName}`,
+                    risk: 'medium',
+                });
+            }
+        }
+    }
+    /**
+     * Validates import statements to ensure NO imports are allowed.
+     * ALL imports are blocked for security - use injected sandbox globals instead.
+     * @param code - Code to validate
+     * @param securityIssues - Array to append issues to
+     */
+    validateImports(code, securityIssues) {
+        try {
+            const ast = acorn.parse(code, {
+                ecmaVersion: 2022,
+                sourceType: 'module',
+                allowAwaitOutsideFunction: true,
+                allowReturnOutsideFunction: true,
+            });
+            const walk = (node) => {
+                if (!node || typeof node !== 'object')
+                    return;
+                if (node.type === 'ImportDeclaration') {
+                    const importSource = node.source?.value;
+                    securityIssues.push({
+                        line: node.loc?.start?.line ?? 0,
+                        issue: `All imports are blocked for security. Import attempted: ${importSource}. Use injected sandbox globals (api, atp) instead.`,
+                        risk: 'high',
+                    });
+                }
+                if (node.type === 'ImportExpression') {
+                    securityIssues.push({
+                        line: node.loc?.start?.line ?? 0,
+                        issue: `Dynamic import() is not allowed. All imports are blocked for security.`,
+                        risk: 'high',
+                    });
+                }
+                if (node.type === 'ExportNamedDeclaration' || node.type === 'ExportAllDeclaration') {
+                    if (node.source?.value) {
+                        const exportSource = node.source.value;
+                        securityIssues.push({
+                            line: node.loc?.start?.line ?? 0,
+                            issue: `Re-exports are not allowed. Attempted re-export from: ${exportSource}.`,
+                            risk: 'high',
+                        });
+                    }
+                }
+                for (const key in node) {
+                    if (key === 'loc' || key === 'range' || key === 'start' || key === 'end')
+                        continue;
+                    const child = node[key];
+                    if (Array.isArray(child)) {
+                        child.forEach(walk);
+                    }
+                    else if (child && typeof child === 'object') {
+                        walk(child);
+                    }
+                }
+            };
+            walk(ast);
+        }
+        catch (error) {
+            const importPattern = /^\s*import\s+.*?\s+from\s+['"](.+?)['"]/gm;
+            let match;
+            while ((match = importPattern.exec(code)) !== null) {
+                const importSource = match[1];
+                securityIssues.push({
+                    line: 0,
+                    issue: `All imports are blocked for security. Import detected: ${importSource}.`,
+                    risk: 'high',
+                });
+            }
+            if (/import\s*\(/.test(code)) {
+                securityIssues.push({
+                    line: 0,
+                    issue: `Dynamic import() is not allowed. All imports are blocked for security.`,
+                    risk: 'high',
+                });
+            }
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/validator/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/validator/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,68 @@
+{
+	"name": "@mondaydotcomorg/atp-server",
+	"version": "0.17.14",
+	"description": "Server implementation for Agent Tool Protocol",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist",
+		"src"
+	],
+	"scripts": {
+		"build": "npm run generate:bootstrap && tsc -p tsconfig.json",
+		"generate:bootstrap": "tsx scripts/generate-bootstrap.ts",
+		"dev": "tsc -p tsconfig.json --watch",
+		"clean": "rm -rf dist *.tsbuildinfo",
+		"test": "vitest run",
+		"lint": "tsc --noEmit"
+	},
+	"keywords": [
+		"agent",
+		"protocol",
+		"server",
+		"ai",
+		"llm"
+	],
+	"license": "MIT",
+	"dependencies": {
+		"@babel/generator": "^7.26.0",
+		"@babel/parser": "^7.26.0",
+		"@babel/traverse": "^7.26.0",
+		"@babel/types": "^7.26.0",
+		"@mondaydotcomorg/atp-compiler": "0.17.14",
+		"@mondaydotcomorg/atp-protocol": "0.17.14",
+		"@mondaydotcomorg/atp-provenance": "0.17.14",
+		"@mondaydotcomorg/atp-runtime": "0.17.14",
+		"@opentelemetry/api": "^1.9.0",
+		"@opentelemetry/auto-instrumentations-node": "^0.66.0",
+		"@opentelemetry/core": "^2.2.0",
+		"@opentelemetry/exporter-metrics-otlp-http": "^0.207.0",
+		"@opentelemetry/exporter-trace-otlp-http": "^0.207.0",
+		"@opentelemetry/resources": "^2.2.0",
+		"@opentelemetry/sdk-node": "^0.207.0",
+		"@opentelemetry/semantic-conventions": "^1.37.0",
+		"@types/acorn": "^6.0.4",
+		"isolated-vm": "5.0.4",
+		"js-yaml": "^4.1.0",
+		"jsonwebtoken": "^9.0.2",
+		"nanoid": "^5.1.6",
+		"rate-limiter-flexible": "*"
+	},
+	"devDependencies": {
+		"@types/babel__generator": "^7.6.8",
+		"@types/babel__traverse": "^7.20.5",
+		"@types/escodegen": "^0.0.10",
+		"@types/js-yaml": "^4.0.9",
+		"@types/jsonwebtoken": "^9.0.5",
+		"@types/node": "^20.11.5",
+		"typescript": "^5.3.3",
+		"vitest": "^1.2.1"
+	}
+}

package/src/aggregator/index.ts

@@ -0,0 +1,207 @@
+import type { APIGroupConfig, CustomFunctionDef } from '@mondaydotcomorg/atp-protocol';
+import { generateRuntimeTypes } from '../utils/runtime-types.js';
+
+/**
+ * APIAggregator generates TypeScript type definitions from API configurations.
+ * Converts API group definitions into TypeScript declarations for use in code generation.
+ */
+export class APIAggregator {
+	private apiGroups: APIGroupConfig[];
+
+	/**
+	 * Creates a new APIAggregator instance.
+	 * @param apiGroups - Array of API group configurations
+	 */
+	constructor(apiGroups: APIGroupConfig[]) {
+		this.apiGroups = apiGroups;
+	}
+
+	/**
+	 * Generates TypeScript type definitions for selected API groups.
+	 * @param selectedGroups - Optional array of group names to include
+	 * @returns TypeScript definition string
+	 */
+	async generateTypeScript(selectedGroups?: string[]): Promise<string> {
+		const groups = selectedGroups
+			? this.apiGroups.filter((g) => selectedGroups.includes(g.name))
+			: this.apiGroups;
+
+		let typescript = `// Agent Tool Protocol Runtime SDK v1.0.0\n\n`;
+
+		typescript += this.generateRuntimeTypes();
+
+		for (const group of groups) {
+			typescript += `\n// API Group: ${group.name}\n`;
+			if (group.functions) {
+				for (const func of group.functions) {
+					typescript += this.generateFunctionTypes(func, group.name);
+				}
+			}
+		}
+
+		typescript += this.generateAPINamespace(groups);
+
+		return typescript;
+	}
+
+	/**
+	 * Generates TypeScript definitions for the runtime SDK.
+	 * @returns TypeScript definition string
+	 */
+	private generateRuntimeTypes(): string {
+		return generateRuntimeTypes();
+	}
+
+	/**
+	 * Generates TypeScript types for a single function.
+	 * @param func - Function definition
+	 * @param groupName - API group name
+	 * @returns TypeScript definition string
+	 */
+	private generateFunctionTypes(func: CustomFunctionDef, groupName: string): string {
+		const inputTypeName = `${func.name}_Input`;
+		const outputTypeName = `${func.name}_Output`;
+
+		let typescript = `\ninterface ${inputTypeName} {\n`;
+		if (func.inputSchema?.properties) {
+			const required = func.inputSchema.required || [];
+			for (const [key, value] of Object.entries(func.inputSchema.properties)) {
+				const prop = value as { type?: string; description?: string };
+				const tsType = this.jsonSchemaTypeToTS(prop.type ?? 'any');
+				const comment = prop.description ? ` // ${prop.description}` : '';
+				const optional = required.includes(key) ? '' : '?';
+				typescript += `  ${key}${optional}: ${tsType};${comment}\n`;
+			}
+		}
+		typescript += `}\n`;
+
+		typescript += `\ninterface ${outputTypeName} {\n`;
+		typescript += `  [key: string]: unknown;\n`;
+		typescript += `}\n`;
+
+		return typescript;
+	}
+
+	/**
+	 * Converts JSON Schema type to TypeScript type.
+	 * @param type - JSON Schema type string
+	 * @returns TypeScript type string
+	 */
+	private jsonSchemaTypeToTS(type: string): string {
+		switch (type) {
+			case 'string':
+				return 'string';
+			case 'number':
+			case 'integer':
+				return 'number';
+			case 'boolean':
+				return 'boolean';
+			case 'array':
+				return 'unknown[]';
+			case 'object':
+				return 'Record<string, unknown>';
+			default:
+				return 'unknown';
+		}
+	}
+
+	/**
+	 * Helper to check if a string is a valid JavaScript identifier
+	 */
+	private isValidIdentifier(name: string): boolean {
+		return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name);
+	}
+
+	/**
+	 * Helper to safely format a property name for TypeScript type definitions
+	 * Returns the property name with quotes if needed, or just the name if valid
+	 */
+	private formatPropertyName(name: string): string {
+		if (!this.isValidIdentifier(name)) {
+			return `'${name}'`;
+		}
+		return name;
+	}
+
+	/**
+	 * Generates the API namespace with all function declarations.
+	 * Handles hierarchical group names (e.g., "github/readOnly" -> api.github.readOnly)
+	 * @param groups - API groups to include
+	 * @returns TypeScript definition string
+	 */
+	private generateAPINamespace(groups: APIGroupConfig[]): string {
+		interface NestedGroup {
+			functions: CustomFunctionDef[];
+			subgroups: Map<string, NestedGroup>;
+		}
+
+		const rootGroups = new Map<string, NestedGroup>();
+
+		for (const group of groups) {
+			if (!group.functions || group.functions.length === 0) continue;
+
+			const parts = group.name.split('/');
+			let current = rootGroups;
+
+			for (let i = 0; i < parts.length; i++) {
+				const part = parts[i]!;
+
+				if (!current.has(part)) {
+					current.set(part, { functions: [], subgroups: new Map() });
+				}
+
+				const node = current.get(part)!;
+
+				if (i === parts.length - 1) {
+					node.functions.push(...group.functions);
+				}
+
+				current = node.subgroups;
+			}
+		}
+
+		const generateLevel = (groups: Map<string, NestedGroup>, indent: string): string => {
+			let ts = '';
+
+			for (const [name, node] of groups.entries()) {
+				if (!name) continue;
+				const formattedName = this.formatPropertyName(name);
+				ts += `${indent}${formattedName}: {\n`;
+
+				for (const func of node.functions) {
+					if (!func.name) continue;
+					const funcName = this.formatPropertyName(func.name);
+					const description =
+						func.description && typeof func.description === 'string'
+							? func.description.replace(/\n/g, ' ').substring(0, 200)
+							: '';
+					ts += `${indent}  /**\n${indent}   * ${description}\n${indent}   */\n`;
+					ts += `${indent}  ${funcName}(params: ${func.name}_Input): Promise<${func.name}_Output>;\n`;
+				}
+
+				if (node.subgroups.size > 0) {
+					ts += generateLevel(node.subgroups, indent + '  ');
+				}
+
+				ts += `${indent}};\n`;
+			}
+
+			return ts;
+		};
+
+		let typescript = `\ndeclare const api: {\n`;
+		typescript += generateLevel(rootGroups, '  ');
+		typescript += `};\n`;
+		typescript += `\nexport { api };\n`;
+
+		return typescript;
+	}
+
+	/**
+	 * Gets the list of available API group names.
+	 * @returns Array of API group names
+	 */
+	getApiGroups(): string[] {
+		return this.apiGroups.map((g) => g.name);
+	}
+}

package/src/callback/index.ts

@@ -0,0 +1,191 @@
+/**
+ * Client Callback Manager
+ *
+ * Handles callbacks to clients for LLM, approval, and embedding requests
+ */
+import type { ClientServices } from '@mondaydotcomorg/atp-protocol';
+
+/**
+ * Callback request types
+ */
+export type CallbackType = 'llm' | 'approval' | 'embedding';
+
+/**
+ * Callback request payload
+ */
+export interface CallbackRequest {
+	type: CallbackType;
+	operation: string;
+	payload: Record<string, unknown>;
+}
+
+/**
+ * Registered client information
+ */
+interface ClientInfo {
+	clientId: string;
+	services: ClientServices;
+	callbackUrl?: string;
+	lastSeen: Date;
+}
+
+/**
+ * Callback handler function
+ */
+export type CallbackHandler = (clientId: string, request: CallbackRequest) => Promise<unknown>;
+
+/**
+ * Manages client callbacks for provided services
+ */
+export class ClientCallbackManager {
+	private clients: Map<string, ClientInfo> = new Map();
+	private callbackHandler?: CallbackHandler;
+	private cleanupInterval?: NodeJS.Timeout;
+
+	/**
+	 * Registers a callback handler for client requests
+	 * @param handler - Function to handle callbacks
+	 */
+	setCallbackHandler(handler: CallbackHandler): void {
+		this.callbackHandler = handler;
+
+		if (!this.cleanupInterval) {
+			this.cleanupInterval = setInterval(
+				() => {
+					const cleaned = this.cleanupStaleClients();
+					if (cleaned > 0) {
+						console.log(`[ClientCallback] Cleaned up ${cleaned} stale clients`);
+					}
+				},
+				5 * 60 * 1000
+			);
+		}
+	}
+
+	/**
+	 * Registers a client with their provided services
+	 * @param clientId - Unique client identifier
+	 * @param services - Services provided by client
+	 * @param callbackUrl - Optional webhook URL for callbacks
+	 */
+	registerClient(clientId: string, services: ClientServices, callbackUrl?: string): void {
+		this.clients.set(clientId, {
+			clientId,
+			services,
+			callbackUrl,
+			lastSeen: new Date(),
+		});
+	}
+
+	/**
+	 * Updates client's last seen timestamp
+	 * @param clientId - Client identifier
+	 */
+	updateClientActivity(clientId: string): void {
+		const client = this.clients.get(clientId);
+		if (client) {
+			client.lastSeen = new Date();
+		}
+	}
+
+	/**
+	 * Checks if client has a specific service
+	 * @param clientId - Client identifier
+	 * @param serviceType - Type of service
+	 * @returns Whether client provides this service
+	 */
+	hasClientService(clientId: string, serviceType: 'llm' | 'approval' | 'embedding'): boolean {
+		const client = this.clients.get(clientId);
+		if (!client) return false;
+
+		switch (serviceType) {
+			case 'llm':
+				return client.services.hasLLM;
+			case 'approval':
+				return client.services.hasApproval;
+			case 'embedding':
+				return client.services.hasEmbedding;
+			default:
+				return false;
+		}
+	}
+
+	/**
+	 * Gets client information
+	 * @param clientId - Client identifier
+	 * @returns Client info or undefined
+	 */
+	getClient(clientId: string): ClientInfo | undefined {
+		return this.clients.get(clientId);
+	}
+
+	/**
+	 * Sends a callback request to a client
+	 * @param clientId - Client identifier
+	 * @param request - Callback request
+	 * @returns Response from client
+	 */
+	async sendCallback(clientId: string, request: CallbackRequest): Promise<unknown> {
+		const client = this.clients.get(clientId);
+		if (!client) {
+			throw new Error(`Client ${clientId} not registered`);
+		}
+
+		if (!this.hasClientService(clientId, request.type)) {
+			throw new Error(`Client ${clientId} does not provide ${request.type} service`);
+		}
+
+		if (!this.callbackHandler) {
+			throw new Error('No callback handler registered');
+		}
+
+		return await this.callbackHandler(clientId, request);
+	}
+
+	/**
+	 * Cleans up stale clients (not seen in specified duration)
+	 * @param maxAge - Maximum age in milliseconds (default: 5 minutes)
+	 */
+	cleanupStaleClients(maxAge: number = 5 * 60 * 1000): number {
+		const now = Date.now();
+		let cleaned = 0;
+
+		for (const [clientId, client] of this.clients.entries()) {
+			if (now - client.lastSeen.getTime() > maxAge) {
+				this.clients.delete(clientId);
+				cleaned++;
+			}
+		}
+
+		return cleaned;
+	}
+
+	/**
+	 * Gets all registered clients
+	 * @returns Array of client information
+	 */
+	getAllClients(): ClientInfo[] {
+		return Array.from(this.clients.values());
+	}
+
+	/**
+	 * Removes a client
+	 * @param clientId - Client identifier
+	 */
+	unregisterClient(clientId: string): void {
+		this.clients.delete(clientId);
+	}
+
+	/**
+	 * Stops automatic cleanup and clears resources
+	 */
+	destroy(): void {
+		if (this.cleanupInterval) {
+			clearInterval(this.cleanupInterval);
+			this.cleanupInterval = undefined;
+		}
+		this.clients.clear();
+	}
+}
+
+export const clientCallbackManager = new ClientCallbackManager();