ai-evaluate 2.1.6 → 2.1.8

package/src/node.ts

@@ -5,8 +5,15 @@
  * For Workers-only builds, import from 'ai-evaluate' instead.
  */
 
-import type { EvaluateOptions, EvaluateResult, WorkerLoader, SandboxEnv } from './types.js'
-import { generateWorkerCode, generateDevWorkerCode } from './worker-template.js'
+import type {
+  EvaluateOptions,
+  EvaluateResult,
+  WorkerLoader,
+  SandboxEnv,
+  FetchConfig,
+} from './types.js'
+import { generateWorkerCode, generateDevWorkerCode } from './worker-template/index.js'
+import { isDomainAllowed, normalizeImports } from './shared.js'
 
 /**
  * Check if code contains JSX syntax that needs transformation
@@ -60,6 +67,7 @@ export async function evaluate(
       module: transformedModule,
       tests: transformedTests,
       script: transformedScript,
+      imports: normalizeImports(options.imports),
     }
 
     // Use worker_loaders if available (Cloudflare Workers)
@@ -122,6 +130,25 @@ async function evaluateWithWorkerLoader(
   }
 }
 
+/**
+ * Determine if network access should be blocked based on fetch options
+ * fetch: false | null -> block
+ */
+function shouldBlockNetwork(options: EvaluateOptions): boolean {
+  return options.fetch === false || options.fetch === null
+}
+
+/**
+ * Get allowlist domains if fetch is an array
+ * fetch: string[] -> allowlist
+ */
+function getAllowlistDomains(options: EvaluateOptions): string[] | null {
+  if (Array.isArray(options.fetch)) {
+    return options.fetch
+  }
+  return null
+}
+
 /**
  * Evaluate using Miniflare (for Node.js/development)
  */
@@ -140,20 +167,38 @@ async function evaluateWithMiniflare(
     fetch: options.fetch, // Pass fetch option to worker template
   })
 
-  // Block outbound network requests at Miniflare level when fetch: null
-  // This complements the globalThis.fetch override in the worker template
-  const blockNetwork = options.fetch === null
+  // Determine outbound service configuration based on fetch option
+  const blockNetwork = shouldBlockNetwork(options)
+  const allowlistDomains = getAllowlistDomains(options)
+
+  // Build outboundService based on mode:
+  // - block: throw error for all requests
+  // - allowlist: check domain against allowlist
+  // - allow (default): no outboundService (allow all)
+  type OutboundServiceFn = (() => never) | ((request: Request) => Response | Promise<Response>)
+  let outboundService: OutboundServiceFn | undefined
+  if (blockNetwork) {
+    outboundService = () => {
+      throw new Error('Network access blocked: fetch is disabled in this sandbox')
+    }
+  } else if (allowlistDomains) {
+    outboundService = (request: Request) => {
+      const url = request.url
+      if (!isDomainAllowed(url, allowlistDomains)) {
+        const hostname = new URL(url).hostname
+        throw new Error(`Network access blocked: domain not in allowlist. Attempted: ${hostname}`)
+      }
+      // Allow the request by returning a fetched response
+      return fetch(request)
+    }
+  }
 
   const mf = new Miniflare({
     modules: true,
     script: workerCode,
     compatibilityDate: '2026-01-01',
-    // Block all outbound fetch/connect when network is disabled
-    ...(blockNetwork && {
-      outboundService: () => {
-        throw new Error('Network access blocked: fetch is disabled in this sandbox')
-      },
-    }),
+    // Configure outbound service based on fetch mode
+    ...(outboundService && { outboundService }),
   })
 
   try {

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 */