@mondaydotcomorg/atp-protocol 0.17.14

package/dist/validation.js

@@ -0,0 +1,129 @@
+/**
+ * Input validation utilities for ExecutionConfig and other types
+ */
+import { z } from 'zod';
+/**
+ * Maximum allowed code size (1MB)
+ */
+export const MAX_CODE_SIZE = 1000000;
+export class ConfigValidationError extends Error {
+    field;
+    value;
+    constructor(message, field, value) {
+        super(message);
+        this.field = field;
+        this.value = value;
+        this.name = 'ConfigValidationError';
+    }
+}
+export class SecurityViolationError extends Error {
+    violations;
+    constructor(message, violations) {
+        super(message);
+        this.violations = violations;
+        this.name = 'SecurityViolationError';
+    }
+}
+/**
+ * Sanitizes input string by removing control characters and normalizing whitespace
+ */
+export function sanitizeInput(input, maxLength = MAX_CODE_SIZE) {
+    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) {
+    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) {
+    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) {
+    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);
+    }
+}
+//# sourceMappingURL=validation.js.map

package/dist/validation.js.map

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

package/package.json

@@ -0,0 +1,41 @@
+{
+	"name": "@mondaydotcomorg/atp-protocol",
+	"version": "0.17.14",
+	"description": "Core protocol types and interfaces 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": "tsc -p tsconfig.json",
+		"dev": "tsc -p tsconfig.json --watch",
+		"clean": "rm -rf dist *.tsbuildinfo",
+		"test": "vitest run",
+		"lint": "tsc --noEmit"
+	},
+	"keywords": [
+		"agent",
+		"protocol",
+		"types",
+		"ai",
+		"llm"
+	],
+	"license": "MIT",
+	"dependencies": {
+		"@mondaydotcomorg/atp-provenance": "0.17.14",
+		"zod": "^3.23.8"
+	},
+	"devDependencies": {
+		"typescript": "^5.3.3",
+		"vitest": "^1.2.1"
+	}
+}

package/src/auth.ts

