@mondaydotcomorg/atp-server 0.17.14

package/src/routes/index.ts

@@ -0,0 +1,93 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { log } from '@mondaydotcomorg/atp-runtime';
+import { handleInfo } from '../controllers/info.controller.js';
+import { handleDefinitions } from '../controllers/definitions.controller.js';
+import { handleSearch } from '../controllers/search.controller.js';
+import { handleExecute } from '../controllers/execute.controller.js';
+import { handleExecuteStream } from '../controllers/stream.controller.js';
+import { handleResume } from '../controllers/resume.controller.js';
+import type { APIAggregator } from '../aggregator/index.js';
+import type { SearchEngine } from '../search/index.js';
+import type { CodeValidator } from '../validator/index.js';
+import type { SandboxExecutor } from '../executor/index.js';
+import type { ExecutionStateManager } from '../execution-state/index.js';
+import type { AuditConfig } from '../middleware/audit.js';
+import { readBody } from '../utils/index.js';
+
+export interface RouteContext {
+	aggregator: APIAggregator;
+	searchEngine: SearchEngine;
+	validator: CodeValidator;
+	executor: SandboxExecutor;
+	stateManager: ExecutionStateManager;
+	auditConfig?: AuditConfig;
+	defaultTimeout: number;
+	defaultMemoryLimit: number;
+	defaultLLMCallLimit: number;
+}
+
+export async function handleRoute(
+	req: IncomingMessage,
+	res: ServerResponse,
+	context: RouteContext,
+	logger: ReturnType<typeof log.child>
+): Promise<boolean> {
+	const clientId = req.headers['x-client-id'] as string | undefined;
+	const url = new URL(req.url ?? '/', `http://${req.headers.host}`);
+
+	if (url.pathname === '/api/info' && req.method === 'GET') {
+		logger.debug('Serving API info');
+		await handleInfo(req, res);
+		return true;
+	}
+
+	if (url.pathname === '/api/definitions' && req.method === 'GET') {
+		logger.debug('Serving API definitions');
+		await handleDefinitions(req, res, context.aggregator, url);
+		return true;
+	}
+
+	if (url.pathname === '/api/search' && req.method === 'POST') {
+		logger.debug('Searching API functions');
+		const body = await readBody(req);
+		await handleSearch(req, res, context.searchEngine, body);
+		return true;
+	}
+
+	if (url.pathname.match(/^\/api\/resume\/[^/]+$/) && req.method === 'POST') {
+		const executionId = url.pathname.split('/').pop()!;
+		const body = await readBody(req);
+		await handleResume(
+			req,
+			res,
+			{ executor: context.executor, stateManager: context.stateManager },
+			executionId,
+			body,
+			logger
+		);
+		return true;
+	}
+
+	if (url.pathname === '/api/execute' && req.method === 'POST') {
+		const body = await readBody(req);
+		await handleExecuteStream(
+			req,
+			res,
+			{
+				validator: context.validator,
+				executor: context.executor,
+				stateManager: context.stateManager,
+				auditConfig: context.auditConfig,
+				defaultTimeout: context.defaultTimeout,
+				defaultMemoryLimit: context.defaultMemoryLimit,
+				defaultLLMCallLimit: context.defaultLLMCallLimit,
+			},
+			body,
+			clientId,
+			logger
+		);
+		return true;
+	}
+
+	return false;
+}

package/src/search/index.ts

