ai-evaluate 2.1.7 → 2.1.8

package/src/shared.ts

@@ -0,0 +1,186 @@
+/**
+ * Shared utilities for ai-evaluate
+ *
+ * Contains constants and helper functions used by both
+ * evaluate.ts (Workers) and node.ts (Node.js/Miniflare)
+ */
+
+import type { EvaluateResult } from './types.js'
+
+/**
+ * Compatibility date for dynamic workers (2026)
+ */
+export const COMPATIBILITY_DATE = '2026-01-01'
+
+/**
+ * Normalize an import specifier to a full URL
+ *
+ * Supports:
+ * - Full URLs: https://esm.sh/lodash@4.17.21 (unchanged)
+ * - Bare package names: lodash -> https://esm.sh/lodash
+ * - Package with version: lodash@4.17.21 -> https://esm.sh/lodash@4.17.21
+ * - Scoped packages: @scope/pkg -> https://esm.sh/@scope/pkg
+ */
+export function normalizeImport(specifier: string): string {
+  // Already a URL - return as-is
+  if (specifier.includes('://')) {
+    return specifier
+  }
+
+  // Bare package name or scoped package - prepend esm.sh
+  return `https://esm.sh/${specifier}`
+}
+
+/**
+ * Normalize an array of import specifiers
+ */
+export function normalizeImports(imports: string[] | undefined): string[] | undefined {
+  if (!imports || imports.length === 0) return imports
+  return imports.map(normalizeImport)
+}
+
+/**
+ * Extract package name from import specifier for variable naming
+ * Supports: lodash, lodash@4.17.21, @scope/pkg, https://esm.sh/lodash
+ */
+export function extractPackageName(specifier: string, index: number): string {
+  let pkgName: string
+  if (specifier.includes('://')) {
+    // Full URL - extract from path
+    const match = specifier.match(/esm\.sh\/(@?[^@/]+)/)
+    pkgName = match ? match[1].replace(/^@/, '').replace(/-/g, '_') : `pkg${index}`
+  } else {
+    // Bare package name - extract before @ version
+    pkgName = specifier.split('@')[0].replace(/^@/, '').replace(/-/g, '_').replace(/\//g, '_')
+  }
+  return pkgName
+}
+
+/**
+ * Default sandbox URL for worker fetch requests
+ */
+export const SANDBOX_URL = 'http://sandbox/execute'
+
+/**
+ * Generate a unique sandbox worker ID
+ */
+export const generateSandboxId = (): string =>
+  `sandbox-${Date.now()}-${Math.random().toString(36).slice(2)}`
+
+/**
+ * Create an error result with consistent structure
+ */
+export function createErrorResult(error: unknown, start: number): EvaluateResult {
+  return {
+    success: false,
+    logs: [],
+    error: error instanceof Error ? error.message : String(error),
+    duration: Date.now() - start,
+  }
+}
+
+/**
+ * Process a result from worker execution, adding duration
+ */
+export function processResult(result: EvaluateResult, start: number): EvaluateResult {
+  return {
+    ...result,
+    duration: Date.now() - start,
+  }
+}
+
+/**
+ * Check if a domain matches a pattern (supports wildcards)
+ * @param domain - The domain to check (e.g., 'api.example.com')
+ * @param pattern - The pattern to match against (e.g., '*.example.com' or 'api.example.com')
+ * @returns true if the domain matches the pattern
+ */
+export function matchesDomainPattern(domain: string, pattern: string): boolean {
+  // Normalize both to lowercase
+  const normalizedDomain = domain.toLowerCase()
+  const normalizedPattern = pattern.toLowerCase()
+
+  // Exact match
+  if (normalizedDomain === normalizedPattern) {
+    return true
+  }
+
+  // Wildcard pattern: *.example.com
+  if (normalizedPattern.startsWith('*.')) {
+    const suffix = normalizedPattern.slice(2) // Remove '*.'
+    // Domain must end with the suffix and have at least one character before it
+    // e.g., 'api.example.com' matches '*.example.com'
+    // but 'example.com' does not match '*.example.com'
+    return normalizedDomain.endsWith('.' + suffix) || normalizedDomain === suffix
+  }
+
+  return false
+}
+
+/**
+ * Check if a URL's domain is in the allowed list
+ * @param url - The URL to check
+ * @param allowedDomains - List of allowed domains (supports wildcards like '*.example.com')
+ * @returns true if the URL's domain is allowed
+ */
+export function isDomainAllowed(url: string, allowedDomains: string[]): boolean {
+  try {
+    const parsedUrl = new URL(url)
+    const hostname = parsedUrl.hostname
+
+    for (const pattern of allowedDomains) {
+      if (matchesDomainPattern(hostname, pattern)) {
+        return true
+      }
+    }
+
+    return false
+  } catch {
+    // Invalid URL - not allowed
+    return false
+  }
+}
+
+/**
+ * Generate JavaScript code for domain checking in workers
+ * This is embedded into the worker source code
+ */
+export function generateDomainCheckCode(allowedDomains: string[]): string {
+  const domainsJson = JSON.stringify(allowedDomains)
+
+  return `
+// Domain allowlist checking
+const __allowedDomains__ = ${domainsJson};
+
+const __matchesDomainPattern__ = (domain, pattern) => {
+  const normalizedDomain = domain.toLowerCase();
+  const normalizedPattern = pattern.toLowerCase();
+  if (normalizedDomain === normalizedPattern) return true;
+  if (normalizedPattern.startsWith('*.')) {
+    const suffix = normalizedPattern.slice(2);
+    return normalizedDomain.endsWith('.' + suffix) || normalizedDomain === suffix;
+  }
+  return false;
+};
+
+const __isDomainAllowed__ = (url) => {
+  try {
+    const parsedUrl = new URL(url);
+    const hostname = parsedUrl.hostname;
+    for (const pattern of __allowedDomains__) {
+      if (__matchesDomainPattern__(hostname, pattern)) return true;
+    }
+    return false;
+  } catch { return false; }
+};
+
+const __originalFetch__ = globalThis.fetch;
+globalThis.fetch = async (input, init) => {
+  const url = typeof input === 'string' ? input : input instanceof Request ? input.url : String(input);
+  if (!__isDomainAllowed__(url)) {
+    throw new Error(\`Network access blocked: domain not in allowlist. Attempted: \${new URL(url).hostname}\`);
+  }
+  return __originalFetch__(input, init);
+};
+`
+}

package/src/type-guards.ts

@@ -0,0 +1,323 @@
+/**
+ * Runtime type guards for JSON response validation
+ */
+
+import type { EvaluateResult, LogEntry, TestResults, TestResult } from './types.js'
+
+/**
+ * Check if a value is a valid LogEntry
+ */
+function isLogEntry(value: unknown): value is LogEntry {
+  if (typeof value !== 'object' || value === null) {
+    return false
+  }
+
+  const obj = value as Record<string, unknown>
+
+  // Check level is one of the allowed values
+  const validLevels = ['log', 'warn', 'error', 'info', 'debug']
+  if (typeof obj.level !== 'string' || !validLevels.includes(obj.level)) {
+    return false
+  }
+
+  // Check message is a string
+  if (typeof obj.message !== 'string') {
+    return false
+  }
+
+  // Check timestamp is a number
+  if (typeof obj.timestamp !== 'number') {
+    return false
+  }
+
+  return true
+}
+
+/**
+ * Check if a value is a valid TestResult
+ */
+function isTestResult(value: unknown): value is TestResult {
+  if (typeof value !== 'object' || value === null) {
+    return false
+  }
+
+  const obj = value as Record<string, unknown>
+
+  // Check required fields
+  if (typeof obj.name !== 'string') {
+    return false
+  }
+
+  if (typeof obj.passed !== 'boolean') {
+    return false
+  }
+
+  if (typeof obj.duration !== 'number') {
+    return false
+  }
+
+  // Check optional error field
+  if (obj.error !== undefined && typeof obj.error !== 'string') {
+    return false
+  }
+
+  return true
+}
+
+/**
+ * Check if a value is a valid TestResults
+ */
+function isTestResults(value: unknown): value is TestResults {
+  if (typeof value !== 'object' || value === null) {
+    return false
+  }
+
+  const obj = value as Record<string, unknown>
+
+  // Check required numeric fields
+  if (typeof obj.total !== 'number') {
+    return false
+  }
+
+  if (typeof obj.passed !== 'number') {
+    return false
+  }
+
+  if (typeof obj.failed !== 'number') {
+    return false
+  }
+
+  if (typeof obj.skipped !== 'number') {
+    return false
+  }
+
+  if (typeof obj.duration !== 'number') {
+    return false
+  }
+
+  // Check tests array
+  if (!Array.isArray(obj.tests)) {
+    return false
+  }
+
+  for (const test of obj.tests) {
+    if (!isTestResult(test)) {
+      return false
+    }
+  }
+
+  return true
+}
+
+/**
+ * Type guard to check if a value is a valid EvaluateResult
+ *
+ * Validates all required fields: success, duration, logs
+ *
+ * @param value - The value to check
+ * @returns True if the value is a valid EvaluateResult
+ */
+export function isEvaluateResult(value: unknown): value is EvaluateResult {
+  if (typeof value !== 'object' || value === null) {
+    return false
+  }
+
+  const obj = value as Record<string, unknown>
+
+  // Check required fields
+  if (typeof obj.success !== 'boolean') {
+    return false
+  }
+
+  if (typeof obj.duration !== 'number') {
+    return false
+  }
+
+  // Check logs is an array of valid LogEntry objects
+  if (!Array.isArray(obj.logs)) {
+    return false
+  }
+
+  for (const log of obj.logs) {
+    if (!isLogEntry(log)) {
+      return false
+    }
+  }
+
+  // Check optional fields have correct types if present
+  if (obj.error !== undefined && typeof obj.error !== 'string') {
+    return false
+  }
+
+  if (obj.testResults !== undefined && !isTestResults(obj.testResults)) {
+    return false
+  }
+
+  // value can be any type, so no validation needed for it
+
+  return true
+}
+
+/**
+ * Assertion function that throws a descriptive error if the value is not a valid EvaluateResult
+ *
+ * @param value - The value to validate
+ * @throws Error with descriptive message if validation fails
+ */
+export function assertEvaluateResult(value: unknown): asserts value is EvaluateResult {
+  if (typeof value !== 'object' || value === null) {
+    throw new Error(
+      `Invalid EvaluateResult: expected object, got ${value === null ? 'null' : typeof value}`
+    )
+  }
+
+  const obj = value as Record<string, unknown>
+
+  // Validate required field: success
+  if (typeof obj.success !== 'boolean') {
+    throw new Error(
+      `Invalid EvaluateResult: 'success' must be a boolean, got ${typeof obj.success}`
+    )
+  }
+
+  // Validate required field: duration
+  if (typeof obj.duration !== 'number') {
+    throw new Error(
+      `Invalid EvaluateResult: 'duration' must be a number, got ${typeof obj.duration}`
+    )
+  }
+
+  // Validate required field: logs
+  if (!Array.isArray(obj.logs)) {
+    throw new Error(`Invalid EvaluateResult: 'logs' must be an array, got ${typeof obj.logs}`)
+  }
+
+  // Validate each log entry
+  for (let i = 0; i < obj.logs.length; i++) {
+    const log = obj.logs[i]
+    if (typeof log !== 'object' || log === null) {
+      throw new Error(
+        `Invalid EvaluateResult: logs[${i}] must be an object, got ${
+          log === null ? 'null' : typeof log
+        }`
+      )
+    }
+
+    const logObj = log as Record<string, unknown>
+    const validLevels = ['log', 'warn', 'error', 'info', 'debug']
+
+    if (typeof logObj.level !== 'string' || !validLevels.includes(logObj.level)) {
+      throw new Error(
+        `Invalid EvaluateResult: logs[${i}].level must be one of ${validLevels.join(', ')}, got '${
+          logObj.level
+        }'`
+      )
+    }
+
+    if (typeof logObj.message !== 'string') {
+      throw new Error(
+        `Invalid EvaluateResult: logs[${i}].message must be a string, got ${typeof logObj.message}`
+      )
+    }
+
+    if (typeof logObj.timestamp !== 'number') {
+      throw new Error(
+        `Invalid EvaluateResult: logs[${i}].timestamp must be a number, got ${typeof logObj.timestamp}`
+      )
+    }
+  }
+
+  // Validate optional field: error
+  if (obj.error !== undefined && typeof obj.error !== 'string') {
+    throw new Error(
+      `Invalid EvaluateResult: 'error' must be a string if present, got ${typeof obj.error}`
+    )
+  }
+
+  // Validate optional field: testResults
+  if (obj.testResults !== undefined) {
+    if (typeof obj.testResults !== 'object' || obj.testResults === null) {
+      throw new Error(
+        `Invalid EvaluateResult: 'testResults' must be an object if present, got ${
+          obj.testResults === null ? 'null' : typeof obj.testResults
+        }`
+      )
+    }
+
+    const testResults = obj.testResults as Record<string, unknown>
+
+    if (typeof testResults.total !== 'number') {
+      throw new Error(
+        `Invalid EvaluateResult: testResults.total must be a number, got ${typeof testResults.total}`
+      )
+    }
+
+    if (typeof testResults.passed !== 'number') {
+      throw new Error(
+        `Invalid EvaluateResult: testResults.passed must be a number, got ${typeof testResults.passed}`
+      )
+    }
+
+    if (typeof testResults.failed !== 'number') {
+      throw new Error(
+        `Invalid EvaluateResult: testResults.failed must be a number, got ${typeof testResults.failed}`
+      )
+    }
+
+    if (typeof testResults.skipped !== 'number') {
+      throw new Error(
+        `Invalid EvaluateResult: testResults.skipped must be a number, got ${typeof testResults.skipped}`
+      )
+    }
+
+    if (typeof testResults.duration !== 'number') {
+      throw new Error(
+        `Invalid EvaluateResult: testResults.duration must be a number, got ${typeof testResults.duration}`
+      )
+    }
+
+    if (!Array.isArray(testResults.tests)) {
+      throw new Error(
+        `Invalid EvaluateResult: testResults.tests must be an array, got ${typeof testResults.tests}`
+      )
+    }
+
+    // Validate each test result
+    for (let i = 0; i < testResults.tests.length; i++) {
+      const test = testResults.tests[i]
+      if (typeof test !== 'object' || test === null) {
+        throw new Error(
+          `Invalid EvaluateResult: testResults.tests[${i}] must be an object, got ${
+            test === null ? 'null' : typeof test
+          }`
+        )
+      }
+
+      const testObj = test as Record<string, unknown>
+
+      if (typeof testObj.name !== 'string') {
+        throw new Error(
+          `Invalid EvaluateResult: testResults.tests[${i}].name must be a string, got ${typeof testObj.name}`
+        )
+      }
+
+      if (typeof testObj.passed !== 'boolean') {
+        throw new Error(
+          `Invalid EvaluateResult: testResults.tests[${i}].passed must be a boolean, got ${typeof testObj.passed}`
+        )
+      }
+
+      if (typeof testObj.duration !== 'number') {
+        throw new Error(
+          `Invalid EvaluateResult: testResults.tests[${i}].duration must be a number, got ${typeof testObj.duration}`
+        )
+      }
+
+      if (testObj.error !== undefined && typeof testObj.error !== 'string') {
+        throw new Error(
+          `Invalid EvaluateResult: testResults.tests[${i}].error must be a string if present, got ${typeof testObj.error}`
+        )
+      }
+    }
+  }
+}

package/src/types.ts

@@ -24,6 +24,17 @@ export interface SDKConfig {
   aiGatewayToken?: string
 }
 
+/**
+ * Network access configuration
+ *
+ * @example
+ * fetch: true           // allow all (default)
+ * fetch: false          // block all
+ * fetch: null           // block all (backwards compat)
+ * fetch: ['api.example.com', '*.trusted.com']  // allowlist with wildcards
+ */
+export type FetchConfig = boolean | null | string[]
+
 /**
  * Options for evaluate()
  */
@@ -38,8 +49,13 @@ export interface EvaluateOptions {
   timeout?: number | undefined
   /** Environment variables to pass to the sandbox */
   env?: Record<string, string> | undefined
-  /** Fetch configuration. Set to null to block network access. Default: allowed */
-  fetch?: null | undefined
+  /**
+   * Network access control
+   * - true: allow all (default)
+   * - false/null: block all
+   * - string[]: allowlist of domains (wildcards: '*.example.com')
+   */
+  fetch?: FetchConfig
   /** RPC services to expose via capnweb (URL -> handler) */
   rpc?: Record<string, unknown> | undefined
   /** Outbound RPC interceptor - intercepts fetch calls to RPC URLs */

package/src/validation.ts

@@ -0,0 +1,120 @@
+/**
+ * Input validation for EvaluateOptions
+ *
+ * Validates options to prevent resource exhaustion and provide clear error messages.
+ */
+
+import type { EvaluateOptions } from './types.js'
+
+/**
+ * Validation limits for EvaluateOptions
+ */
+export const MAX_SCRIPT_SIZE = 1024 * 1024 // 1MB
+export const MAX_IMPORTS = 100
+export const MAX_TIMEOUT = 60000 // 60 seconds
+export const DEFAULT_TIMEOUT = 5000 // 5 seconds
+
+/**
+ * Validation error thrown when options fail validation
+ */
+export class ValidationError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'ValidationError'
+  }
+}
+
+/**
+ * Validate a URL string
+ */
+function isValidUrl(urlString: string): boolean {
+  try {
+    const url = new URL(urlString)
+    return url.protocol === 'http:' || url.protocol === 'https:'
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Validate EvaluateOptions
+ *
+ * @throws ValidationError if any validation fails
+ */
+export function validateOptions(options: EvaluateOptions): void {
+  // Validate timeout
+  if (options.timeout !== undefined) {
+    if (typeof options.timeout !== 'number') {
+      throw new ValidationError('timeout must be a number')
+    }
+    if (!Number.isFinite(options.timeout)) {
+      throw new ValidationError('timeout must be a finite number')
+    }
+    if (options.timeout <= 0) {
+      throw new ValidationError('timeout must be a positive number')
+    }
+    if (options.timeout > MAX_TIMEOUT) {
+      throw new ValidationError(`timeout exceeds maximum allowed value of ${MAX_TIMEOUT}ms`)
+    }
+  }
+
+  // Validate script length
+  if (options.script !== undefined && options.script !== null) {
+    if (typeof options.script !== 'string') {
+      throw new ValidationError('script must be a string')
+    }
+    const scriptBytes = new TextEncoder().encode(options.script).length
+    if (scriptBytes > MAX_SCRIPT_SIZE) {
+      throw new ValidationError(
+        `script size (${scriptBytes} bytes) exceeds maximum allowed size of ${MAX_SCRIPT_SIZE} bytes (1MB)`
+      )
+    }
+  }
+
+  // Validate module length
+  if (options.module !== undefined && options.module !== null) {
+    if (typeof options.module !== 'string') {
+      throw new ValidationError('module must be a string')
+    }
+    const moduleBytes = new TextEncoder().encode(options.module).length
+    if (moduleBytes > MAX_SCRIPT_SIZE) {
+      throw new ValidationError(
+        `module size (${moduleBytes} bytes) exceeds maximum allowed size of ${MAX_SCRIPT_SIZE} bytes (1MB)`
+      )
+    }
+  }
+
+  // Validate tests length
+  if (options.tests !== undefined && options.tests !== null) {
+    if (typeof options.tests !== 'string') {
+      throw new ValidationError('tests must be a string')
+    }
+    const testsBytes = new TextEncoder().encode(options.tests).length
+    if (testsBytes > MAX_SCRIPT_SIZE) {
+      throw new ValidationError(
+        `tests size (${testsBytes} bytes) exceeds maximum allowed size of ${MAX_SCRIPT_SIZE} bytes (1MB)`
+      )
+    }
+  }
+
+  // Validate imports
+  if (options.imports !== undefined && options.imports !== null) {
+    if (!Array.isArray(options.imports)) {
+      throw new ValidationError('imports must be an array')
+    }
+    if (options.imports.length > MAX_IMPORTS) {
+      throw new ValidationError(
+        `imports count (${options.imports.length}) exceeds maximum allowed count of ${MAX_IMPORTS}`
+      )
+    }
+    for (let i = 0; i < options.imports.length; i++) {
+      const importUrl = options.imports[i]
+      if (typeof importUrl !== 'string') {
+        throw new ValidationError(`imports[${i}] must be a string`)
+      }
+      if (!isValidUrl(importUrl)) {
+        throw new ValidationError(`imports[${i}] is not a valid URL: ${importUrl}`)
+      }
+    }
+  }
+}

package/src/worker-template/code-transforms.ts

@@ -0,0 +1,32 @@
+/**
+ * Module transformation and export detection utilities
+ */
+
+/**
+ * Transform module code to work in sandbox
+ * Converts ES module exports to CommonJS-style for the sandbox
+ */
+export function transformModuleCode(moduleCode: string): string {
+  let code = moduleCode
+
+  // Transform: export const foo = ... -> const foo = ...; exports.foo = foo;
+  code = code.replace(/export\s+(const|let|var)\s+(\w+)\s*=/g, '$1 $2 = exports.$2 =')
+
+  // Transform: export function foo(...) -> function foo(...) exports.foo = foo;
+  // Also handles async generators: export async function* foo
+  code = code.replace(/export\s+(async\s+)?function(\*?)\s+(\w+)/g, '$1function$2 $3')
+  // Add exports for functions after their definition
+  const funcNames = [...moduleCode.matchAll(/export\s+(?:async\s+)?function\*?\s+(\w+)/g)]
+  for (const [, name] of funcNames) {
+    code += `\nexports.${name} = ${name};`
+  }
+
+  // Transform: export class Foo -> class Foo; exports.Foo = Foo;
+  code = code.replace(/export\s+class\s+(\w+)/g, 'class $1')
+  const classNames = [...moduleCode.matchAll(/export\s+class\s+(\w+)/g)]
+  for (const [, name] of classNames) {
+    code += `\nexports.${name} = ${name};`
+  }
+
+  return code
+}