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#
| Boundary | As-is | Proposed rule |
|---|---|---|
| Wallet ↔ site | Signed consent bound to exact origin (packages/p2p/index.js, SECURITY.md) | Unchanged. A capability grant is not a resource grant. |
| Site ↔ agent | Signed agent/action events over WebRTC | Unchanged. Peer data is untrusted. |
| Page ↔ tool (WebMCP) | Page origin, authorize callback, tools.invoke | Keep the three draft gates (embedder allow, provider exposedTo, consumer fromOrigins); never claim browser privileges the adapter lacks. |
| Agent ↔ MCP server | Secret loopback URL; no OAuth | Pass through MCP's native auth untouched. AI Auth scopes gate local tool registration only. |
| Agent ↔ UTCP endpoint | None today | Destination allowlist, HTTPS/literal-loopback rule, DNS-rebinding check, credential namespace isolation, cancellation wrapper. |
| Tool description ↔ policy | Descriptions are advisory (webmcp.js) | Description text is never an instruction or a permission source. |
| Tools ↔ commerce | None today | Hard separation. tools.invoke cannot authorize spending. |
5. Proposed module map#
All paths below are proposed, except the existing files noted as such.
| Module | Path | Responsibility |
|---|---|---|
| Canonical identity (existing) | packages/p2p/index.js | identityFor, signEnvelope, verifyEnvelope. Keep agent: canonical. |
| DID alias (existing) | packages/p2p/did.js | Additive did:key, not an attestation. |
| Trust core (proposed facade) | packages/p2p/trust-core.js | Read-only view of verified identity, owner relationship, grants, revocation state. No new key format. |
| Tool descriptor (proposed) | packages/p2p/tool-descriptor.js | Protocol-neutral descriptor builder and validator. |
| Registry (proposed) | packages/p2p/tool-registry.js | Namespaced registration, source tracking, capability matching, policy hooks, bounded audit. |
| Invocation API (proposed) | packages/p2p/tool-invoke.js | listTools, getTool, invoke, cancel, close. |
| MCP adapter (proposed) | packages/mcp/adapter.js | Wraps the official MCP SDK; preserves native errors and OAuth. |
| WebMCP adapter (proposed change) | packages/p2p/webmcp.js | Refactor existing bridge behind the adapter interface; keep document.modelContext. |
| UTCP adapter (proposed) | packages/p2p/utcp-adapter.js | Thin wrapper over @utcp/sdk; adds AI Auth destination policy. |
| Tool audit (proposed) | packages/p2p/tool-audit.js | Bounded 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#
- Discover the provider.
- Validate provenance against the local trust policy.
- Parse the native tool definition.
- Register a namespaced descriptor.
- Match the request to approved capabilities.
- Validate target origin, resource and arguments.
- Apply local security policy (deny by default).
- Require owner or site approval where applicable.
- Invoke through the native adapter.
- Normalize success/error without discarding native detail.
- Record bounded audit metadata.
- Handle cancellation, timeout, expiry and disconnect.
Tool availability never implies permission. A tool's description is data.
9. Migration strategy#
| Phase | Change | Breaking? |
|---|---|---|
| M0 | Baseline tests and code inventory | No |
| M1 | Add descriptor and registry modules; no callers yet | No (additive exports, docs updated with the BOUNDARIES list) |
| M2 | Route existing WebMCP catalog through the registry | No, wire shape unchanged |
| M3 | Add MCP adapter alongside the existing command | No |
| M4 | Add UTCP adapter behind an opt-in flag | No |
| M5 | Cross-provider policy and audit | No |
| M6 | Additive identity adapters (VC/DID proof verification) | No |
| M7 | Delegation experiments in a separate package | No |
| M8 | A2A/ACP adapters | No, optional |
| M9 | UCP/AP2 layer with mocks/sandbox only | No, optional |
| M10 | MCP 2026-07-28 revision migration | Yes — 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.mdpins the live export list (DTC-06), so this needs an explicit doc update. - Whether UTCP cancellation should be wrapped with an
AbortSignalabove 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.