palyrad daemon or a dedicated palyra-browserd instance.
Overview and Purpose
The extension acts as a “Relay” that allows the Palyra agent to interact with the user’s active browsing session without requiring the agent to have direct OS-level control over the browser process. It provides capabilities for:- Context Capture: Extracting DOM snapshots and visible text from the active tab.
- Remote Navigation: Opening and activating tabs within the user’s browser.
- Security Isolation: Operating strictly over loopback interfaces with non-persistent tokens to minimize the attack surface.
Architecture and Data Flow
The extension follows the standard Manifest V3 architecture, utilizing a Background Service Worker for relay logic and Content Scripts for DOM interaction.System Component Diagram
The following diagram illustrates the relationship between the extension components and the Palyra daemon. Relay Companion Entity Mapping Sources: apps/browser-extension/manifest.json#1-40, apps/browser-extension/background.js#159-187, apps/browser-extension/content_script.js#184-208Data Flow: Page Snapshot Capture
When a snapshot is requested, the Background script injects a content script to perform capped extraction to ensure the payload does not exceed configured limits.- Trigger: User or Agent initiates a snapshot via
captureCurrentTabContextapps/browser-extension/background.js#117-142. - Injection:
background.jscallschrome.scripting.executeScriptto ensurecontent_script.jsis present apps/browser-extension/background.js#120-123. - Extraction:
content_script.jslistens forpalyra.collect_snapshotapps/browser-extension/content_script.js#184-187. - Capping:
collectDomSnapshotCappedandcollectVisibleTextCappedtraverse the DOM, appending to a buffer untilmaxBytesis reached apps/browser-extension/content_script.js#98-182. - Relay:
background.jsreceives the response and dispatches it viadispatchRelayActionto the loopback API apps/browser-extension/background.js#159-187.
Key Implementation Details
Security Posture
The extension implements several strict security guardrails:- Loopback Only: The
relayBaseUrlis strictly validated to ensure it only targets127.0.0.1,localhost, or::1apps/browser-extension/lib.mjs#81-83. - URL Allowlisting: Remote
open_tabrequests are checked against a prefix allowlist (e.g.,https://) to prevent protocol handler abuse or navigation to sensitive local files apps/browser-extension/lib.mjs#126-192. - Token Handling: While
relayTokenandsessionIdare stored inchrome.storage.localfor convenience, the architecture is designed for “Pairing” flows where tokens can be rotated apps/browser-extension/background.js#40-57. - Credential Validation:
normalizeRelayTokenandnormalizeSessionIdenforce byte limits to prevent buffer overflow or DOS attempts against the relay endpoint apps/browser-extension/lib.mjs#104-124.
Content Script Logic
Thecontent_script.js is optimized for performance and safety, avoiding heavy operations like outerHTML or innerText which can trigger expensive reflows or layout calculations.
| Function | Purpose | Logic |
|---|---|---|
collectDomSnapshotCapped | Safe DOM extraction | Uses a stack-based traversal (non-recursive) to build a string representation of the DOM up to maxBytes apps/browser-extension/content_script.js#98-151. |
collectVisibleTextCapped | Text extraction | Uses document.createTreeWalker with NodeFilter.SHOW_TEXT to gather visible strings apps/browser-extension/content_script.js#159-182. |
clampUtf8Bytes | Byte-level truncation | Ensures strings are truncated without splitting multi-byte UTF-8 characters apps/browser-extension/lib.mjs#28-50. |
Pairing and Configuration
The extension requires pairing with a running Palyra daemon. This is managed via thepopup.html interface and popup.js.
Configuration Schema
The extension persists the following configuration inchrome.storage.local under the key palyraRelayConfig:
| Key | Default | Description |
|---|---|---|
relayBaseUrl | http://127.0.0.1:7142 | The loopback address of the Palyra daemon apps/browser-extension/lib.mjs#1. |
sessionId | "" | The active session identifier for the relay apps/browser-extension/background.js#22. |
relayToken | "" | Bearer token for authenticating with the daemon apps/browser-extension/background.js#23. |
openTabAllowlistRaw | https://, http://127.0.0.1... | CSV/Newline separated list of allowed URL prefixes apps/browser-extension/lib.mjs#2-6. |
Relay Action Dispatch
Actions are dispatched viadispatchRelayAction, which targets the /console/v1/browser/relay/actions endpoint.
Relay Protocol Sequence
Sources: apps/browser-extension/background.js#159-187, crates/palyra-daemon/src/transport/http/handlers/console/browser.rs#5-32
Testing and Validation
The extension includes a suite of Node.js-based tests that simulate the browser environment using thevm module.
- Content Script Tests: Validates that snapshots are correctly capped and that HTML entities are escaped without materializing the full DOM apps/browser-extension/tests/content_script.test.mjs#133-183.
- Library Tests: Ensures that URL normalization and allowlist logic correctly reject malicious inputs like username/password confusion (
https://user@evil.com) apps/browser-extension/tests/lib.test.mjs#18-55.