DOCUMENTATION · v0.12.2

Code Mode options and security review — AI Auth

Date: 2026-11-19 Status: Design/research only; not a new executable backend Decision: Preserve direct tool calls as the default. The existing --code-mode and ai_auth_code route remain optional. Evaluate safe extension to MCP / WebMCP / UTCP _after_ provider authorization and sandbox gates.

ConcernCloudflare (initial + later Code Mode)Pi coding agent (0.99+ built-in Code Mode)AI Auth current code
RoleProgrammatically orchestrates MCP/API calls; can sit behind a Code Mode MCP serverOptional local codemode tool for calling registered tools through JavaScriptOptional ai_auth_code exposed by MCP server when --code-mode
Execution environmentCloudflare Dynamic Workers / V8 isolate; no arbitrary internet or filesystem by default in described profileQuickJS WASM sandbox inside a worker, per public release docsNode worker_threads + node:vm with codeGeneration disabled
DiscoveryTypes and progressive search/describe in newer docstool_search plus tool namespaces and configured inline budgetaiAuth.listTools() shows joined room catalogs (WebMCP and participant tools)
AuthorizationHost-side dispatch approvals remain mandatoryTool invocations mediated by Pi harnessCode Mode calls the same AI Auth host bridge invoke path; site provider still approves
Existing APIsMCP tools can be converted into typed SDK; Cloudflare later runs behind MCPAny registered tool and optional MCP supportstatus, listTools, events, send, move, invoke only
Default behaviorDepends on app configurationExplicitly selectable in tools/configOff unless --code-mode and tools.invoke granted
Adversarial isolationIsolated Worker model; still subject to workerd security vulnerabilitiesQuickJS adds guest isolation; security must be verified for current releasevm is NOT a hard security sandbox; runs with host process privileges
Bounded operationPer execution and sandbox budget according to platformTool/script limits and output controls via config8,000-character script, ~2s host timer, 50 logs, bounded exposed event list
Best reuse for AI AuthAPI/progressive discovery concepts and per-call host checksOpt-in UX, tool namespaces, result filtering, QuickJS comparisonReuse current flag/tool/dispatch; no parallel second engine

This matrix is based on public docs and inspected AI Auth code, not a security audit or interoperability benchmark.

Code Mode is not authorization#

Model-written code is untrusted, even in a local coding harness.

For every script-originated invocation, the trusted host must check:

  1. which agent/key/session is invoking;
  2. exact target provider, origin and resource;
  3. token/issuer audience and native transport authorization;
  4. owner-approved scope and per-tool site policy;
  5. whether new consent is required for mutating/high-risk actions;
  6. session/catalog freshness and revocation;
  7. call budgets, deadlines and cancellation;
  8. audit metadata and truthful side-effect status.

A successful sandbox result does not imply the operation was authorized. The host dispatcher is the policy enforcement point; the guest cannot be allowed to assert approval.

Do not grant a script ambient network/fetch, process, filesystem, arbitrary imports, API keys, OAuth tokens, payment credentials, or the ability to alter the tool registry.

AI Auth implementation-specific observations#

Inspected:

  • packages/mcp/cli.js — --code-mode parsed.
  • packages/mcp/bridge.js — buildAgentActions hides ai_auth_code unless codeMode true and relevant scope approved; runCode starts worker.
  • packages/mcp/code-mode-worker.js — guest-realm wrappers and JSON bridge; node:vm codeGeneration disabled.
  • packages/mcp/test/code-mode-timeout.test.mjs — verifies runaway async loop termination and cancellation signal for active tool invocation.
  • docs/mcp.md — user-facing opt-in and limitations.

Positive:

  • Non-replacing opt-in design already matches the user's requirement.
  • Host's api.invoke goes through connection, catalog lookup and remote provider rules.
  • Each code execution receives a new worker and host timeout, not just Promise.race.
  • Existing direct MCP actions remain present.
  • Guest doesn't get join, leave or act through the script API.

