DOCUMENTATION · v0.12.2
AI Auth generic integration review and browser evidence
Review scope: the AI Auth browser SDK, its existing browser E2E harness, CI workflow and public documentation; plus the consumer boundary represented by an external website built on the wallet. This document is a traceability and review record, not a claim that all runtime/harness combinations or every public document has been exercised.
Architectural separation#
- AI Auth owns wallet identity, signed consent, permissions, room transport, peer presence, messaging, and generic WebMCP tool advertisement/invocation. It does not contain a product catalog.
- An agent harness owns the process that keeps a headless agent connection alive. An identity or a non-expiring grant alone is not a running connection.
- The website owns the implementation and authorization of the actions it exposes. A page-hosted tool is unavailable if its page is gone; this is not a failure of the remaining agent's identity or P2P presence.
- An example consumer imports the published SDK (no version pin) from its own entry file and registers site-specific tools through page actions. The catalog stays with that website.
The independent page built in scripts/test-browser-e2e.mjs is separate from that example consumer. Its arbitrary tools demo.echo and demo.increment demonstrate that the SDK transports tools whose names, schemas and behavior come entirely from a website.
Feature → implementation → actual test#
| Feature | Implementation and owner | Verification path |
|---|---|---|
| Wallet creation and origin-bound consent | AI Auth wallet/modal and session code | scripts/test-browser-e2e.mjs: two isolated wallet approvals |
| Direct agent/site room communication | packages/p2p/p2p.js, wallet room transport | Playwright browser E2E: signed events, agent discovery and data-channel communication |
| Generic tool advertisement | packages/p2p/webmcp.js, site-provided action definitions | The separate agent sees page.review, demo.echo and demo.increment in the site's catalog |
| Tool authorization and execution | mountAIAuthInPageAgent; site-provided approval callback and executors | Separate agent calls demo.echo once and demo.increment twice; asserted results require browser approval |
| Cursor and visible signed-event log | AI Auth room events and browser fixture | Browser E2E asserts agent cursor and human cursor, and screenshots the receiving page after assertions |
| Screenshot evidence | Playwright page.screenshot() | test-results/screenshots/generic-site-verified-events.png and generic-agent-client-connected.png; GitHub Actions artifact ai-auth-playwright-screenshots |
| Failure evidence | Browser E2E error handler | Attempts test-results/screenshots/generic-site-failure.png; original failure is re-thrown |
| Headless runtime, human departure/return | packages/agent + separate consumer tests | Not covered by this screenshot test; see the dedicated multi-agent E2E and example-site keep-alive test |
| Production consumer deployment | external website, not the AI Auth SDK | Not established by this PR; requires a separate production deployment/review |
| ChatGPT/Codex/Claude Code/OpenCode lifecycle | Host harness/MCP and optional AI Auth adapters | Not fully established by browser E2E; runtime may suspend or stop independently |
Reproduce the evidence#
With Node.js 22+, Chromium/Playwright dependencies and a network allowing public Nostr signaling and direct ICE:
npm ci
npm run build
npx playwright install --with-deps --only-shell chromium
npm run test:browser:e2e
After the browser test passes, inspect the PNG files in test-results/screenshots/. On pull requests, GitHub Actions runs npm run test:e2e and uploads the screenshots as a workflow artifact, even if the run fails after a screenshot can be captured. A screenshot is UI evidence, not proof of peer delivery by itself; the assertions and logs are required.
Observed documentation corrections in this PR#
- A dated 0.6.2-era correction: the root README version table had fallen behind the manifests and was aligned to wallet 0.6.2, agent 0.1.3 and MCP 0.3.2. Those figures are historical; current versions are in the README and SDK guide.
- The generic connect-instruction example used a real site's name and address, making the public SDK look site-specific. It now uses an intentionally fictitious workspace origin.
- Browser and headless identity storage are described separately.
- The security documentation must distinguish _private presence_ from _not joining the room_; they are not equivalent.
docs/archive/implementation-plan-v0.4.mdis an older release tracker, not an up-to-date account of the current release or verification evidence.
Remaining limits and review gate#
- No TURN is configured; one-machine Chromium tests do not prove communication across all NATs or firewalls.
- A tool served by an absent browser page cannot be invoked just because a headless agent remains connected.
- A valid wallet and signed identity do not establish that an idle ChatGPT conversation is still executing or that its MCP transport remains alive.
- Browser screenshots show actual browser rendering, not the state of a production deployment.
- Existing example-site scripts use Ego Lite for visual/agent-flow checks, but those tests depend on the Ego Lite runner and are outside this AI Auth repository's GitHub CI.
- No merge into
mainshould occur until the PR workflow is green and the screenshot artifact has been inspected. Production deployment must be verified separately after a later authorized merge.