captchaforge 0.2.38

[DO NOT USE — UNDER ACTIVE DEVELOPMENT, NOT PRODUCTION-READY] Captcha solver scaffolding for Firefox + BiDi-driven browsers. The architecture is in place (vendor solvers, retry-loop iframe walking, VLM provider abstraction, real-WAF bench harness) but the live-vendor success rate is still 0% — Cloudflare Turnstile / hCaptcha / reCAPTCHA detect us at a TLS / BiDi fingerprint layer that no flag-based stealth has cleared. Watch the repo; do not depend on this for any real workload.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202

//! End-to-end solve-loop validation for the dedicated vendor solvers.
//!
//! The per-vendor unit tests cover the *pure* classifiers. These tests cover the
//! other half the Testing Contract requires — the probe-JS ↔ solver pair — by
//! serving a local page that reproduces the exact DOM / cookie / window state
//! each vendor's clearance flow leaves behind, driving a real headless Firefox,
//! and asserting the solver's `solve()` reaches the right terminal outcome
//! (success / hard-block failure / interactive yield). This catches probe-JS
//! bugs (selector typos, cookie-parsing slips, phase mislabelling) that a pure
//! classifier test cannot.
//!
//! A real HTTP origin is required: `about:blank` has an opaque origin where
//! `document.cookie` writes are dropped, so the cookie-reading probes would see
//! nothing. `common::serve_once` gives each test a real `http://127.0.0.1:port`.

use captchaforge::detect::{CaptchaInfo, DetectedCaptcha};
use captchaforge::solver::{
    CaptchaSolver, CloudflareInterstitialSolver, DataDomeSolver, ImpervaSolver, KasadaSolver,
};

mod common;

fn info(kind: DetectedCaptcha, url: &str) -> CaptchaInfo {
    CaptchaInfo {
        kind,
        site_key: None,
        page_url: url.to_string(),
        container_selector: None,
    }
}

/// Serve `body_html` at a fresh local origin, navigate a real browser to it, and
/// return the live page wrapped in its `TestBrowser` (kept alive by the caller).
async fn page_with(body_html: &str) -> (common::TestBrowser, String) {
    let html = format!(
        "<!doctype html><html><head><title>t</title></head><body>{body_html}</body></html>"
    );
    let addr = common::serve_once(html).await;
    let url = format!("http://{addr}/");
    let browser = common::launch_browser().await;
    browser.new_page(&url).await.expect("navigate to mock origin");
    (browser, url)
}

#[tokio::test]
async fn datadome_valid_cookie_solves() {
    // Long base64-ish datadome cookie ⇒ DataDomeCookie::Valid ⇒ success.
    let (browser, url) = page_with(
        r#"<script>document.cookie = 'datadome=' + 'A1b2C3d4'.repeat(16);</script>Loaded"#,
    )
    .await;
    let solver = DataDomeSolver::new().with_max_wait_ms(5_000);
    let res = solver
        .solve(&browser, &info(DetectedCaptcha::Custom("datadome".into()), &url))
        .await
        .unwrap();
    assert!(res.success, "valid datadome cookie should solve");
    assert_eq!(res.solution, "datadome:cookie");
    browser.close().await.unwrap();
}

#[tokio::test]
async fn datadome_slider_iframe_yields() {
    // captcha-delivery.com iframe present, no cookie ⇒ yield to slider
    // (success=false, screenshot captured for the fallback).
    let (browser, url) = page_with(
        r#"<iframe src="https://geo.captcha-delivery.com/captcha/"></iframe>"#,
    )
    .await;
    let solver = DataDomeSolver::new().with_max_wait_ms(3_000);
    let res = solver
        .solve(&browser, &info(DetectedCaptcha::Custom("datadome".into()), &url))
        .await
        .unwrap();
    assert!(!res.success, "slider variant must yield, not falsely succeed");
    browser.close().await.unwrap();
}

#[tokio::test]
async fn imperva_reese84_cookie_solves() {
    let (browser, url) = page_with(
        r#"<script>document.cookie = 'reese84=' + 'r'.repeat(90);</script>Loaded"#,
    )
    .await;
    let solver = ImpervaSolver::new().with_max_wait_ms(5_000);
    let res = solver
        .solve(
            &browser,
            &info(DetectedCaptcha::Custom("imperva_incapsula".into()), &url),
        )
        .await
        .unwrap();
    assert!(res.success, "valid reese84 token should solve");
    assert_eq!(res.solution, "imperva:cookie");
    browser.close().await.unwrap();
}

