DOCUMENTATION · v0.12.2

Threat model

Status: proposed threat model for the architecture in REFERENCE_ARCHITECTURE.md. As-is controls cite files at v0.11.1. "Control" rows marked proposed are not implemented. Every security claim must have test evidence or be labelled unverified.

1. Assets#

AssetAs-is protection
Signing private keyNon-extractable IndexedDB in browser; encrypted mode 0600 file keystore for headless agents (docs/ARCHITECTURE.md, packages/agent/README.md).
Consent and grantsSigned, origin-bound, bounded lifetime, stored as public data (packages/p2p/capabilities.js, grant-store.js).
Agent identityagent: thumbprint of public JWK; signature proves key control only (packages/p2p/index.js, docs/SECURITY.md).
Tool catalogsBounded, signed, 120 s expiry, 45 s refresh (packages/p2p/webmcp.js).
Approval decisionsHuman authorize callback; authorizeProtected fails closed (packages/p2p/webmcp.js, membership.js).
Audit metadataBounded local logs: 256 P2PRoom.audit entries, 100 activity entries (packages/p2p/p2p.js, index.js).
User data in a pagePage owns its data; WebMCP results marked untrusted; no secrets in room (docs/SECURITY.md).

2. Attackers and entry points#

AttackerEntry points
Malicious peer in a roomSigned events, chat, cursors, tool requests and results.
Malicious or compromised tool providerTool name, description, schema, result payload, error text.
Malicious websiteConnect request, capability list, WebMCP registration, tool annotations, iframe embedding.
Relay operatorTiming, participation and hashed room topic.
Stolen credential holderMCP HTTP secret URL, UTCP provider token, wallet backup file.
Malicious dependencynpm updates in any package, especially adapters.
Network attackerDNS rebinding, redirect chains, private-network addressing, replayed requests.

3. Attacks, controls and evidence#

AttackAs-is controlProposed controlEvidence / status
Forged identity claimverifyEnvelope checks signature, issuer, audience, freshnessKeep; add standardized proof verification additivelytests/did.test.mjs, tests/webmcp-contract.test.mjs
Replayed requestNonce, createdAt, 120 s freshness, signed session bindingKeep; UTCP/MCP requests must be bound to the same contextpackages/p2p/index.js; test needed for cross-provider replay
Unauthorized tool invocationtools.invoke plus owner/site approval; protected operations need membership and short grantRegistry-level capability match and deny-by-default policy before adapter calltests/webmcp-contract.test.mjs, packages/agent/test/tool-provider.test.mjs
Stolen MCP URL credentialPath secret mode 0600, loopback onlyKeep; never treat the URL as an AI Auth grantpackages/mcp/http.js; no authentication bypass test yet
Custom signature substituted for MCP OAuthNot applicable to local-only adapterPass native OAuth through; never send AI Auth signatures as bearer tokensNo test yet; conformance plan item
Tool description prompt injectionDescriptions advisory; untrusted content hintsDescription text never enters policy or instruction channelwebmcp.js; adversarial test required
Malicious tool metadataName pattern, size caps, bounded catalogRegistry validates provenance and preserves native descriptortests/tool-catalog-validation.test.mjs, tests/catalog-flood.test.mjs
Cross-origin WebMCP callNative draft gates; exposedTo, fromOrigins, embedder allowAI Auth records source origin; no emulation of browser privilegesWebMCP draft §4.4; no cross-origin browser test yet
Tool invoked after page destructionCatalog expiry, presence checks, CATALOG_EXPIREDImmediate withdrawal on lifecycle signal where availabletests/tool-expiry.test.mjs, agent-client-presence.test.mjs
UTCP SSRF to private networksOptional adapter: HTTPS/literal-loopback rule, endpoint allowlistResolve-and-check plus redirect preflight above the SDKtests/utcp-adapter.test.mjs; limitations in §4
DNS rebindingResolve before connect and re-check at call timeAdapter rechecks DNS; SDK connection is not pinnedtests/utcp-adapter.test.mjs; residual gap in §4
Credential leakage across providersAI Auth grants are never provider credentials; adapter namespaces secretsNo secrets in audit or roomtests/utcp-adapter.test.mjs
Cross-provider data leakageRegistry with source and protocol fields ships as an optional subpathRegistry enforces audience and source restrictions on every calltests/tool-registry.test.mjs, tests/unified-tools.test.mjs
Privilege escalation via delegationGrants are subsets; renewal cannot add scopes; execution grants max 15 minNever derive a broader native credential from a narrower grantdocs/SECURITY.md, membership.js
Revocation under partitionGossip + bounded 7 day catch-up; epoch bumpsKeep; document eventual consistency honestlytests/revocation.test.mjs, docs/limits.md
Protocol version downgradeFreshness and consent version checksRequire explicit supported-version sets per adapterCHANGELOG.md 0.5.0; adapter tests required
Malicious dependency updateVersion ranges in manifests, resolved versions pinned by lockfilesReview adapter dependencies, verify packed tarballsnpm run verify:packages, CI npm audit
Financial action through generic toolsAdditive deny-by-default ./commerce-boundary guard; no payment operationsHard separation; tools.invoke cannot mint mandatestests/commerce-boundary.test.mjs, COMMERCE_PAYMENTS.md
Confused deputy in MCP OAuthNot implemented locallyDo not forward tokens not issued to this server; never proxy a client token upstreamMCP security best practices; test required

4. Residual risks#

  1. No TURN. A restrictive NAT can keep a peer in waiting-for-peers. Relays see timing and participation metadata. (docs/limits.md)
  2. Revocation is eventually consistent. A peer offline beyond the catch-up window may not converge.
  3. Signature is not identity. It proves control of a key, not a human or a trustworthy agent.
  4. Private mode is not anonymity. Relays and direct peers still see metadata.
  5. UTCP cancellation and DNS rebinding are not verified in the official SDK; an AI Auth-side wrapper is proposed.
  6. WebMCP is a moving draft. Browser implementations are experimental; feature detection and versioned adapters are required.
  7. AP2 is pre-1.0 with a known signature-algorithm inconsistency (issue #268).
  8. MCP 2026-07-28 migration is breaking and unplanned in this milestone; the current adapter targets an older revision.

Implementation note (2026-11-19)#

The optional UTCP adapter now enforces HTTPS/literal-loopback rules, private and link-local blocking, endpoint allowlists, a redirect preflight, credential namespace isolation and a resolve-and-re-check. Two limitations remain and must not be claimed as solved: the redirect check is a separate GET probe, not control of the official SDK transport, and the DNS check does not pin the SDK's connection (no resolver hook is exposed). Code Mode is not yet routed through the UTCP adapter.

5. Sign-off rule#

A security-sensitive change is complete only when an independent reviewer who did not author it has checked the tests and the Security Supervisor has recorded a decision. An unverified claim must be labelled as such in the code, doc or release note that carries it.

On this page