DOCUMENTATION · v0.12.2

Readme

AI Auth, identity for AI agents

An identity your agents can take with them.

Live site · Wallet · Architecture · npm

npm version CI License: MIT

An agent turns up at a website. The site needs to know which agent it is, and it needs a way to say what that agent may do. AI Auth handles both with a wallet the agent keeps. You approve the capabilities, and the site stays in charge of its own data and tools.

There is no AI Auth account and no server holding your keys. A browser wallet keeps its key in origin-scoped storage. A headless agent keeps its key in an encrypted file on its machine. Public Nostr relays help peers find each other; after that, messages and signed events go straight over WebRTC. There is no blockchain or token.

AI Auth is generic. Body4AI is one example consumer under examples/body4ai/; its product catalog and commands are not part of AI Auth. Generic integration tests use an independent site with demo.echo and demo.increment. See session and connection lifecycle.

AI Auth is published on GitHub Pages only. See the hosting policy for the CI guard and removal of the legacy Vercel GitHub App.

Install#

Pick the package for the side you are building.

PackageWhat it doesVersion
@enzovezzaro/ai-auth-walletBrowser SDK, wallet dialog, collaboration, WebMCP bridge. This is the repository root.0.12.2
@enzovezzaro/ai-auth-agentHeadless Node agent with an encrypted keystore, room runtime, and real WebRTC0.2.0
@enzovezzaro/ai-auth-mcpai-auth-mcp command and MCP tools for local coding agents0.3.9
@enzovezzaro/ai-auth-runtimePlugin host for local agent applications, independent of any provider0.1.3

None of them needs an AI Auth service to run.

Version source of truth: each version above mirrors that package's own package.json; the root package.json is the single source for the product release label. Version strings shown in UI surfaces are generated from that source at build time or omitted from nontechnical UI. Do not maintain a separate hardcoded product version in page markup (release note).

npm install @enzovezzaro/ai-auth-wallet
npm install @enzovezzaro/ai-auth-agent
npm install @enzovezzaro/ai-auth-mcp

The static site is hosted on GitHub Pages, while the npm packages above are published to npm by .github/workflows/release.yml. The hosting policy explains why the site is hosted on GitHub Pages only.

Run it locally#

You need Node.js 22 or newer and npm.

npm ci
npm run dev

The site root is the landing page. /wallet/ is the local wallet, and /docs/ARCHITECTURE.md is the architecture document. The dev command only builds and serves static files. The wallet starts in private mode. Switch on public collaboration when you want to join the current page's shared space.

Put AI Auth on a site#

The build writes the browser bundle to dist-p2p/ai-auth.js. You can bundle the SDK as an ES module or load that file from your wallet host.

import {
  connectAIAuthModal,
  mountAIAuthCollaboration,
  mountAIAuthInPageAgent,
} from "@enzovezzaro/ai-auth-wallet";

// Call from a user gesture. The wallet is shown in an in-page modal.
const connection = await connectAIAuthModal({
  walletUrl: "https://wallet.example/wallet/",
  capabilities: ["presence.read", "tools.invoke"],
  room: "project-room",
});

const removeCursorOverlay = mountAIAuthCollaboration(connection);

const pageAgent = await mountAIAuthInPageAgent({
  connection,
  actions: [
    {
      name: "workspace.summary",
      description: "Summarize the current workspace.",
      inputSchema: { type: "object", properties: {} },
      requiredCapability: "tools.invoke",
      readOnly: true,
      execute: async () => ({ summary: "Site-specific result" }),
    },
  ],
  // Every requested action needs a human approval step.
  authorize: async (action, input, context) =>
    showApprovalDialog({
      action,
      input,
      sharedPublicly: context.sharedPublicly,
    }),
  publishAction: (event) =>
    connection.publishAction({
      name: event.name,
      state: event.state,
      summary: event.summary,
    }),
});

connection.onEvent((event) => {
  // Check the event's site-specific effects before acting on it.
  console.log(event.body.type, event.body.payload);
});

// When the page is done:
pageAgent.close();
removeCursorOverlay();
connection.close();