@@ -0,0 +1,216 @@
+import type {
+	SearchOptions,
+	SearchResult,
+	APIGroupConfig,
+	AuthProvider,
+	ScopeFilteringConfig,
+} from '@mondaydotcomorg/atp-protocol';
+
+interface IndexedFunction {
+	apiGroup: string;
+	functionName: string;
+	description: string;
+	signature: string;
+	keywords: string[];
+	metadata?: {
+		requiredScopes?: string[];
+		provider?: string;
+		source?: 'server' | 'user';
+	};
+}
+
+/**
+ * SearchEngine provides semantic and keyword-based search over available API functions.
+ */
+export class SearchEngine {
+	private index: IndexedFunction[] = [];
+
+	/**
+	 * Creates a new SearchEngine instance.
+	 * @param apiGroups - Array of API group configurations to index
+	 */
+	constructor(apiGroups?: APIGroupConfig[]) {
+		if (apiGroups) {
+			this.buildIndex(apiGroups);
+		}
+	}
+
+	/**
+	 * Builds the search index from API group configurations.
+	 * @param apiGroups - API groups to index
+	 */
+	private buildIndex(apiGroups: APIGroupConfig[]): void {
+		this.index = [];
+
+		for (const group of apiGroups) {
+			if (group.functions) {
+				for (const func of group.functions) {
+					const keywords = this.extractKeywords(func.description);
+					const signature = this.generateSignature(func);
+
+					this.index.push({
+						apiGroup: group.name,
+						functionName: func.name,
+						description: func.description,
+						signature,
+						keywords,
+						metadata: {
+							requiredScopes: func.requiredScopes,
+							provider: func.auth?.oauthProvider,
+							source: func.auth?.source,
+						},
+					});
+				}
+			}
+		}
+	}
+
+	/**
+	 * Searches for API functions matching the query.
+	 * @param options - Search options including query and filters
+	 * @param userId - Optional user ID for scope filtering
+	 * @param authProvider - Optional auth provider for checking user scopes
+	 * @param scopeFilteringConfig - Optional scope filtering configuration
+	 * @returns Array of search results sorted by relevance
+	 */
+	async search(
+		options: SearchOptions,
+		userId?: string,
+		authProvider?: AuthProvider,
+		scopeFilteringConfig?: ScopeFilteringConfig
+	): Promise<SearchResult[]> {
+		const queryWords = this.extractKeywords(options.query);
+		const results: Array<{ result: SearchResult; score: number }> = [];
+
+		for (const item of this.index) {
+			if (options.apiGroups && !options.apiGroups.includes(item.apiGroup)) {
+				continue;
+			}
+
+			if (scopeFilteringConfig?.enabled && item.metadata?.source === 'user') {
+				const shouldInclude = await this.checkScopes(
+					item,
+					userId,
+					authProvider,
+					scopeFilteringConfig
+				);
+				if (!shouldInclude) {
+					continue;
+				}
+			}
+
+			let score = 0;
+
+			if (item.description.toLowerCase().includes(options.query.toLowerCase())) {
+				score += 100;
+			}
+
+			if (item.functionName.toLowerCase().includes(options.query.toLowerCase())) {
+				score += 50;
+			}
+
+			for (const word of queryWords) {
+				if (item.keywords.includes(word)) {
+					score += 10;
+				}
+				if (item.functionName.toLowerCase().includes(word)) {
+					score += 5;
+				}
+				if (item.description.toLowerCase().includes(word)) {
+					score += 3;
+				}
+			}
+
+			if (score > 0) {
+				results.push({
+					result: {
+						apiGroup: item.apiGroup,
+						functionName: item.functionName,
+						description: item.description,
+						signature: item.signature,
+						relevanceScore: score,
+					},
+					score,
+				});
+			}
+		}
+
+		results.sort((a, b) => b.score - a.score);
+
+		const limit = options.maxResults ?? 10;
+		return results.slice(0, limit).map((r) => r.result);
+	}
+
+	/**
+	 * Checks if a user has the required scopes for a function.
+	 * @param item - Indexed function to check
+	 * @param userId - User ID
+	 * @param authProvider - Auth provider for looking up credentials
+	 * @param config - Scope filtering configuration
+	 * @returns True if function should be included in results
+	 */
+	private async checkScopes(
+		item: IndexedFunction,
+		userId: string | undefined,
+		authProvider: AuthProvider | undefined,
+		config: ScopeFilteringConfig
+	): Promise<boolean> {
+		const requiredScopes = item.metadata?.requiredScopes;
+		const provider = item.metadata?.provider;
+
+		if (!requiredScopes || requiredScopes.length === 0) {
+			return true;
+		}
+
+		if (!userId || !authProvider || !provider) {
+			return config.fallback === 'allow';
+		}
+
+		try {
+			const userCreds = await authProvider.getUserCredential?.(userId, provider);
+
+			if (!userCreds) {
+				return config.fallback === 'allow';
+			}
+
+			const userScopes = userCreds.scopes ?? [];
+			const hasAllScopes = requiredScopes.every((required) => userScopes.includes(required));
+
+			return hasAllScopes;
+		} catch (error) {
+			return config.fallback === 'allow';
+		}
+	}
+
+	/**
+	 * Extracts keywords from a text string.
+	 * @param text - Text to extract keywords from
+	 * @returns Array of lowercase keywords
+	 */
+	private extractKeywords(text: string): string[] {
+		return text
+			.toLowerCase()
+			.replace(/[^\w\s]/g, ' ')
+			.split(/\s+/)
+			.filter((word) => word.length > 2);
+	}
+
+	/**
+	 * Generates a function signature string.
+	 * @param func - Function definition
+	 * @returns Signature string
+	 */
+	private generateSignature(func: {
+		name: string;
+		inputSchema?: { properties?: Record<string, unknown> };
+	}): string {
+		const params: string[] = [];
+		if (func.inputSchema?.properties) {
+			for (const [key, value] of Object.entries(func.inputSchema.properties)) {
+				const prop = value as { type?: string };
+				params.push(`${key}: ${prop.type ?? 'any'}`);
+			}
+		}
+		return `${func.name}({ ${params.join(', ')} })`;
+	}
+}

