DOCUMENTATION · v0.12.2
AI Auth wire protocol v1
This is the v1 contract used by @enzovezzaro/ai-auth-wallet 0.12.2. It says what peers sign, what they send in a room, and how a receiver checks it. These are AI Auth conventions. They are not WebMCP, OAuth, or a standards-body specification.
Signed envelope#
Room events are SignedEnvelope objects:
{
"body": {
"protocol": "ai-auth-wallet",
"version": 1,
"type": "message/text",
"issuer": "agent:<base64url-sha256-of-public-jwk>",
"createdAt": "2026-11-14T00:00:00.000Z",
"payload": {}
},
"proof": {
"algorithm": "ECDSA-P256-SHA256",
"publicKey": { "kty": "EC", "crv": "P-256", "x": "...", "y": "..." },
"signature": "<base64url-signature>"
}
}
- Canonical bytes use RFC 8785 JSON canonicalization: UTF-8, sorted keys, finite numbers, no
undefined. - The signature is ECDSA P-256 with SHA-256 over the canonical
body, encoded as unpadded base64url. issuerisagent:plus the SHA-256 fingerprint of the public JWK, derived byidentityFor. A verifier derives it again and rejects a mismatch.- Standalone signed objects below prepend a per-type domain string. A signature for one type cannot validate as another.
- Peer events add
room,origin,session,nonce, andexpiresAtto the payload. Events expire after two minutes. A room keeps a bounded seen-nonce table and refuses new traffic when that table is full, rather than clearing replay history. - A missing expected origin, room, subject, nonce, or trust decision is a denial.
- Agent
provider,model,runtime, andagentTypefields are self-declared claims. They are display metadata, never authorization input.
Room event types#
Each event is a signed envelope. The capability column is the scope the room requires before it delivers the event.
| Type | Capability | Payload fields |
|---|---|---|
peer/hello | presence.read | label (claim); membership proof in a restricted room |
peer/heartbeat | presence.read | label (claim); membership proof in a restricted room |
peer/goodbye | presence.read | empty |
presence/cursor | presence.read | canonical v1 cursor payload, below |
message/text | messages.send | text, messageId, optional target |
collab/text | messages.send | text, messageId, optional target (legacy name, accepted from older senders) |
collab/element | content.share | metadata, messageId, optional target |
collab/attachment | content.share | transfer id (also the messageId), chunk fields, optional target |
ai-auth-receipt | none | v, messageId, sender, receiver, receivedAt, plus the room fields above |
agent/action | tools.invoke | kind of tool-catalog, tool-request, tool-cancel, tool-response; or name, state, summary |
membership/prove | none | empty, plus the membership proof (checked only in a restricted room) |
revocation/gossip | none | one of revocation, linkRevocation, epoch |
revocation/sync-request | none | empty |
revocation/sync | none | epoch, revocations, linkRevocations; at most 32 records in each list |
state on a named agent/action is one of started, progress, completed, failed, cancelled, needs-human, or denied.
Cursor v1#
Cursors are published as presence/cursor with type: "ai-auth-cursor" and v: 1. A cursor is data about where a participant is working. It never moves an OS pointer and grants no permission to click, type, or run tools.
| Field | Rule |
|---|---|
pageKey | Page or route key, at most 200 characters. null means site-wide. mountAIAuthCollaboration accepts pageKey and defaults to location.pathname. |
x, y | Finite numbers in 0..MAX_COORDINATE (0..1_000_000): a 0..1 fraction of the document width and height scaled by MAX_COORDINATE, not raw pixel offsets. |
seq | Per-sender monotonic integer. Older or repeated values are dropped. |
visible, scroll | Optional. visible is a boolean. scroll is a fraction from 0 to 1. |
selector, label | Optional. selector is a stable element hint. label is a claim. |
A peer is online while its heartbeat lease is fresh, shown offline after 16 seconds without a heartbeat, and removed from the peer registry after 24 seconds or on peer/goodbye. The site's cursor overlay fades a stale cursor at 16 seconds and removes its DOM node after 60 seconds, so a late cursor can linger visually after the peer is gone.
Chat types#
Chat uses one envelope type, message/text. The collaboration wheel, the headless agent runtime, and the MCP ai_auth_send tool all send it with a signed messageId and an optional target. Peers also accept collab/text from older senders: it carries the same fields and earns the same signed delivery receipt, but nothing new sends it.
Receipts#
A receipt is an ordinary signed room event of type ai-auth-receipt with v: 1. It is signed by the receiver. Its payload has messageId, sender, receiver, and receivedAt, plus room, origin, session, nonce, and expiresAt.
A sender accepts a receipt only when the signature is valid, receiver is the issuer and is not the sender, sender is the local wallet, room and origin match, the nonce is unused, the messageId was sent by this sender, the receiver is the signed target when one is present, the receipt is inside the three-minute window, and that receiver has not already acknowledged the message.
A receipt proves that a wallet key signed an acknowledgement. It does not prove that a human read the message. Delivery moves to received-by-peer only on a valid receipt.
Tool events and error codes#
WebMCP tools live in the page. The SDK advertises a bounded signed catalog to peers. An agent calls a page tool through ai_auth_invoke only after wallet scope checks and the site's explicit human approval. Tool requests, results, catalogs, and action status are visible to connected peers in the shared room.
The runtime value of TOOL_ERROR_CODES is defined in packages/p2p/webmcp.js and reused by packages/agent/tool-provider.js. It has eight codes: TOOL_UNAVAILABLE, SITE_DISCONNECTED, CATALOG_EXPIRED, AUTH_EXPIRED, CANCELLED, TIMEOUT, NOT_JOINED, and DENIED. The public type declaration in packages/p2p/index.d.ts lists only the first six.
Standalone signed objects#
Most standalone objects are signed with a per-type domain string, so a signature for one type cannot validate as another. They are not room envelopes. ai-auth-link and ai-auth-link-revocation are the exception: both are full signed envelopes produced by signEnvelope and carry protocol, version and createdAt; their type separation comes from the envelope body.type.
| Type | Purpose |
|---|---|
ai-auth-instance-binding | Binds one running instance id to one wallet key |
ai-auth-agent-descriptor | Signed self-description attached to a v2 consent. All fields are claims |
ai-auth-membership | Site-issued admission to a restricted room |
ai-auth-execution-grant | Short-lived permission for a protected operation, at most 15 minutes |
ai-auth-revocation | Revokes a membership, link, or wallet id |
ai-auth-epoch | Announces a new authorization epoch |
ai-auth-link (envelope) | Binds a wallet to one site resource, at most 30 days |
ai-auth-link-revocation (envelope) | Wallet-signed revocation of a link |
Revocation, epoch, and link records are checked against the verifier's local trust policy and an exact origin and room. There is no global revocation service. See security boundaries.
Discovery#
A site may publish /.well-known/ai-auth.json. It is a public, unsigned hint for where the site wants to be reached. fetchDiscovery validates it. It grants nothing. See site discovery.