@vinkius-core/mcp-fusion 2.12.0 → 2.13.1

package/dist/sandbox/SandboxGuard.js

@@ -0,0 +1,90 @@
+/**
+ * SandboxGuard — Fail-Fast Syntax Checker for LLM-Provided Code
+ *
+ * Provides quick feedback BEFORE sending code to the isolated-vm engine.
+ * This is NOT a security boundary — security comes from the empty V8
+ * Context (no `process`, `require`, `fs`, or `globalThis` injected).
+ *
+ * Purpose:
+ * - Validate that the code is syntactically valid JavaScript
+ * - Check that it looks like a function expression / arrow function
+ * - Provide fast, descriptive error messages to the LLM
+ *
+ * Properties:
+ * - Zero runtime dependencies (pure string analysis)
+ * - Fail-fast: rejects obviously broken code before V8 boot
+ * - NOT a security gate (LLMs can obfuscate; the Isolate is the real wall)
+ *
+ * @module
+ * @internal
+ */
+// ── Constants ────────────────────────────────────────────
+/**
+ * Patterns that indicate the code is NOT a pure function.
+ * These are fail-fast hints, not security barriers.
+ * The V8 Isolate with an empty Context is the real security wall.
+ */
+const SUSPICIOUS_PATTERNS = [
+    { pattern: /\bimport\s*\(/, reason: 'Dynamic import() is not available in the sandbox.' },
+    { pattern: /\bimport\s+/, reason: 'ES module imports are not available in the sandbox.' },
+    { pattern: /\brequire\s*\(/, reason: 'require() is not available in the sandbox.' },
+];
+/**
+ * The code must start with one of these patterns to be recognized
+ * as a function expression or arrow function.
+ */
+const FUNCTION_PATTERNS = [
+    /^\s*\(.*\)\s*=>/s, // (x) => ...
+    /^\s*[a-zA-Z_$]\w*\s*=>/, // x => ...
+    /^\s*function\s*\(/, // function(x) { ... }
+    /^\s*function\s+\w+\s*\(/, // function name(x) { ... }
+    /^\s*async\s+\(.*\)\s*=>/s, // async (x) => ...
+    /^\s*async\s+function\s*\(/, // async function(x) { ... }
+    /^\s*async\s+[a-zA-Z_$]\w*\s*=>/, // async x => ...
+];
+// ── Guard Implementation ─────────────────────────────────
+/**
+ * Validate LLM-provided code before sending it to the sandbox.
+ *
+ * Performs two checks:
+ * 1. **Shape check**: The code must look like a function expression
+ * 2. **Suspicious pattern check**: Fail-fast for obviously unsandboxable patterns
+ *
+ * @param code - The JavaScript code string from the LLM
+ * @returns A `GuardResult` indicating whether the code passed
+ *
+ * @example
+ * ```typescript
+ * const result = validateSandboxCode('(data) => data.filter(d => d.x > 5)');
+ * // { ok: true }
+ *
+ * const bad = validateSandboxCode('require("fs").readFileSync("/etc/passwd")');
+ * // { ok: false, violation: 'Code must be a function expression...' }
+ * ```
+ */
+export function validateSandboxCode(code) {
+    if (!code || typeof code !== 'string') {
+        return { ok: false, violation: 'Code must be a non-empty string.' };
+    }
+    const trimmed = code.trim();
+    if (trimmed.length === 0) {
+        return { ok: false, violation: 'Code must be a non-empty string.' };
+    }
+    // Shape check: must look like a function
+    const looksLikeFunction = FUNCTION_PATTERNS.some(p => p.test(trimmed));
+    if (!looksLikeFunction) {
+        return {
+            ok: false,
+            violation: 'Code must be a function expression or arrow function. ' +
+                'Example: (data) => data.filter(d => d.value > 10)',
+        };
+    }
+    // Suspicious pattern check (fail-fast hints, not security)
+    for (const { pattern, reason } of SUSPICIOUS_PATTERNS) {
+        if (pattern.test(trimmed)) {
+            return { ok: false, violation: reason };
+        }
+    }
+    return { ok: true };
+}
+//# sourceMappingURL=SandboxGuard.js.map

package/dist/sandbox/SandboxGuard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SandboxGuard.js","sourceRoot":"","sources":["../../src/sandbox/SandboxGuard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAWH,4DAA4D;AAE5D;;;;GAIG;AACH,MAAM,mBAAmB,GAAuD;IAC5E,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,mDAAmD,EAAE;IACzF,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,qDAAqD,EAAE;IACzF,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,4CAA4C,EAAE;CACtF,CAAC;AAEF;;;GAGG;AACH,MAAM,iBAAiB,GAA0B;IAC7C,kBAAkB,EAAe,aAAa;IAC9C,wBAAwB,EAAQ,WAAW;IAC3C,mBAAmB,EAAc,sBAAsB;IACvD,yBAAyB,EAAQ,2BAA2B;IAC5D,0BAA0B,EAAO,mBAAmB;IACpD,2BAA2B,EAAM,4BAA4B;IAC7D,gCAAgC,EAAE,iBAAiB;CACtD,CAAC;AAEF,4DAA4D;AAE5D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC5C,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACpC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,kCAAkC,EAAE,CAAC;IACxE,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAE5B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,kCAAkC,EAAE,CAAC;IACxE,CAAC;IAED,yCAAyC;IACzC,MAAM,iBAAiB,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;IACvE,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACrB,OAAO;YACH,EAAE,EAAE,KAAK;YACT,SAAS,EACL,wDAAwD;gBACxD,mDAAmD;SAC1D,CAAC;IACN,CAAC;IAED,2DAA2D;IAC3D,KAAK,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,mBAAmB,EAAE,CAAC;QACpD,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YACxB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;QAC5C,CAAC;IACL,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACxB,CAAC"}

package/dist/sandbox/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Sandbox — Barrel Export
+ *
+ * Zero-Trust Computation Delegation via isolated-vm.
+ * Allows LLMs to send JavaScript functions to be executed
+ * in a sealed V8 isolate on the client's machine.
+ *
+ * The `isolated-vm` package is an optional peerDependency.
+ * The framework works fully without it — sandbox is a power add-on.
+ */
+export { SandboxEngine } from './SandboxEngine.js';
+export type { SandboxConfig, SandboxResult, SandboxErrorCode } from './SandboxEngine.js';
+export { validateSandboxCode } from './SandboxGuard.js';
+export type { GuardResult } from './SandboxGuard.js';
+/**
+ * System instruction auto-injected into the tool description
+ * when `.sandboxed()` is used. Teaches the LLM how to send
+ * JavaScript functions for server-side computation delegation.
+ *
+ * @internal
+ */
+export declare const SANDBOX_SYSTEM_INSTRUCTION: string;
+//# sourceMappingURL=index.d.ts.map

package/dist/sandbox/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sandbox/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACzF,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAIrD;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,QAKiC,CAAC"}

package/dist/sandbox/index.js

@@ -0,0 +1,26 @@
+/**
+ * Sandbox — Barrel Export
+ *
+ * Zero-Trust Computation Delegation via isolated-vm.
+ * Allows LLMs to send JavaScript functions to be executed
+ * in a sealed V8 isolate on the client's machine.
+ *
+ * The `isolated-vm` package is an optional peerDependency.
+ * The framework works fully without it — sandbox is a power add-on.
+ */
+export { SandboxEngine } from './SandboxEngine.js';
+export { validateSandboxCode } from './SandboxGuard.js';
+// ── HATEOAS Auto-Prompting Instruction ───────────────────
+/**
+ * System instruction auto-injected into the tool description
+ * when `.sandboxed()` is used. Teaches the LLM how to send
+ * JavaScript functions for server-side computation delegation.
+ *
+ * @internal
+ */
+export const SANDBOX_SYSTEM_INSTRUCTION = '\n\n[SYSTEM: This tool supports Zero-Trust Compute. ' +
+    'You MUST pass a valid, pure, synchronous JavaScript arrow function as a string ' +
+    'to filter/map the data on the server before receiving it. ' +
+    'E.g.: (data) => data.filter(d => d.value > 10). ' +
+    'Do not use markdown formatting, async/await, or external imports.]';
+//# sourceMappingURL=index.js.map

package/dist/sandbox/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sandbox/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAGxD,4DAA4D;AAE5D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,0BAA0B,GACnC,sDAAsD;IACtD,iFAAiF;IACjF,4DAA4D;IAC5D,kDAAkD;IAClD,oEAAoE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@vinkius-core/mcp-fusion",
-    "version": "2.12.0",
+    "version": "2.13.1",
     "description": "MVA (Model-View-Agent) framework for the Model Context Protocol. Structured perception packages with Presenters, cognitive guardrails, self-healing errors, action consolidation, and tRPC-style type safety — so AI agents perceive and act on your data deterministically.",
     "type": "module",
     "main": "dist/index.js",
@@ -52,6 +52,10 @@
         "./introspection": {
             "import": "./dist/introspection/index.js",
             "types": "./dist/introspection/index.d.ts"
+        },
+        "./sandbox": {
+            "import": "./dist/sandbox/index.js",
+            "types": "./dist/sandbox/index.d.ts"
         }
     },
     "scripts": {
@@ -108,11 +112,19 @@
     },
     "peerDependencies": {
         "@modelcontextprotocol/sdk": "^1.12.1",
+        "fast-json-stringify": "^6.0.0",
+        "isolated-vm": "^5.0.4",
         "zod": "^3.25.1 || ^4.0.0"
     },
     "peerDependenciesMeta": {
         "zod": {
             "optional": true
+        },
+        "isolated-vm": {
+            "optional": true
+        },
+        "fast-json-stringify": {
+            "optional": true
         }
     },
     "license": "Apache-2.0"