package/src/security/index.ts

@@ -0,0 +1 @@
+export * from '@mondaydotcomorg/atp-provenance';

package/src/shutdown.ts

@@ -0,0 +1,108 @@
+import { log } from '@mondaydotcomorg/atp-runtime';
+import type { Server } from 'node:http';
+import { flushAuditQueue, shutdownAudit } from './middleware/audit.js';
+import type { ExecutionStateManager } from './execution-state/index.js';
+import type { ClientCallbackManager } from './callback/index.js';
+
+interface ShutdownHandlers {
+	server?: Server;
+	stateManager?: ExecutionStateManager;
+	callbackManager?: ClientCallbackManager;
+	customHandlers?: Array<() => Promise<void>>;
+}
+
+let isShuttingDown = false;
+let shutdownHandlers: ShutdownHandlers = {};
+
+/**
+ * Registers handlers for graceful shutdown
+ */
+export function registerShutdownHandlers(handlers: ShutdownHandlers): void {
+	shutdownHandlers = handlers;
+
+	process.on('SIGTERM', handleShutdown);
+	process.on('SIGINT', handleShutdown);
+
+	process.on('uncaughtException', (error) => {
+		log.error('Uncaught exception', { error: error.message, stack: error.stack });
+		handleShutdown();
+	});
+
+	process.on('unhandledRejection', (reason) => {
+		log.error('Unhandled promise rejection', { reason });
+		handleShutdown();
+	});
+}
+
+/**
+ * Performs graceful shutdown
+ */
+async function handleShutdown(): Promise<void> {
+	if (isShuttingDown) {
+		log.warn('Shutdown already in progress');
+		return;
+	}
+
+	isShuttingDown = true;
+	log.info('Starting graceful shutdown...');
+
+	const shutdownTimeout = setTimeout(() => {
+		log.error('Shutdown timeout exceeded, forcing exit');
+		process.exit(1);
+	}, 30000);
+
+	try {
+		if (shutdownHandlers.server) {
+			log.info('Closing HTTP server...');
+			await new Promise<void>((resolve, reject) => {
+				shutdownHandlers.server!.close((err) => {
+					if (err) reject(err);
+					else resolve();
+				});
+			});
+			log.info('HTTP server closed');
+		}
+
+		log.info('Flushing audit queue...');
+		await flushAuditQueue();
+		shutdownAudit();
+		log.info('Audit system stopped');
+
+		if (shutdownHandlers.stateManager) {
+			log.info('Closing state manager...');
+			await shutdownHandlers.stateManager.close();
+			log.info('State manager closed');
+		}
+
+		if (shutdownHandlers.callbackManager) {
+			log.info('Cleaning up callback manager...');
+			shutdownHandlers.callbackManager.destroy();
+			log.info('Callback manager cleaned up');
+		}
+
+		if (shutdownHandlers.customHandlers) {
+			log.info('Running custom shutdown handlers...');
+			for (const handler of shutdownHandlers.customHandlers) {
+				await handler();
+			}
+			log.info('Custom handlers completed');
+		}
+
+		clearTimeout(shutdownTimeout);
+		log.info('Graceful shutdown completed');
+		process.exit(0);
+	} catch (error) {
+		clearTimeout(shutdownTimeout);
+		log.error('Error during shutdown', {
+			error: error instanceof Error ? error.message : 'Unknown error',
+		});
+		process.exit(1);
+	}
+}
+
+/**
+ * Triggers graceful shutdown programmatically
+ */
+export function shutdown(): void {
+	handleShutdown();
+}

package/src/utils/banner.ts

