From b2ca8191f1fb91e5cc47bbe0528ef3e595c5e0ce Mon Sep 17 00:00:00 2001 From: Jack Herrington Date: Mon, 16 Nov 2026 14:09:33 -0800 Subject: [PATCH 1/6] feat(ai-mcp-sandbox): per-tool sandboxing for createMCPServer New package @tanstack/ai-mcp-sandbox. sandboxedTool() returns a plain ServerTool that runs an untrusted, snippet-backed tool body inside any Code Mode IsolateDriver, capability-scoped per caller by a manifest (required scope, injected facades, resource limits, optional Ed25519 signature). Drops into createMCPServer({ tools }) next to trusted tools, with no change to createMCPServer or the IsolateDriver contract. Includes a two-phase approval store for Tier-3 writes and a deny-by-default snippet importer (importSnippet + the tanstack-ai-sandbox-import CLI). Driver-agnostic, tested against ai-isolate-quickjs plus a createMCPServer composition and a hashed-token OAuth verifier bridge. Docs under docs/mcp. Co-Authored-By: Claude Opus 4.8 (1M context) --- .changeset/ai-mcp-sandbox-initial.md | 11 + docs/config.json | 7 +- docs/mcp/server-sandboxed-tools.md | 196 ++++++++++++ docs/mcp/server.md | 1 + packages/ai-mcp-sandbox/README.md | 130 ++++++++ packages/ai-mcp-sandbox/package.json | 80 +++++ packages/ai-mcp-sandbox/src/approval.ts | 65 ++++ packages/ai-mcp-sandbox/src/bin/import.ts | 31 ++ packages/ai-mcp-sandbox/src/capability.ts | 96 ++++++ packages/ai-mcp-sandbox/src/importer.ts | 43 +++ packages/ai-mcp-sandbox/src/index.ts | 59 ++++ packages/ai-mcp-sandbox/src/limits.ts | 39 +++ packages/ai-mcp-sandbox/src/manifest.ts | 73 +++++ packages/ai-mcp-sandbox/src/result.ts | 47 +++ packages/ai-mcp-sandbox/src/sandboxed-tool.ts | 176 +++++++++++ packages/ai-mcp-sandbox/src/types.ts | 106 +++++++ packages/ai-mcp-sandbox/tests/sandbox.test.ts | 278 ++++++++++++++++++ .../tests/server-integration.test.ts | 97 ++++++ packages/ai-mcp-sandbox/tsconfig.json | 8 + packages/ai-mcp-sandbox/vite.config.ts | 36 +++ pnpm-lock.yaml | 32 +- 21 files changed, 1602 insertions(+), 9 deletions(-) create mode 100644 .changeset/ai-mcp-sandbox-initial.md create mode 100644 docs/mcp/server-sandboxed-tools.md create mode 100644 packages/ai-mcp-sandbox/README.md create mode 100644 packages/ai-mcp-sandbox/package.json create mode 100644 packages/ai-mcp-sandbox/src/approval.ts create mode 100644 packages/ai-mcp-sandbox/src/bin/import.ts create mode 100644 packages/ai-mcp-sandbox/src/capability.ts create mode 100644 packages/ai-mcp-sandbox/src/importer.ts create mode 100644 packages/ai-mcp-sandbox/src/index.ts create mode 100644 packages/ai-mcp-sandbox/src/limits.ts create mode 100644 packages/ai-mcp-sandbox/src/manifest.ts create mode 100644 packages/ai-mcp-sandbox/src/result.ts create mode 100644 packages/ai-mcp-sandbox/src/sandboxed-tool.ts create mode 100644 packages/ai-mcp-sandbox/src/types.ts create mode 100644 packages/ai-mcp-sandbox/tests/sandbox.test.ts create mode 100644 packages/ai-mcp-sandbox/tests/server-integration.test.ts create mode 100644 packages/ai-mcp-sandbox/tsconfig.json create mode 100644 packages/ai-mcp-sandbox/vite.config.ts diff --git a/.changeset/ai-mcp-sandbox-initial.md b/.changeset/ai-mcp-sandbox-initial.md new file mode 100644 index 0000000000..eaff1a4001 --- /dev/null +++ b/.changeset/ai-mcp-sandbox-initial.md @@ -0,0 +1,11 @@ +--- +'@tanstack/ai-mcp-sandbox': minor +--- + +New package: per-tool sandboxing for `@tanstack/ai-mcp`. `sandboxedTool()` +returns a plain `ServerTool` that runs an untrusted, snippet-backed tool body +inside any Code Mode `IsolateDriver`, capability-scoped per caller by a signed +manifest (scope, injected facades, resource limits, optional Ed25519 signature). +Drops into `createMCPServer({ tools })` alongside trusted tools. Includes a +two-phase approval store for Tier-3 writes and a deny-by-default snippet +importer (`importSnippet` + `tanstack-ai-sandbox-import` CLI). diff --git a/docs/config.json b/docs/config.json index 828c20c7a8..bc772fea69 100644 --- a/docs/config.json +++ b/docs/config.json @@ -701,7 +701,7 @@ "label": "Serve Tools over HTTP", "to": "mcp/server", "addedAt": "2026-09-22", - "updatedAt": "2026-10-22" + "updatedAt": "2026-11-16" }, { "label": "Serve Resources and Prompts", @@ -733,6 +733,11 @@ "addedAt": "2026-09-22", "updatedAt": "2026-10-22" }, + { + "label": "Sandboxed Tools", + "to": "mcp/server-sandboxed-tools", + "addedAt": "2026-11-16" + }, { "label": "MCP Server Sessions", "to": "mcp/server-sessions", diff --git a/docs/mcp/server-sandboxed-tools.md b/docs/mcp/server-sandboxed-tools.md new file mode 100644 index 0000000000..5cb5266644 --- /dev/null +++ b/docs/mcp/server-sandboxed-tools.md @@ -0,0 +1,196 @@ +--- +title: Sandboxed Tools +id: mcp-server-sandboxed-tools +order: 13 +description: "Back an MCP tool with an untrusted snippet that runs in an isolate, so you can serve a tool whose code you did not write without giving it your whole process." +keywords: + - tanstack ai + - mcp + - model context protocol + - mcp server + - sandbox + - isolate + - sandboxedTool + - createMCPServer + - code mode +--- + +`createMCPServer` runs each tool's `.server()` function in your process, with full access to your files, network, and secrets. That is right for tools you wrote. It is not right for a tool you installed, or one whose code you do not fully trust. + +Back that tool with a snippet that runs in an isolate instead. The snippet reaches the host only through facades you declare, under limits you set, and only for a caller whose token carries the right scope. `sandboxedTool()` returns a normal server tool, so it drops into the same `tools` list next to your plain tools. + +## Quick setup + +1. Install the sandbox package and an isolate driver: + + + +react: @tanstack/ai-mcp-sandbox @tanstack/ai-isolate-quickjs +vue: @tanstack/ai-mcp-sandbox @tanstack/ai-isolate-quickjs +solid: @tanstack/ai-mcp-sandbox @tanstack/ai-isolate-quickjs +svelte: @tanstack/ai-mcp-sandbox @tanstack/ai-isolate-quickjs +preact: @tanstack/ai-mcp-sandbox @tanstack/ai-isolate-quickjs +angular: @tanstack/ai-mcp-sandbox @tanstack/ai-isolate-quickjs +vanilla: @tanstack/ai-mcp-sandbox @tanstack/ai-isolate-quickjs +octane: @tanstack/ai-mcp-sandbox @tanstack/ai-isolate-quickjs + + + +The driver is swappable. `@tanstack/ai-isolate-quickjs` runs anywhere, including edge runtimes. See [Isolate Drivers](../code-mode/code-mode-isolates) for the others. + +2. 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: + +```ts +// src/facades.ts +const ALLOWED = new Set(['https://api.example.com']) + +export const facades = { + 'http.get': { + description: 'GET an allowlisted URL', + execute: async (args: unknown) => { + if (typeof args !== 'object' || args === null || !('url' in args)) { + throw new Error('url is required') + } + const url = new URL(String(args.url)) + if (!ALLOWED.has(url.origin)) throw new Error('origin not allowed') + const response = await fetch(url, { signal: AbortSignal.timeout(3000) }) + return response.text() + }, + }, +} +``` + +3. Write the snippet and its manifest, then wrap them. The snippet is plain JavaScript. It reads its input from `input` and calls facades on `host`: + +```ts group=server-sandboxed-tools +// src/mcp-server.ts +import { createMCPServer } from '@tanstack/ai-mcp/server' +import { hashSnippet, sandboxedTool } from '@tanstack/ai-mcp-sandbox' +import { createQuickJSIsolateDriver } from '@tanstack/ai-isolate-quickjs' +import type { Manifest } from '@tanstack/ai-mcp-sandbox' +import { facades } from './facades' + +const driver = createQuickJSIsolateDriver() + +const snippet = ` + const body = await host.http.get({ url: input.url }) + return { length: body.length } +` + +const manifest = { + name: 'page_size', + version: '1.0.0', + tier: 1, + scope: 'web:read', + inject: ['http.get'], + limits: { + wallClockMs: 5000, + memoryMb: 64, + maxInjectedCalls: 3, + resultBytes: 16384, + }, + truncatable: [], + inputSchema: { + type: 'object', + properties: { url: { type: 'string' } }, + required: ['url'], + }, + description: 'Fetch a URL and return its length', + snippetHash: hashSnippet(snippet), +} satisfies Manifest + +const pageSize = sandboxedTool({ manifest, snippet, facades, driver }) + +export const server = createMCPServer({ + name: 'web', + version: '1.0.0', + tools: [pageSize], // mix freely with plain tools +}) +``` + +Serve it from a route the same way as any MCP server. See [Serve Tools over HTTP](./server). + +## How a call runs + +Each time a host calls the tool, the wrapper: + +1. Reads the caller's token from `ctx.context.authInfo` and checks that its scopes include the manifest `scope`. A caller without it gets a scope error, and the snippet never runs. This needs [MCP Server Auth](./server-auth); without it, there is no caller to check. +2. Builds the capability set: only the facades named in `inject`. A snippet that calls anything else fails inside the isolate. +3. Runs the snippet on the driver under the manifest `limits`. The isolate has no files, no network, and no secrets of its own. +4. Shapes the result, then returns it to the host. + +The snippet source must match `snippetHash`, so a changed snippet with an unchanged manifest is refused at startup. + +## Limits + +`limits` is the budget for one run. The wrapper stops a run that goes past any of them: + +- `wallClockMs`: total time for the run. +- `memoryMb`: isolate heap. +- `maxInjectedCalls`: how many facade calls the run may make. +- `resultBytes`: size of the returned result. Over this, the wrapper truncates the paths you list in `truncatable`, then errors if it is still too large. + +To cap every tool on the server, pass `serverCaps`. Each run uses the tighter of the two: + +```ts group=server-sandboxed-tools +sandboxedTool({ + manifest, + snippet, + facades, + driver, + serverCaps: { wallClockMs: 3000 }, +}) +``` + +## Per-caller policy + +Limit which facades a caller may use with `policy`. It returns the subset of declared facades allowed for that caller. Value-level rules (which targets, which rows) belong inside the facade, which reads the caller from its `FacadeContext`: + +```ts group=server-sandboxed-tools +sandboxedTool({ + manifest, + snippet, + facades, + driver, + policy: (authInfo, declared) => + authInfo.scopes.includes('web:write') ? declared : [], +}) +``` + +## Sign the manifest + +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. + +Signing uses Ed25519. Pass the public key and require a valid signature: + +```ts group=server-sandboxed-tools +import { generateManifestKeyPair, signManifest } from '@tanstack/ai-mcp-sandbox' + +const { publicKey, privateKey } = generateManifestKeyPair() +const signature = signManifest(manifest, privateKey) + +sandboxedTool({ + manifest: { ...manifest, signature }, + snippet, + facades, + driver, + publicKey, + requireSignature: true, +}) +``` + +## Import an existing snippet + +Turn a plain [Code Mode](../code-mode/code-mode) snippet into a starting manifest with the CLI: + +```sh +npx tanstack-ai-sandbox-import ./my-snippet.js +``` + +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. + +## Lasting writes + +A sandboxed tool is a good fit for reads and safe actions. Approval never happens inside the isolate. + +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. diff --git a/docs/mcp/server.md b/docs/mcp/server.md index da2734084d..ba53a7376a 100644 --- a/docs/mcp/server.md +++ b/docs/mcp/server.md @@ -198,6 +198,7 @@ Pick the one you need: - Serve documents and prompts: [Serve Resources and Prompts](./server-content). - Let only signed-in users call the tools: [MCP Server Auth](./server-auth). +- Serve a tool whose code you do not fully trust: [Sandboxed Tools](./server-sandboxed-tools). - Ask the user a question from a tool: [Ask for Input](./server-input). - Run a long tool in the background: [MCP Server Tasks](./server-tasks). - Let a desktop host start your server as a local process: [MCP Server on stdio](./server-stdio). diff --git a/packages/ai-mcp-sandbox/README.md b/packages/ai-mcp-sandbox/README.md new file mode 100644 index 0000000000..63aca07c4d --- /dev/null +++ b/packages/ai-mcp-sandbox/README.md @@ -0,0 +1,130 @@ +
+ + + + TanStack AI + +
+ +
+ +# @tanstack/ai-mcp-sandbox + +Per-tool sandboxing for `@tanstack/ai-mcp`. Serve a tool whose body is an +**untrusted snippet** running inside a Code Mode isolate, capability-scoped per +caller by a signed manifest. + +## Why + +`createMCPServer` authenticates the caller and then trusts the tool code. That +is right for first-party tools. It is not enough when the tool code is something +the operator did not write (installed/third-party tools, an "app store" for a +pod). This package adds the missing execution layer: a tool backed by a snippet +that runs in an isolate and touches the host only through narrow, typed +**facades** — so a tool you do not fully trust can be served safely. + +Sandboxing is a property of an **individual tool**. A `createMCPServer` tool +list can freely mix plain in-process tools and sandboxed, snippet-backed tools. + +## How it works + +`sandboxedTool()` returns a plain `ServerTool`, so it drops straight into +`createMCPServer({ tools: [...] })`. Per call it: + +1. Reads `ctx.context.authInfo` and checks the manifest's required **scope** + against the caller's token (the server's `requiredScopes` is too coarse). +2. Builds the **capability set** — the manifest's declared facades, narrowed by + an optional per-client policy. +3. Runs the snippet on any Code Mode `IsolateDriver` with only those facade + bindings, under `min(manifest.limits, serverCaps)` (wall clock, memory, + injected-call count, result size). +4. Shapes the result (author-declared truncation + size cap) and emits an audit + record. + +It is driver-agnostic — pass `@tanstack/ai-isolate-quickjs` (portable), +`@tanstack/ai-isolate-node` (V8), or any other `IsolateDriver`. + +## Example + +```ts +import { toolDefinition } from '@tanstack/ai' +import { createMCPServer } from '@tanstack/ai-mcp/server' +import { sandboxedTool } from '@tanstack/ai-mcp-sandbox' +import { createQuickJSIsolateDriver } from '@tanstack/ai-isolate-quickjs' + +const driver = createQuickJSIsolateDriver() + +// Host-side facade: secrets and backend URLs live here, never in the isolate. +const facades = { + 'http.get': { + description: 'GET an allowlisted URL', + execute: async (args: unknown) => { + if (typeof args !== 'object' || args === null || !('url' in args)) { + throw new Error('url is required') + } + return (await fetch(String(args.url))).text() + }, + }, +} + +// Snippet is already-transpiled JS. Its SHA-256 must equal manifest.snippetHash. +const snippet = ` + const body = await host.http.get({ url: input.url }) + return { length: body.length } +` + +const fetchLength = sandboxedTool({ + manifest: { + name: 'fetch_length', + version: '1.0.0', + tier: 1, + scope: 'web:read', + inject: ['http.get'], + limits: { wallClockMs: 5000, memoryMb: 64, maxInjectedCalls: 3, resultBytes: 16384 }, + truncatable: [], + inputSchema: { type: 'object', properties: { url: { type: 'string' } } }, + description: 'Fetch a URL and return its length', + snippetHash: '', + }, + snippet, + facades, + driver, +}) + +export const server = createMCPServer({ + name: 'demo', + version: '1.0.0', + tools: [fetchLength], // mix freely with plain tools +}) +``` + +## Manifest signing (optional) + +The manifest is the security contract. `signature` (Ed25519 over the canonical +manifest) is **optional** in the format — ceremony for first-party tools in a +repo. Make it mandatory by policy when a registry is writable by anyone but the +operator: pass `publicKey` + `requireSignature: true` to `sandboxedTool()`. + +## Importer + +`importSnippet()` (and the `tanstack-ai-sandbox-import` CLI) turn a plain Code +Mode snippet into a **deny-by-default, unreviewed** manifest (no injections, +tightest limits, Tier 1). The tool is refused at build time until a human fills +the security fields. Authoring-time only — never a runtime path. + +## Approval + +Approval never happens inside the isolate. For lasting (Tier-3) writes served to +a foreign MCP host, use `createApprovalStore()` for a host-agnostic two-phase +proposal (`propose → proposalId → confirm`, 5-minute expiry, hash-bound, +fail-closed). diff --git a/packages/ai-mcp-sandbox/package.json b/packages/ai-mcp-sandbox/package.json new file mode 100644 index 0000000000..69201c4942 --- /dev/null +++ b/packages/ai-mcp-sandbox/package.json @@ -0,0 +1,80 @@ +{ + "name": "@tanstack/ai-mcp-sandbox", + "version": "0.1.0", + "description": "Per-tool sandboxing for @tanstack/ai-mcp: run untrusted snippet-backed MCP tools inside a Code Mode isolate, capability-scoped per caller via a signed manifest.", + "author": "Tanner Linsley", + "license": "MIT", + "homepage": "https://tanstack.com/ai", + "repository": { + "type": "git", + "url": "git+https://github.com/TanStack/ai.git", + "directory": "packages/ai-mcp-sandbox" + }, + "bugs": { + "url": "https://github.com/TanStack/ai/issues" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/tannerlinsley" + }, + "type": "module", + "module": "./dist/esm/index.js", + "types": "./dist/esm/index.d.ts", + "exports": { + ".": { + "types": "./dist/esm/index.d.ts", + "import": "./dist/esm/index.js" + }, + "./importer": { + "types": "./dist/esm/importer.d.ts", + "import": "./dist/esm/importer.js" + } + }, + "bin": { + "tanstack-ai-sandbox-import": "./dist/esm/bin/import.js" + }, + "sideEffects": false, + "engines": { + "node": ">=18" + }, + "files": [ + "dist", + "src" + ], + "scripts": { + "build": "vite build", + "clean": "premove ./build ./dist", + "lint:fix": "oxlint src --type-aware --fix", + "test:build": "publint --strict", + "test:oxlint": "oxlint src --type-aware", + "test:coverage": "vitest run --coverage --coverage.include='src/**' --coverage.reporter=text-summary --coverage.reporter=json-summary", + "test:lib": "vitest", + "test:lib:dev": "pnpm test:lib --watch", + "test:types": "tsc" + }, + "keywords": [ + "ai", + "ai-sdk", + "typescript", + "tanstack", + "mcp", + "sandbox", + "isolate", + "code-mode", + "security", + "tool-calling", + "manifest" + ], + "peerDependencies": { + "@tanstack/ai": "workspace:^", + "@tanstack/ai-code-mode": "workspace:^", + "@tanstack/ai-mcp": "workspace:^" + }, + "devDependencies": { + "@tanstack/ai": "workspace:*", + "@tanstack/ai-code-mode": "workspace:*", + "@tanstack/ai-isolate-quickjs": "workspace:*", + "@tanstack/ai-mcp": "workspace:*", + "@vitest/coverage-v8": "4.1.12" + } +} diff --git a/packages/ai-mcp-sandbox/src/approval.ts b/packages/ai-mcp-sandbox/src/approval.ts new file mode 100644 index 0000000000..014a2d046e --- /dev/null +++ b/packages/ai-mcp-sandbox/src/approval.ts @@ -0,0 +1,65 @@ +import { createHash, randomBytes } from 'node:crypto' +import { canonicalize } from './manifest' + +/** + * Host-agnostic two-phase approval for lasting (Tier-3) writes. Approval never + * happens inside the isolate: a Tier-3 tool calls `propose()` first (phase 1, + * returns a proposalId), and a second call with that id `consume()`s it + * (phase 2) to run the write. Hash-bound, single-use, 5-minute expiry, + * fail-closed (a restart drops every pending proposal). + * + * ponytail: in-memory Map. Swap for a shared store if you run more than one + * server process. + */ +export interface Proposal { + id: string + clientId: string + /** The exact action to perform in phase 2. */ + action: unknown + /** SHA-256 of the canonical action — detects tampering between phases. */ + actionHash: string + expiresAtMs: number +} + +export class ProposalExpiredError extends Error { + constructor() { + // Unknown / expired / replayed are indistinguishable on purpose. + super('proposal_expired') + this.name = 'ProposalExpiredError' + } +} + +export interface ApprovalStore { + propose: ( + clientId: string, + action: unknown, + ) => { proposalId: string; actionHash: string; expiresAtMs: number } + consume: (clientId: string, proposalId: string) => unknown +} + +const TTL_MS = 5 * 60 * 1000 + +export function createApprovalStore(ttlMs: number = TTL_MS): ApprovalStore { + const pending = new Map() + const now = () => Date.now() + + return { + propose(clientId, action) { + const id = randomBytes(18).toString('hex') + const actionHash = createHash('sha256') + .update(canonicalize({ clientId, action }), 'utf8') + .digest('hex') + const expiresAtMs = now() + ttlMs + pending.set(id, { id, clientId, action, actionHash, expiresAtMs }) + return { proposalId: id, actionHash, expiresAtMs } + }, + consume(clientId, proposalId) { + const p = pending.get(proposalId) + pending.delete(proposalId) // single-use: gone whether or not it was valid + if (!p || p.clientId !== clientId || p.expiresAtMs < now()) { + throw new ProposalExpiredError() + } + return p.action + }, + } +} diff --git a/packages/ai-mcp-sandbox/src/bin/import.ts b/packages/ai-mcp-sandbox/src/bin/import.ts new file mode 100644 index 0000000000..9189c63cd5 --- /dev/null +++ b/packages/ai-mcp-sandbox/src/bin/import.ts @@ -0,0 +1,31 @@ +#!/usr/bin/env node +import { basename, extname } from 'node:path' +import { readFileSync, writeFileSync } from 'node:fs' +import { importSnippet } from '../importer' + +/** + * tanstack-ai-sandbox-import [manifest.json] + * + * Emits a deny-by-default, unreviewed manifest next to the snippet. The tool is + * NOT servable until a human fills the security fields (scope, inject, limits) + * and removes `unreviewed`. + */ +function main(argv: Array): void { + const [snippetPath, outPath] = argv + if (!snippetPath) { + console.error( + 'usage: tanstack-ai-sandbox-import [manifest.json]', + ) + process.exit(1) + } + const snippet = readFileSync(snippetPath, 'utf8') + const name = basename(snippetPath, extname(snippetPath)) + const manifest = importSnippet(snippet, { name }) + const target = outPath ?? snippetPath.replace(/\.[^.]+$/, '.manifest.json') + writeFileSync(target, `${JSON.stringify(manifest, null, 2)}\n`) + console.error( + `Wrote ${target} (unreviewed). Fill scope/inject/limits and drop "unreviewed" before serving.`, + ) +} + +main(process.argv.slice(2)) diff --git a/packages/ai-mcp-sandbox/src/capability.ts b/packages/ai-mcp-sandbox/src/capability.ts new file mode 100644 index 0000000000..e0238fa2a0 --- /dev/null +++ b/packages/ai-mcp-sandbox/src/capability.ts @@ -0,0 +1,96 @@ +import type { + AuthInfo, + ClientPolicy, + Facades, + FacadeContext, + ToolBinding, +} from './types' + +/** Dotted facade name → a JS identifier usable as an isolate binding name. */ +export function safeName(dotted: string): string { + return `facade_${dotted.replace(/[^A-Za-z0-9_$]/g, '_')}` +} + +/** + * Resolve which declared facades this caller may use (apply per-client + * policy) and verify each exists. Throws on an unknown facade — a manifest + * injecting something the server can't provide is a configuration error. + */ +export function resolveAllowed( + declared: ReadonlyArray, + facades: Facades, + authInfo: AuthInfo, + policy?: ClientPolicy, +): ReadonlyArray { + for (const dotted of declared) { + if (!facades[dotted]) { + throw new Error(`Manifest injects unknown facade "${dotted}"`) + } + } + if (!policy) return declared + const declaredSet = new Set(declared) + // Policy can only narrow, never widen past what the manifest declared. + return policy(authInfo, declared).filter((n) => declaredSet.has(n)) +} + +/** + * Wrap the allowed facades as isolate bindings. Each binding's `execute` + * ticks the call counter and injects `FacadeContext` (authInfo, clientId). + */ +export function buildBindings(opts: { + allowed: ReadonlyArray + facades: Facades + authInfo: AuthInfo + signal?: AbortSignal + tick: () => void +}): Record { + const { allowed, facades, authInfo, signal, tick } = opts + const ctx: FacadeContext = { authInfo, clientId: authInfo.clientId, signal } + + const bindings: Record = {} + const seen = new Set() + for (const dotted of allowed) { + const key = safeName(dotted) + if (seen.has(key)) { + throw new Error(`Facade name collision after sanitizing: "${dotted}"`) + } + seen.add(key) + const facade = facades[dotted] + if (!facade) continue // resolveAllowed already verified existence + bindings[key] = { + name: key, + description: facade.description ?? dotted, + inputSchema: facade.inputSchema ?? {}, + execute: async (args) => { + tick() + return facade.execute(args, ctx) + }, + } + } + return bindings +} + +/** + * Prelude evaluated before the snippet: rebuilds the `host..` tree + * from the flat bindings and binds `input`. Only allowed facades appear, so + * a denied one is simply absent (a call to it throws in-isolate). + */ +export function buildPrelude( + allowed: ReadonlyArray, + input: unknown, +): string { + const lines = ['const host = {};'] + for (const dotted of allowed) { + const parts = dotted.split('.') + let path = 'host' + for (let i = 0; i < parts.length - 1; i++) { + path += `[${JSON.stringify(parts[i])}]` + lines.push(`${path} = ${path} || {};`) + } + lines.push( + `${path}[${JSON.stringify(parts[parts.length - 1])}] = ${safeName(dotted)};`, + ) + } + lines.push(`const input = ${JSON.stringify(input ?? {})};`) + return lines.join('\n') +} diff --git a/packages/ai-mcp-sandbox/src/importer.ts b/packages/ai-mcp-sandbox/src/importer.ts new file mode 100644 index 0000000000..e7b2e2adc8 --- /dev/null +++ b/packages/ai-mcp-sandbox/src/importer.ts @@ -0,0 +1,43 @@ +import { hashSnippet } from './manifest' +import type { Manifest } from './types' + +/** Tightest defaults an imported-but-unreviewed tool is pinned to. */ +const DENY_BY_DEFAULT_LIMITS = { + wallClockMs: 1000, + memoryMb: 32, + maxInjectedCalls: 0, + resultBytes: 16 * 1024, +} as const + +export interface ImportOptions { + name: string + description?: string + inputSchema?: Record + version?: string +} + +/** + * Convert a plain Code Mode snippet into a sandboxed-tool manifest. The snippet + * body carries over verbatim; the manifest is generated **deny-by-default**: + * no injections, tightest limits, Tier 1, and `unreviewed: true` — which makes + * `sandboxedTool()` refuse to serve it. A human must fill the security fields + * (and sign, under policy) before the tool runs. Authoring-time only. + */ +export function importSnippet( + snippet: string, + options: ImportOptions, +): Manifest { + return { + name: options.name, + version: options.version ?? '0.0.0', + tier: 1, + scope: `${options.name}:TODO`, + inject: [], + limits: { ...DENY_BY_DEFAULT_LIMITS }, + truncatable: [], + inputSchema: options.inputSchema ?? { type: 'object' }, + description: options.description ?? `TODO: describe ${options.name}`, + snippetHash: hashSnippet(snippet), + unreviewed: true, + } +} diff --git a/packages/ai-mcp-sandbox/src/index.ts b/packages/ai-mcp-sandbox/src/index.ts new file mode 100644 index 0000000000..b1aabb8524 --- /dev/null +++ b/packages/ai-mcp-sandbox/src/index.ts @@ -0,0 +1,59 @@ +// The wrapper: a signed snippet + manifest → a plain ServerTool. +export { + sandboxedTool, + UnauthorizedError, + ScopeDeniedError, +} from './sandboxed-tool' + +// Manifest: hashing, canonical-JSON signing (optional), keygen. +export { + hashSnippet, + canonicalize, + signManifest, + verifyManifest, + generateManifestKeyPair, +} from './manifest' + +// Limits + the injected-call counter. +export { + intersectLimits, + makeCallCounter, + InjectedCallLimitError, +} from './limits' + +// Result shaping. +export { byteLength, shapeResult, ResultTooLargeError } from './result' + +// Capability set (exposed for custom wrappers/tests). +export { + safeName, + resolveAllowed, + buildBindings, + buildPrelude, +} from './capability' + +// Authoring-time importer: plain snippet → unreviewed, deny-by-default manifest. +export { importSnippet, type ImportOptions } from './importer' + +// Two-phase approval for Tier-3 writes. +export { + createApprovalStore, + ProposalExpiredError, + type ApprovalStore, + type Proposal, +} from './approval' + +export type { + AuthInfo, + AuditEntry, + ClientPolicy, + Facade, + FacadeContext, + Facades, + IsolateDriver, + Limits, + Manifest, + SandboxedToolConfig, + Tier, + ToolBinding, +} from './types' diff --git a/packages/ai-mcp-sandbox/src/limits.ts b/packages/ai-mcp-sandbox/src/limits.ts new file mode 100644 index 0000000000..c49377a0e1 --- /dev/null +++ b/packages/ai-mcp-sandbox/src/limits.ts @@ -0,0 +1,39 @@ +import type { Limits } from './types' + +/** Intersect a manifest's limits with server caps: the tighter of each. */ +export function intersectLimits( + limits: Limits, + caps: Partial | undefined, +): Limits { + if (!caps) return limits + const tighter = (a: number, b: number | undefined) => + b === undefined ? a : Math.min(a, b) + return { + wallClockMs: tighter(limits.wallClockMs, caps.wallClockMs), + memoryMb: tighter(limits.memoryMb, caps.memoryMb), + maxInjectedCalls: tighter(limits.maxInjectedCalls, caps.maxInjectedCalls), + resultBytes: tighter(limits.resultBytes, caps.resultBytes), + } +} + +/** Thrown by a facade when the run exceeds its injected-call budget. */ +export class InjectedCallLimitError extends Error { + constructor(max: number) { + super(`Injected-call limit reached (${max})`) + this.name = 'InjectedCallLimitError' + } +} + +/** A shared counter: `tick()` before each facade call, throws past `max`. */ +export function makeCallCounter(max: number) { + let count = 0 + return { + tick() { + count += 1 + if (count > max) throw new InjectedCallLimitError(max) + }, + get count() { + return count + }, + } +} diff --git a/packages/ai-mcp-sandbox/src/manifest.ts b/packages/ai-mcp-sandbox/src/manifest.ts new file mode 100644 index 0000000000..539fae97ae --- /dev/null +++ b/packages/ai-mcp-sandbox/src/manifest.ts @@ -0,0 +1,73 @@ +import { + createHash, + generateKeyPairSync, + sign as edSign, + verify as edVerify, +} from 'node:crypto' +import type { Manifest } from './types' + +/** Hex SHA-256 of a snippet's source. */ +export function hashSnippet(source: string): string { + return createHash('sha256').update(source, 'utf8').digest('hex') +} + +/** Deterministic JSON: object keys sorted recursively so bytes are stable. */ +export function canonicalize(value: unknown): string { + return JSON.stringify(sortKeys(value)) +} + +function sortKeys(value: unknown): unknown { + if (Array.isArray(value)) return value.map(sortKeys) + if (value && typeof value === 'object') { + const out: Record = {} + for (const key of Object.keys(value as Record).sort()) { + out[key] = sortKeys((value as Record)[key]) + } + return out + } + return value +} + +/** The exact bytes signed/verified: the manifest minus its `signature`. */ +function signingBytes(manifest: Manifest): Buffer { + const { signature: _signature, ...rest } = manifest + return Buffer.from(canonicalize(rest), 'utf8') +} + +/** Sign a manifest with a PEM Ed25519 private key; returns base64. */ +export function signManifest( + manifest: Manifest, + privateKeyPem: string, +): string { + return edSign(null, signingBytes(manifest), privateKeyPem).toString('base64') +} + +/** True when `manifest.signature` is a valid Ed25519 signature for `publicKeyPem`. */ +export function verifyManifest( + manifest: Manifest, + publicKeyPem: string, +): boolean { + if (!manifest.signature) return false + try { + return edVerify( + null, + signingBytes(manifest), + publicKeyPem, + Buffer.from(manifest.signature, 'base64'), + ) + } catch { + return false + } +} + +/** Convenience for authoring/tests: a fresh Ed25519 keypair as PEM strings. */ +export function generateManifestKeyPair(): { + publicKey: string + privateKey: string +} { + const { publicKey, privateKey } = generateKeyPairSync('ed25519') + return { + publicKey: publicKey.export({ type: 'spki', format: 'pem' }).toString(), + privateKey: privateKey.export({ type: 'pkcs8', format: 'pem' }).toString(), + } +} diff --git a/packages/ai-mcp-sandbox/src/result.ts b/packages/ai-mcp-sandbox/src/result.ts new file mode 100644 index 0000000000..4ca2626494 --- /dev/null +++ b/packages/ai-mcp-sandbox/src/result.ts @@ -0,0 +1,47 @@ +/** Serialized byte length of a value (what the result-size cap measures). */ +export function byteLength(value: unknown): number { + return Buffer.byteLength(JSON.stringify(value) ?? 'undefined', 'utf8') +} + +export class ResultTooLargeError extends Error { + constructor(bytes: number, max: number) { + super(`Result too large: ${bytes} bytes (max ${max})`) + this.name = 'ResultTooLargeError' + } +} + +/** + * Shape a run's result to fit `maxBytes`. First truncates the author-declared + * `truncatable` string paths (dotted) to a `…` marker; if still over, throws. + * Returns the (possibly mutated copy of the) value. + */ +export function shapeResult( + value: unknown, + truncatable: ReadonlyArray, + maxBytes: number, +): unknown { + if (byteLength(value) <= maxBytes) return value + + // Work on a structural clone so we never mutate the snippet's return value. + let shaped: unknown = structuredClone(value) + for (const path of truncatable) { + if (byteLength(shaped) <= maxBytes) break + shaped = truncateAtPath(shaped, path.split('.')) + } + + const bytes = byteLength(shaped) + if (bytes > maxBytes) throw new ResultTooLargeError(bytes, maxBytes) + return shaped +} + +function truncateAtPath(value: unknown, parts: ReadonlyArray): unknown { + const head = parts[0] + if (head === undefined) { + return typeof value === 'string' ? '…' : value + } + if (!value || typeof value !== 'object') return value + const obj = value as Record + if (!(head in obj)) return value + obj[head] = truncateAtPath(obj[head], parts.slice(1)) + return obj +} diff --git a/packages/ai-mcp-sandbox/src/sandboxed-tool.ts b/packages/ai-mcp-sandbox/src/sandboxed-tool.ts new file mode 100644 index 0000000000..5e4b6a0842 --- /dev/null +++ b/packages/ai-mcp-sandbox/src/sandboxed-tool.ts @@ -0,0 +1,176 @@ +import { toolDefinition } from '@tanstack/ai' +import { buildBindings, buildPrelude, resolveAllowed } from './capability' +import { hashSnippet, verifyManifest } from './manifest' +import { intersectLimits, makeCallCounter } from './limits' +import { byteLength, shapeResult } from './result' +import type { MCPToolContext } from '@tanstack/ai-mcp/server' +import type { AuditEntry, Manifest, SandboxedToolConfig, Tier } from './types' + +export class UnauthorizedError extends Error { + constructor() { + super('unauthorized: no verified caller identity') + this.name = 'UnauthorizedError' + } +} + +export class ScopeDeniedError extends Error { + constructor(scope: string) { + super(`forbidden: missing required scope "${scope}"`) + this.name = 'ScopeDeniedError' + } +} + +/** MCP annotation hints a well-behaved host may prompt on (advisory only). */ +function tierAnnotations(tier: Tier): Record { + return { + readOnlyHint: tier === 1, + destructiveHint: tier === 3, + } +} + +/** + * Reject a manifest/snippet pair that must not be served. Runs once, at + * build time: tamper (hash mismatch), unreviewed import, or missing/invalid + * signature under policy. + */ +function assertServable( + manifest: Manifest, + snippet: string, + publicKey: string | undefined, + requireSignature: boolean | undefined, +): void { + if (manifest.unreviewed) { + throw new Error( + `Tool "${manifest.name}" is unreviewed (imported, security fields not filled). Refusing to serve.`, + ) + } + if (hashSnippet(snippet) !== manifest.snippetHash) { + throw new Error( + `Tool "${manifest.name}": snippet hash does not match manifest.snippetHash.`, + ) + } + if (requireSignature) { + if (!publicKey) { + throw new Error( + `Tool "${manifest.name}": requireSignature is set but no publicKey was provided.`, + ) + } + if (!verifyManifest(manifest, publicKey)) { + throw new Error(`Tool "${manifest.name}": manifest signature is invalid.`) + } + } else if (manifest.signature && publicKey) { + // Not required, but if both are present a bad signature still means tamper. + if (!verifyManifest(manifest, publicKey)) { + throw new Error(`Tool "${manifest.name}": manifest signature is invalid.`) + } + } +} + +/** + * Turn a signed snippet + manifest into a plain `ServerTool` that runs the + * snippet inside an isolate, capability-scoped per caller. Drops straight into + * `createMCPServer({ tools: [...] })` alongside trusted tools. + */ +export function sandboxedTool(config: SandboxedToolConfig) { + const { + manifest, + snippet, + facades, + driver, + serverCaps, + policy, + publicKey, + requireSignature, + onAudit, + } = config + + assertServable(manifest, snippet, publicKey, requireSignature) + const limits = intersectLimits(manifest.limits, serverCaps) + + return toolDefinition({ + name: manifest.name, + description: manifest.description, + inputSchema: manifest.inputSchema, + metadata: { annotations: tierAnnotations(manifest.tier) }, + }).server(async (args, context) => { + const started = Date.now() + const authInfo = context.context.authInfo + const signal = context.abortSignal + + const audit = ( + outcome: AuditEntry['outcome'], + injectedCalls: number, + resultBytes: number, + error?: string, + ) => { + onAudit?.({ + clientId: authInfo?.clientId ?? 'anonymous', + tool: manifest.name, + snippetHash: manifest.snippetHash, + scope: manifest.scope, + injectedCalls, + durationMs: Date.now() - started, + resultBytes, + outcome, + error, + }) + } + + // 1. Per-tool scope gate (the server's requiredScopes is too coarse). + if (!authInfo) { + audit('denied', 0, 0, 'unauthorized') + throw new UnauthorizedError() + } + if (!authInfo.scopes.includes(manifest.scope)) { + audit('denied', 0, 0, 'scope_denied') + throw new ScopeDeniedError(manifest.scope) + } + + // 2. Capability set: declared facades ∩ per-client policy. + const allowed = resolveAllowed(manifest.inject, facades, authInfo, policy) + const counter = makeCallCounter(limits.maxInjectedCalls) + const bindings = buildBindings({ + allowed, + facades, + authInfo, + signal, + tick: counter.tick, + }) + + // 3. Run the snippet with only those bindings, under the merged limits. + const ctx = await driver.createContext({ + bindings, + timeout: limits.wallClockMs, + memoryLimit: limits.memoryMb, + }) + try { + // Raw function-body code: top-level return/await. The driver wraps it + // (async IIFE + JSON round-trip), so we must NOT wrap it ourselves. + const code = `${buildPrelude(allowed, args)}\n${snippet}` + const result = await ctx.execute(code, signal ? { signal } : undefined) + + if (!result.success) { + const message = result.error?.message ?? 'execution failed' + const limitHit = /timed out|memory|stack/i.test(message) + audit(limitHit ? 'limit' : 'error', counter.count, 0, message) + throw new Error(message) + } + + // 4. Shape: author-declared truncation + result-size cap. + const shaped = shapeResult( + result.value, + manifest.truncatable, + limits.resultBytes, + ) + audit('ok', counter.count, byteLength(shaped)) + return shaped + } catch (error) { + if (error instanceof Error && error.name === 'ResultTooLargeError') { + audit('limit', counter.count, 0, error.message) + } + throw error + } finally { + await ctx.dispose() + } + }) +} diff --git a/packages/ai-mcp-sandbox/src/types.ts b/packages/ai-mcp-sandbox/src/types.ts new file mode 100644 index 0000000000..760a38763b --- /dev/null +++ b/packages/ai-mcp-sandbox/src/types.ts @@ -0,0 +1,106 @@ +import type { AuthInfo } from '@tanstack/ai-mcp/server' +import type { IsolateDriver, ToolBinding } from '@tanstack/ai-code-mode' + +export type { AuthInfo, IsolateDriver, ToolBinding } + +/** 1 = read-only, 2 = write, 3 = lasting write (two-phase approval). */ +export type Tier = 1 | 2 | 3 + +/** Resource limits an isolate run is held to. */ +export interface Limits { + /** Wall-clock budget for the whole run, ms. */ + wallClockMs: number + /** Isolate heap cap, MB. */ + memoryMb: number + /** Max host-facade calls a single run may make. */ + maxInjectedCalls: number + /** Max serialized result size, bytes (over → truncate `truncatable`, then error). */ + resultBytes: number +} + +/** + * The security contract for a sandboxed tool. Ships next to the snippet. + * `signature` is optional in the format; policy (`requireSignature`) makes it + * mandatory when a registry is writable by anyone but the operator. + */ +export interface Manifest { + name: string + version: string + tier: Tier + /** Required OAuth scope — checked per-tool against the caller's token. */ + scope: string + /** Dotted facade names this tool may call, e.g. `["http.get"]`. */ + inject: ReadonlyArray + limits: Limits + /** Dotted paths into the result the author allows to be truncated. */ + truncatable: ReadonlyArray + /** JSON Schema for the tool's input. */ + inputSchema: Record + description: string + /** Hex SHA-256 of the exact snippet source this manifest authorizes. */ + snippetHash: string + /** Base64 Ed25519 signature over the canonical manifest (minus this field). */ + signature?: string + /** Set by the importer. A tool with this flag is refused at build time. */ + unreviewed?: boolean +} + +/** Context a facade receives on every call. */ +export interface FacadeContext { + authInfo: AuthInfo + clientId: string + signal?: AbortSignal +} + +/** + * A host-side capability. Narrow and typed: the snippet calls it as + * `host..(input)`. Secrets and backend URLs live in the + * closure here, never in the isolate. + */ +export interface Facade { + description?: string + inputSchema?: Record + execute: (args: unknown, ctx: FacadeContext) => Promise +} + +/** Facades keyed by the dotted name used in `Manifest.inject`. */ +export type Facades = Record + +/** + * Per-client capability filter. Return the subset of declared facade names + * this caller may use (default: all declared). Value-level policy + * (e.g. which targets) is enforced inside the facade via `FacadeContext`. + */ +export type ClientPolicy = ( + authInfo: AuthInfo, + declared: ReadonlyArray, +) => ReadonlyArray + +/** Audit record emitted once per run (success or failure). */ +export interface AuditEntry { + clientId: string + tool: string + snippetHash: string + scope: string + injectedCalls: number + durationMs: number + resultBytes: number + outcome: 'ok' | 'denied' | 'error' | 'limit' + error?: string +} + +export interface SandboxedToolConfig { + manifest: Manifest + /** The snippet source. Its SHA-256 must equal `manifest.snippetHash`. */ + snippet: string + facades: Facades + driver: IsolateDriver + /** Server-wide caps; the run uses `min(manifest.limits, serverCaps)`. */ + serverCaps?: Partial + policy?: ClientPolicy + /** PEM Ed25519 public key. Required when `requireSignature` is true. */ + publicKey?: string + /** Refuse to build unless the manifest carries a valid signature. */ + requireSignature?: boolean + onAudit?: (entry: AuditEntry) => void +} diff --git a/packages/ai-mcp-sandbox/tests/sandbox.test.ts b/packages/ai-mcp-sandbox/tests/sandbox.test.ts new file mode 100644 index 0000000000..2f993636bc --- /dev/null +++ b/packages/ai-mcp-sandbox/tests/sandbox.test.ts @@ -0,0 +1,278 @@ +import { describe, expect, it, vi } from 'vitest' +import { createQuickJSIsolateDriver } from '@tanstack/ai-isolate-quickjs' +import { + ProposalExpiredError, + createApprovalStore, + generateManifestKeyPair, + hashSnippet, + importSnippet, + intersectLimits, + makeCallCounter, + sandboxedTool, + shapeResult, + signManifest, + verifyManifest, +} from '../src/index' +import type { AuditEntry, AuthInfo, Facades, Manifest } from '../src/index' + +const driver = createQuickJSIsolateDriver() + +function authInfo(scopes: Array, clientId = 'c1'): AuthInfo { + return { + token: 'tok', + clientId, + scopes, + expiresAt: Date.now() + 1_000_000, + extra: {}, + } +} + +// Mirrors what createMCPServer passes a tool: ctx.context carries authInfo +// (plus the hooks the sandbox wrapper never uses here — stubbed to satisfy +// the MCPToolContext type). +function ctx(info: AuthInfo | undefined) { + return { + context: { + authInfo: info, + requestInput: async () => undefined, + sample: async () => undefined, + }, + abortSignal: undefined, + emitCustomEvent: () => {}, + } +} + +const LIMITS = { + wallClockMs: 5000, + memoryMb: 64, + maxInjectedCalls: 5, + resultBytes: 64 * 1024, +} + +/** A snippet (already-JS) that echoes input through a host facade. */ +const SNIPPET = ` +const out = await host.demo.echo({ value: input.value }); +return { echoed: out }; +` + +function manifestFor(snippet: string, over: Partial = {}): Manifest { + return { + name: 'demo_echo', + version: '1.0.0', + tier: 1, + scope: 'demo:read', + inject: ['demo.echo'], + limits: LIMITS, + truncatable: [], + inputSchema: { type: 'object' }, + description: 'Echo via a host facade', + snippetHash: hashSnippet(snippet), + ...over, + } +} + +const facades: Facades = { + 'demo.echo': { + description: 'echo', + execute: async (args) => { + const a = args as { value?: unknown } + return `echo:${String(a.value)}` + }, + }, +} + +describe('sandboxedTool — end to end on quickjs', () => { + it('runs the snippet in-isolate for an authorized caller', async () => { + const audits: Array = [] + const tool = sandboxedTool({ + manifest: manifestFor(SNIPPET), + snippet: SNIPPET, + facades, + driver, + onAudit: (e) => audits.push(e), + }) + const out = await tool.execute!( + { value: 'hi' }, + ctx(authInfo(['demo:read'])), + ) + expect(out).toEqual({ echoed: 'echo:hi' }) + expect(audits[0]).toMatchObject({ + outcome: 'ok', + injectedCalls: 1, + clientId: 'c1', + }) + }) + + it('denies a caller missing the required scope — no isolate run', async () => { + const tool = sandboxedTool({ + manifest: manifestFor(SNIPPET), + snippet: SNIPPET, + facades, + driver, + }) + await expect( + tool.execute!({ value: 'x' }, ctx(authInfo(['other:read']))), + ).rejects.toThrow(/missing required scope/) + }) + + it('rejects an unauthenticated caller', async () => { + const tool = sandboxedTool({ + manifest: manifestFor(SNIPPET), + snippet: SNIPPET, + facades, + driver, + }) + await expect(tool.execute!({ value: 'x' }, ctx(undefined))).rejects.toThrow( + /unauthorized/, + ) + }) + + it('trips the wall-clock limit on a runaway snippet', async () => { + const spin = `while (true) {}` + const tool = sandboxedTool({ + manifest: manifestFor(spin, { + inject: [], + limits: { ...LIMITS, wallClockMs: 100 }, + }), + snippet: spin, + facades, + driver, + }) + await expect( + tool.execute!({}, ctx(authInfo(['demo:read']))), + ).rejects.toThrow() + }) + + it('trips the injected-call limit', async () => { + const loop = ` + for (let i = 0; i < 3; i++) { await host.demo.echo({ value: i }); } + return 'done'; + ` + const tool = sandboxedTool({ + manifest: manifestFor(loop, { + limits: { ...LIMITS, maxInjectedCalls: 1 }, + }), + snippet: loop, + facades, + driver, + }) + await expect( + tool.execute!({}, ctx(authInfo(['demo:read']))), + ).rejects.toThrow(/Injected-call limit/) + }) +}) + +describe('build-time guards', () => { + it('refuses a snippet whose hash does not match the manifest', () => { + expect(() => + sandboxedTool({ + manifest: manifestFor(SNIPPET, { snippetHash: 'deadbeef' }), + snippet: SNIPPET, + facades, + driver, + }), + ).toThrow(/hash does not match/) + }) + + it('refuses an unreviewed (imported) manifest', () => { + const snippet = `return 1` + const imported = importSnippet(snippet, { name: 'x' }) + expect(imported.unreviewed).toBe(true) + expect(imported.inject).toEqual([]) + expect(imported.tier).toBe(1) + expect(() => + sandboxedTool({ manifest: imported, snippet, facades, driver }), + ).toThrow(/unreviewed/) + }) + + it('enforces a valid signature when required', () => { + const { publicKey, privateKey } = generateManifestKeyPair() + const base = manifestFor(SNIPPET) + const signed: Manifest = { + ...base, + signature: signManifest(base, privateKey), + } + expect(verifyManifest(signed, publicKey)).toBe(true) + // builds fine with a good signature + expect(() => + sandboxedTool({ + manifest: signed, + snippet: SNIPPET, + facades, + driver, + publicKey, + requireSignature: true, + }), + ).not.toThrow() + // tamper the scope → signature no longer matches + const tampered: Manifest = { ...signed, scope: 'demo:admin' } + expect(verifyManifest(tampered, publicKey)).toBe(false) + expect(() => + sandboxedTool({ + manifest: tampered, + snippet: SNIPPET, + facades, + driver, + publicKey, + requireSignature: true, + }), + ).toThrow(/signature is invalid/) + }) +}) + +describe('limits + result shaping', () => { + it('intersects limits to the tighter of each', () => { + expect( + intersectLimits(LIMITS, { wallClockMs: 1000, maxInjectedCalls: 99 }), + ).toMatchObject({ wallClockMs: 1000, maxInjectedCalls: 5 }) + }) + + it('counts injected calls and throws past max', () => { + const c = makeCallCounter(2) + c.tick() + c.tick() + expect(() => c.tick()).toThrow(/Injected-call limit/) + expect(c.count).toBe(3) + }) + + it('truncates declared paths, then errors if still too large', () => { + const value = { keep: 'x', big: 'y'.repeat(1000) } + expect(shapeResult(value, ['big'], 50)).toEqual({ keep: 'x', big: '…' }) + expect(() => shapeResult(value, [], 50)).toThrow(/too large/) + }) +}) + +describe('two-phase approval', () => { + it('consumes a valid proposal exactly once', () => { + const store = createApprovalStore() + const { proposalId } = store.propose('c1', { set: 'on' }) + expect(store.consume('c1', proposalId)).toEqual({ set: 'on' }) + // replay → indistinguishable from expired/unknown + expect(() => store.consume('c1', proposalId)).toThrow(ProposalExpiredError) + }) + + it('rejects a foreign client and an expired proposal', () => { + const store = createApprovalStore(0) + const { proposalId } = store.propose('c1', { set: 'on' }) + expect(() => store.consume('c2', proposalId)).toThrow(ProposalExpiredError) + }) +}) + +describe('per-client policy', () => { + it('narrows the capability set, denying a facade the client may not use', async () => { + const tool = sandboxedTool({ + manifest: manifestFor(SNIPPET), + snippet: SNIPPET, + facades, + driver, + // this client gets no facades → host.demo.echo is absent in-isolate + policy: () => [], + }) + const spy = vi.spyOn(facades['demo.echo']!, 'execute') + await expect( + tool.execute!({ value: 'hi' }, ctx(authInfo(['demo:read']))), + ).rejects.toThrow() + expect(spy).not.toHaveBeenCalled() + spy.mockRestore() + }) +}) diff --git a/packages/ai-mcp-sandbox/tests/server-integration.test.ts b/packages/ai-mcp-sandbox/tests/server-integration.test.ts new file mode 100644 index 0000000000..578ee69cfd --- /dev/null +++ b/packages/ai-mcp-sandbox/tests/server-integration.test.ts @@ -0,0 +1,97 @@ +import { createHash } from 'node:crypto' +import { describe, expect, it } from 'vitest' +import { toolDefinition } from '@tanstack/ai' +import { OAuthError, createMCPServer } from '@tanstack/ai-mcp/server' +import { createQuickJSIsolateDriver } from '@tanstack/ai-isolate-quickjs' +import { hashSnippet, sandboxedTool } from '../src/index' +import type { AuthInfo, OAuthTokenVerifier } from '@tanstack/ai-mcp/server' +import type { Facades, Manifest } from '../src/index' + +/** + * The migration bridge from the design note: a custom OAuthTokenVerifier over a + * hashed-token table (home-mcp's existing auth) so v1 tokens keep working under + * createMCPServer's native OAuth. clientId + scopes land on ctx.context.authInfo, + * which the sandboxed tool's per-tool scope gate reads. + */ +function hashedTokenVerifier( + table: Record }>, +): OAuthTokenVerifier { + return { + async verifyAccessToken(token: string): Promise { + const record = table[createHash('sha256').update(token).digest('hex')] + if (!record) throw new OAuthError('invalid_token', 'Unknown token') + return { + token, + clientId: record.clientId, + scopes: record.scopes, + expiresAt: Math.floor(Date.now() / 1000) + 3600, + extra: {}, + } + }, + } +} + +const driver = createQuickJSIsolateDriver() +const snippet = `return { ok: input.n * 2 }` + +const manifest: Manifest = { + name: 'double', + version: '1.0.0', + tier: 1, + scope: 'math:read', + inject: [], + limits: { + wallClockMs: 2000, + memoryMb: 32, + maxInjectedCalls: 0, + resultBytes: 1024, + }, + truncatable: [], + inputSchema: { type: 'object', properties: { n: { type: 'number' } } }, + description: 'Double a number in a sandbox', + snippetHash: hashSnippet(snippet), +} + +const facades: Facades = {} + +describe('createMCPServer integration', () => { + it('bridges a hashed-token table to AuthInfo with scopes', async () => { + const token = 'secret-token' + const verifier = hashedTokenVerifier({ + [createHash('sha256').update(token).digest('hex')]: { + clientId: 'home-client', + scopes: ['math:read'], + }, + }) + + const info = await verifier.verifyAccessToken(token) + expect(info).toMatchObject({ + clientId: 'home-client', + scopes: ['math:read'], + }) + await expect(verifier.verifyAccessToken('wrong')).rejects.toBeInstanceOf( + OAuthError, + ) + }) + + it('composes a sandboxed tool and a plain tool in one server', () => { + const sandboxed = sandboxedTool({ manifest, snippet, facades, driver }) + const plain = toolDefinition({ + name: 'ping', + description: 'trusted in-process tool', + inputSchema: { type: 'object' }, + }).server(async () => 'pong') + + const server = createMCPServer({ + name: 'mixed', + version: '1.0.0', + auth: { + verifier: hashedTokenVerifier({}), + }, + tools: [sandboxed, plain], + }) + + expect(server.tools.map((t) => t.name).sort()).toEqual(['double', 'ping']) + expect(typeof server.fetch).toBe('function') + }) +}) diff --git a/packages/ai-mcp-sandbox/tsconfig.json b/packages/ai-mcp-sandbox/tsconfig.json new file mode 100644 index 0000000000..c38689f4ea --- /dev/null +++ b/packages/ai-mcp-sandbox/tsconfig.json @@ -0,0 +1,8 @@ +{ + "extends": "../../tsconfig.base.json", + "compilerOptions": { + "outDir": "dist" + }, + "include": ["src", "tests"], + "exclude": ["node_modules", "dist"] +} diff --git a/packages/ai-mcp-sandbox/vite.config.ts b/packages/ai-mcp-sandbox/vite.config.ts new file mode 100644 index 0000000000..713e1f0374 --- /dev/null +++ b/packages/ai-mcp-sandbox/vite.config.ts @@ -0,0 +1,36 @@ +import { defineConfig, mergeConfig } from 'vitest/config' +import { tanstackViteConfig } from '@tanstack/vite-config' +import packageJson from './package.json' + +const config = defineConfig({ + test: { + name: packageJson.name, + dir: './', + watch: false, + globals: true, + environment: 'node', + include: ['tests/**/*.test.ts'], + coverage: { + provider: 'v8', + reporter: ['text', 'json', 'html', 'lcov'], + exclude: [ + 'node_modules/', + 'dist/', + 'tests/', + '**/*.test.ts', + '**/*.config.ts', + '**/types.ts', + ], + include: ['src/**/*.ts'], + }, + }, +}) + +export default mergeConfig( + config, + tanstackViteConfig({ + entry: ['./src/index.ts', './src/importer.ts', './src/bin/import.ts'], + srcDir: './src', + cjs: false, + }), +) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index c0068c95ed..3fa1b18f74 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -3226,6 +3226,24 @@ importers: specifier: ^4.2.0 version: 4.3.6 + packages/ai-mcp-sandbox: + devDependencies: + '@tanstack/ai': + specifier: workspace:* + version: link:../ai + '@tanstack/ai-code-mode': + specifier: workspace:* + version: link:../ai-code-mode + '@tanstack/ai-isolate-quickjs': + specifier: workspace:* + version: link:../ai-isolate-quickjs + '@tanstack/ai-mcp': + specifier: workspace:* + version: link:../ai-mcp + '@vitest/coverage-v8': + specifier: 4.1.12 + version: 4.1.12(vitest@4.1.12) + packages/ai-memory: dependencies: '@tanstack/ai-event-client': @@ -22469,7 +22487,7 @@ snapshots: '@blaxel/core@0.3.11(@cfworker/json-schema@4.1.1)(@hey-api/openapi-ts@0.99.0(magicast@0.5.2)(typescript@7.0.2))': dependencies: '@hey-api/client-fetch': 0.10.2(@hey-api/openapi-ts@0.99.0(magicast@0.5.2)(typescript@7.0.2)) - '@modelcontextprotocol/sdk': 1.29.0(@cfworker/json-schema@4.1.1)(zod@4.3.6) + '@modelcontextprotocol/sdk': 1.29.0(@cfworker/json-schema@4.1.1)(zod@4.6.5) archiver: 7.0.1 axios: 1.18.1(supports-color@7.2.0) dockerfile-ast: 0.7.1 @@ -22480,7 +22498,7 @@ snapshots: uuid: 11.1.1 ws: 8.21.0 yaml: 2.9.0 - zod: 4.3.6 + zod: 4.6.5 transitivePeerDependencies: - '@cfworker/json-schema' - '@hey-api/openapi-ts' @@ -24301,8 +24319,8 @@ snapshots: '@mistralai/mistralai@2.2.0': dependencies: ws: 8.21.0 - zod: 4.3.6 - zod-to-json-schema: 3.25.2(zod@4.3.6) + zod: 4.6.5 + zod-to-json-schema: 3.25.2(zod@4.6.5) transitivePeerDependencies: - bufferutil - utf-8-validate @@ -24427,7 +24445,6 @@ snapshots: '@cfworker/json-schema': 4.1.1 transitivePeerDependencies: - supports-color - optional: true '@modelcontextprotocol/server@2.1.0': dependencies: @@ -24705,7 +24722,7 @@ snapshots: '@openrouter/sdk@0.13.20': dependencies: - zod: 4.3.6 + zod: 4.6.5 '@opentelemetry/api-logs@0.217.0': dependencies: @@ -30282,7 +30299,7 @@ snapshots: tar-stream: 3.1.7 undici: 7.28.0 xdg-app-paths: 5.1.0 - zod: 4.3.6 + zod: 4.6.5 transitivePeerDependencies: - bare-abort-controller - react-native-b4a @@ -40240,7 +40257,6 @@ snapshots: zod-to-json-schema@3.25.2(zod@4.6.5): dependencies: zod: 4.6.5 - optional: true zod@3.25.76: {} From 9e5a085ad6b05da3a845d17deebe654e7c8e0789 Mon Sep 17 00:00:00 2001 From: "autofix-ci[bot]" <114827586+autofix-ci[bot]@users.noreply.github.com> Date: Mon, 16 Nov 2026 22:12:31 +0000 Subject: [PATCH 2/6] ci: apply automated fixes --- packages/ai-mcp-sandbox/README.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/packages/ai-mcp-sandbox/README.md b/packages/ai-mcp-sandbox/README.md index 63aca07c4d..82256e2792 100644 --- a/packages/ai-mcp-sandbox/README.md +++ b/packages/ai-mcp-sandbox/README.md @@ -90,7 +90,12 @@ const fetchLength = sandboxedTool({ tier: 1, scope: 'web:read', inject: ['http.get'], - limits: { wallClockMs: 5000, memoryMb: 64, maxInjectedCalls: 3, resultBytes: 16384 }, + limits: { + wallClockMs: 5000, + memoryMb: 64, + maxInjectedCalls: 3, + resultBytes: 16384, + }, truncatable: [], inputSchema: { type: 'object', properties: { url: { type: 'string' } } }, description: 'Fetch a URL and return its length', From 046fc93d4c64bc7b8402872dbb92ddb26ca78867 Mon Sep 17 00:00:00 2001 From: Jack Herrington Date: Mon, 16 Nov 2026 16:33:01 -0800 Subject: [PATCH 3/6] =?UTF-8?q?fix(ai-mcp-sandbox):=20address=20review=20?= =?UTF-8?q?=E2=80=94=20prototype-key=20signing,=20audit,=20importer?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Sign and pass `__proto__` keys correctly. canonicalize() uses a null-proto accumulator so a `__proto__` schema key stays in the signing bytes, and the isolate input is emitted as JSON.parse() instead of an object literal. Both closed a path where such a key was silently dropped. - Approval store snapshots the action (structuredClone) and prunes expired proposals, so a later caller mutation cannot change phase 2 and the map cannot grow unbounded. - sandboxedTool emits exactly one audit record per call (setup and execution failures included) and classifies an injected-call overrun as `limit`. - Importer CLI appends `.manifest.json` for an extensionless snippet and refuses to overwrite its input. - Harden the doc and README facade examples: origin allowlist plus redirect: 'error'. Use `npx --package=` for the importer command. - Add regression tests (21 total). Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/mcp/server-sandboxed-tools.md | 9 ++- packages/ai-mcp-sandbox/README.md | 5 +- packages/ai-mcp-sandbox/src/approval.ts | 21 ++++- packages/ai-mcp-sandbox/src/bin/import.ts | 17 ++++- packages/ai-mcp-sandbox/src/capability.ts | 7 +- packages/ai-mcp-sandbox/src/manifest.ts | 5 +- packages/ai-mcp-sandbox/src/sandboxed-tool.ts | 70 ++++++++++++----- packages/ai-mcp-sandbox/tests/sandbox.test.ts | 76 +++++++++++++++++++ 8 files changed, 179 insertions(+), 31 deletions(-) diff --git a/docs/mcp/server-sandboxed-tools.md b/docs/mcp/server-sandboxed-tools.md index 5cb5266644..325ad25d86 100644 --- a/docs/mcp/server-sandboxed-tools.md +++ b/docs/mcp/server-sandboxed-tools.md @@ -53,7 +53,12 @@ export const facades = { } const url = new URL(String(args.url)) if (!ALLOWED.has(url.origin)) throw new Error('origin not allowed') - const response = await fetch(url, { signal: AbortSignal.timeout(3000) }) + // redirect: 'error' stops an allowed origin from bouncing the request to + // an internal address. Without it, fetch follows the redirect for you. + const response = await fetch(url, { + redirect: 'error', + signal: AbortSignal.timeout(3000), + }) return response.text() }, }, @@ -184,7 +189,7 @@ sandboxedTool({ Turn a plain [Code Mode](../code-mode/code-mode) snippet into a starting manifest with the CLI: ```sh -npx tanstack-ai-sandbox-import ./my-snippet.js +npx --package=@tanstack/ai-mcp-sandbox tanstack-ai-sandbox-import ./my-snippet.js ``` 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. diff --git a/packages/ai-mcp-sandbox/README.md b/packages/ai-mcp-sandbox/README.md index 82256e2792..ede8ec1345 100644 --- a/packages/ai-mcp-sandbox/README.md +++ b/packages/ai-mcp-sandbox/README.md @@ -65,6 +65,7 @@ import { createQuickJSIsolateDriver } from '@tanstack/ai-isolate-quickjs' const driver = createQuickJSIsolateDriver() // Host-side facade: secrets and backend URLs live here, never in the isolate. +const ALLOWED = new Set(['https://api.example.com']) const facades = { 'http.get': { description: 'GET an allowlisted URL', @@ -72,7 +73,9 @@ const facades = { if (typeof args !== 'object' || args === null || !('url' in args)) { throw new Error('url is required') } - return (await fetch(String(args.url))).text() + const url = new URL(String(args.url)) + if (!ALLOWED.has(url.origin)) throw new Error('origin not allowed') + return (await fetch(url, { redirect: 'error' })).text() }, }, } diff --git a/packages/ai-mcp-sandbox/src/approval.ts b/packages/ai-mcp-sandbox/src/approval.ts index 014a2d046e..967a7933aa 100644 --- a/packages/ai-mcp-sandbox/src/approval.ts +++ b/packages/ai-mcp-sandbox/src/approval.ts @@ -43,14 +43,31 @@ export function createApprovalStore(ttlMs: number = TTL_MS): ApprovalStore { const pending = new Map() const now = () => Date.now() + const prune = () => { + const t = now() + for (const [id, p] of pending) { + if (p.expiresAtMs < t) pending.delete(id) + } + } + return { propose(clientId, action) { + prune() // bound the map: expired proposals never linger + // Snapshot the action so a later mutation of the caller's object cannot + // change what phase 2 runs. The hash describes this snapshot. + const snapshot = structuredClone(action) const id = randomBytes(18).toString('hex') const actionHash = createHash('sha256') - .update(canonicalize({ clientId, action }), 'utf8') + .update(canonicalize({ clientId, action: snapshot }), 'utf8') .digest('hex') const expiresAtMs = now() + ttlMs - pending.set(id, { id, clientId, action, actionHash, expiresAtMs }) + pending.set(id, { + id, + clientId, + action: snapshot, + actionHash, + expiresAtMs, + }) return { proposalId: id, actionHash, expiresAtMs } }, consume(clientId, proposalId) { diff --git a/packages/ai-mcp-sandbox/src/bin/import.ts b/packages/ai-mcp-sandbox/src/bin/import.ts index 9189c63cd5..35467e8613 100644 --- a/packages/ai-mcp-sandbox/src/bin/import.ts +++ b/packages/ai-mcp-sandbox/src/bin/import.ts @@ -1,5 +1,5 @@ #!/usr/bin/env node -import { basename, extname } from 'node:path' +import { basename, extname, resolve } from 'node:path' import { readFileSync, writeFileSync } from 'node:fs' import { importSnippet } from '../importer' @@ -19,9 +19,20 @@ function main(argv: Array): void { process.exit(1) } const snippet = readFileSync(snippetPath, 'utf8') - const name = basename(snippetPath, extname(snippetPath)) + const ext = extname(snippetPath) + const name = basename(snippetPath, ext) const manifest = importSnippet(snippet, { name }) - const target = outPath ?? snippetPath.replace(/\.[^.]+$/, '.manifest.json') + // Append rather than replace when the snippet has no extension, so we never + // write the manifest back over the snippet. + const target = + outPath ?? + (ext + ? snippetPath.replace(/\.[^.]+$/, '.manifest.json') + : `${snippetPath}.manifest.json`) + if (resolve(target) === resolve(snippetPath)) { + console.error(`Refusing to overwrite the snippet at ${snippetPath}.`) + process.exit(1) + } writeFileSync(target, `${JSON.stringify(manifest, null, 2)}\n`) console.error( `Wrote ${target} (unreviewed). Fill scope/inject/limits and drop "unreviewed" before serving.`, diff --git a/packages/ai-mcp-sandbox/src/capability.ts b/packages/ai-mcp-sandbox/src/capability.ts index e0238fa2a0..9217f5ed44 100644 --- a/packages/ai-mcp-sandbox/src/capability.ts +++ b/packages/ai-mcp-sandbox/src/capability.ts @@ -91,6 +91,11 @@ export function buildPrelude( `${path}[${JSON.stringify(parts[parts.length - 1])}] = ${safeName(dotted)};`, ) } - lines.push(`const input = ${JSON.stringify(input ?? {})};`) + // Parse the input as JSON inside the isolate instead of inlining an object + // literal: JSON.parse keeps a "__proto__" key as an own property, whereas an + // object literal would run the prototype setter and drop it. + lines.push( + `const input = JSON.parse(${JSON.stringify(JSON.stringify(input ?? {}))});`, + ) return lines.join('\n') } diff --git a/packages/ai-mcp-sandbox/src/manifest.ts b/packages/ai-mcp-sandbox/src/manifest.ts index 539fae97ae..05838e9185 100644 --- a/packages/ai-mcp-sandbox/src/manifest.ts +++ b/packages/ai-mcp-sandbox/src/manifest.ts @@ -19,7 +19,10 @@ export function canonicalize(value: unknown): string { function sortKeys(value: unknown): unknown { if (Array.isArray(value)) return value.map(sortKeys) if (value && typeof value === 'object') { - const out: Record = {} + // Null-proto accumulator: `out[key] = ...` sets an own property even when + // key is "__proto__", so a manifest with that key is covered by the + // signature instead of silently dropped from the signing bytes. + const out: Record = Object.create(null) for (const key of Object.keys(value as Record).sort()) { out[key] = sortKeys((value as Record)[key]) } diff --git a/packages/ai-mcp-sandbox/src/sandboxed-tool.ts b/packages/ai-mcp-sandbox/src/sandboxed-tool.ts index 5e4b6a0842..bd5169b9c1 100644 --- a/packages/ai-mcp-sandbox/src/sandboxed-tool.ts +++ b/packages/ai-mcp-sandbox/src/sandboxed-tool.ts @@ -3,9 +3,25 @@ import { buildBindings, buildPrelude, resolveAllowed } from './capability' import { hashSnippet, verifyManifest } from './manifest' import { intersectLimits, makeCallCounter } from './limits' import { byteLength, shapeResult } from './result' +import type { IsolateContext } from '@tanstack/ai-code-mode' import type { MCPToolContext } from '@tanstack/ai-mcp/server' import type { AuditEntry, Manifest, SandboxedToolConfig, Tier } from './types' +/** + * Classify a failed run for the audit outcome. `overCallBudget` comes from the + * host counter, which is authoritative for the injected-call limit; wall-clock + * and memory trips are matched by the driver's error text. + */ +function classifyFailure( + message: string, + overCallBudget: boolean, +): AuditEntry['outcome'] { + if (overCallBudget) return 'limit' + return /timed out|out of memory|memory limit|stack/i.test(message) + ? 'limit' + : 'error' +} + export class UnauthorizedError extends Error { constructor() { super('unauthorized: no verified caller identity') @@ -126,24 +142,29 @@ export function sandboxedTool(config: SandboxedToolConfig) { throw new ScopeDeniedError(manifest.scope) } - // 2. Capability set: declared facades ∩ per-client policy. - const allowed = resolveAllowed(manifest.inject, facades, authInfo, policy) + // Everything past the scope gate runs under one audit boundary: exactly + // one record is emitted whether setup, execution, or shaping fails. const counter = makeCallCounter(limits.maxInjectedCalls) - const bindings = buildBindings({ - allowed, - facades, - authInfo, - signal, - tick: counter.tick, - }) - - // 3. Run the snippet with only those bindings, under the merged limits. - const ctx = await driver.createContext({ - bindings, - timeout: limits.wallClockMs, - memoryLimit: limits.memoryMb, - }) + let audited = false + let ctx: IsolateContext | undefined try { + // 2. Capability set: declared facades ∩ per-client policy. + const allowed = resolveAllowed(manifest.inject, facades, authInfo, policy) + const bindings = buildBindings({ + allowed, + facades, + authInfo, + signal, + tick: counter.tick, + }) + + // 3. Run the snippet with only those bindings, under the merged limits. + ctx = await driver.createContext({ + bindings, + timeout: limits.wallClockMs, + memoryLimit: limits.memoryMb, + }) + // Raw function-body code: top-level return/await. The driver wraps it // (async IIFE + JSON round-trip), so we must NOT wrap it ourselves. const code = `${buildPrelude(allowed, args)}\n${snippet}` @@ -151,8 +172,9 @@ export function sandboxedTool(config: SandboxedToolConfig) { if (!result.success) { const message = result.error?.message ?? 'execution failed' - const limitHit = /timed out|memory|stack/i.test(message) - audit(limitHit ? 'limit' : 'error', counter.count, 0, message) + const overBudget = counter.count > limits.maxInjectedCalls + audit(classifyFailure(message, overBudget), counter.count, 0, message) + audited = true throw new Error(message) } @@ -163,14 +185,20 @@ export function sandboxedTool(config: SandboxedToolConfig) { limits.resultBytes, ) audit('ok', counter.count, byteLength(shaped)) + audited = true return shaped } catch (error) { - if (error instanceof Error && error.name === 'ResultTooLargeError') { - audit('limit', counter.count, 0, error.message) + if (!audited) { + const message = error instanceof Error ? error.message : String(error) + const outcome = + error instanceof Error && error.name === 'ResultTooLargeError' + ? 'limit' + : 'error' + audit(outcome, counter.count, 0, message) } throw error } finally { - await ctx.dispose() + if (ctx) await ctx.dispose() } }) } diff --git a/packages/ai-mcp-sandbox/tests/sandbox.test.ts b/packages/ai-mcp-sandbox/tests/sandbox.test.ts index 2f993636bc..9cfe1293d6 100644 --- a/packages/ai-mcp-sandbox/tests/sandbox.test.ts +++ b/packages/ai-mcp-sandbox/tests/sandbox.test.ts @@ -2,6 +2,7 @@ import { describe, expect, it, vi } from 'vitest' import { createQuickJSIsolateDriver } from '@tanstack/ai-isolate-quickjs' import { ProposalExpiredError, + canonicalize, createApprovalStore, generateManifestKeyPair, hashSnippet, @@ -242,7 +243,82 @@ describe('limits + result shaping', () => { }) }) +describe('prototype-key safety', () => { + it('signs a __proto__ schema key so tampering is caught', () => { + const { publicKey, privateKey } = generateManifestKeyPair() + // Own "__proto__" key, created via JSON.parse (not an object literal). + const asString = JSON.parse( + '{"properties":{"__proto__":{"type":"string"}}}', + ) + const base: Manifest = { ...manifestFor(SNIPPET), inputSchema: asString } + const signed: Manifest = { + ...base, + signature: signManifest(base, privateKey), + } + expect(verifyManifest(signed, publicKey)).toBe(true) + + const asNumber = JSON.parse( + '{"properties":{"__proto__":{"type":"number"}}}', + ) + const tampered: Manifest = { ...signed, inputSchema: asNumber } + // Before the null-proto fix, the __proto__ schema fell out of the signing + // bytes and this changed manifest still verified. Now it does not. + expect(verifyManifest(tampered, publicKey)).toBe(false) + }) + + it('keeps a __proto__ key in the canonical bytes', () => { + expect(canonicalize(JSON.parse('{"__proto__":1}'))).toContain('__proto__') + }) + + it('passes a __proto__ input key as an own property, not the prototype', async () => { + const snippet = `return Object.getOwnPropertyNames(input)` + const tool = sandboxedTool({ + manifest: manifestFor(snippet, { inject: [] }), + snippet, + facades, + driver, + }) + const out = await tool.execute!( + JSON.parse('{"__proto__":{"x":1},"a":2}'), + ctx(authInfo(['demo:read'])), + ) + expect(out).toContain('__proto__') + expect(out).toContain('a') + }) +}) + +describe('audit outcomes', () => { + it('audits an injected-call overrun as a limit, not an error', async () => { + const loop = ` + for (let i = 0; i < 3; i++) { await host.demo.echo({ value: i }); } + return 'done'; + ` + const audits: Array = [] + const tool = sandboxedTool({ + manifest: manifestFor(loop, { + limits: { ...LIMITS, maxInjectedCalls: 1 }, + }), + snippet: loop, + facades, + driver, + onAudit: (e) => audits.push(e), + }) + await expect( + tool.execute!({}, ctx(authInfo(['demo:read']))), + ).rejects.toThrow() + expect(audits.at(-1)).toMatchObject({ outcome: 'limit' }) + }) +}) + describe('two-phase approval', () => { + it('binds the proposal to a snapshot, not the caller object', () => { + const store = createApprovalStore() + const action = { amount: 1 } + const { proposalId } = store.propose('c1', action) + action.amount = 1000 // mutate after proposing + expect(store.consume('c1', proposalId)).toEqual({ amount: 1 }) + }) + it('consumes a valid proposal exactly once', () => { const store = createApprovalStore() const { proposalId } = store.propose('c1', { set: 'on' }) From 935a6e11a2d601edf555f5f9bd89373d1eecd585 Mon Sep 17 00:00:00 2001 From: Jack Herrington Date: Thu, 19 Nov 2026 14:32:38 -0800 Subject: [PATCH 4/6] fix(ai-mcp-sandbox): address CodeRabbit review - approval: cap pending proposals (MAX_PENDING) and evict oldest on overflow so un-consumed proposals cannot grow the map without bound - bin/import: write the manifest with flag 'wx' so a hard/sym link aliasing the snippet (which a resolved-path compare misses) cannot truncate the source; also refuses to clobber a reviewed manifest - sandboxed-tool: set `audited` before invoking onAudit on both the success and execution-failure paths, so a throwing onAudit cannot produce a second (error) record for one execution - docs: state the importer flag is the only gate sandboxedTool checks; the user must review scope/facades/limits before dropping the flag - test: onAudit throwing after success emits exactly one record Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/config.json | 3 ++- docs/mcp/server-sandboxed-tools.md | 2 +- packages/ai-mcp-sandbox/src/approval.ts | 22 ++++++++++++++++++- packages/ai-mcp-sandbox/src/bin/import.ts | 17 +++++++++++++- packages/ai-mcp-sandbox/src/sandboxed-tool.ts | 8 +++++-- packages/ai-mcp-sandbox/tests/sandbox.test.ts | 20 +++++++++++++++++ 6 files changed, 66 insertions(+), 6 deletions(-) diff --git a/docs/config.json b/docs/config.json index bc772fea69..c93c494979 100644 --- a/docs/config.json +++ b/docs/config.json @@ -736,7 +736,8 @@ { "label": "Sandboxed Tools", "to": "mcp/server-sandboxed-tools", - "addedAt": "2026-11-16" + "addedAt": "2026-11-16", + "updatedAt": "2026-11-19" }, { "label": "MCP Server Sessions", diff --git a/docs/mcp/server-sandboxed-tools.md b/docs/mcp/server-sandboxed-tools.md index 325ad25d86..1beb3df151 100644 --- a/docs/mcp/server-sandboxed-tools.md +++ b/docs/mcp/server-sandboxed-tools.md @@ -192,7 +192,7 @@ Turn a plain [Code Mode](../code-mode/code-mode) snippet into a starting manifes npx --package=@tanstack/ai-mcp-sandbox tanstack-ai-sandbox-import ./my-snippet.js ``` -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. +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. ## Lasting writes diff --git a/packages/ai-mcp-sandbox/src/approval.ts b/packages/ai-mcp-sandbox/src/approval.ts index 967a7933aa..ef8447c713 100644 --- a/packages/ai-mcp-sandbox/src/approval.ts +++ b/packages/ai-mcp-sandbox/src/approval.ts @@ -38,6 +38,12 @@ export interface ApprovalStore { } const TTL_MS = 5 * 60 * 1000 +/** + * Hard ceiling on pending proposals. Even if every proposal is live, the map + * cannot grow without bound: once full, propose() evicts the oldest-expiring + * entry so a flood of un-consumed proposals cannot exhaust memory. + */ +const MAX_PENDING = 10_000 export function createApprovalStore(ttlMs: number = TTL_MS): ApprovalStore { const pending = new Map() @@ -48,11 +54,25 @@ export function createApprovalStore(ttlMs: number = TTL_MS): ApprovalStore { for (const [id, p] of pending) { if (p.expiresAtMs < t) pending.delete(id) } + // After dropping expired entries, if still at the ceiling, evict the + // oldest-expiring proposals until there is room for one more. + while (pending.size >= MAX_PENDING) { + let oldestId: string | undefined + let oldestExp = Infinity + for (const [id, p] of pending) { + if (p.expiresAtMs < oldestExp) { + oldestExp = p.expiresAtMs + oldestId = id + } + } + if (oldestId === undefined) break + pending.delete(oldestId) + } } return { propose(clientId, action) { - prune() // bound the map: expired proposals never linger + prune() // bound the map: expired/overflow proposals never linger // Snapshot the action so a later mutation of the caller's object cannot // change what phase 2 runs. The hash describes this snapshot. const snapshot = structuredClone(action) diff --git a/packages/ai-mcp-sandbox/src/bin/import.ts b/packages/ai-mcp-sandbox/src/bin/import.ts index 35467e8613..aa991dd8ef 100644 --- a/packages/ai-mcp-sandbox/src/bin/import.ts +++ b/packages/ai-mcp-sandbox/src/bin/import.ts @@ -33,7 +33,22 @@ function main(argv: Array): void { console.error(`Refusing to overwrite the snippet at ${snippetPath}.`) process.exit(1) } - writeFileSync(target, `${JSON.stringify(manifest, null, 2)}\n`) + try { + // 'wx' fails with EEXIST if the target exists — including when it is a + // hard link or symlink aliasing the snippet, which a resolved-path compare + // cannot detect. It also refuses to clobber a reviewed manifest in place. + writeFileSync(target, `${JSON.stringify(manifest, null, 2)}\n`, { + flag: 'wx', + }) + } catch (error) { + if ((error as NodeJS.ErrnoException).code === 'EEXIST') { + console.error( + `Refusing to overwrite the existing file at ${target}. Remove it first.`, + ) + process.exit(1) + } + throw error + } console.error( `Wrote ${target} (unreviewed). Fill scope/inject/limits and drop "unreviewed" before serving.`, ) diff --git a/packages/ai-mcp-sandbox/src/sandboxed-tool.ts b/packages/ai-mcp-sandbox/src/sandboxed-tool.ts index bd5169b9c1..be885c09c5 100644 --- a/packages/ai-mcp-sandbox/src/sandboxed-tool.ts +++ b/packages/ai-mcp-sandbox/src/sandboxed-tool.ts @@ -173,8 +173,10 @@ export function sandboxedTool(config: SandboxedToolConfig) { if (!result.success) { const message = result.error?.message ?? 'execution failed' const overBudget = counter.count > limits.maxInjectedCalls - audit(classifyFailure(message, overBudget), counter.count, 0, message) + // Mark audited before invoking onAudit: if the callback throws, the + // catch must not emit a second (error) record for this one execution. audited = true + audit(classifyFailure(message, overBudget), counter.count, 0, message) throw new Error(message) } @@ -184,8 +186,10 @@ export function sandboxedTool(config: SandboxedToolConfig) { manifest.truncatable, limits.resultBytes, ) - audit('ok', counter.count, byteLength(shaped)) + // Mark audited before invoking onAudit: if the callback throws, the + // catch must not emit a second (error) record for this one execution. audited = true + audit('ok', counter.count, byteLength(shaped)) return shaped } catch (error) { if (!audited) { diff --git a/packages/ai-mcp-sandbox/tests/sandbox.test.ts b/packages/ai-mcp-sandbox/tests/sandbox.test.ts index 9cfe1293d6..c7599d82aa 100644 --- a/packages/ai-mcp-sandbox/tests/sandbox.test.ts +++ b/packages/ai-mcp-sandbox/tests/sandbox.test.ts @@ -104,6 +104,26 @@ describe('sandboxedTool — end to end on quickjs', () => { }) }) + it('does not emit a second audit record when onAudit throws after success', async () => { + let calls = 0 + const tool = sandboxedTool({ + manifest: manifestFor(SNIPPET), + snippet: SNIPPET, + facades, + driver, + onAudit: () => { + calls++ + throw new Error('sink down') + }, + }) + // The success-path onAudit throws; the catch must not call onAudit again + // (audited is set before the first call), so exactly one record is emitted. + await expect( + tool.execute!({ value: 'hi' }, ctx(authInfo(['demo:read']))), + ).rejects.toThrow('sink down') + expect(calls).toBe(1) + }) + it('denies a caller missing the required scope — no isolate run', async () => { const tool = sandboxedTool({ manifest: manifestFor(SNIPPET), From 90d6fbc8c594b1751ed6ec64ac3f37d70050becf Mon Sep 17 00:00:00 2001 From: Jack Herrington Date: Thu, 19 Nov 2026 14:54:18 -0800 Subject: [PATCH 5/6] fix(mcp-sandbox): harden approval store, audit classification, and docs Address CodeRabbit round-2 review on PR #2171. approval.ts: - propose(): prepare snapshot/id/hash before prune() so a DataCloneError (e.g. a function action) never evicts a live proposal first. - consume(): check validity and ownership before deleting, so a foreign client cannot evict the real owner's proposal. sandboxed-tool.ts: - classifyFailure(): stop treating every message containing "stack" as a limit; match only real stack-overflow text so app errors stay 'error'. - Snapshot (structuredClone) the manifest before verifying, so later host mutation of scope/inject/truncatable cannot bypass the signed contract. - Reject a caught injected-call overrun after a "successful" run, auditing it as 'limit'. docs/mcp/server-sandboxed-tools.md: - Bound the host facade response body with a streamed byte cap. - Show auth config (jwtVerifier) in the quick-setup example + link to auth. - Split signing into an offline step; server only loads the public key. - Clarify proposal ids prevent replay, not write dedup; recommend a durable idempotency key. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/mcp/server-sandboxed-tools.md | 80 ++++++++++++++++--- packages/ai-mcp-sandbox/src/approval.ts | 11 ++- packages/ai-mcp-sandbox/src/sandboxed-tool.ts | 24 +++++- packages/ai-mcp-sandbox/tests/sandbox.test.ts | 71 ++++++++++++++++ 4 files changed, 170 insertions(+), 16 deletions(-) diff --git a/docs/mcp/server-sandboxed-tools.md b/docs/mcp/server-sandboxed-tools.md index 1beb3df151..1f89c68d06 100644 --- a/docs/mcp/server-sandboxed-tools.md +++ b/docs/mcp/server-sandboxed-tools.md @@ -43,6 +43,40 @@ The driver is swappable. `@tanstack/ai-isolate-quickjs` runs anywhere, including ```ts // src/facades.ts const ALLOWED = new Set(['https://api.example.com']) +// Cap the body read into the host process. The isolate limits bound the +// snippet's heap and result, not what the facade buffers, so an allowed +// endpoint that returns a huge body could exhaust host memory without this. +const MAX_BODY_BYTES = 256 * 1024 + +async function readCapped(response: Response, max: number): Promise { + const body = response.body + if (!body) return '' + const reader = body.getReader() + const chunks: Array = [] + let total = 0 + try { + for (;;) { + const { done, value } = await reader.read() + if (done) break + total += value.length + if (total > max) { + await reader.cancel() + throw new Error('response body too large') + } + chunks.push(value) + } + } finally { + reader.releaseLock() + } + return new TextDecoder().decode( + chunks.reduce((acc, c) => { + const next = new Uint8Array(acc.length + c.length) + next.set(acc) + next.set(c, acc.length) + return next + }, new Uint8Array(0)), + ) +} export const facades = { 'http.get': { @@ -59,7 +93,7 @@ export const facades = { redirect: 'error', signal: AbortSignal.timeout(3000), }) - return response.text() + return readCapped(response, MAX_BODY_BYTES) }, }, } @@ -69,7 +103,7 @@ export const facades = { ```ts group=server-sandboxed-tools // src/mcp-server.ts -import { createMCPServer } from '@tanstack/ai-mcp/server' +import { createMCPServer, jwtVerifier } from '@tanstack/ai-mcp/server' import { hashSnippet, sandboxedTool } from '@tanstack/ai-mcp-sandbox' import { createQuickJSIsolateDriver } from '@tanstack/ai-isolate-quickjs' import type { Manifest } from '@tanstack/ai-mcp-sandbox' @@ -109,11 +143,21 @@ const pageSize = sandboxedTool({ manifest, snippet, facades, driver }) export const server = createMCPServer({ name: 'web', version: '1.0.0', + // A sandboxed tool needs a verified caller: the scope gate reads the token's + // scopes (here, web:read). Without auth there is no caller and the tool + // throws before the snippet runs. See MCP Server Auth for the full setup. + auth: { + verifier: jwtVerifier({ + jwksUrl: 'https://auth.example.com/.well-known/jwks.json', + issuer: 'https://auth.example.com/', + audience: 'https://mcp.example.com/mcp', + }), + }, tools: [pageSize], // mix freely with plain tools }) ``` -Serve it from a route the same way as any MCP server. See [Serve Tools over HTTP](./server). +The `scope` on the manifest (`web:read`) must be one of the token's scopes, or the caller gets a scope error and the snippet never runs. See [MCP Server Auth](./server-auth) for issuing and verifying those tokens. Serve it from a route the same way as any MCP server. See [Serve Tools over HTTP](./server). ## How a call runs @@ -166,16 +210,28 @@ sandboxedTool({ 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. -Signing uses Ed25519. Pass the public key and require a valid signature: +Signing uses Ed25519. It happens in two separate places. Keep them apart: if the server both signs and verifies, a manifest tampered with before signing gets a fresh, valid signature, and verification can no longer catch the change. -```ts group=server-sandboxed-tools -import { generateManifestKeyPair, signManifest } from '@tanstack/ai-mcp-sandbox' +Step one is offline, on a trusted machine. A reviewer checks the manifest, signs it with a private key the server never sees, and keeps that private key protected: + +```ts +// sign-manifest.ts — run once, offline, on a trusted machine. The private key +// stays here and never ships to the server. +import { signManifest } from '@tanstack/ai-mcp-sandbox' + +// privateKey comes from your secret store or an earlier generateManifestKeyPair(). +const signature = signManifest(reviewedManifest, privateKey) +// Attach `signature` to the manifest you ship, and publish only the matching +// public key to the server. +``` -const { publicKey, privateKey } = generateManifestKeyPair() -const signature = signManifest(manifest, privateKey) +Step two is on the server. It loads only the public key and the already-signed manifest, and requires a valid signature. It never holds the private key: +```ts group=server-sandboxed-tools +// The manifest arrives already signed; publicKey is the one matching key the +// server trusts. The server cannot sign, only verify. sandboxedTool({ - manifest: { ...manifest, signature }, + manifest: signedManifest, snippet, facades, driver, @@ -184,6 +240,8 @@ sandboxedTool({ }) ``` +`generateManifestKeyPair()` makes the key pair once, during setup, not on every serve. + ## Import an existing snippet Turn a plain [Code Mode](../code-mode/code-mode) snippet into a starting manifest with the CLI: @@ -198,4 +256,6 @@ It writes a deny-by-default manifest: a placeholder scope, no facades, the tight A sandboxed tool is a good fit for reads and safe actions. Approval never happens inside the isolate. -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. +Use a two-phase proposal to put a human decision in front of a write. 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. + +A proposal id stops one id from being replayed: consume it once and a second consume of the same id fails. It is not write deduplication. Each `propose()` call mints a new id, so the same action proposed twice yields two ids, and consuming both runs the write twice. For a write that must never run twice, carry a durable idempotency key into the write itself (a unique order id, a row your database rejects on a second insert) so the underlying store refuses the duplicate. diff --git a/packages/ai-mcp-sandbox/src/approval.ts b/packages/ai-mcp-sandbox/src/approval.ts index ef8447c713..8537f3787d 100644 --- a/packages/ai-mcp-sandbox/src/approval.ts +++ b/packages/ai-mcp-sandbox/src/approval.ts @@ -72,15 +72,16 @@ export function createApprovalStore(ttlMs: number = TTL_MS): ApprovalStore { return { propose(clientId, action) { - prune() // bound the map: expired/overflow proposals never linger - // Snapshot the action so a later mutation of the caller's object cannot - // change what phase 2 runs. The hash describes this snapshot. + // Prepare the proposal fully before touching the map. If snapshotting + // throws (e.g. structuredClone rejects a function with DataCloneError), + // we must not have already evicted a live proposal to make room. const snapshot = structuredClone(action) const id = randomBytes(18).toString('hex') const actionHash = createHash('sha256') .update(canonicalize({ clientId, action: snapshot }), 'utf8') .digest('hex') const expiresAtMs = now() + ttlMs + prune() // bound the map: expired/overflow proposals never linger pending.set(id, { id, clientId, @@ -92,10 +93,12 @@ export function createApprovalStore(ttlMs: number = TTL_MS): ApprovalStore { }, consume(clientId, proposalId) { const p = pending.get(proposalId) - pending.delete(proposalId) // single-use: gone whether or not it was valid + // Check validity and ownership BEFORE deleting. A client that supplies a + // proposal it does not own must not evict the real owner's proposal. if (!p || p.clientId !== clientId || p.expiresAtMs < now()) { throw new ProposalExpiredError() } + pending.delete(proposalId) // single-use: a valid owner consumes it once return p.action }, } diff --git a/packages/ai-mcp-sandbox/src/sandboxed-tool.ts b/packages/ai-mcp-sandbox/src/sandboxed-tool.ts index be885c09c5..8c71223957 100644 --- a/packages/ai-mcp-sandbox/src/sandboxed-tool.ts +++ b/packages/ai-mcp-sandbox/src/sandboxed-tool.ts @@ -17,7 +17,12 @@ function classifyFailure( overCallBudget: boolean, ): AuditEntry['outcome'] { if (overCallBudget) return 'limit' - return /timed out|out of memory|memory limit|stack/i.test(message) + // Match only genuine resource diagnostics. "stack" alone is too broad: an + // application error like `stack service unavailable` must stay an 'error', + // so we only treat a real stack-overflow message as a limit. + return /timed out|out of memory|memory limit|stack overflow|maximum call stack/i.test( + message, + ) ? 'limit' : 'error' } @@ -89,7 +94,7 @@ function assertServable( */ export function sandboxedTool(config: SandboxedToolConfig) { const { - manifest, + manifest: callerManifest, snippet, facades, driver, @@ -100,6 +105,11 @@ export function sandboxedTool(config: SandboxedToolConfig) { onAudit, } = config + // Snapshot the manifest once so the verified contract is a fixed snapshot: + // host code that still holds the config object cannot mutate manifest.scope, + // manifest.inject, or manifest.truncatable after construction and have the + // next call read the new values without a fresh signature check. + const manifest = structuredClone(callerManifest) assertServable(manifest, snippet, publicKey, requireSignature) const limits = intersectLimits(manifest.limits, serverCaps) @@ -180,6 +190,16 @@ export function sandboxedTool(config: SandboxedToolConfig) { throw new Error(message) } + // A snippet can catch the injected-call rejection and still return a + // value. The documented contract says an over-budget run stops, so treat + // a tripped counter as a limit even on an otherwise-successful run. + if (counter.count > limits.maxInjectedCalls) { + const message = `Injected-call limit reached (${limits.maxInjectedCalls})` + audited = true + audit('limit', counter.count, 0, message) + throw new Error(message) + } + // 4. Shape: author-declared truncation + result-size cap. const shaped = shapeResult( result.value, diff --git a/packages/ai-mcp-sandbox/tests/sandbox.test.ts b/packages/ai-mcp-sandbox/tests/sandbox.test.ts index c7599d82aa..af3c87ef36 100644 --- a/packages/ai-mcp-sandbox/tests/sandbox.test.ts +++ b/packages/ai-mcp-sandbox/tests/sandbox.test.ts @@ -328,6 +328,59 @@ describe('audit outcomes', () => { ).rejects.toThrow() expect(audits.at(-1)).toMatchObject({ outcome: 'limit' }) }) + + it('rejects a caught injected-call overrun instead of returning success', async () => { + // The snippet swallows the over-budget rejection and returns normally. + const sneaky = ` + await host.demo.echo({ value: 1 }); + try { await host.demo.echo({ value: 2 }); } catch (e) {} + return 'done'; + ` + const audits: Array = [] + const tool = sandboxedTool({ + manifest: manifestFor(sneaky, { + limits: { ...LIMITS, maxInjectedCalls: 1 }, + }), + snippet: sneaky, + facades, + driver, + onAudit: (e) => audits.push(e), + }) + await expect( + tool.execute!({}, ctx(authInfo(['demo:read']))), + ).rejects.toThrow(/Injected-call limit/) + expect(audits).toHaveLength(1) + expect(audits.at(-1)).toMatchObject({ outcome: 'limit' }) + }) + + it('audits an ordinary error whose message contains "stack" as an error, not a limit', async () => { + const snippet = `throw new Error('stack service unavailable')` + const audits: Array = [] + const tool = sandboxedTool({ + manifest: manifestFor(snippet, { inject: [] }), + snippet, + facades, + driver, + onAudit: (e) => audits.push(e), + }) + await expect( + tool.execute!({}, ctx(authInfo(['demo:read']))), + ).rejects.toThrow() + expect(audits.at(-1)).toMatchObject({ outcome: 'error' }) + }) + + it('enforces the scope snapshotted at build time, ignoring later manifest mutation', async () => { + const manifest = manifestFor(SNIPPET) + const tool = sandboxedTool({ manifest, snippet: SNIPPET, facades, driver }) + // Mutating the caller's manifest after construction must not change the + // enforced scope — the wrapper works from a detached snapshot. + manifest.scope = 'demo:admin' + const out = await tool.execute!( + { value: 'hi' }, + ctx(authInfo(['demo:read'])), + ) + expect(out).toEqual({ echoed: 'echo:hi' }) + }) }) describe('two-phase approval', () => { @@ -352,6 +405,24 @@ describe('two-phase approval', () => { const { proposalId } = store.propose('c1', { set: 'on' }) expect(() => store.consume('c2', proposalId)).toThrow(ProposalExpiredError) }) + + it('does not evict the owner proposal when a foreign client consumes it', () => { + const store = createApprovalStore() + const { proposalId } = store.propose('c1', { set: 'on' }) + // A client that does not own the proposal must not consume (delete) it. + expect(() => store.consume('c2', proposalId)).toThrow(ProposalExpiredError) + // The real owner can still consume it afterwards. + expect(store.consume('c1', proposalId)).toEqual({ set: 'on' }) + }) + + it('does not drop a live proposal when preparing an un-cloneable action', () => { + const store = createApprovalStore() + const { proposalId } = store.propose('c1', { set: 'on' }) + // A function action throws DataCloneError inside structuredClone before the + // map is pruned, so the existing proposal must survive the failed propose. + expect(() => store.propose('c2', () => {})).toThrow() + expect(store.consume('c1', proposalId)).toEqual({ set: 'on' }) + }) }) describe('per-client policy', () => { From e148211d8f19064328f8658dba70afeb04840923 Mon Sep 17 00:00:00 2001 From: Jack Herrington Date: Thu, 19 Nov 2026 15:10:23 -0800 Subject: [PATCH 6/6] docs(mcp-sandbox): fix kiira type-check on sandboxed-tools snippets The offline-signing snippets referenced reviewedManifest, privateKey, signedManifest, and publicKey without declaring them, so kiira's type-check failed (TS2304/TS18004). Declare them with `declare const` (typed as Manifest/string) so the fences type-check while keeping the sign-offline / verify-on-server split and security guidance intact. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/mcp/server-sandboxed-tools.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/mcp/server-sandboxed-tools.md b/docs/mcp/server-sandboxed-tools.md index 1f89c68d06..7a715b8757 100644 --- a/docs/mcp/server-sandboxed-tools.md +++ b/docs/mcp/server-sandboxed-tools.md @@ -218,8 +218,13 @@ Step one is offline, on a trusted machine. A reviewer checks the manifest, signs // sign-manifest.ts — run once, offline, on a trusted machine. The private key // stays here and never ships to the server. import { signManifest } from '@tanstack/ai-mcp-sandbox' +import type { Manifest } from '@tanstack/ai-mcp-sandbox' +// The manifest a reviewer has read and approved by hand. +declare const reviewedManifest: Manifest // privateKey comes from your secret store or an earlier generateManifestKeyPair(). +declare const privateKey: string + const signature = signManifest(reviewedManifest, privateKey) // Attach `signature` to the manifest you ship, and publish only the matching // public key to the server. @@ -230,6 +235,9 @@ Step two is on the server. It loads only the public key and the already-signed m ```ts group=server-sandboxed-tools // The manifest arrives already signed; publicKey is the one matching key the // server trusts. The server cannot sign, only verify. +declare const signedManifest: Manifest +declare const publicKey: string + sandboxedTool({ manifest: signedManifest, snippet,