feat(ai-mcp-sandbox): per-tool sandboxing for createMCPServer #2171
tanstack-source added labelsfeature
- docs/mcp/server-sandboxed-tools.md line 56Outdated@@ -0,0 +36,21 @@36+37+<!-- ::end:tabs -->38+39+The driver is swappable. `@tanstack/ai-isolate-quickjs` runs anywhere, including edge runtimes. See [Isolate Drivers](../code-mode/code-mode-isolates) for the others.40+41+Define the facades. A facade is a host function the snippet may call. Secrets and backend URLs live here, in your process, and never enter the isolate:42+43+```ts44+// src/facades.ts45+const ALLOWED = new Set(['https://api.example.com'])46+47+export const facades = {48+ 'http.get': {49+ description: 'GET an allowlisted URL',50+ execute: async (args: unknown) => {51+ if (typeof args !== 'object' || args === null || !('url' in args)) {52+ throw new Error('url is required')53+ }54+ const url = new URL(String(args.url))55+ if (!ALLOWED.has(url.origin)) throw new Error('origin not allowed')56+ const response = await fetch(url, { signal: AbortSignal.timeout(3000) })docs/mcp/server-sandboxed-tools.md line 187Outdated@@ -0,0 +167,21 @@167+import { generateManifestKeyPair, signManifest } from '@tanstack/ai-mcp-sandbox'168+169+const { publicKey, privateKey } = generateManifestKeyPair()170+const signature = signManifest(manifest, privateKey)171+172+sandboxedTool({173+ manifest: { ...manifest, signature },174+ snippet,175+ facades,176+ driver,177+ publicKey,178+ requireSignature: true,179+})180+```181+182+## Import an existing snippet183+184+Turn a plain [Code Mode](../code-mode/code-mode) snippet into a starting manifest with the CLI:185+186+```sh187+npx tanstack-ai-sandbox-import ./my-snippet.jspackages/ai-mcp-sandbox/README.md line 75Outdated@@ -0,0 +55,21 @@55+`@tanstack/ai-isolate-node` (V8), or any other `IsolateDriver`.56+57+## Example58+59+```ts60+import { toolDefinition } from '@tanstack/ai'61+import { createMCPServer } from '@tanstack/ai-mcp/server'62+import { sandboxedTool } from '@tanstack/ai-mcp-sandbox'63+import { createQuickJSIsolateDriver } from '@tanstack/ai-isolate-quickjs'64+65+const driver = createQuickJSIsolateDriver()66+67+// Host-side facade: secrets and backend URLs live here, never in the isolate.68+const facades = {69+ 'http.get': {70+ description: 'GET an allowlisted URL',71+ execute: async (args: unknown) => {72+ if (typeof args !== 'object' || args === null || !('url' in args)) {73+ throw new Error('url is required')74+ }75+ return (await fetch(String(args.url))).text()packages/ai-mcp-sandbox/src/approval.ts line 43Outdated@@ -0,0 +23,21 @@23+24+export class ProposalExpiredError extends Error {25+ constructor() {26+ // Unknown / expired / replayed are indistinguishable on purpose.27+ super('proposal_expired')28+ this.name = 'ProposalExpiredError'29+ }30+}31+32+export interface ApprovalStore {33+ propose: (34+ clientId: string,35+ action: unknown,36+ ) => { proposalId: string; actionHash: string; expiresAtMs: number }37+ consume: (clientId: string, proposalId: string) => unknown38+}39+40+const TTL_MS = 5 * 60 * 100041+42+export function createApprovalStore(ttlMs: number = TTL_MS): ApprovalStore {43+ const pending = new Map<string, Proposal>()packages/ai-mcp-sandbox/src/approval.ts line 53Outdated@@ -0,0 +33,21 @@33+ propose: (34+ clientId: string,35+ action: unknown,36+ ) => { proposalId: string; actionHash: string; expiresAtMs: number }37+ consume: (clientId: string, proposalId: string) => unknown38+}39+40+const TTL_MS = 5 * 60 * 100041+42+export function createApprovalStore(ttlMs: number = TTL_MS): ApprovalStore {43+ const pending = new Map<string, Proposal>()44+ const now = () => Date.now()45+46+ return {47+ propose(clientId, action) {48+ const id = randomBytes(18).toString('hex')49+ const actionHash = createHash('sha256')50+ .update(canonicalize({ clientId, action }), 'utf8')51+ .digest('hex')52+ const expiresAtMs = now() + ttlMs53+ pending.set(id, { id, clientId, action, actionHash, expiresAtMs })packages/ai-mcp-sandbox/src/bin/import.ts line 24Outdated@@ -0,0 +4,21 @@4+import { importSnippet } from '../importer'5+6+/**7+ * tanstack-ai-sandbox-import <snippet.ts> [manifest.json]8+ *9+ * Emits a deny-by-default, unreviewed manifest next to the snippet. The tool is10+ * NOT servable until a human fills the security fields (scope, inject, limits)11+ * and removes `unreviewed`.12+ */13+function main(argv: Array<string>): void {14+ const [snippetPath, outPath] = argv15+ if (!snippetPath) {16+ console.error(17+ 'usage: tanstack-ai-sandbox-import <snippet.ts> [manifest.json]',18+ )19+ process.exit(1)20+ }21+ const snippet = readFileSync(snippetPath, 'utf8')22+ const name = basename(snippetPath, extname(snippetPath))23+ const manifest = importSnippet(snippet, { name })24+ const target = outPath ?? snippetPath.replace(/\.[^.]+$/, '.manifest.json')packages/ai-mcp-sandbox/src/capability.ts line 94Outdated@@ -0,0 +74,21 @@74+ * Prelude evaluated before the snippet: rebuilds the `host.<ns>.<fn>` tree75+ * from the flat bindings and binds `input`. Only allowed facades appear, so76+ * a denied one is simply absent (a call to it throws in-isolate).77+ */78+export function buildPrelude(79+ allowed: ReadonlyArray<string>,80+ input: unknown,81+): string {82+ const lines = ['const host = {};']83+ for (const dotted of allowed) {84+ const parts = dotted.split('.')85+ let path = 'host'86+ for (let i = 0; i < parts.length - 1; i++) {87+ path += `[${JSON.stringify(parts[i])}]`88+ lines.push(`${path} = ${path} || {};`)89+ }90+ lines.push(91+ `${path}[${JSON.stringify(parts[parts.length - 1])}] = ${safeName(dotted)};`,92+ )93+ }94+ lines.push(`const input = ${JSON.stringify(input ?? {})};`)packages/ai-mcp-sandbox/src/manifest.ts line 24Outdated@@ -0,0 +4,21 @@4+ sign as edSign,5+ verify as edVerify,6+} from 'node:crypto'7+import type { Manifest } from './types'8+9+/** Hex SHA-256 of a snippet's source. */10+export function hashSnippet(source: string): string {11+ return createHash('sha256').update(source, 'utf8').digest('hex')12+}13+14+/** Deterministic JSON: object keys sorted recursively so bytes are stable. */15+export function canonicalize(value: unknown): string {16+ return JSON.stringify(sortKeys(value))17+}18+19+function sortKeys(value: unknown): unknown {20+ if (Array.isArray(value)) return value.map(sortKeys)21+ if (value && typeof value === 'object') {22+ const out: Record<string, unknown> = {}23+ for (const key of Object.keys(value as Record<string, unknown>).sort()) {24+ out[key] = sortKeys((value as Record<string, unknown>)[key])packages/ai-mcp-sandbox/src/sandboxed-tool.ts lines 141 to 145Outdated@@ -0,0 +125,21 @@125+ audit('denied', 0, 0, 'scope_denied')126+ throw new ScopeDeniedError(manifest.scope)127+ }128+129+ // 2. Capability set: declared facades ∩ per-client policy.130+ const allowed = resolveAllowed(manifest.inject, facades, authInfo, policy)131+ const counter = makeCallCounter(limits.maxInjectedCalls)132+ const bindings = buildBindings({133+ allowed,134+ facades,135+ authInfo,136+ signal,137+ tick: counter.tick,138+ })139+140+ // 3. Run the snippet with only those bindings, under the merged limits.141+ const ctx = await driver.createContext({142+ bindings,143+ timeout: limits.wallClockMs,144+ memoryLimit: limits.memoryMb,145+ })packages/ai-mcp-sandbox/src/sandboxed-tool.ts lines 154 to 155Outdated@@ -0,0 +135,21 @@135+ authInfo,136+ signal,137+ tick: counter.tick,138+ })139+140+ // 3. Run the snippet with only those bindings, under the merged limits.141+ const ctx = await driver.createContext({142+ bindings,143+ timeout: limits.wallClockMs,144+ memoryLimit: limits.memoryMb,145+ })146+ try {147+ // Raw function-body code: top-level return/await. The driver wraps it148+ // (async IIFE + JSON round-trip), so we must NOT wrap it ourselves.149+ const code = `${buildPrelude(allowed, args)}\n${snippet}`150+ const result = await ctx.execute(code, signal ? { signal } : undefined)151+152+ if (!result.success) {153+ const message = result.error?.message ?? 'execution failed'154+ const limitHit = /timed out|memory|stack/i.test(message)155+ audit(limitHit ? 'limit' : 'error', counter.count, 0, message)
- docs/mcp/server-sandboxed-tools.md line 195Outdated@@ -0,0 +175,21 @@175+const signature = signManifest(manifest, privateKey)176+177+sandboxedTool({178+ manifest: { ...manifest, signature },179+ snippet,180+ facades,181+ driver,182+ publicKey,183+ requireSignature: true,184+})185+```186+187+## Import an existing snippet188+189+Turn a plain [Code Mode](../code-mode/code-mode) snippet into a starting manifest with the CLI:190+191+```sh192+npx --package=@tanstack/ai-mcp-sandbox tanstack-ai-sandbox-import ./my-snippet.js193+```194+195+It writes a deny-by-default manifest: no facades, the tightest limits, and an `unreviewed` flag. `sandboxedTool()` refuses to serve it until you fill in the scope, facades, and limits, then remove the flag. This keeps an unreviewed tool from running by accident.packages/ai-mcp-sandbox/src/bin/import.ts line 32Outdated@@ -0,0 +12,21 @@12+ */13+function main(argv: Array<string>): void {14+ const [snippetPath, outPath] = argv15+ if (!snippetPath) {16+ console.error(17+ 'usage: tanstack-ai-sandbox-import <snippet.ts> [manifest.json]',18+ )19+ process.exit(1)20+ }21+ const snippet = readFileSync(snippetPath, 'utf8')22+ const ext = extname(snippetPath)23+ const name = basename(snippetPath, ext)24+ const manifest = importSnippet(snippet, { name })25+ // Append rather than replace when the snippet has no extension, so we never26+ // write the manifest back over the snippet.27+ const target =28+ outPath ??29+ (ext30+ ? snippetPath.replace(/\.[^.]+$/, '.manifest.json')31+ : `${snippetPath}.manifest.json`)32+ if (resolve(target) === resolve(snippetPath)) {packages/ai-mcp-sandbox/src/sandboxed-tool.ts line 188Outdated@@ -0,0 +168,21 @@168+ // Raw function-body code: top-level return/await. The driver wraps it169+ // (async IIFE + JSON round-trip), so we must NOT wrap it ourselves.170+ const code = `${buildPrelude(allowed, args)}\n${snippet}`171+ const result = await ctx.execute(code, signal ? { signal } : undefined)172+173+ if (!result.success) {174+ const message = result.error?.message ?? 'execution failed'175+ const overBudget = counter.count > limits.maxInjectedCalls176+ audit(classifyFailure(message, overBudget), counter.count, 0, message)177+ audited = true178+ throw new Error(message)179+ }180+181+ // 4. Shape: author-declared truncation + result-size cap.182+ const shaped = shapeResult(183+ result.value,184+ manifest.truncatable,185+ limits.resultBytes,186+ )187+ audit('ok', counter.count, byteLength(shaped))188+ audited = true
github-actions[bot](GitHub profile, opens in a new tab) assignedAlemTuzlak
github-actions[bot](GitHub profile, opens in a new tab) added labelswaiting-on: maintainer
Pushed935a6e1
- docs/mcp/server-sandboxed-tools.md line 62Outdated@@ -0,0 +42,21 @@42+43+```ts44+// src/facades.ts45+const ALLOWED = new Set(['https://api.example.com'])46+47+export const facades = {48+ 'http.get': {49+ description: 'GET an allowlisted URL',50+ execute: async (args: unknown) => {51+ if (typeof args !== 'object' || args === null || !('url' in args)) {52+ throw new Error('url is required')53+ }54+ const url = new URL(String(args.url))55+ if (!ALLOWED.has(url.origin)) throw new Error('origin not allowed')56+ // redirect: 'error' stops an allowed origin from bouncing the request to57+ // an internal address. Without it, fetch follows the redirect for you.58+ const response = await fetch(url, {59+ redirect: 'error',60+ signal: AbortSignal.timeout(3000),61+ })62+ return response.text()docs/mcp/server-sandboxed-tools.md lines 109 to 112Outdated@@ -0,0 +92,21 @@92+ wallClockMs: 5000,93+ memoryMb: 64,94+ maxInjectedCalls: 3,95+ resultBytes: 16384,96+ },97+ truncatable: [],98+ inputSchema: {99+ type: 'object',100+ properties: { url: { type: 'string' } },101+ required: ['url'],102+ },103+ description: 'Fetch a URL and return its length',104+ snippetHash: hashSnippet(snippet),105+} satisfies Manifest106+107+const pageSize = sandboxedTool({ manifest, snippet, facades, driver })108+109+export const server = createMCPServer({110+ name: 'web',111+ version: '1.0.0',112+ tools: [pageSize], // mix freely with plain toolsdocs/mcp/server-sandboxed-tools.md lines 174 to 175Outdated@@ -0,0 +155,21 @@155+sandboxedTool({156+ manifest,157+ snippet,158+ facades,159+ driver,160+ policy: (authInfo, declared) =>161+ authInfo.scopes.includes('web:write') ? declared : [],162+})163+```164+165+## Sign the manifest166+167+The manifest is the security contract. For first-party tools in your repo, the snippet hash is enough. When the manifest comes from somewhere you do not control, sign it so a tampered one is rejected.168+169+Signing uses Ed25519. Pass the public key and require a valid signature:170+171+```ts group=server-sandboxed-tools172+import { generateManifestKeyPair, signManifest } from '@tanstack/ai-mcp-sandbox'173+174+const { publicKey, privateKey } = generateManifestKeyPair()175+const signature = signManifest(manifest, privateKey)docs/mcp/server-sandboxed-tools.md line 201Outdated@@ -0,0 +181,21 @@181+ driver,182+ publicKey,183+ requireSignature: true,184+})185+```186+187+## Import an existing snippet188+189+Turn a plain [Code Mode](../code-mode/code-mode) snippet into a starting manifest with the CLI:190+191+```sh192+npx --package=@tanstack/ai-mcp-sandbox tanstack-ai-sandbox-import ./my-snippet.js193+```194+195+It writes a deny-by-default manifest: a placeholder scope, no facades, the tightest limits, and an `unreviewed` flag. `sandboxedTool()` refuses to serve any manifest that still carries the flag. The flag is the only gate it checks. It does not inspect the scope, facades, or limits, so you must review those yourself and set real values before you remove the flag. This keeps an unreviewed tool from running by accident.196+197+## Lasting writes198+199+A sandboxed tool is a good fit for reads and safe actions. Approval never happens inside the isolate.200+201+For a write that must not run twice, use a two-phase proposal. The first call returns a `proposalId`, and a second call with that id performs the write. `createApprovalStore()` gives you the store: single-use ids, a short expiry, and no surviving proposals after a restart. This works with any MCP host, since it does not rely on a host-side approval prompt.packages/ai-mcp-sandbox/src/approval.ts line 75Outdated@@ -0,0 +55,21 @@55+ if (p.expiresAtMs < t) pending.delete(id)56+ }57+ // After dropping expired entries, if still at the ceiling, evict the58+ // oldest-expiring proposals until there is room for one more.59+ while (pending.size >= MAX_PENDING) {60+ let oldestId: string | undefined61+ let oldestExp = Infinity62+ for (const [id, p] of pending) {63+ if (p.expiresAtMs < oldestExp) {64+ oldestExp = p.expiresAtMs65+ oldestId = id66+ }67+ }68+ if (oldestId === undefined) break69+ pending.delete(oldestId)70+ }71+ }72+73+ return {74+ propose(clientId, action) {75+ prune() // bound the map: expired/overflow proposals never lingerpackages/ai-mcp-sandbox/src/approval.ts line 95Outdated@@ -0,0 +75,21 @@75+ prune() // bound the map: expired/overflow proposals never linger76+ // Snapshot the action so a later mutation of the caller's object cannot77+ // change what phase 2 runs. The hash describes this snapshot.78+ const snapshot = structuredClone(action)79+ const id = randomBytes(18).toString('hex')80+ const actionHash = createHash('sha256')81+ .update(canonicalize({ clientId, action: snapshot }), 'utf8')82+ .digest('hex')83+ const expiresAtMs = now() + ttlMs84+ pending.set(id, {85+ id,86+ clientId,87+ action: snapshot,88+ actionHash,89+ expiresAtMs,90+ })91+ return { proposalId: id, actionHash, expiresAtMs }92+ },93+ consume(clientId, proposalId) {94+ const p = pending.get(proposalId)95+ pending.delete(proposalId) // single-use: gone whether or not it was validpackages/ai-mcp-sandbox/src/sandboxed-tool.ts line 20Outdated@@ -0,0 +1,20 @@1+import { toolDefinition } from '@tanstack/ai'2+import { buildBindings, buildPrelude, resolveAllowed } from './capability'3+import { hashSnippet, verifyManifest } from './manifest'4+import { intersectLimits, makeCallCounter } from './limits'5+import { byteLength, shapeResult } from './result'6+import type { IsolateContext } from '@tanstack/ai-code-mode'7+import type { MCPToolContext } from '@tanstack/ai-mcp/server'8+import type { AuditEntry, Manifest, SandboxedToolConfig, Tier } from './types'9+10+/**11+ * Classify a failed run for the audit outcome. `overCallBudget` comes from the12+ * host counter, which is authoritative for the injected-call limit; wall-clock13+ * and memory trips are matched by the driver's error text.14+ */15+function classifyFailure(16+ message: string,17+ overCallBudget: boolean,18+): AuditEntry['outcome'] {19+ if (overCallBudget) return 'limit'20+ return /timed out|out of memory|memory limit|stack/i.test(message)packages/ai-mcp-sandbox/src/sandboxed-tool.ts line 103Outdated@@ -0,0 +83,21 @@83+}84+85+/**86+ * Turn a signed snippet + manifest into a plain `ServerTool` that runs the87+ * snippet inside an isolate, capability-scoped per caller. Drops straight into88+ * `createMCPServer({ tools: [...] })` alongside trusted tools.89+ */90+export function sandboxedTool(config: SandboxedToolConfig) {91+ const {92+ manifest,93+ snippet,94+ facades,95+ driver,96+ serverCaps,97+ policy,98+ publicKey,99+ requireSignature,100+ onAudit,101+ } = config102+103+ assertServable(manifest, snippet, publicKey, requireSignature)packages/ai-mcp-sandbox/src/sandboxed-tool.ts line 183Outdated@@ -0,0 +163,21 @@163+ bindings,164+ timeout: limits.wallClockMs,165+ memoryLimit: limits.memoryMb,166+ })167+168+ // Raw function-body code: top-level return/await. The driver wraps it169+ // (async IIFE + JSON round-trip), so we must NOT wrap it ourselves.170+ const code = `${buildPrelude(allowed, args)}\n${snippet}`171+ const result = await ctx.execute(code, signal ? { signal } : undefined)172+173+ if (!result.success) {174+ const message = result.error?.message ?? 'execution failed'175+ const overBudget = counter.count > limits.maxInjectedCalls176+ // Mark audited before invoking onAudit: if the callback throws, the177+ // catch must not emit a second (error) record for this one execution.178+ audited = true179+ audit(classifyFailure(message, overBudget), counter.count, 0, message)180+ throw new Error(message)181+ }182+183+ // 4. Shape: author-declared truncation + result-size cap.
Pushede148211
Sign in to join this conversation.
🦋 Changeset detected#
Latest commit: e148211d8f19064328f8658dba70afeb04840923
The changes in this PR will be included in the next version bump.
This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are.
Click here if you're a maintainer who wants to add another changeset to this PR