Gaps / security questions (tests required, not reported vulnerabilities):

  • node:vm is not a high-assurance boundary for hostile generated code; evaluate QuickJS/subprocess/isolate options and published workerd sandbox security research.
  • The global script timeout cannot reverse committed side effects (especially send and non-idempotent invoke). This is now reported honestly with partial: true and rolledBack: false; no blind retry is attempted. A stronger sandbox is still required before hostile-code use.
  • Current async send now passes the shared abort controller; termination semantics are covered by code-mode-hardening.test.mjs. Transport-level sends already committed are still irreversible.
  • Per-script tool call count (64) and outstanding-call cap (8) are now enforced in packages/mcp/bridge.js and tested. Nested fan-out remains bounded by those two caps rather than by a separate depth limit.
  • UTCP now has an optional adapter with destination and credential gates and injected-client tests (tests/utcp-adapter.test.mjs), but it is not yet routed through Code Mode. Its redirect preflight is advisory because the official SDK's transport is not controlled by this adapter; do not claim full SSRF containment.
  • Guest logs now cap both count (50) and per-entry length (240 chars), and shared-buffer replies reject oversized data explicitly.
  • The synchronous shared buffer now rejects oversized or corrupt replies with an explicit error instead of truncating JSON (packages/mcp/bridge.js, code-mode-worker.js).
  • A runtime escape may threaten the host MCP process's credentials; never advertise hostile multi-tenant isolation under the current design.

Do not assume Cloudflare's or Pi's sandbox proves the safety of AI Auth's own implementation. Likewise, do not assume a cited vulnerability affects a patched runtime version without reproduction or advisory matching.

Suggested decision#

  • Keep: --code-mode, ai_auth_code, direct tools, existing connection/permission checks.
  • Harden first: sandbox assurance, resource bounds, per-call approval, cancellation/partial success, output limits and audit.
  • Additive second step: provider-aware discovery/description of MCP, WebMCP, UTCP with exact native authorization.
  • Optional third step: isolated QuickJS or process backend after benchmark. No Cloudflare-hosted mandatory service.
  • Not yet: cross-provider write operations, payment mandates, credential issuance, arbitrary JavaScript networking, or automatic code-mode enablement for all agents.

The UX should permit (a) normal direct calls, (b) opt-in code orchestration for trusted read-only or low-risk tasks, (c) off again without losing functionality.

Required comparisons and measurable tests#

ScenarioDirectOptional Code ModePass condition
List 50 harmless toolsListing native descriptorsProgressive search/describe via guestSame authorized visibility, less/equal irrelevant context if claimed
Read 5 independent mock sources5 explicit callsScript batches calls with bounded concurrencySame results and auth, truthful per-call status
Provider denies toolDeniedCode program attempts same toolSame denial, no bypass
Ambiguous tool name across providersExplicit selectionNamespaced selectionNo wrong-target execution
Wrong origin, stale catalogDeniedScript tries stale capabilityDenied
Cancels during slow callIn-flight abortWorker timeout/abortAbort if possible, side effects reported honestly
Script attempts process/env/fetchN/AGuest code attempts escapeNo access; test under isolated risk model
Script triggers destructive toolExplicit high-risk approvalProgrammatic callDenied by default; no automatic consent
UTCP endpoint points to localhost/private IPEndpoint validationScript attempts direct callBoth blocked unless explicit policy
Expired payment mandateNo payment permissionProgram attempts purchaseNever reaches payment execution
Large payload/log or infinite async loopBounded inputHost-enforced limitsNo crash, no secret disclosure, clear outcome

Record measurements for token input, tool schemas injected, runtime latency, startup, memory, total tool calls, and errors. Cloudflare's reported savings are not AI Auth measurements.

  • Cloudflare original: https://blog.cloudflare.com/code-mode
  • Cloudflare code-mode MCP server: https://blog.cloudflare.com/code-mode-mcp/
  • Cloudflare current agent docs: https://developers.cloudflare.com/agents/tools/codemode/mcp/
  • Cloudflare isolation docs: https://developers.cloudflare.com/dynamic-workers/examples/codemode/
  • Pi release notes: https://pi.dev/changelog/releases/0.99.0
  • Pi CLI: https://docs.pi.dev/latest/cli
  • MCP programmatic tool calling guidance: https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/docs/2026-07-28/develop/clients/client-best-practices.mdx
  • Check Point workerd sandbox research: https://research.checkpoint.com/2026/when-agentic-glue-melts/

Independent reviewer assignment#

  1. Confirm exact package and runtime versions, then examine vm/Worker escape surface and outstanding execution accounting.
  2. Produce tests for the noted limits and allowlist requirements.
  3. Compare QuickJS/isolate/subprocess backend costs in Node and browser environments, considering no mandatory external service.
  4. Determine whether the existing trusted MCP host dispatch can safely route separate WebMCP and UTCP adapters while preserving native auth.
  5. Do not ship increased tool reach or a new sandbox backend until the review gate and tests pass.

The safe design is one explicit execution-mode choice above provider-specific tools, not an AI Auth-owned replacement for the tools themselves.

On this page