DOCUMENTATION · v0.12.2
Full-protocol multi-agent E2E (example demo site)
npm run test:e2e:body4ai runs one reproducible browser scenario in which several agents and visitors use a website built with the AI Auth SDK. It exercises every merged protocol interaction with real Chromium, real public Nostr relays and real direct WebRTC. Nothing in the SDK, Nostr or WebRTC is mocked. The only stand-in is getDisplayMedia (a synthetic canvas stream), because headless Chromium cannot show a screen-capture prompt.
Mocked unit tests live in tests/; this scenario is the evidence that the pieces work together.
Run it#
npm ci
(cd packages/agent && npm ci) # headless agent dependencies (node-datachannel)
npx playwright install chromium # once
npm run test:e2e:body4ai # builds dist-p2p first
Environment: AI_AUTH_CHROMIUM_PATH selects another Chromium. B4A_STOP_AFTER=<n> stops after step n (debugging). The whole run times out after 10 minutes. Output: a PASS / FAIL / KNOWN-BUG / PENDING / NETWORK line per step, a summary table, and test-results/e2e-report.json (gitignored) with each step's duration and evidence such as wallet ids and peer counts. The exit code is 0 only when every recorded step is PASS; PENDING, FAIL, KNOWN-BUG and NETWORK all make it non-zero (scripts/e2e/report.mjs). A NETWORK result (ICE or relay failure) is reported as a network problem, not a product failure.
Network requirements#
- Outbound WebSocket access to public Nostr relays (Trystero's defaults). Relays carry signaling only; every application event travels over direct WebRTC data channels.
- UDP/ICE connectivity between Chromium processes and the Node agent on this machine. There is no TURN. If the relays are unreachable or ICE fails, the step is reported as NETWORK, not as a product failure.
- Every run uses a random room name, so concurrent or repeated runs do not see each other.
Participants#
Each browser participant has its own Chromium context (storage and identity). All of them load the demo site at /body4ai/ (examples/body4ai/site/, bundled by scripts/build-p2p-static.mjs).
| Who | Role |
|---|---|
| Human A, Human B | Visitors. They host the WebMCP tools and approve protected calls. |
| Agent 1, Agent 2 | Admitted agents with separate wallets. |
| Agent 3 | Knows origin and room, holds only a forged membership. |
| Headless agent | packages/agent in a child process with a temp keystore. |
| Origin B | The same site on a second port, for cross-origin negatives. |
Site operator (site-authority.mjs) | Holds the issuer key: issues memberships and execution grants, revokes, and verifies site links. |
The demo site has no backend, so the operator is the test controller using only public SDK functions. Membership proofs are handed to participants out of band, like an invitation.
Steps#
Each step is named and asserted in scripts/e2e/steps-*.mjs. Steps run in dependency order; the table is sorted by number.
- Wallets are created on first connect; ids and public keys are distinct.
- Consent: the site requests four capabilities, Agent 2 approves three, the site sees exactly those, and the SDK refuses the rest.
- Session grant: expiry is shown, the session outlives the 120 s handshake (controllable clock), renews without widening scopes, and an expired session cannot publish.
- Connection state:
waiting-for-peersprecedesdirect-peer-connected;directPeerCountis read fromNostrWebRTC.connectionState. - Site link:
approveLink(subset) thenverifyLink; listed after a fresh page load; only approved scopes work. - Restricted room: an uninvited agent cannot invoke tools, receives no restricted events, and its forged membership is rejected.
- Presence: one cursor per verified identity, labels shown as claims.
- Wheel: broadcast chat, targeted message, receipt-driven state, password redaction, synthetic screenshot, oversized attachment rejected.
- Agent to agent: signed events in both directions.
- WebMCP: discovery, read-only call, approve, deny, cancel, duplicate request id.
- Mixed permissions: no
tools.invokemembership scope means no tool run. - Human A leaves; agents and the headless agent stay connected and keep talking.
- Human B opens the site fresh, sees the agents' cursors, messages one and gets a signed receipt.
- Agent 1 reloads: same identity, membership recovered, no ghost cursor. The headless agent restarts with the same keystore identity.
- Revocation record gossiped; the revoked agent's protected calls fail.
- Unlink: the wallet emits the revocation, the site applies it, link use fails.
- Disconnect: the cursor leaves within the lease.
- Cross-origin: a second origin rejects origin A's consent, link and membership and shares no room.
- Private presence: a private agent receives authorized events, advertises no presence or cursor, and its signed events are audited.
- Headless agent: visible to browsers, exchanges signed events with Agent 1.
How the site uses the SDK#
The demo is a static page. Every protocol decision is made by the SDK:
- Consent and session:
createPermissionRequest/approvePermissionRequest/verifyPermissionConsent/SessionLease(examples/body4ai/site/session.js). - Room and transport:
P2PRoom(optionallyprivateMode) withNostrWebRTC,CollaborationTransfersandmountCollaborationWheel. - Presence:
createPresenceTrackerfed only with verified room events; cursors are protocol v1 (buildCursorPayload, document coordinates, per page). - WebMCP tools:
mountAIAuthInPageAgentwithpolicy, so every remote run passes the SDK membership and execution-grant gate (authorizeProtected). The site'sauthorizeadds the human decision. Read-only tools need no click. - Revocation:
createRevocationGossipon the room, applied to the site's participation policy. - Links:
approveLink/verifyLink/listLinks/unlink, verified by the operator insite-authority.mjs.
The wallet iframe flow (apps/p2p) is covered by scripts/test-browser-e2e.mjs; this scenario drives the same SDK functions directly from the demo page.
Agent-owned connection scenarios (no browser)#
node --test tests/agent-scenarios.test.mjs runs eight scenario tests against real P2PRoom signing and verification with an in-process transport:
| Scenario | What it proves |
|---|---|
| A | Three independent agent wallets discover each other, message, and move cursors |
| B | A human connection closes; the other agents stay connected and keep talking |
| C | A returning participant sees the connected agents' names and live cursors |
| D | With every browser closed, peers call tools the agent runtime publishes itself |
| D2 | A page-only tool answers "unavailable" instead of returning a fake result |
| E | A restarted runtime stops being live, keeps its wallet id, and rejoins |
| F | An MCP-bridge agent and a direct SDK runtime interoperate in one room |
| G | A generic site works using only the public SDK, with no example-specific code |
These run in CI-friendly conditions (no network). The real-network, real-browser evidence remains the multi-agent scenario above.
SDK defects this scenario found and fixed#
These were real product bugs. Each fix has a unit test that fails on the old code.
- Restricted-room confidentiality (step 6).
NostrWebRTC.deliverpassed the peer list as a positional argument to Trystero'saction.send. Trystero 0.27 readssend(data, { target }), so the list was ignored and restricted events were broadcast to every direct peer, including wallets with no membership. Fixed inpackages/p2p/p2p.js; the test fakes (tests/participation.test.mjs,packages/agent/test/fake-transport.mjs) now follow the real contract, and a contract test pins it to the installed Trystero types. - Denied tool calls (step 10). A denied call resolved as success. Fixed in
packages/p2p/webmcp.js(refusals are sent astool-response.errorwith noresult); released in tagv0.5.0. The matchingwebmcp-contracttodos are closed. - Presence for private wallets (step 19). Implemented in
packages/p2p/p2p.js(private presence andmembership/prove); released in tagv0.5.0. The step now runs instead of reporting PENDING. - Headless agent (step 20). Implemented in
packages/agent; the step runs against a real child process.
Post-release check (deferred)#
This run uses the workspace sources. After the release, the same scenario should be run against the published packages: install @enzovezzaro/ai-auth-wallet and @enzovezzaro/ai-auth-agent from npm in a clean directory, serve the published example demo, and run the steps again. That check is not part of this change and has not been done.
What this does not prove#
- Behaviour across NATs, mobile networks or restrictive firewalls: everything runs on one machine.
- Interoperability with an installed external coding agent harness.
- Six-participant scale evidence from separate devices.
- Human identity: signatures prove key possession only. Membership is the operator's decision.
- Publishing: this run does not publish, and does not verify the npm artifacts.