@papicandela/mcx-core 0.2.2 → 0.2.6

package/src/sandbox/bun-worker.ts

@@ -120,16 +120,19 @@ export class BunWorkerSandbox implements ISandbox {
       const worker = new Worker(url);
 
       let resolved = false;
+      let timeoutId: ReturnType<typeof setTimeout> | undefined;
+
       const cleanup = () => {
         if (!resolved) {
           resolved = true;
+          if (timeoutId) clearTimeout(timeoutId);
           worker.terminate();
           URL.revokeObjectURL(url);
         }
       };
 
       // Timeout handler
-      const timeoutId = setTimeout(() => {
+      timeoutId = setTimeout(() => {
         if (!resolved) {
           cleanup();
           resolve({
@@ -142,6 +145,9 @@ export class BunWorkerSandbox implements ISandbox {
       }, this.config.timeout);
 
       worker.onmessage = async (event: MessageEvent) => {
+        // Guard against stale messages after resolution
+        if (resolved) return;
+
         const { type, ...data } = event.data;
 
         if (type === "ready") {
@@ -164,7 +170,6 @@ export class BunWorkerSandbox implements ISandbox {
         }
 
         else if (type === "result") {
-          clearTimeout(timeoutId);
           cleanup();
           resolve({
             success: data.success,
@@ -177,7 +182,6 @@ export class BunWorkerSandbox implements ISandbox {
       };
 
       worker.onerror = (error: ErrorEvent) => {
-        clearTimeout(timeoutId);
         cleanup();
         resolve({
           success: false,
@@ -211,11 +215,27 @@ export class BunWorkerSandbox implements ISandbox {
       const pendingCalls = new Map();
       let callId = 0;
 
+      // Safe stringify that handles BigInt and circular refs
+      const safeStr = (val) => {
+        if (typeof val !== 'object' || val === null) return String(val);
+        try {
+          const seen = new WeakSet();
+          return JSON.stringify(val, (k, v) => {
+            if (typeof v === 'bigint') return v.toString() + 'n';
+            if (typeof v === 'object' && v !== null) {
+              if (seen.has(v)) return '[Circular]';
+              seen.add(v);
+            }
+            return v;
+          });
+        } catch { return String(val); }
+      };
+
       const console = {
-        log: (...args) => logs.push(args.map(a => typeof a === 'object' ? JSON.stringify(a) : String(a)).join(' ')),
-        warn: (...args) => logs.push('[WARN] ' + args.map(a => typeof a === 'object' ? JSON.stringify(a) : String(a)).join(' ')),
-        error: (...args) => logs.push('[ERROR] ' + args.map(a => typeof a === 'object' ? JSON.stringify(a) : String(a)).join(' ')),
-        info: (...args) => logs.push('[INFO] ' + args.map(a => typeof a === 'object' ? JSON.stringify(a) : String(a)).join(' ')),
+        log: (...args) => logs.push(args.map(safeStr).join(' ')),
+        warn: (...args) => logs.push('[WARN] ' + args.map(safeStr).join(' ')),
+        error: (...args) => logs.push('[ERROR] ' + args.map(safeStr).join(' ')),
+        info: (...args) => logs.push('[INFO] ' + args.map(safeStr).join(' ')),
       };
       globalThis.console = console;
 
@@ -265,25 +285,73 @@ export class BunWorkerSandbox implements ISandbox {
         return arr.slice(0, n);
       };
 
+      // SECURITY: Reserved keys that must not be overwritten by user-provided variables/globals
+      const RESERVED_KEYS = new Set([
+        'onmessage', 'postMessage', 'close', 'terminate', 'self',
+        'constructor', 'prototype', '__proto__',
+        'pendingCalls', 'callId', 'logs', 'console', 'adapters',
+        'fetch', 'XMLHttpRequest', 'WebSocket', 'EventSource',
+        'pick', 'table', 'count', 'sum', 'first', 'safeStr'
+      ]);
+
       self.onmessage = async (event) => {
         const { type, data } = event.data;
 
         if (type === 'init') {
           const { variables, adapterMethods, globals } = data;
 
+          // Inject user variables (skip reserved keys to prevent internal state corruption)
           for (const [key, value] of Object.entries(variables || {})) {
+            if (RESERVED_KEYS.has(key)) {
+              logs.push('[WARN] Skipped reserved variable key: ' + key);
+              continue;
+            }
             globalThis[key] = value;
           }
 
+          // Inject sandbox globals (skip reserved keys)
           for (const [key, value] of Object.entries(globals || {})) {
+            if (RESERVED_KEYS.has(key)) {
+              logs.push('[WARN] Skipped reserved globals key: ' + key);
+              continue;
+            }
             globalThis[key] = value;
           }
 
-          globalThis.adapters = {};
+          // Levenshtein distance for fuzzy matching
+          const levenshtein = (a, b) => {
+            if (a.length === 0) return b.length;
+            if (b.length === 0) return a.length;
+            const matrix = [];
+            for (let i = 0; i <= b.length; i++) matrix[i] = [i];
+            for (let j = 0; j <= a.length; j++) matrix[0][j] = j;
+            for (let i = 1; i <= b.length; i++) {
+              for (let j = 1; j <= a.length; j++) {
+                matrix[i][j] = b[i-1] === a[j-1]
+                  ? matrix[i-1][j-1]
+                  : Math.min(matrix[i-1][j-1] + 1, matrix[i][j-1] + 1, matrix[i-1][j] + 1);
+              }
+            }
+            return matrix[b.length][a.length];
+          };
+
+          // Find similar method names
+          const findSimilar = (name, methods, maxDist = 3) => {
+            const normalized = name.toLowerCase().replace(/[-_]/g, '');
+            return methods
+              .map(m => ({ method: m, dist: levenshtein(normalized, m.toLowerCase().replace(/[-_]/g, '')) }))
+              .filter(x => x.dist <= maxDist)
+              .sort((a, b) => a.dist - b.dist)
+              .slice(0, 3)
+              .map(x => x.method);
+          };
+
+          // Create adapter proxies with helpful error messages
+          const adaptersObj = {};
           for (const [adapterName, methods] of Object.entries(adapterMethods)) {
-            const adapterObj = {};
+            const methodsImpl = {};
             for (const methodName of methods) {
-              adapterObj[methodName] = async (...args) => {
+              methodsImpl[methodName] = async (...args) => {
                 const id = ++callId;
                 return new Promise((resolve, reject) => {
                   pendingCalls.set(id, { resolve, reject });
@@ -297,9 +365,33 @@ export class BunWorkerSandbox implements ISandbox {
                 });
               };
             }
-            globalThis.adapters[adapterName] = adapterObj;
-            globalThis[adapterName] = adapterObj;
+
+            // Use Proxy to intercept undefined method calls
+            const adapterProxy = new Proxy(methodsImpl, {
+              get(target, prop) {
+                if (prop in target) return target[prop];
+                if (typeof prop === 'symbol') return undefined;
+                const similar = findSimilar(String(prop), methods);
+                const suggestion = similar.length > 0
+                  ? '. Did you mean: ' + similar.join(', ') + '?'
+                  : '. Available: ' + methods.slice(0, 5).join(', ') + (methods.length > 5 ? '...' : '');
+                throw new Error(adapterName + '.' + String(prop) + ' is not a function' + suggestion);
+              }
+            });
+
+            adaptersObj[adapterName] = adapterProxy;
+            // Also expose at top level but as non-writable
+            Object.defineProperty(globalThis, adapterName, {
+              value: adapterProxy,
+              writable: false,
+              configurable: false
+            });
           }
+          Object.defineProperty(globalThis, 'adapters', {
+            value: adaptersObj,
+            writable: false,
+            configurable: false
+          });
 
           self.postMessage({ type: 'ready' });
         }
@@ -322,10 +414,12 @@ export class BunWorkerSandbox implements ISandbox {
             const result = await fn();
             self.postMessage({ type: 'result', success: true, value: result, logs });
           } catch (err) {
+            // Truncate stack to 5 lines to prevent context bloat
+            const stack = err.stack ? err.stack.split('\\n').slice(0, 5).join('\\n') : undefined;
             self.postMessage({
               type: 'result',
               success: false,
-              error: { name: err.name, message: err.message, stack: err.stack },
+              error: { name: err.name, message: err.message, stack },
               logs
             });
           }

package/src/sandbox/network-policy.ts

@@ -75,83 +75,139 @@ export function generateNetworkIsolationCode(policy: NetworkPolicy): string {
   }
 
   if (policy.mode === "blocked") {
+    // SECURITY: Wrap in IIFE to prevent user code from accessing __original_fetch
+    // Use Object.defineProperty with writable:false to prevent user code from overwriting
     return `
 // Network isolation: BLOCKED
-const __original_fetch = globalThis.fetch;
-globalThis.fetch = async function(url, options) {
-  throw new Error('Network access is blocked in sandbox. Use adapters instead.');
-};
+(function() {
+  const blockedFetch = async function() {
+    throw new Error('Network access is blocked in sandbox. Use adapters instead.');
+  };
+  Object.defineProperty(globalThis, 'fetch', {
+    value: blockedFetch,
+    writable: false,
+    configurable: false
+  });
+})();
 
 // Block XMLHttpRequest
-globalThis.XMLHttpRequest = class {
-  constructor() {
-    throw new Error('XMLHttpRequest is blocked in sandbox.');
-  }
-};
+Object.defineProperty(globalThis, 'XMLHttpRequest', {
+  value: class {
+    constructor() {
+      throw new Error('XMLHttpRequest is blocked in sandbox.');
+    }
+  },
+  writable: false,
+  configurable: false
+});
 
 // Block WebSocket
-globalThis.WebSocket = class {
-  constructor(url) {
-    throw new Error('WebSocket is blocked in sandbox.');
-  }
-};
+Object.defineProperty(globalThis, 'WebSocket', {
+  value: class {
+    constructor() {
+      throw new Error('WebSocket is blocked in sandbox.');
+    }
+  },
+  writable: false,
+  configurable: false
+});
 
 // Block EventSource (SSE)
-globalThis.EventSource = class {
-  constructor(url) {
-    throw new Error('EventSource is blocked in sandbox.');
-  }
-};
+Object.defineProperty(globalThis, 'EventSource', {
+  value: class {
+    constructor() {
+      throw new Error('EventSource is blocked in sandbox.');
+    }
+  },
+  writable: false,
+  configurable: false
+});
 `;
   }
 
   // mode === 'allowed' - whitelist specific domains
+  // SECURITY: Wrap in IIFE to prevent user code from accessing internals
+  // Use Object.defineProperty with writable:false to prevent user code from overwriting
   const domainsJson = JSON.stringify(policy.domains);
   return `
 // Network isolation: ALLOWED (whitelist)
-const __allowed_domains = ${domainsJson};
-const __original_fetch = globalThis.fetch;
+(function() {
+  const _domains = ${domainsJson};
+  const _real_fetch = globalThis.fetch;
 
-function __isUrlAllowed(url) {
-  try {
-    const hostname = new URL(url).hostname;
-    return __allowed_domains.some(d => hostname === d || hostname.endsWith('.' + d));
-  } catch {
-    return false;
+  // Block private/link-local IPs to prevent DNS rebinding attacks
+  function _isPrivateIp(hostname) {
+    return /^(localhost|127\\.|10\\.|192\\.168\\.|172\\.(1[6-9]|2\\d|3[01])\\.|169\\.254\\.|\\[::1\\]|\\[fc|\\[fd)/.test(hostname);
   }
-}
 
-globalThis.fetch = async function(url, options) {
-  const urlStr = typeof url === 'string' ? url : url instanceof URL ? url.toString() : url.url;
-  if (!__isUrlAllowed(urlStr)) {
-    const hostname = new URL(urlStr).hostname;
-    throw new Error(\`Network access blocked: \${hostname} not in allowed domains: \${__allowed_domains.join(', ')}\`);
+  function _isUrlAllowed(url) {
+    try {
+      const parsed = new URL(url);
+      // Only allow http/https protocols
+      if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') return false;
+      const hostname = parsed.hostname;
+      if (!hostname || _isPrivateIp(hostname)) return false;
+      return _domains.some(d => d && (hostname === d || hostname.endsWith('.' + d)));
+    } catch {
+      return false;
+    }
   }
-  return __original_fetch(url, options);
-};
 
-// Block XMLHttpRequest (not easily whitelistable)
-globalThis.XMLHttpRequest = class {
-  constructor() {
-    throw new Error('XMLHttpRequest is blocked. Use fetch() with allowed domains.');
-  }
-};
+  const whitelistedFetch = async function(url, options) {
+    // Safely extract URL string from various input types
+    let urlStr;
+    try {
+      if (typeof url === 'string') urlStr = url;
+      else if (url instanceof URL) urlStr = url.toString();
+      else if (url && typeof url.url === 'string') urlStr = url.url;
+      else throw new Error('Invalid URL type');
+    } catch {
+      throw new Error('Network access blocked: could not determine request URL.');
+    }
+    if (!_isUrlAllowed(urlStr)) {
+      throw new Error('Network access blocked: domain not in allowed list.');
+    }
+    return _real_fetch(url, options);
+  };
+
+  Object.defineProperty(globalThis, 'fetch', {
+    value: whitelistedFetch,
+    writable: false,
+    configurable: false
+  });
+})();
 
-// Block WebSocket (would need separate whitelist)
-globalThis.WebSocket = class {
-  constructor(url) {
-    if (!__isUrlAllowed(url)) {
-      throw new Error('WebSocket blocked: domain not in allowed list.');
+// Block XMLHttpRequest (not easily whitelistable)
+Object.defineProperty(globalThis, 'XMLHttpRequest', {
+  value: class {
+    constructor() {
+      throw new Error('XMLHttpRequest is blocked. Use fetch() with allowed domains.');
     }
-    throw new Error('WebSocket not supported in sandbox even for allowed domains.');
-  }
-};
+  },
+  writable: false,
+  configurable: false
+});
+
+// Block WebSocket - opaque error to prevent allowlist enumeration
+Object.defineProperty(globalThis, 'WebSocket', {
+  value: class {
+    constructor() {
+      throw new Error('WebSocket is not supported in sandbox.');
+    }
+  },
+  writable: false,
+  configurable: false
+});
 
 // Block EventSource
-globalThis.EventSource = class {
-  constructor(url) {
-    throw new Error('EventSource is blocked in sandbox.');
-  }
-};
+Object.defineProperty(globalThis, 'EventSource', {
+  value: class {
+    constructor() {
+      throw new Error('EventSource is blocked in sandbox.');
+    }
+  },
+  writable: false,
+  configurable: false
+});
 `;
 }

package/src/type-generator.ts

@@ -48,7 +48,8 @@ export function generateTypes(
     // Generate input interface for each tool with parameters
     for (const [toolName, tool] of Object.entries(adapter.tools)) {
       if (tool.parameters && Object.keys(tool.parameters).length > 0) {
-        const inputTypeName = `${capitalize(safeName)}_${capitalize(toolName)}_Input`;
+        const safeToolNameForType = sanitizeIdentifier(toolName);
+        const inputTypeName = `${capitalize(safeName)}_${capitalize(safeToolNameForType)}_Input`;
         lines.push(generateInputInterface(inputTypeName, tool.parameters, includeDescriptions));
         lines.push("");
       }
@@ -56,17 +57,18 @@ export function generateTypes(
 
     // Generate adapter declaration
     if (includeDescriptions && adapter.description) {
-      lines.push(`/** ${adapter.description} */`);
+      lines.push(`/** ${sanitizeJSDoc(adapter.description)} */`);
     }
     lines.push(`declare const ${safeName}: {`);
 
     for (const [toolName, tool] of Object.entries(adapter.tools)) {
       const safeToolName = sanitizeIdentifier(toolName);
       const hasParams = tool.parameters && Object.keys(tool.parameters).length > 0;
-      const inputTypeName = `${capitalize(safeName)}_${capitalize(toolName)}_Input`;
+      // Use sanitized tool name in type name to ensure consistency
+      const inputTypeName = `${capitalize(safeName)}_${capitalize(safeToolName)}_Input`;
 
       if (includeDescriptions && tool.description) {
-        lines.push(`  /** ${tool.description} */`);
+        lines.push(`  /** ${sanitizeJSDoc(tool.description)} */`);
       }
 
       const paramStr = hasParams ? `params: ${inputTypeName}` : "";
@@ -83,18 +85,76 @@ export function generateTypes(
 
 /**
  * Generate a compact type summary for token-constrained contexts.
- * Returns a condensed one-liner per adapter.
+ * Groups adapters by domain and shows method count.
+ * Use mcx_search to discover specific methods.
  *
  * @param adapters - Array of adapters
- * @returns Compact summary string
+ * @returns Compact summary string with domain hints
  */
 export function generateTypesSummary(adapters: Adapter[]): string {
-  return adapters
-    .map((adapter) => {
-      const methods = Object.keys(adapter.tools).join(", ");
-      return `${adapter.name}: { ${methods} }`;
-    })
-    .join("\n");
+  // Group adapters by domain
+  const byDomain = new Map<string, Adapter[]>();
+
+  for (const adapter of adapters) {
+    const domain = inferDomain(adapter);
+    if (!byDomain.has(domain)) {
+      byDomain.set(domain, []);
+    }
+    byDomain.get(domain)!.push(adapter);
+  }
+
+  // If only one domain or fewer than 4 adapters, simple list
+  if (byDomain.size <= 1 || adapters.length < 4) {
+    return adapters
+      .map((adapter) => {
+        const count = Object.keys(adapter.tools).length;
+        return `- ${adapter.name} (${count} methods)`;
+      })
+      .join("\n");
+  }
+
+  // Group by domain for better discoverability
+  const lines: string[] = [];
+  for (const [domain, domainAdapters] of byDomain) {
+    const adapterList = domainAdapters
+      .map((a) => `${a.name}(${Object.keys(a.tools).length})`)
+      .join(", ");
+    lines.push(`[${domain}] ${adapterList}`);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Infer domain from adapter name/description if not explicitly set.
+ * Returns the adapter's explicit domain if set, otherwise infers from name/description.
+ */
+export function inferDomain(adapter: Adapter): string {
+  if (adapter.domain) return adapter.domain;
+
+  const name = adapter.name.toLowerCase();
+  const desc = (adapter.description || "").toLowerCase();
+  const combined = `${name} ${desc}`;
+
+  const domains: Record<string, string[]> = {
+    payments: ["stripe", "paypal", "square", "payment", "checkout", "billing", "invoice"],
+    database: ["supabase", "postgres", "mysql", "mongodb", "redis", "database", "sql", "query"],
+    email: ["sendgrid", "mailgun", "postmark", "email", "smtp", "mail"],
+    storage: ["s3", "cloudflare", "storage", "blob", "file", "upload"],
+    auth: ["auth", "oauth", "login", "jwt", "clerk", "auth0"],
+    ai: ["openai", "anthropic", "claude", "gpt", "llm", "ai", "ml"],
+    messaging: ["slack", "discord", "telegram", "twilio", "sms", "chat"],
+    crm: ["hubspot", "salesforce", "crm", "customer"],
+    analytics: ["analytics", "metrics", "tracking", "mixpanel", "amplitude"],
+    devtools: ["github", "gitlab", "jira", "linear", "chrome", "devtools", "ci", "cd"],
+  };
+
+  for (const [domain, keywords] of Object.entries(domains)) {
+    if (keywords.some((k) => combined.includes(k))) {
+      return domain;
+    }
+  }
+
+  return "general";
 }
 
 /**
@@ -108,13 +168,16 @@ function generateInputInterface(
   const lines: string[] = [`interface ${typeName} {`];
 
   for (const [paramName, param] of Object.entries(parameters)) {
+    // Sanitize parameter name to prevent injection
+    const safeParamName = sanitizeIdentifier(paramName);
+
     if (includeDescriptions && param.description) {
-      lines.push(`  /** ${param.description} */`);
+      lines.push(`  /** ${sanitizeJSDoc(param.description)} */`);
     }
 
     const tsType = paramTypeToTS(param.type);
-    const optional = param.required === false ? "?" : "";
-    lines.push(`  ${paramName}${optional}: ${tsType};`);
+    const optional = param.required === true ? "" : "?";
+    lines.push(`  ${safeParamName}${optional}: ${tsType};`);
   }
 
   lines.push("}");
@@ -170,3 +233,11 @@ export function sanitizeIdentifier(name: string): string {
 function capitalize(str: string): string {
   return str.charAt(0).toUpperCase() + str.slice(1);
 }
+
+/**
+ * Sanitize text for use in JSDoc comments.
+ * Prevents comment injection via `*​/` sequences.
+ */
+function sanitizeJSDoc(text: string): string {
+  return text.replace(/\*\//g, "* /").replace(/[\r\n]+/g, " ");
+}

package/src/types.ts

@@ -12,6 +12,8 @@ export interface ParameterDefinition {
   description?: string;
   required?: boolean;
   default?: unknown;
+  /** Example value for this parameter (helps LLMs understand expected format) */
+  example?: unknown;
 }
 
 /**
@@ -33,6 +35,8 @@ export interface Adapter<TTools extends Record<string, AdapterTool> = Record<str
   name: string;
   description?: string;
   version?: string;
+  /** Domain/category for tool discovery (e.g., 'payments', 'database', 'email') */
+  domain?: string;
   tools: TTools;
   dispose?: () => Promise<void> | void;
 }