@agentic-passport/agent-browser

Browser-runtime AgentPassport agent. Runs the HTTP handshake (same as @agentic-passport/agent), then drives a real Playwright browser context so the agent can navigate JS-rendered pages exactly as a human would.

Use this when the protected resource is HTML (a React SPA, a dashboard, a /account page — anything that hydrates client-side). A bare HTTP fetch against such a URL returns the SPA shell with an empty <main> even if you're authenticated — because the data is fetched by JavaScript that hasn't run yet. The browser-runtime SDK handles the vendor's bootstrap_url handoff so the page renders for real.

For JSON endpoints (/api/...), use @agentic-passport/agent instead.

Install

pnpm add @agentic-passport/agent-browser
# Playwright browsers also need to be installed:
pnpm exec playwright install chromium

Use

import { chromium } from 'playwright';
import { browserAgent } from '@agentic-passport/agent-browser';

const browser = await chromium.launch();
const context = await browser.newContext();

const agent = await browserAgent({
  context,
  vendorUrl: 'https://vendor.example',
  issuerUrl: 'https://issuer.agentpassport.app',
  mandate: {
    task: 'view my account',
    budget: { usd: 1 },
    scopes: ['account.read'],
  },
});

// agent.page is a Playwright Page with the vendor's native session set.
await agent.page.goto('https://vendor.example/account');
const text = await agent.page.locator('main').textContent();
console.log(text);

await browser.close();

What it returns

type BrowserAgent = {
  page: Page;              // Playwright page, post-bootstrap, ready to navigate
  httpSession: HttpSession; // The underlying AgentPassport HTTP session
  agentId: string;         // Vendor-assigned during /agent/register
  bootstrapped: boolean;   // true iff vendor returned a bootstrap_url
  audit: () => readonly { step: string; ok: boolean; detail?: unknown }[];
};

The handshake is identical to @agentic-passport/agent. The difference is that the vendor's onAgentSessionMint hook returns a bootstrap_url; browserAgent navigates to it, the vendor's auth provider (Clerk, Auth.js, WorkOS, etc.) mints its native session cookie in the browser context, and you land on a fully authenticated browser ready to render the SPA.

If the vendor doesn't implement onAgentSessionMint, bootstrapped is false and the browser is not authenticated to the vendor — only direct API calls via agent.httpSession.fetch() work.

Spec

Wire format — see vendor_session in the /agent/authorize response and WWW-Authenticate: ... resource_type="html" in §2.

License

Apache-2.0. Repository