@@ -0,0 +1,25 @@
+import type { CacheProvider, AuthProvider, AuditSink } from '@mondaydotcomorg/atp-protocol';
+
+export interface BannerOptions {
+	port: number;
+	cacheProvider?: CacheProvider;
+	authProvider?: AuthProvider;
+	auditSink?: AuditSink;
+}
+
+/**
+ * Prints a startup banner with server information
+ */
+export function printBanner(options: BannerOptions): void {
+	const { port, cacheProvider, authProvider, auditSink } = options;
+
+	console.log('\n✨ ATP Server ready!');
+	console.log(`📍 http://localhost:${port}/`);
+	console.log(`📚 Type definitions: http://localhost:${port}/openapi.json`);
+	console.log(`🔍 API search: http://localhost:${port}/explorer`);
+
+	if (cacheProvider) console.log(`💾 Cache: ${cacheProvider.name}`);
+	if (authProvider) console.log(`🔒 Auth: ${authProvider.name}`);
+	if (auditSink) console.log(`📝 Audit: ${auditSink.name}`);
+	console.log();
+}

package/src/utils/context.ts

@@ -0,0 +1,58 @@
+import { IncomingMessage } from 'node:http';
+import type { CacheProvider, AuthProvider, AuditSink } from '@mondaydotcomorg/atp-protocol';
+import { log } from '@mondaydotcomorg/atp-runtime';
+import type { RequestContext } from '../core/config.js';
+import { parseQuery } from '../core/http.js';
+
+export interface CreateContextOptions {
+	req: IncomingMessage;
+	cacheProvider?: CacheProvider;
+	authProvider?: AuthProvider;
+	auditSink?: AuditSink;
+	customLogger?: any;
+	responseHeaders: Map<IncomingMessage, Map<string, string>>;
+}
+
+/**
+ * Creates a request context object with all necessary helpers and providers
+ */
+export function createContext(options: CreateContextOptions): RequestContext {
+	const { req, cacheProvider, authProvider, auditSink, customLogger, responseHeaders } = options;
+
+	const clientId = (req.headers['x-client-id'] as string) || undefined;
+	const userId = (req.headers['x-user-id'] as string) || undefined;
+
+	return {
+		method: req.method || 'GET',
+		path: req.url || '/',
+		query: parseQuery(req.url || '/'),
+		headers: req.headers as Record<string, string>,
+		body: null,
+		status: 200,
+		responseBody: null,
+		clientId,
+		userId,
+		cache: cacheProvider,
+		auth: authProvider,
+		audit: auditSink,
+		logger: customLogger || log,
+		throw: (status, message) => {
+			const error = new Error(message) as any;
+			error.status = status;
+			throw error;
+		},
+		assert: (condition, message) => {
+			if (!condition) {
+				const error = new Error(message) as any;
+				error.status = 400;
+				throw error;
+			}
+		},
+		set: (header, value) => {
+			if (!responseHeaders.has(req)) {
+				responseHeaders.set(req, new Map());
+			}
+			responseHeaders.get(req)!.set(header, value);
+		},
+	};
+}

package/src/utils/error.ts

@@ -0,0 +1,25 @@
+import { ServerResponse } from 'node:http';
+import { log } from '@mondaydotcomorg/atp-runtime';
+
+/**
+ * Handles HTTP request errors and sends appropriate responses
+ */
+export function handleError(
+	res: ServerResponse,
+	error: Error & { status?: number },
+	requestId: string,
+	additionalHeaders?: Map<string, string>
+): void {
+	const status = error.status || 500;
+	log.error('Request failed', { requestId, error: error.message, stack: error.stack });
+
+	const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+	if (additionalHeaders) {
+		for (const [key, value] of additionalHeaders.entries()) {
+			headers[key] = value;
+		}
+	}
+
+	res.writeHead(status, headers);
+	res.end(JSON.stringify({ error: error.message, requestId }));
+}

package/src/utils/hint-based-instrumentation.ts

