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..c93c494979 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,12 @@ "addedAt": "2026-09-22", "updatedAt": "2026-10-22" }, + { + "label": "Sandboxed Tools", + "to": "mcp/server-sandboxed-tools", + "addedAt": "2026-11-16", + "updatedAt": "2026-11-19" + }, { "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..7a715b8757 --- /dev/null +++ b/docs/mcp/server-sandboxed-tools.md @@ -0,0 +1,269 @@ +--- +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']) +// 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': { + 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') + // 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 readCapped(response, MAX_BODY_BYTES) + }, + }, +} +``` + +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, 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' +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', + // 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 +}) +``` + +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 + +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. 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. + +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' +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. +``` + +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. +declare const signedManifest: Manifest +declare const publicKey: string + +sandboxedTool({ + manifest: signedManifest, + snippet, + facades, + driver, + publicKey, + requireSignature: true, +}) +``` + +`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: + +```sh +npx --package=@tanstack/ai-mcp-sandbox tanstack-ai-sandbox-import ./my-snippet.js +``` + +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 + +A sandboxed tool is a good fit for reads and safe actions. Approval never happens inside the isolate. + +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/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..ede8ec1345 --- /dev/null +++ b/packages/ai-mcp-sandbox/README.md @@ -0,0 +1,138 @@ +
+ + + + 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 ALLOWED = new Set(['https://api.example.com']) +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') + return (await fetch(url, { redirect: 'error' })).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..8537f3787d --- /dev/null +++ b/packages/ai-mcp-sandbox/src/approval.ts @@ -0,0 +1,105 @@ +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 +/** + * 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() + const now = () => Date.now() + + const prune = () => { + const t = now() + 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) { + // 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, + action: snapshot, + actionHash, + expiresAtMs, + }) + return { proposalId: id, actionHash, expiresAtMs } + }, + consume(clientId, proposalId) { + const p = pending.get(proposalId) + // 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/bin/import.ts b/packages/ai-mcp-sandbox/src/bin/import.ts new file mode 100644 index 0000000000..aa991dd8ef --- /dev/null +++ b/packages/ai-mcp-sandbox/src/bin/import.ts @@ -0,0 +1,57 @@ +#!/usr/bin/env node +import { basename, extname, resolve } 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 ext = extname(snippetPath) + const name = basename(snippetPath, ext) + const manifest = importSnippet(snippet, { name }) + // 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) + } + 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.`, + ) +} + +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..9217f5ed44 --- /dev/null +++ b/packages/ai-mcp-sandbox/src/capability.ts @@ -0,0 +1,101 @@ +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)};`, + ) + } + // 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/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..05838e9185 --- /dev/null +++ b/packages/ai-mcp-sandbox/src/manifest.ts @@ -0,0 +1,76 @@ +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') { + // 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]) + } + 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..8c71223957 --- /dev/null +++ b/packages/ai-mcp-sandbox/src/sandboxed-tool.ts @@ -0,0 +1,228 @@ +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 { 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' + // 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' +} + +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: callerManifest, + snippet, + facades, + driver, + serverCaps, + policy, + publicKey, + requireSignature, + 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) + + 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) + } + + // 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) + 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}` + const result = await ctx.execute(code, signal ? { signal } : undefined) + + if (!result.success) { + const message = result.error?.message ?? 'execution failed' + const overBudget = counter.count > limits.maxInjectedCalls + // 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) + } + + // 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, + manifest.truncatable, + limits.resultBytes, + ) + // 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) { + 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 { + if (ctx) 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..af3c87ef36 --- /dev/null +++ b/packages/ai-mcp-sandbox/tests/sandbox.test.ts @@ -0,0 +1,445 @@ +import { describe, expect, it, vi } from 'vitest' +import { createQuickJSIsolateDriver } from '@tanstack/ai-isolate-quickjs' +import { + ProposalExpiredError, + canonicalize, + 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('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), + 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('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' }) + }) + + 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', () => { + 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' }) + 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) + }) + + 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', () => { + 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: {}