DOCUMENTATION · v0.12.2

Reference architecture

Status: proposed target architecture. As-is facts cite repository files at v0.11.1. Proposed modules and interfaces are not implemented by this document.

1. Goal and non-goals#

Goal: one AI Auth identity, permission and audit layer serving three first-class tool providers (MCP, WebMCP, UTCP), while preserving each provider's native authorization, transport and lifecycle semantics.

Non-goals: a new tool protocol, a new agent communication protocol, a new identity standard, a payment authority layer, a hosted registry, and a breaking identity or wire migration.

2. As-is layering#

flowchart TB
  W[Wallet identity + signed envelopes] --> C[Capability grants / memberships / execution grants]
  C --> P1[WebMCP bridge: document.modelContext]
  C --> P2[MCP command: stdio + loopback HTTP]
  C --> P3[Agent tool provider: signed room catalog]
  P1 --> S[WebRTC room / signed events]
  P2 --> S
  P3 --> S

Three independent catalogs share only a wire convention. A protocol-neutral descriptor, a default-deny registry with source tracking and a bounded audit now ship as optional ./tool-descriptor, ./tool-registry and ./tool-audit subpaths; they are not yet wired into all three live catalogs. This paragraph was accurate at the v0.11.1 snapshot. Evidence: packages/p2p/webmcp.js, packages/mcp/bridge.js, packages/agent/tool-provider.js, packages/p2p/tool-registry.js, standards matrix.

3. Proposed layering#

flowchart TB
  ID[AI Auth identity and trust core] --> POL[Permission and delegation layer]
  POL --> REG[Unified tool registry and invocation API]
  REG --> A1[MCP adapter]
  REG --> A2[WebMCP adapter]
  REG --> A3[UTCP adapter]
  A1 --> M1[Local stdio / remote MCP server, native OAuth]
  A2 --> M2[Page tools via document.modelContext]
  A3 --> M3[Native APIs and endpoints via official UTCP SDK]
  REG --> AUD[Bounded privacy-preserving tool audit]
  ID --> INT[Optional A2A / ACP adapters]
  ID --> COM[Separate UCP / AP2 commerce layer]

The identity core and the registry are separate. The registry consumes identity facts; it never mints transport credentials.

Optional Code Mode sits above the registry as a second execution interface. It may reach a tool only through the same host dispatcher used by direct calls, with the same per-call checks. It adds no protocol, identity or authority of its own. Evidence and hardening gates are in docs/CODE_MODE_COMPARISON.md and docs/INTEROPERABILITY_CODE_MODE_RFC.md.

4. Trust boundaries#

BoundaryAs-isProposed rule
Wallet ↔ siteSigned consent bound to exact origin (packages/p2p/index.js, SECURITY.md)Unchanged. A capability grant is not a resource grant.
Site ↔ agentSigned agent/action events over WebRTCUnchanged. Peer data is untrusted.
Page ↔ tool (WebMCP)Page origin, authorize callback, tools.invokeKeep the three draft gates (embedder allow, provider exposedTo, consumer fromOrigins); never claim browser privileges the adapter lacks.
Agent ↔ MCP serverSecret loopback URL; no OAuthPass through MCP's native auth untouched. AI Auth scopes gate local tool registration only.
Agent ↔ UTCP endpointNone todayDestination allowlist, HTTPS/literal-loopback rule, DNS-rebinding check, credential namespace isolation, cancellation wrapper.
Tool description ↔ policyDescriptions are advisory (webmcp.js)Description text is never an instruction or a permission source.
Tools ↔ commerceNone todayHard separation. tools.invoke cannot authorize spending.

5. Proposed module map#

All paths below are proposed, except the existing files noted as such.

ModulePathResponsibility
Canonical identity (existing)packages/p2p/index.jsidentityFor, signEnvelope, verifyEnvelope. Keep agent: canonical.
DID alias (existing)packages/p2p/did.jsAdditive did:key, not an attestation.
Trust core (proposed facade)packages/p2p/trust-core.jsRead-only view of verified identity, owner relationship, grants, revocation state. No new key format.
Tool descriptor (proposed)packages/p2p/tool-descriptor.jsProtocol-neutral descriptor builder and validator.
Registry (proposed)packages/p2p/tool-registry.jsNamespaced registration, source tracking, capability matching, policy hooks, bounded audit.
Invocation API (proposed)packages/p2p/tool-invoke.jslistTools, getTool, invoke, cancel, close.
MCP adapter (proposed)packages/mcp/adapter.jsWraps the official MCP SDK; preserves native errors and OAuth.
WebMCP adapter (proposed change)packages/p2p/webmcp.jsRefactor existing bridge behind the adapter interface; keep document.modelContext.
UTCP adapter (proposed)packages/p2p/utcp-adapter.jsThin wrapper over @utcp/sdk; adds AI Auth destination policy.
Tool audit (proposed)packages/p2p/tool-audit.jsBounded records: caller, provider, protocol, tool id, decision, outcome. No payloads or secrets.

