palyrad). It enables secure, local-only relaying of DOM snapshots, screenshots, and browser actions to the daemon’s loopback interface, allowing agents to interact with the user’s real-time web context without requiring full remote control of the browser.
Architecture and Data Flow
The extension consists of a background service worker for orchestration, a content script for DOM manipulation, and a popup UI for configuration. It communicates exclusively with the local daemon via a validated loopback URL. Relay Communication Overview- Relay Dispatch: The extension sends POST requests to the daemon’s
/console/v1/browser/relay/actionsendpoint apps/browser-extension/background.js#159-160. - Authentication: Requests are authenticated using a
Relay Tokenand aSession IDminted by the Palyra Console apps/browser-extension/README.md#31-41. - Loopback Enforcement: The extension strictly validates that the
relayBaseUrltargets127.0.0.1,localhost, or::1to prevent data exfiltration to remote servers apps/browser-extension/lib.mjs#81-83.
Core Components
1. Content Script (DOM/Text Capture)
Thecontent_script.js is responsible for extracting page content. It avoids high-overhead properties like outerHTML or innerText to prevent browser hangs on large pages. Instead, it performs a manual, capped traversal of the DOM tree.
collectDomSnapshotCapped: Implements a stack-based traversal of the DOM to build a serialized HTML string apps/browser-extension/content_script.js#98-151.collectVisibleTextCapped: Uses aTreeWalkerto extract visible text fragments apps/browser-extension/content_script.js#159-182.- Capping Logic: Both functions respect
maxDomBytesandmaxVisibleTextByteslimits, truncating the output at valid UTF-8 boundaries usingclampUtf8Bytesapps/browser-extension/content_script.js#11-32.
2. Background Service Worker
Thebackground.js script acts as the central relay hub. It manages extension state, handles messages from the popup, and dispatches actions to the daemon.
captureCurrentTabContext: Orchestrates the injection of the content script and retrieves the DOM/Text snapshot apps/browser-extension/background.js#117-142.captureScreenshot: Utilizeschrome.tabs.captureVisibleTabto take a PNG screenshot of the active tab apps/browser-extension/background.js#144-157.dispatchRelayAction: Constructs the JSON payload includingsession_idandextension_idand performs the HTTP POST to the daemon apps/browser-extension/background.js#159-187.
3. Relay Actions
The extension supports three primary relay actions defined in thedispatchRelayAction logic:
| Action | Function | Description |
|---|---|---|
open_tab | runRelayOpenTab | Opens a URL in a new tab, guarded by an allowlist apps/browser-extension/background.js#189-200. |
capture_selection | runRelayCaptureSelection | Captures a specific DOM element via CSS selector apps/browser-extension/background.js#202-214. |
send_page_snapshot | runRelaySendPageSnapshot | Sends the full URL, Title, and DOM snapshot to the daemon apps/browser-extension/background.js#216-224. |
Security Posture
The extension implements a “Narrow Capability” security model to minimize the attack surface of the browser-to-daemon bridge. Logic Flow: URL Validation & Safety Sources: apps/browser-extension/lib.mjs#126-192, apps/browser-extension/README.md#15-21- Loopback Validation: The
normalizeRelayBaseUrlfunction ensures the daemon endpoint is on a loopback address, preventing the extension from being used as a generic web proxy apps/browser-extension/lib.mjs#67-88. - Open Tab Allowlist: The
open_tabaction is restricted byDEFAULT_OPEN_TAB_ALLOWLIST(defaults tohttps://,localhost,127.0.0.1) apps/browser-extension/lib.mjs#2-6. - Data Limits: Payloads are strictly bounded to prevent memory exhaustion in the daemon or the browser process.
- Default DOM Snapshot: 16 KB apps/browser-extension/lib.mjs#10.
- Default Visible Text: 8 KB apps/browser-extension/lib.mjs#11.
- Default Screenshot: 256 KB apps/browser-extension/lib.mjs#12.
- Credential Isolation: The
Relay Tokenis stored inchrome.storage.localand is never persisted outside the extension’s private storage apps/browser-extension/README.md#18.
Technical Constants
| Constant | Value | Source |
|---|---|---|
DEFAULT_RELAY_BASE_URL | http://127.0.0.1:7142 | apps/browser-extension/lib.mjs#1 |
MAX_EXTENSION_ID_BYTES | 128 | apps/browser-extension/lib.mjs#7 |
MAX_SESSION_ID_BYTES | 128 | apps/browser-extension/lib.mjs#8 |
MAX_RELAY_TOKEN_BYTES | 2,048 | apps/browser-extension/lib.mjs#9 |