Browser Context Bridge Broker

Tiny localhost broker for Browser Context Bridge.

Links:

• Chrome extension: Browser Context Bridge on Chrome Web Store
• npm package: browser-context-bridge-broker

It does only two things:

• forwards cookie and storage snapshot commands from local agents to the browser extension
• forwards request capture configuration and reads to the browser extension

It does not automate tabs, expose CDP, store cookies, or listen on the LAN.

Endpoints

• WebSocket for the extension: ws://127.0.0.1:37181/extension?pairingToken=...
• Status: GET /api/browser-context-bridge/status
• Pairing: GET /api/browser-context-bridge/pairing
• Command: POST /api/browser-context-bridge/command

Allowed command methods:

• browserContext.cookies.getAll
• browserContext.cookies.getAllByLabel
• browserContext.storage.readForUrl
• browserContext.requests.configure
• browserContext.requests.getRecent
• browserContext.requests.prune

CLI

bunx browser-context-bridge-broker

Optional:

BROWSER_CONTEXT_BRIDGE_BROKER_TOKEN=... bunx browser-context-bridge-broker

The CLI persists the extension pairing token in the user's profile by default, so restarting or upgrading the broker does not invalidate an already connected extension. Override the token with --pairing-token or BROWSER_CONTEXT_BRIDGE_PAIRING_TOKEN; override the token file with --pairing-token-file or BROWSER_CONTEXT_BRIDGE_PAIRING_TOKEN_FILE.

Local lifecycle managers should call GET /api/browser-context-bridge/pairing, pass the returned relayUrl to the installed extension through a localhost connect page, and then let agents use the command endpoint. If BROWSER_CONTEXT_BRIDGE_BROKER_TOKEN is set, the pairing and command endpoints both require Authorization: Bearer <token>.

During the Chrome Web Store rollout window, the broker accepts both the new paired extension URL and the legacy unpaired /extension URL used by extension 0.4.3. Once the extension update has propagated, start the broker with strict pairing to close the legacy path:

BROWSER_CONTEXT_BRIDGE_STRICT_PAIRING=1 bunx browser-context-bridge-broker

or:

bunx browser-context-bridge-broker --strict-pairing

The CLI runs as a foreground long-running process. The npm package does not install a launchd, systemd, or other OS background service by itself. If a local agent wants broker-on-demand behavior, it should probe the fixed status endpoint, acquire a per-user lock, then start and supervise one shared broker process.

Core Client

Local JavaScript and TypeScript runtimes should import the core client, not the broker server:

import { createBrowserContextBridgeClient } from 'browser-context-bridge-broker/core';

const bridge = createBrowserContextBridgeClient({
  token: process.env.BROWSER_CONTEXT_BRIDGE_BROKER_TOKEN,
});

const probe = await bridge.probe();
if (!probe.ok) {
  throw new Error(`broker unavailable: ${probe.reason}`);
}

if (!(await bridge.extensionConnected())) {
  throw new Error('Browser Context Bridge extension is not connected');
}

const capabilities = await bridge.checkCapabilities([
  'browserContext.requests.getRecent',
  'browserContext.requests.prune',
]);
if (!capabilities.ok) {
  throw new Error(`broker is missing capabilities: ${capabilities.missingCapabilities.join(', ')}`);
}

const cookies = await bridge.getCookiesForUrl('https://example.com');
const storage = await bridge.getStorageForUrl('https://example.com');

await bridge.configureRequests({
  enabled: true,
  methods: ['POST'],
  includeHosts: ['example.com'],
  captureBodyKeys: true,
});

const recentPosts = await bridge.getRecentRequests({
  hosts: ['example.com'],
  maxResults: 20,
});

The core client only speaks the fixed HTTP protocol. It does not start the broker, open Chrome, or import the Bun WebSocket server.

Direct HTTP remains supported for non-JS runtimes or agents that already own their transport layer. The core client and direct HTTP API should expose the same broker protocol capabilities; lifecycle management stays outside the core client.