Call the modal from a click or another user gesture; the SDK does not enforce a gesture check, so this is a convention for the calling site rather than a guarantee. It shows the site's request and signs only the scopes you select. Use HTTPS once you leave local development.

The default room name is the literal default. The site's exact origin still matters: the shared topic hash is createSharedRoomTopic(origin, room), so agents on the same origin and room name find one another. Pass a room key if you want a separate space. A room puts peers in the same place. It does not hand out access, so the site still checks every request.

The details are in the architecture, security boundaries, wire protocol, and wallet recovery documents.

Hand an agent a connect instruction#

You can publish a connect instruction that an agent can copy, along with a panel that shows what happens during the handshake.

import {
  createAIAuthConnectInstruction,
  mountAIAuthConnectPanel,
} from "@enzovezzaro/ai-auth-wallet";

const instruction = createAIAuthConnectInstruction({
  siteName: "Example Workspace",
  siteOrigin: "https://workspace.example",
  walletUrl: "https://wallet.example/wallet/",
  capabilities: ["presence.read", "messages.send", "tools.invoke"],
});

mountAIAuthConnectPanel({
  target: document.getElementById("agent-connect"),
  instruction,
  connect: () =>
    connectAIAuthModal({
      origin: instruction.origin,
      walletUrl: instruction.walletUrl,
      capabilities: [...instruction.capabilities],
      room: instruction.room,
    }),
  onStateChange: (state) => {
    document.body.toggleAttribute(
      "data-agent-connected",
      state.status === "connected",
    );
  },
});

The panel shows the instruction with a copy button, then the handshake state (idle → connecting → connected → disconnected), the verified identity and its approved scopes, and the time left on the session. It also mirrors that state as data-status on the host element, so your CSS and header badges can read it without touching the shadow root. The instruction itself only carries public details: origin, room, wallet URL, and requested capabilities.

Headless agents#

An agent does not need an open browser tab. @enzovezzaro/ai-auth-agent keeps its wallet in an encrypted 0600 keystore file. The passphrase comes from AI_AUTH_PASSPHRASE or a terminal prompt. A broken keystore fails closed; it never quietly creates a new identity.

createAgentRuntime joins the room, sends heartbeat leases, and reconnects after a drop. resume() picks up a saved room after a restart. You will not see direct-peer-connected until a real WebRTC data channel is open. There is a worked example in packages/agent/examples/peer.mjs. The agents and MCP guide covers the runtime, its keystore, and the local coding agents.

For local coding agents, ai-auth-mcp exposes the same wallet through MCP stdio:

npx -y @enzovezzaro/ai-auth-mcp init
npx -y @enzovezzaro/ai-auth-mcp serve \
  --connect https://workspace.example \
  --room project-room \
  --caps presence.read,tools.invoke \
  --auto-join

The terminal shows a preview when an agent asks to connect. With nobody there to approve it, the command stops unless --approve lists the exact scopes. The agents and MCP guide records verification on 2026-11-15: a Claude Code tool call reached a peer over WebRTC, but Codex and OpenCode tool calls remain unverified (those runs stopped before a tool call).

WebMCP is the tool surface inside the page. The SDK finds the page's tools, advertises a bounded catalog, and only runs a call after the wallet scope check and the page's own approval step. These local integrations are optional for a website. Never put secrets or private page data in the shared room.

Sessions, rooms, and revocation

A session starts when a wallet approves a connection. A site that sets no limit gets Never, which lasts until you end it, the site ends it, or someone revokes it. The wallet also offers 5, 15, 30, and 60 minute choices. A site can set its own ceiling with sessionTtlMs and idleTimeoutMs. A numeric ceiling rules out Never. A numeric session with no idle setting ends after 10 minutes of no authorized activity.

connection.renew() takes the request back to the owner. It can keep or narrow the scopes, but it cannot add capabilities. After a session expires, goes idle, or ends, publishing, receiving, transfers, and WebMCP calls stop.

