Crate captchaforge

Expand description

captchaforge, automatic CAPTCHA detection and solving for Firefox + BiDi-driven headless browsers.

Extracted from golemn-browser (originally GPL-3.0) and re-licensed MIT OR Apache-2.0 by the original author so it can stand alone and be embedded by other Santh-ecosystem tools (wafrift, gossan, sear, …).

§Module map

detect (heuristic + DOM-based CAPTCHA identification).
solver, multi-strategy solving chain (behavioural, VLM, audio, third-party, pattern-cached, human fallback).
stealth / stealth_profiles, pre-navigation fingerprint hardening + named browser-vendor profiles.
warmup, natural pre-captcha activity (mouse / scroll entropy) so passive challenges score the visitor as human.
behavior, primitive realistic gestures (Bézier mouse, variable-cadence typing, hover dwell, touch swipe, jitter).
cookies (capture / replay session cookies, vendor-filter).
frame (same-origin iframe + cross-origin CDP frame walk).
provider (pluggable vendor-rule registry).
config. Tier-A .captchaforge.toml discovery.
backends (local backend probe (Ollama / Whisper / Tesseract)).
stt (speech-to-text endpoint ladder).
sdk, one-call orchestration (solve_url, prepare_page, auto_solve_with_retries, dismiss_cookie_consent, dismiss_chat_widget, wait_for_no_captcha).
prelude (glob-import target for the most-used types).

Three layered consumption modes:

One-call: captchaforge::solve_url(&page, url, None).await? when you want the whole chain wired for you.
Building blocks: call detect::detect then drive a custom solver::CaptchaSolverChain when you need telemetry, custom solvers, or non-default cache semantics.
Primitives: embed individual modules (stealth, behavior, frame, cookies) inside an existing BiDi flow without touching the solver chain.

Originally extracted from golemn-browser and re-licensed MIT OR Apache-2.0 by the original author so it can stand alone and be embedded by other Santh-ecosystem tools (wafrift, gossan, sear, …).

§Example, one-call solve

use captchaforge::prelude::*;
match solve_url(page, "https://example.com", Some(StealthProfile::FirefoxLinux)).await? {
    None => println!("no captcha detected"),
    Some(r) if r.success => println!("solved via {:?} in {}ms", r.method, r.time_ms),
    Some(r) => println!("failed: {:?}", r.method),
}

§Example, detect + custom chain

use captchaforge::{detect, solver::CaptchaSolverChain};
let info = detect::detect(page).await?;
if detect::is_captcha(&info) {
    let chain = CaptchaSolverChain::default_chain();
    // chain.solve(page, &info).await?;
}

§Example, pattern store

use captchaforge::solver::{CaptchaType, PatternStore, SolveMethod};

let store = PatternStore::default();
store.record("example.com", &CaptchaType::CloudflareTurnstile, true, 1200, SolveMethod::BehavioralBypass);
assert_eq!(store.best_method("example.com", &CaptchaType::CloudflareTurnstile), Some(SolveMethod::BehavioralBypass));

§Example, primitives only (no chain)

use captchaforge::behavior::{mouse_move_bezier, click_realistic};
use captchaforge::frame::evaluate_in_all_frames;
mouse_move_bezier(page, 0.0, 0.0, 400.0, 300.0).await?;
click_realistic(page, 400.0, 300.0).await?;
let titles: Vec<String> = evaluate_in_all_frames(page, "document.title").await?;

Re-exports§