@@ -0,0 +1,99 @@
+/**
+ * Pre-process code to mark string literals that match provenance hints as tainted
+ * This enables cross-execution provenance tracking
+ */
+
+import * as acorn from 'acorn';
+import * as walk from 'acorn-walk';
+import * as escodegen from 'escodegen';
+import type { ProvenanceMetadata } from '@mondaydotcomorg/atp-provenance';
+import { computeDigest } from '@mondaydotcomorg/atp-provenance';
+
+/**
+ * Instrument string literals in code that match hint digests
+ * Wraps them in __mark_tainted(value, hintId) calls
+ */
+export function instrumentLiteralsFromHints(
+	code: string,
+	hintMetadata: Map<string, ProvenanceMetadata>
+): { code: string; taintedCount: number } {
+	if (!hintMetadata || hintMetadata.size === 0) {
+		return { code, taintedCount: 0 };
+	}
+
+	let taintedCount = 0;
+
+	const valueMap = (hintMetadata as any).__valueMap as Map<string, ProvenanceMetadata> | undefined;
+
+	try {
+		const isAlreadyWrapped = code.trim().startsWith('(async function');
+
+		const wrappedCode = isAlreadyWrapped ? code : `(async function() {\n${code}\n})`;
+
+		const ast = acorn.parse(wrappedCode, {
+			ecmaVersion: 2022,
+			sourceType: 'script',
+		}) as any;
+
+		walk.simple(ast, {
+			Literal(node: any) {
+				if (typeof node.value === 'string') {
+					let shouldTaint = false;
+
+					const digest = computeDigest(node.value);
+					if (digest && hintMetadata.has(digest)) {
+						shouldTaint = true;
+					}
+
+					if (!shouldTaint && valueMap && valueMap.size > 0) {
+						for (const hintValue of valueMap.keys()) {
+							if (node.value.includes(hintValue)) {
+								shouldTaint = true;
+								break;
+							}
+						}
+					}
+
+					if (shouldTaint) {
+						const originalValue = node.value;
+						const originalRaw = (node as any).raw || JSON.stringify(originalValue);
+						(node as any).type = 'CallExpression';
+						(node as any).callee = {
+							type: 'Identifier',
+							name: '__mark_tainted',
+						};
+						(node as any).arguments = [
+							{
+								type: 'Literal',
+								value: originalValue,
+								raw: originalRaw,
+							},
+						];
+						delete (node as any).value;
+						delete (node as any).raw;
+						taintedCount++;
+					}
+				}
+			},
+		});
+
+		let instrumentedCode = escodegen.generate(ast);
+
+		if (!isAlreadyWrapped) {
+			const unwrapPrefix = '(async function () {\n';
+			const unwrapSuffix = '\n})';
+			if (instrumentedCode.startsWith(unwrapPrefix) && instrumentedCode.endsWith(unwrapSuffix)) {
+				instrumentedCode = instrumentedCode.slice(unwrapPrefix.length, -unwrapSuffix.length);
+			}
+		} else {
+			if (instrumentedCode.endsWith(');')) {
+				instrumentedCode = instrumentedCode.slice(0, -1);
+			}
+		}
+
+		return { code: instrumentedCode, taintedCount };
+	} catch (error) {
+		console.error('Failed to instrument literals from hints:', error);
+		return { code, taintedCount: 0 };
+	}
+}

package/src/utils/index.ts

@@ -0,0 +1,15 @@
+export { toJSONSchema } from './schema.js';
+export { printBanner, type BannerOptions } from './banner.js';
+export { handleError } from './error.js';
+export { createContext, type CreateContextOptions } from './context.js';
+export { getServerInfo, type ServerInfo, type ServerLimits } from './info.js';
+export { readBody, readJsonBody, DEFAULT_MAX_BODY_SIZE } from './request.js';
+export {
+	sendJson,
+	sendError,
+	send404,
+	sendBadRequest,
+	sendServiceUnavailable,
+	setCorsHeaders,
+	handleOptions,
+} from './response.js';

package/src/utils/info.ts

@@ -0,0 +1,31 @@
+export interface ServerLimits {
+	maxTimeout: number;
+	maxMemory: number;
+	maxLLMCalls: number;
+}
+
+export interface ServerInfo {
+	version: string;
+	capabilities: {
+		execution: boolean;
+		search: boolean;
+		streaming: boolean;
+		llmCalls: boolean;
+	};
+	limits: ServerLimits;
+}
+
+/**
+ * Generates server information object
+ */
+export function getServerInfo(limits: ServerLimits): ServerInfo {
+	return {
+		version: '1.0.0',
+		capabilities: { execution: true, search: true, streaming: false, llmCalls: true },
+		limits: {
+			maxTimeout: limits.maxTimeout,
+			maxMemory: limits.maxMemory,
+			maxLLMCalls: limits.maxLLMCalls,
+		},
+	};
+}