palyra-browserd. It covers how browser sessions are saved and restored across restarts, the multi-tenant profile registry, cryptographic isolation of session data, and the safety measures applied to browser-generated artifacts.
Browser Profile Registry and Persistence
palyra-browserd manages a registry of browser profiles, each representing a distinct set of user data (cookies, local storage, history). These profiles are persisted in an encrypted registry file, ensuring that sensitive session metadata is never stored in plaintext on disk.
BrowserProfileRegistryDocument
The registry is managed via theBrowserProfileRegistryDocument, which tracks profiles associated with specific principals.
- Registry Storage: The registry is stored in a file named
profiles.enccrates/palyra-browserd/src/lib.rs#138-138. - Schema Versioning: The registry uses a versioned schema to handle migrations crates/palyra-browserd/src/lib.rs#139-140.
- Principal Isolation: Profiles are scoped to a
principal(e.g.,user:ops). A principal can own multiple profiles, but they are isolated from other principals crates/palyra-daemon/src/transport/http/handlers/console/browser.rs#11-19.
PersistedStateStore
ThePersistedStateStore handles the low-level serialization and encryption of session snapshots. When a session is created with persistence_enabled=true, the browser engine’s state is periodically snapshotted and saved crates/palyra-browserd/src/transport/grpc/service.rs#51-58.
Data Flow: Profile and State Persistence
The following diagram illustrates how a profile is resolved and its state is loaded from the encrypted store. Browser State Resolution Flow Sources: crates/palyra-browserd/src/transport/grpc/service.rs#29-91, crates/palyra-browserd/src/lib.rs#131-145, crates/palyra-identity/src/store.rs#20-31Per-Profile Derived Encryption Keys
Security is enforced by deriving unique encryption keys for every profile. This prevents a compromise of one profile’s data from affecting others.- Master Key: The system uses a master key, often provided via
PALYRA_BROWSERD_STATE_ENCRYPTION_KEYcrates/palyra-browserd/src/lib.rs#123-123. - Key Derivation: Keys are derived using a specific namespace:
palyra.browser.profile.dek.v1crates/palyra-browserd/src/lib.rs#135-135. - Algorithm: The system utilizes
CHACHA20_POLY1305for authenticated encryption of state blobs crates/palyra-browserd/src/lib.rs#46-50. - Integrity Checks: Snapshots include a hash (SHA256) of the content to detect tampering crates/palyra-browserd/src/support/tests.rs#5-7.
Download Artifact Quarantine
To prevent malicious files from reaching the host system directly,palyra-browserd implements a multi-stage download handling process involving sandboxing and quarantine.
DownloadSandboxSession
Every browser session that allows downloads is assigned aDownloadSandboxSession. This creates a temporary directory structure to isolate files crates/palyra-browserd/src/domain/downloads.rs#20-25.
- Directory Structure:
allowlist/: Files that pass all security checks crates/palyra-browserd/src/domain/downloads.rs#33-34.quarantine/: Files that are suspicious or fail validation crates/palyra-browserd/src/domain/downloads.rs#35-36.
Validation Logic
Files are quarantined based on two primary criteria:- Extension Allowlist: Only safe extensions (e.g.,
.txt,.pdf,.json) are permitted crates/palyra-browserd/src/lib.rs#153-153. - MIME Type Validation: The
Content-Typemust match a set of known-safe types crates/palyra-browserd/src/lib.rs#154-162.
quarantine_reason (e.g., extension_not_allowlisted) crates/palyra-browserd/src/domain/downloads.rs#105-118.
| Constraint | Default Value | Source |
|---|---|---|
| Max File Size | 8 MB | crates/palyra-browserd/src/lib.rs#148-148 |
| Max Session Storage | 32 MB | crates/palyra-browserd/src/lib.rs#147-147 |
| Max Artifacts | 128 | crates/palyra-browserd/src/lib.rs#149-149 |
CLI Browser Commands
Thepalyra CLI provides a suite of commands to interact with the browser daemon. These commands translate user intent into gRPC calls to palyra-browserd.
Core Commands and Functions
| CLI Command | Internal Function | Purpose |
|---|---|---|
palyra browser console | run_browser_console | Opens an interactive REPL or executes JS in the session. |
palyra browser highlight | run_browser_highlight | Visually highlights elements matching a CSS selector. |
palyra browser select | run_browser_select | Returns the text or attributes of specific DOM elements. |
palyra browser pdf | run_browser_pdf | Generates a PDF print-out of the current page. |
palyra browser trace | run_browser_trace | Captures network and console logs for the session. |
Implementation Detail: Browser Action Lifecycle
The CLI uses theBrowserServiceImpl gRPC client to communicate with the daemon. Most actions follow a pattern of resolving the session, performing a blocking Chromium operation, and returning the result as JSON or text.
CLI to Code Entity Mapping
Sources: crates/palyra-cli/src/commands/browser.rs#160-240, crates/palyra-browserd/src/transport/grpc/service.rs#13-32, crates/palyra-browserd/src/engine/chromium.rs#60-68
Output Modes
The CLI supports multiple output formats via the--output or --json flags:
- Text: Human-readable summary crates/palyra-cli/src/commands/browser.rs#155-155.
- JSON: Full structured data for programmatic use crates/palyra-cli/src/commands/browser.rs#156-156.
- NDJSON: Newline-delimited JSON for streaming events (common in
trace) crates/palyra-cli/src/commands/browser.rs#157-157.