6. Proposed tool descriptor#

interface UnifiedToolDescriptor {
  id: string; // e.g. "utcp:manual:github/issues.search"
  protocol: "mcp" | "webmcp" | "utcp";
  providerId: string;
  source: { origin?: string; endpoint?: string; page?: string };
  name: string;
  title?: string;
  description: string; // untrusted text
  inputSchema: object;
  outputSchema?: object;
  capabilities: string[]; // AI Auth scopes required
  risk: {
    sideEffect: "read" | "write" | "consequential";
    untrustedContent: boolean;
  };
  audience?: { origins?: string[]; walletIds?: string[] };
  requiredAuthorization: {
    kind: "owner" | "site" | "native" | "none";
    detail?: string;
  };
  availability: "online" | "offline" | "expired" | "unknown";
  native: object; // preserved original descriptor, never weakened
}

Rules: the native descriptor is preserved verbatim; unsupported native semantics are never translated into a weaker generic field; IDs must be namespaced by protocol plus provider.

7. Proposed adapter interface#

interface ToolProviderAdapter {
  readonly protocol: "mcp" | "webmcp" | "utcp";
  discover(): Promise<UnifiedToolDescriptor[]>;
  listTools(): Promise<UnifiedToolDescriptor[]>;
  getTool(id: string): Promise<UnifiedToolDescriptor | undefined>;
  invoke(
    id: string,
    args: unknown,
    ctx: InvocationContext,
  ): Promise<InvocationResult>;
  cancel?(requestId: string): Promise<void>; // only where the protocol supports it
  subscribe?(onChange: () => void): () => void;
  close(): Promise<void>;
}

invoke receives the verified caller identity, delegated authority, origin, session, intended resource and protocol-specific context. InvocationResult keeps native error codes alongside a normalized outcome.

8. Required invocation flow#

  1. Discover the provider.
  2. Validate provenance against the local trust policy.
  3. Parse the native tool definition.
  4. Register a namespaced descriptor.
  5. Match the request to approved capabilities.
  6. Validate target origin, resource and arguments.
  7. Apply local security policy (deny by default).
  8. Require owner or site approval where applicable.
  9. Invoke through the native adapter.
  10. Normalize success/error without discarding native detail.
  11. Record bounded audit metadata.
  12. Handle cancellation, timeout, expiry and disconnect.

Tool availability never implies permission. A tool's description is data.

9. Migration strategy#

PhaseChangeBreaking?
M0Baseline tests and code inventoryNo
M1Add descriptor and registry modules; no callers yetNo (additive exports, docs updated with the BOUNDARIES list)
M2Route existing WebMCP catalog through the registryNo, wire shape unchanged
M3Add MCP adapter alongside the existing commandNo
M4Add UTCP adapter behind an opt-in flagNo
M5Cross-provider policy and auditNo
M6Additive identity adapters (VC/DID proof verification)No
M7Delegation experiments in a separate packageNo
M8A2A/ACP adaptersNo, optional
M9UCP/AP2 layer with mocks/sandbox onlyNo, optional
M10MCP 2026-07-28 revision migrationYes — separate compatibility decision and approval

Rollback: each milestone is a small commit behind a flag where user-visible, with the previous catalog path retained until conformance tests pass.

10. What remains unresolved#

  • Whether to expose unified registry exports from the root package or only through subpaths. docs/BOUNDARIES.md pins the live export list (DTC-06), so this needs an explicit doc update.
  • Whether UTCP cancellation should be wrapped with an AbortSignal above the SDK, given the SDK has no verified cancellation API.
  • Whether MCP revision migration is justified by a concrete compatibility need; no evidence yet.
  • Whether any standardized identity adapter is worth the resolver dependency before an external verifier requires it.
On this page