@@ -0,0 +1,404 @@
+/**
+ * Authentication and credential management types for Agent Tool Protocol
+ */
+
+/**
+ * Supported authentication schemes
+ */
+export type AuthScheme = 'apiKey' | 'bearer' | 'basic' | 'oauth2' | 'custom' | 'composite';
+
+/**
+ * Base authentication configuration
+ */
+export interface BaseAuthConfig {
+	scheme: AuthScheme;
+	/** Environment variable name to read credentials from */
+	envVar?: string;
+	/** Direct credential value (not recommended for production) */
+	value?: string;
+	/**
+	 * Credential source: 'server' for server-level env vars (default), 'user' for user-scoped OAuth
+	 */
+	source?: 'server' | 'user';
+	/**
+	 * OAuth provider name for user-scoped credentials (e.g., 'github', 'google')
+	 * Required when source='user'. Used to look up user's OAuth token from AuthProvider.
+	 * Note: This is different from the 'provider' field which is for runtime credential providers.
+	 */
+	oauthProvider?: string;
+	/** Runtime credential provider function name */
+	provider?: string;
+}
+
+/**
+ * API Key authentication (in header or query param)
+ */
+export interface APIKeyAuthConfig extends BaseAuthConfig {
+	scheme: 'apiKey';
+	/** Where to send the API key */
+	in: 'header' | 'query';
+	/** Parameter/header name */
+	name: string;
+}
+
+/**
+ * Bearer token authentication
+ */
+export interface BearerAuthConfig extends BaseAuthConfig {
+	scheme: 'bearer';
+	/** Optional bearer format (e.g., 'JWT') */
+	bearerFormat?: string;
+}
+
+/**
+ * HTTP Basic authentication
+ */
+export interface BasicAuthConfig extends BaseAuthConfig {
+	scheme: 'basic';
+	/** Username (can use envVar for dynamic value) */
+	username?: string;
+	/** Username environment variable */
+	usernameEnvVar?: string;
+	/** Password environment variable */
+	passwordEnvVar?: string;
+}
+
+/**
+ * OAuth2 authentication with automatic token refresh
+ */
+export interface OAuth2AuthConfig extends BaseAuthConfig {
+	scheme: 'oauth2';
+	/** OAuth2 flow type */
+	flow: 'clientCredentials' | 'authorizationCode' | 'implicit' | 'password';
+	/** Token endpoint URL */
+	tokenUrl: string;
+	/** Authorization endpoint (for authorizationCode/implicit) */
+	authorizationUrl?: string;
+	/** Client ID */
+	clientId?: string;
+	/** Client ID environment variable */
+	clientIdEnvVar?: string;
+	/** Client secret environment variable */
+	clientSecretEnvVar?: string;
+	/** Scopes required */
+	scopes?: string[];
+	/** Refresh token environment variable (for token refresh) */
+	refreshTokenEnvVar?: string;
+}
+
+/**
+ * Custom authentication with arbitrary headers
+ */
+export interface CustomAuthConfig extends BaseAuthConfig {
+	scheme: 'custom';
+	/** Custom headers to inject */
+	headers: Record<string, string>;
+	/** Environment variables to use for header values */
+	headerEnvVars?: Record<string, string>;
+	/** Query parameters to inject */
+	queryParams?: Record<string, string>;
+	/** Environment variables to use for query parameter values */
+	queryParamEnvVars?: Record<string, string>;
+}
+
+/**
+ * Composite authentication - combines multiple auth mechanisms
+ * Useful for APIs that require multiple credentials (e.g., projectId + apiKey + secret)
+ */
+export interface CompositeAuthConfig extends BaseAuthConfig {
+	scheme: 'composite';
+	/**
+	 * Multiple credentials to combine
+	 * Example: { projectId: { envVar: 'PROJECT_ID' }, apiKey: { envVar: 'API_KEY' }, secret: { envVar: 'API_SECRET' } }
+	 */
+	credentials: Record<string, CredentialConfig>;
+	/** How to inject credentials: 'header', 'query', or 'both' */
+	injectAs?: 'header' | 'query' | 'both';
+}
+
+/**
+ * Individual credential configuration for composite auth
+ */
+export interface CredentialConfig {
+	/** Environment variable to read from */
+	envVar?: string;
+	/** Direct value (not recommended) */
+	value?: string;
+	/** Header name if injecting as header */
+	headerName?: string;
+	/** Query param name if injecting as query */
+	queryParamName?: string;
+	/** Whether this credential is required */
+	required?: boolean;
+}
+
+/**
+ * Union type of all auth configurations
+ */
+export type AuthConfig =
+	| APIKeyAuthConfig
+	| BearerAuthConfig
+	| BasicAuthConfig
+	| OAuth2AuthConfig
+	| CustomAuthConfig
+	| CompositeAuthConfig;
+
+/**
+ * Runtime credential provider
+ * Allows dynamic credential resolution at runtime
+ */
+export interface CredentialProvider {
+	name: string;
+	/** Resolves credentials dynamically */
+	resolve: () => Promise<Credentials> | Credentials;
+}
+
+/**
+ * Resolved credentials ready to be injected into requests
+ */
+export interface Credentials {
+	headers?: Record<string, string>;
+	queryParams?: Record<string, string>;
+}
+
+/**
+ * Credential resolver - resolves auth config to actual credentials
+ */
+export class CredentialResolver {
+	private providers: Map<string, CredentialProvider> = new Map();
+
+	/**
+	 * Registers a runtime credential provider
+	 */
+	registerProvider(provider: CredentialProvider): void {
+		this.providers.set(provider.name, provider);
+	}
+
+	/**
+	 * Resolves auth configuration to credentials
+	 */
+	async resolve(authConfig: AuthConfig): Promise<Credentials> {
+		if (authConfig.provider) {
+			const provider = this.providers.get(authConfig.provider);
+			if (!provider) {
+				throw new Error(`Credential provider '${authConfig.provider}' not found`);
+			}
+			return await provider.resolve();
+		}
+
+		switch (authConfig.scheme) {
+			case 'apiKey':
+				return this.resolveAPIKey(authConfig);
+			case 'bearer':
+				return this.resolveBearer(authConfig);
+			case 'basic':
+				return this.resolveBasic(authConfig);
+			case 'oauth2':
+				return this.resolveOAuth2(authConfig);
+			case 'custom':
+				return this.resolveCustom(authConfig);
+			case 'composite':
+				return this.resolveComposite(authConfig);
+			default:
+				throw new Error(`Unsupported auth scheme: ${(authConfig as any).scheme}`);
+		}
+	}
+
+	private resolveAPIKey(config: APIKeyAuthConfig): Credentials {
+		const value = this.getValue(config);
+		if (!value) {
+			throw new Error(`API key not provided for '${config.name}'`);
+		}
+
+		if (config.in === 'header') {
+			return { headers: { [config.name]: value } };
+		} else {
+			return { queryParams: { [config.name]: value } };
+		}
+	}
+
+	private resolveBearer(config: BearerAuthConfig): Credentials {
+		const token = this.getValue(config);
+		if (!token) {
+			throw new Error('Bearer token not provided');
+		}
+
+		return {
+			headers: {
+				Authorization: `Bearer ${token}`,
+			},
+		};
+	}
+
+	private resolveBasic(config: BasicAuthConfig): Credentials {
+		const username = config.usernameEnvVar ? process.env[config.usernameEnvVar] : config.username;
+		const password = config.passwordEnvVar
+			? process.env[config.passwordEnvVar]
+			: this.getValue(config);
+
+		if (!username || !password) {
+			throw new Error('Basic auth username and password not provided');
+		}
+
+		const credentials = Buffer.from(`${username}:${password}`).toString('base64');
+		return {
+			headers: {
+				Authorization: `Basic ${credentials}`,
+			},
+		};
+	}
+
+	private async resolveOAuth2(config: OAuth2AuthConfig): Promise<Credentials> {
+		const clientId = config.clientIdEnvVar ? process.env[config.clientIdEnvVar] : config.clientId;
+		const clientSecret = config.clientSecretEnvVar
+			? process.env[config.clientSecretEnvVar]
+			: undefined;
+
+		if (!clientId || !clientSecret) {
+			throw new Error('OAuth2 client credentials not provided');
+		}
+
+		if (config.flow === 'clientCredentials') {
+			const token = await this.fetchOAuth2Token(
+				config.tokenUrl,
+				clientId,
+				clientSecret,
+				config.scopes
+			);
+			return {
+				headers: {
+					Authorization: `Bearer ${token}`,
+				},
+			};
+		}
+
+		const token = this.getValue(config);
+		if (token) {
+			return {
+				headers: {
+					Authorization: `Bearer ${token}`,
+				},
+			};
+		}
+
+		throw new Error(`OAuth2 flow '${config.flow}' requires manual token setup`);
+	}
+
+	private resolveCustom(config: CustomAuthConfig): Credentials {
+		const headers: Record<string, string> = {};
+		const queryParams: Record<string, string> = {};
+
+		Object.assign(headers, config.headers);
+
+		if (config.headerEnvVars) {
+			for (const [headerName, envVar] of Object.entries(config.headerEnvVars)) {
+				const value = process.env[envVar];
+				if (value) {
+					headers[headerName] = value;
+				}
+			}
+		}
+
+		if (config.queryParams) {
+			Object.assign(queryParams, config.queryParams);
+		}
+
+		if (config.queryParamEnvVars) {
+			for (const [paramName, envVar] of Object.entries(config.queryParamEnvVars)) {
+				const value = process.env[envVar];
+				if (value) {
+					queryParams[paramName] = value;
+				}
+			}
+		}
+
+		return {
+			headers: Object.keys(headers).length > 0 ? headers : undefined,
+			queryParams: Object.keys(queryParams).length > 0 ? queryParams : undefined,
+		};
+	}
+
+	private resolveComposite(config: CompositeAuthConfig): Credentials {
+		const headers: Record<string, string> = {};
+		const queryParams: Record<string, string> = {};
+
+		for (const [credName, credConfig] of Object.entries(config.credentials)) {
+			const value = credConfig.envVar ? process.env[credConfig.envVar] : credConfig.value;
+
+			if (!value) {
+				if (credConfig.required !== false) {
+					throw new Error(`Required credential '${credName}' not provided`);
+				}
+				continue;
+			}
+
+			const injectAs = config.injectAs || 'header';
+
+			if ((injectAs === 'header' || injectAs === 'both') && credConfig.headerName) {
+				headers[credConfig.headerName] = value;
+			}
+
+			if ((injectAs === 'query' || injectAs === 'both') && credConfig.queryParamName) {
+				queryParams[credConfig.queryParamName] = value;
+			}
+
+			if (!credConfig.headerName && !credConfig.queryParamName) {
+				if (injectAs === 'query' || injectAs === 'both') {
+					queryParams[credName] = value;
+				} else {
+					headers[`X-${credName}`] = value;
+				}
+			}
+		}
+
+		return {
+			headers: Object.keys(headers).length > 0 ? headers : undefined,
+			queryParams: Object.keys(queryParams).length > 0 ? queryParams : undefined,
+		};
+	}
+
+	/**
+	 * Gets credential value from config (env var or direct value)
+	 */
+	private getValue(config: BaseAuthConfig): string | undefined {
+		if (config.envVar) {
+			return process.env[config.envVar];
+		}
+		return config.value;
+	}
+
+	/**
+	 * Fetches OAuth2 token using client credentials flow
+	 */
+	private async fetchOAuth2Token(
+		tokenUrl: string,
+		clientId: string,
+		clientSecret: string,
+		scopes?: string[]
+	): Promise<string> {
+		const params = new URLSearchParams({
+			grant_type: 'client_credentials',
+			client_id: clientId,
+			client_secret: clientSecret,
+		});
+
+		if (scopes && scopes.length > 0) {
+			params.append('scope', scopes.join(' '));
+		}
+
+		const response = await fetch(tokenUrl, {
+			method: 'POST',
+			headers: {
+				'Content-Type': 'application/x-www-form-urlencoded',
+			},
+			body: params.toString(),
+		});
+
+		if (!response.ok) {
+			throw new Error(`OAuth2 token fetch failed: ${response.statusText}`);
+		}
+
+		const data = (await response.json()) as { access_token: string };
+		return data.access_token;
+	}
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './types.js';
+export * from './schemas.js';
+export * from './validation.js';
+export * from './auth.js';
+export * from './providers.js';
+export * from './oauth.js';

package/src/oauth.ts

@@ -0,0 +1,74 @@
+/**
+ * OAuth and scope checking interfaces for Agent Tool Protocol
+ */
+
+/**
+ * Scope checker interface
+ * Checks what OAuth scopes a token has for a given provider
+ */
+export interface ScopeChecker {
+	/** Provider name (e.g., 'github', 'google', 'microsoft') */
+	provider: string;
+
+	/**
+	 * Check what scopes a token has
+	 * @param token - Access token to check
+	 * @returns Array of scope strings (e.g., ['repo', 'read:user'])
+	 */
+	check(token: string): Promise<string[]>;
+
+	/**
+	 * Validate if a token is still valid (optional)
+	 * @param token - Access token to validate
+	 * @returns true if valid, false if expired/revoked
+	 */
+	validate?(token: string): Promise<boolean>;
+}
+
+/**
+ * Token information returned by providers
+ */
+export interface TokenInfo {
+	/** Whether the token is valid */
+	valid: boolean;
+
+	/** OAuth scopes the token has */
+	scopes: string[];
+
+	/** Token expiration timestamp (milliseconds since epoch) */
+	expiresAt?: number;
+
+	/** User identifier from the provider */
+	userId?: string;
+
+	/** Additional provider-specific data */
+	metadata?: Record<string, unknown>;
+}
+
+/**
+ * Scope filtering configuration
+ */
+export interface ScopeFilteringConfig {
+	/** Enable scope-based filtering */
+	enabled: boolean;
+
+	/**
+	 * Filtering mode:
+	 * - 'eager': Filter tools at /api/definitions based on user's scopes
+	 * - 'lazy': Return all tools, validate scopes only at execution time
+	 */
+	mode: 'eager' | 'lazy';
+
+	/**
+	 * Cache TTL for scope checks in seconds
+	 * Default: 3600 (1 hour)
+	 */
+	cacheTTL?: number;
+
+	/**
+	 * Fail behavior when scope checker not available for a provider
+	 * - 'allow': Allow all tools (no filtering)
+	 * - 'deny': Hide all tools requiring scopes
+	 */
+	fallback?: 'allow' | 'deny';
+}