pub use config::Config;
pub use detect as captcha_detect;
pub use provider::CaptchaProvider;
pub use provider::ProviderRegistry;
pub use backends::Capabilities;
pub use backends::OcrBackend;
pub use backends::SttBackend;
pub use backends::SttKind;
pub use backends::VlmBackend;
pub use solver::AudioCaptchaSolver;
pub use solver::BehavioralCaptchaSolver;
pub use solver::CaptchaSolveResult;
pub use solver::CaptchaSolver;
pub use solver::CaptchaSolverChain;
pub use solver::CaptchaType;
pub use solver::OcrCaptchaSolver;
pub use solver::SolveMethod;
pub use solver::TokenCache;
pub use solver::VlmCaptchaSolver;
pub use sdk::auto_solve_with_retries;
pub use sdk::dismiss_chat_widget;
pub use sdk::dismiss_cookie_consent;
pub use sdk::prepare_page;
pub use sdk::solve_url;
pub use sdk::wait_for_no_captcha;
pub use guise as stealth;

Modules§

adversarial_replay: Adversarial WAF response replay framework.
audio_dsp: Audio captcha pre-processing pipeline.
backends: Auto-detect available solver backends and configure the chain.
behavior: Compatibility path for behavior primitives (now backed by rustenium BiDi). Human behavior simulation - realistic mouse, keyboard, and scroll patterns.
browser: Re-export of the Firefox + BiDi runtime from runtime-foxdriver.
browser_runtime: Browser launch via rustenium Firefox (replaces runtime_headless).
config: Tier-A operational configuration loaded from .captchaforge.toml.
cookies: Re-export of cookie helpers from runtime-foxdriver.
detect
fingerprint_lru: Persistent solver-decision LRU keyed by (vendor, fingerprint).
frame: Re-export of frame helpers from runtime-foxdriver.
frame_graph: Re-export of frame-graph helpers from runtime-foxdriver.
keystroke_timing: Re-export shim: the canonical implementation lives in guise::human.
mobile_screenshot: Mobile-app captcha screenshot solving.
mobile_webview: Android WebView + iOS WKWebView captcha solving over BiDi-over-USB.
plugin: Dynamic-load plugin system for custom CaptchaSolver impls.
prelude: Convenience re-exports for the most-used types.
provider: CaptchaProvider, bundles a captcha’s detector with its recommended solver routing in one self-contained unit.
rule_watcher: Hot-reload of TOML rule packs.
sdk: High-level SDK convenience helpers.
solver
stealth_profiles: Stealth profile application for Firefox + BiDi.
stt: Speech-to-text endpoint ladder.
telemetry: Solver telemetry (structured event hooks for external analytics).
trace_ingest: Mouse-trace ingest server, receive traces from a consenting- human harvester (Chrome extension or instrumented page) and append them to a crate::training_corpus::TrainingCorpus- style on-disk store.
training_corpus: Adversarial training corpus, failure-driven feedback loop storage layer.
vendor_scraper: Vendor-JS scraper + auto-stealth synthesis.
vision: Local vision backend: YOLOv8 + CRNN inference via ONNX Runtime.
vlm_dataset: VLM training dataset format for captcha-specific fine-tuning.
waf_gate: WAF-gate preflight and token-verify HTTP via canonical substrate.
warmup: Page-warming (natural pre-captcha visitor activity).

Structs§

CapturedCookie: A single captured browser cookie. Fields mirror the subset of Network.Cookie that’s relevant for replay.
Page: Primary browser page handle (now backed by Firefox + BiDi via rustenium). Wrapper around rustenium’s FirefoxBrowser.
ProfileBundle: A coherent stealth configuration spanning browser JS fingerprint and TLS ClientHello.
ProfileOverrides: The set of fingerprint values a profile pins.

Enums§

StealthProfile: Named browser fingerprint variants. Each one identifies a coherent (browser, OS, GPU class) tuple used by higher-level stealth crates.

Functions§

apply_default_stealth_profile: The canonical default disguise: max coherence.
apply_stealth: Apply generic anti-detection JS to page.
apply_stealth_profile: Apply a stealth profile’s JS anti-detection patches to page.
auto_solve: One-call convenience: detect + solve in a single API.
profile_js: Build the override JS for a given profile.
profile_to_overrides: Materialise the override values for a given profile. Pure.