guise-bridge 0.1.4

Meridian Guise Firefox/BiDi bridge with live-page challenge solving
guise-bridge-0.1.4 is not a library.

guise-bridge

Role-bound Firefox/BiDi bridge daemon used by Meridian for browser automation actions and live-page challenge solving.

guise-bridge owns the HTTP integration binary so guise remains the reusable stealth and fingerprint runtime library, and CaptchaForge can run directly against an already-open Firefox session without launching a separate browser instance.

Status: beta (package.metadata.santh.status = "beta")

Features

  • Persistent Context Management: Spawns and manages isolated Firefox profile directories per context ID.
  • Non-Blocking Concurrency: Uses granular per-page handles and per-context launch locks to permit parallel execution across distinct contexts.
  • Stealth & Persona Coherence: Enforces persona launch coherence through guise and integrates with reynard binary stealth wrappers.
  • Live Challenge Solving: Integrates CaptchaForge to solve Turnstile/reCAPTCHA challenges directly on live BiDi pages.
  • Profile Sandbox: Neutralizes path traversal attempts (.., .) to restrict profile directories strictly within MERIDIAN_GUISE_PROFILE_ROOT.
  • Fail-Closed Evaluation: Surfaces invalid or corrupted JS evaluation responses as explicit errors rather than returning zero elements.

Execution

Run the bridge daemon from the Santh workspace root:

cargo run -p guise-bridge --release

Point Meridian clients at the bridge:

export MERIDIAN_BROWSER_BACKEND=guise_foxdriver
export MERIDIAN_GUISE_BRIDGE_URL=http://127.0.0.1:7432

Environment Variables

Variable Default Description
MERIDIAN_GUISE_PROFILE_ROOT System Temp Directory Root directory for isolated Firefox browser profiles
GUISE_REYNARD_BIN Evaluated paths Path to the reynard stealth browser binary wrapper
GUISE_BRIDGE_TZ Host default Default timezone set via TZ on spawned Firefox instances
GUISE_BRIDGE_HEADFUL 0 Set to 1 or true to enable visible browser window rendering

HTTP API

GET /health

Used by Meridian readiness probes. Returns HTTP 200 with JSON payload reporting posture:

  • browser_backend: "guise_foxdriver"
  • browser_runtime: "runtime_foxdriver_firefox_bidi"
  • stealth_engine: "reynard" (or "plain_firefox" if degraded)
  • webdriver_masked: true (when running under Reynard)
  • persona_coherence_gate: "enforced"
  • active_browser_contexts: Count of currently open browser instances
  • captcha_solve: true

POST /v1/browser/command

Executes browser lifecycle and DOM automation commands over JSON payloads.

Supported command actions:

  • Lifecycle: launch, resume, launch_or_resume, close
  • Navigation: goto, get_url, get_html, get_cookies, set_cookie
  • DOM: dom_snapshot, dom_query, dom_click, dom_type, dom_key, dom_select, dom_check, dom_wait, dom_extract, dom_readonly_eval, execute_js, submit, scroll, mouse
  • Media & Upload: dom_screenshot, dom_upload, dom_downloads
  • Diagnostics: dom_frames, dialog, dom_signals, dom_console, dom_network
  • Challenge Solving: captcha_solve

Verification

Run package-local unit tests:

cargo test -p guise-bridge

Run end-to-end integration suites:

bash tests/e2e_concurrent_browsers.sh
bash tests/e2e_dialog_frames.sh
bash tests/e2e_upload.sh
bash tests/e2e_mouse.sh
bash tests/e2e_sensors.sh