Rooms start as open. The SDK does not emit a join notice; it exposes the open-room disclosure text as OPEN_ROOM_DISCLOSURE (policy.disclosure / room.disclosure), which the site should display. Anyone with the origin and room name can get in. A restricted room only admits peers with a site-issued ai-auth-membership proof. The site creates and checks those with createParticipationPolicy, issueMembership, and verifyMembership. Membership can expire or last until revoked. Even a valid membership cannot run a protected operation by itself. Each of those needs a short-lived execution grant (issueExecutionGrant, checked by authorizeProtected). Revoke with a signed ai-auth-revocation record, shared through createRevocationGossip.

A peer that was offline learns about a revocation when it reconnects through gossip catch-up. There is no single on/off switch for all authorization: revocations target one membership, link, or wallet id, while a room-wide epoch (bumpEpoch() or a signed ai-auth-epoch record) invalidates every proof and grant issued under an older epoch. Short-lived execution grants keep the exposure window small. Private mode joins without showing a cursor or presence. The participant still receives authorized events, and its actions are still signed and audited. Private mode does not bypass site authorization or hide metadata from relays.

Upgrading from 0.4.x
  • registerAIAuthPageActions throws unless you pass authorize. Every page action needs a human approval step.
  • A denied or failed WebMCP call now rejects on the agent side instead of reporting success.
  • privateMode joins a room quietly instead of being refused.
  • Ship the SDK and wallet together. Older SDKs cannot verify the version 2 consent that carries long sessions.

The changelog has the full list.

Example#

examples/body4ai/ is a demo website built with the public SDK. It brings its own catalog, tools, and authorization rules. It consumes AI Auth; none of that site-specific code ships in the SDK or wallet.

How the pieces connect#

flowchart LR
  A[Agent runtime] -->|signed identity| S[Website]
  S -->|capability request| W[Wallet owner]
  W -->|scoped grant| S
  A <-->|WebRTC data channel| B[Other agents]
  R[Nostr relays] -. signaling .-> A
  R -. signaling .-> B

Relay operators can see timing and participation metadata. The hashed room topic is not a secret, and it grants nothing. There is no TURN server. Collaboration goes peer to peer, so a restrictive NAT or firewall can stop a connection.

The generic-site fixture in scripts/test-browser-e2e.mjs is an independent test website. It runs a real wallet handshake and direct WebRTC session to check signed events, cursors, site-authorized tool calls, and approval or cancellation. CI saves the browser screenshots as the ai-auth-playwright-screenshots artifact. Read the generic integration review for what that evidence does and does not cover.

Docs#

The docs index is the table of contents. The docs are grouped by what they help you do.

What you needStart here
Connect a site and an agentQuickstart
Connect a site in depthSite integration
Understand the modelArchitecture
Connect Claude Code, Codex, OpenCodeAgents and MCP · MCP command
Check harness support and evidenceAgent harness support
Follow sessions, refresh, and resumeSession lifecycle · Limits
Recover or back up a walletWallet recovery
Serve the static siteHosting policy
Look up a wire contractWire protocol · Security boundaries
Check a trust boundary or discoveryBoundaries · Site discovery
Read test recordsEvidence index · E2E guide
Read dated snapshotsArchive

The architecture document explains how the pieces connect and what the system does not provide.

Checks#

npm test                 # wallet SDK suite
npm run test:all         # SDK, runtime, MCP and agent suites
npm run test:types       # strict type check of the public declarations
npm run build
npm run verify:packages  # pack all packages and import them from a clean install
npm run test:browser:e2e
npm run test:e2e:body4ai # multi-agent demo-site E2E (see docs/E2E.md)

The browser tests use two isolated wallets and public relay and WebRTC connectivity. They need network paths that allow direct ICE. Seeing a peer discovered is not the same as seeing a collaboration session work.

Contributing#

If something is broken or unclear, open an issue. For a pull request, keep the change focused and run npm run test:all, npm run build, and npm run format:check first. Tell me what you actually checked. For a security problem, follow docs/SECURITY.md instead of filing a public issue.

License#

MIT. The SDK, agent runtime, MCP tools, and landing page are all open source.

On this page