#[tokio::test]
async fn imperva_incident_page_is_blocked() {
    // The classic Incapsula block body ⇒ hard failure (no screenshot/yield).
    let (browser, url) = page_with(
        r#"Request unsuccessful. Incapsula incident ID: 1234-5678901234567890"#,
    )
    .await;
    let solver = ImpervaSolver::new().with_max_wait_ms(2_000);
    let res = solver
        .solve(
            &browser,
            &info(DetectedCaptcha::Custom("imperva_incapsula".into()), &url),
        )
        .await
        .unwrap();
    assert!(!res.success, "incident page must not be reported as solved");
    assert!(res.screenshot.is_none(), "a hard block is a failure(), not a yield");
    browser.close().await.unwrap();
}

#[tokio::test]
async fn kasada_token_and_kpsdk_solves() {
    // KP_UIDz long-form + KPSDK initialised + no ips.js interruption ⇒ success.
    let (browser, url) = page_with(
        r#"<script>window.KPSDK = { configured: true };
           document.cookie = 'KP_UIDz=' + 'k'.repeat(40);</script>Loaded"#,
    )
    .await;
    let solver = KasadaSolver::new().with_max_wait_ms(5_000);
    let res = solver
        .solve(&browser, &info(DetectedCaptcha::Custom("kasada".into()), &url))
        .await
        .unwrap();
    assert!(res.success, "kasada clearance should solve");
    assert_eq!(res.solution, "kasada:cookie");
    browser.close().await.unwrap();
}

#[tokio::test]
async fn kasada_interruption_present_does_not_falsely_solve() {
    // ips.js interruption still active (KPSDK not ready) ⇒ no false success.
    let (browser, url) = page_with(
        r#"<script src="/ips.js"></script>
           <script>document.cookie = 'KP_UIDz=' + 'k'.repeat(40);</script>"#,
    )
    .await;
    let solver = KasadaSolver::new().with_max_wait_ms(1_500);
    let res = solver
        .solve(&browser, &info(DetectedCaptcha::Custom("kasada".into()), &url))
        .await
        .unwrap();
    assert!(!res.success, "active interruption must not be reported as solved");
    browser.close().await.unwrap();
}

#[tokio::test]
async fn cloudflare_clearance_cookie_solves() {
    let (browser, url) = page_with(
        r#"<script>document.cookie = 'cf_clearance=' + 'c'.repeat(48);</script>Loaded"#,
    )
    .await;
    let solver = CloudflareInterstitialSolver::new().with_max_wait_ms(5_000);
    let res = solver
        .solve(&browser, &info(DetectedCaptcha::Turnstile, &url))
        .await
        .unwrap();
    assert!(res.success, "valid cf_clearance should solve");
    assert_eq!(res.solution, "cf_clearance");
    browser.close().await.unwrap();
}

#[tokio::test]
async fn cloudflare_error_1020_is_blocked() {
    let (browser, url) = page_with(r#"<h1>Sorry, you have been blocked</h1><p>Error 1020</p>"#).await;
    let solver = CloudflareInterstitialSolver::new().with_max_wait_ms(2_000);
    let res = solver
        .solve(&browser, &info(DetectedCaptcha::Turnstile, &url))
        .await
        .unwrap();
    assert!(!res.success, "error 1020 block must fail");
    assert!(res.screenshot.is_none(), "a hard block is a failure(), not a yield");
    browser.close().await.unwrap();
}

#[tokio::test]
async fn cloudflare_managed_turnstile_yields_interactive() {
    // _cf_chl_opt + an embedded challenges.cloudflare.com widget ⇒ interactive
    // yield (success=false WITH a screenshot) so the chain hands off.
    let (browser, url) = page_with(
        r#"<script>window._cf_chl_opt = { cType: 'managed' };</script>
           <iframe src="https://challenges.cloudflare.com/cdn-cgi/challenge-platform/x"></iframe>"#,
    )
    .await;
    let solver = CloudflareInterstitialSolver::new().with_max_wait_ms(2_000);
    let res = solver
        .solve(&browser, &info(DetectedCaptcha::Turnstile, &url))
        .await
        .unwrap();
    assert!(!res.success, "interactive managed challenge must yield, not auto-pass");
    assert!(
        res.screenshot.is_some(),
        "interactive yield must capture a screenshot for the hand-off"
    );
    browser.close().await.unwrap();
}