Crate captchaforge

Expand description

captchaforge — automatic CAPTCHA detection and solving for chromiumoxide-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 chromiumoxide 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::ChromeMacStable)).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 cookies::CapturedCookie;
pub use stealth_profiles::StealthProfile;
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::recommended_chromium_args;
pub use sdk::solve_url;
pub use sdk::wait_for_no_captcha;

Modules§

audio_dsp: Audio captcha pre-processing pipeline.
backends: Auto-detect available solver backends and configure the chain.
behavior
config: Tier-A operational configuration loaded from .captchaforge.toml.
cookies: Captured browser cookies — preserve a solved-captcha session across page loads.
detect
frame: Cross-origin iframe evaluation helpers.
frame_graph: Frame + shadow-root graph for the current page.
keystroke_timing: Bigram-aware keystroke timing.
mouse_sampler: Real-human mouse-trace sampler.
mouse_traces: Real-human mouse trajectory replay.
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: Chromium anti-detection (stealth) overrides.
stealth_profiles: Named browser fingerprint profiles.
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.
vlm_dataset: VLM training dataset format for captcha-specific fine-tuning.
warmup: Page-warming — natural pre-captcha visitor activity.

Functions§

auto_solve: One-call convenience: detect + solve in a single API.