Ecosystem

OpenApe Browser

Grant-aware headless browser with route interception and delegation login.

@openape/browser

A Playwright wrapper that adds grant-based route interception and delegation login. Every HTTP(S) request from the browser is evaluated against rules — unauthorized requests are blocked before reaching the network.

Installation

npm install @openape/browser playwright

Quick Start

import { createGrantedBrowser } from '@openape/browser'

const browser = await createGrantedBrowser({
  rulesFile: './rules.toml',
  idpUrl: 'https://id.example.com',
  agentEmail: 'agent+scraper@example.com'
})

const page = await browser.newPage()
await page.goto('https://target-app.example.com')

// Do your automation work...
const title = await page.title()
console.log('Page title:', title)

await browser.close()

Configuration Options

interface GrantedBrowserOptions {
  // Rule source (one of)
  rulesFile?: string       // Path to TOML rules file
  rules?: Rules            // Inline rules object

  // IdP connection
  idpUrl: string           // IdP URL for grant requests
  agentEmail: string       // Agent identity

  // Playwright options
  headless?: boolean       // Default: true
  browserType?: 'chromium' | 'firefox' | 'webkit'  // Default: 'chromium'
}

Rules

Rules use the same TOML format as @openape/proxy:

[[rules.allow]]
domains = ["target-app.example.com"]

[[rules.deny]]
domains = ["*.tracking.com", "analytics.*"]

[[rules.grant_required]]
domains = ["api.external-service.com"]
methods = ["POST"]
grant_type = "once"

Route Interception

Every request the browser makes (page loads, XHR, fetch, images, scripts) is evaluated against your rules:

allow — Request proceeds normally
deny — Request is aborted, page receives a network error
grant_required — A grant is requested from the IdP; the request is held until approved

const browser = await createGrantedBrowser({
  rules: {
    allow: [{ domains: ['app.example.com'] }],
    deny: [{ domains: ['*.ads.com'] }],
    grant_required: [
      { domains: ['api.example.com'], methods: ['POST'], grant_type: 'once' }
    ]
  },
  idpUrl: 'https://id.example.com',
  agentEmail: 'agent+bot@example.com'
})

const browser = await createGrantedBrowser({
  rulesFile: './rules.toml',
  idpUrl: 'https://id.example.com',
  agentEmail: 'agent+bot@example.com'
})

// Login as alice via delegation
await browser.loginAs({
  email: 'alice@example.com',
  delegationToken: '<delegation-jwt>'
})

// Browser now has alice's session
const page = await browser.newPage()
await page.goto('https://app.example.com/dashboard')

Delegation tokens are created via grapes delegate or the Delegation API.

API

`GrantedBrowser`

Property / Method	Description
`context`	Underlying Playwright `BrowserContext`
`newPage()`	Create a new page with route interception enabled
`loginAs(options)`	Login as a delegated user
`close()`	Close the browser and clean up

Use Cases

Web scraping with access control — Only allow requests to approved domains
Automated testing — Test grant approval flows in a real browser
Agent browser automation — Let agents browse the web with human-approved boundaries
Delegation workflows — Act on behalf of users who granted delegation permissions

OpenApe Proxy

Agent HTTP gateway with grant-based access control.

OpenApe Auth

DNS-based identity for humans and agents.