captchaforge 0.2.39

//! Third-party CAPTCHA-solving service adapter.
//!
//! Talks the 2captcha-compatible HTTP protocol: POST `in.php` to submit
//! a task, poll `res.php` until the worker returns a token. This
//! protocol is supported (with the same endpoints relative to a base
//! URL) by 2captcha, CapMonster and CapSolver, so a single solver
//! covers all three services. Use `ThirdPartyCaptchaSolver::two_captcha`
//! / `::cap_monster` / `::cap_solver` / `::custom_endpoint` to point at
//! the service of your choice.
//!
//! Why this matters: every TOML-bundled vendor in `community.toml`
//! recommends `SolveMethod::ThirdPartyService` somewhere in its
//! method list. Without an actual solver implementing that method,
//! the chain skips the recommendation and either falls through to
//! Behavioral / VLM (which often can't handle a vendor like DataDome
//! or AWS WAF) or returns unsolved.
//!
//! Supported captcha shapes:
//! - Cloudflare Turnstile (`method=turnstile`, sitekey + pageurl)
//! - reCAPTCHA v2 (`method=userrecaptcha`, googlekey + pageurl)
//! - reCAPTCHA v3 (`method=userrecaptcha`, googlekey + pageurl + version=v3)
//! - hCaptcha (`method=hcaptcha`, sitekey + pageurl)
//! - DataDome (`method=datadome`, captcha_url + pageurl). DataDome's
//!   `captcha_url` lives in CaptchaInfo::container_selector by
//!   convention for TOML rules that emit it.
//! - FunCaptcha / Arkose (`method=funcaptcha`, publickey + pageurl)
//! - GeeTest v3 + v4 (`method=geetest` / `geetest_v4`, gt + challenge + pageurl)
//!
//! For captcha kinds the third-party services don't have a standard
//! method for (PoW, slider, canvas, multi-step), `supports()` returns
//! false and the chain skips this solver. For TOML-rule vendors that
//! aren't in the supported-vendors list above, `supports()` also
//! returns false, better to return cleanly than to send a malformed
//! task that wastes the user's API balance.
//!
//! API key: pass via [`ThirdPartyCaptchaSolver::with_api_key`] or via
//! the `CAPTCHAFORGE_THIRDPARTY_API_KEY` env var (read once at
//! solver-construction time). With no key, `supports()` returns false
//! across the board so the chain skips this solver entirely instead
//! of issuing requests that would 401.
//!
//! Module layout (Law 5, responsibility split):
//! - this file: construction, key-pool rotation, SSRF endpoint guard,
//!   and the [`CaptchaSolver`] trait impl that wires it all together.
//! - [`protocol`]: the 2captcha wire protocol (task-param building,
//!   `submit_task`, `poll_result`).
//! - [`retry`]: the transient-error exponential-backoff primitive.

use super::*;
use crate::captcha_detect::DetectedCaptcha;
use std::time::Duration;

mod protocol;
mod retry;
pub(crate) use retry::*;

#[cfg(test)]
#[path = "third_party/tests.rs"]
mod tests;

const POLL_INTERVAL_MS: u64 = 5_000;
const MAX_POLLS: u32 = 30;
const ENV_API_KEY: &str = "CAPTCHAFORGE_THIRDPARTY_API_KEY";
const ENV_ENDPOINT: &str = "CAPTCHAFORGE_THIRDPARTY_ENDPOINT";

/// Which third-party service to talk to.
///
/// All three speak the 2captcha `in.php` / `res.php` protocol, so the
/// only difference is the base URL. Custom lets callers point at a
/// self-hosted gateway (or a service we haven't enum-ed yet).
#[derive(Debug, Clone)]
pub enum ThirdPartyService {
    /// `https://2captcha.com`
    TwoCaptcha,
    /// `https://api.capmonster.cloud` (2captcha-compat endpoint at
    /// `/in.php` + `/res.php`).
    CapMonster,
    /// `https://api.capsolver.com` (2captcha-compat endpoint).
    CapSolver,
    /// A self-hosted or custom 2captcha-compatible gateway.
    Custom { base_url: String },
}

impl ThirdPartyService {
    /// Base URL the `in.php` / `res.php` endpoints hang off of.
    pub fn base_url(&self) -> &str {
        match self {
            Self::TwoCaptcha => "https://2captcha.com",
            Self::CapMonster => "https://api.capmonster.cloud",
            Self::CapSolver => "https://api.capsolver.com",
            Self::Custom { base_url } => base_url,
        }
    }
}

/// Round-robin pool of API keys. Survives clones via Arc so the
/// rotation state is shared across all clones of the solver.
#[derive(Debug)]
pub(crate) struct KeyPool {
    keys: Vec<String>,
    cursor: std::sync::atomic::AtomicUsize,
}

impl KeyPool {
    fn new(keys: Vec<String>) -> Self {
        Self {
            keys,
            cursor: std::sync::atomic::AtomicUsize::new(0),
        }
    }

    /// Advance to the next key, wrapping. Returns the new active key.
    pub(crate) fn advance(&self) -> String {
        let n = self.keys.len();
        if n == 0 {
            return String::new();
        }
        let prev = self
            .cursor
            .fetch_add(1, std::sync::atomic::Ordering::SeqCst);
        self.keys[(prev + 1) % n].clone()
    }

    #[cfg(test)]
    /// Current active key (without rotating).
    pub(crate) fn current(&self) -> String {
        let n = self.keys.len();
        if n == 0 {
            return String::new();
        }
        let idx = self.cursor.load(std::sync::atomic::Ordering::SeqCst);
        self.keys[idx % n].clone()
    }
}

/// Solver that delegates to a 2captcha-compatible third-party service.
pub struct ThirdPartyCaptchaSolver {
    pub(crate) client: reqwest::Client,
    pub(crate) service: ThirdPartyService,
    pub(crate) api_key: Option<String>,
    pub(crate) poll_interval_ms: u64,
    pub(crate) max_polls: u32,
    pub(crate) key_pool: Option<std::sync::Arc<KeyPool>>,
}

impl Default for ThirdPartyCaptchaSolver {
    fn default() -> Self {
        Self::two_captcha()
    }
}

/// SSRF guard for third-party API endpoints. Permits only http(s)
/// schemes pointing at non-private hosts. Mirrors the policy applied
/// to TOML-configured `service = "custom"` endpoints in
/// [`crate::config::Config::build_third_party_solver`] so the env-var
/// override path can't be a back door.
fn validate_endpoint_url(raw: &str) -> bool {
    let Ok(parsed) = url::Url::parse(raw) else {
        return false;
    };
    if !matches!(parsed.scheme(), "http" | "https") {
        return false;
    }
    let Some(host) = parsed.host() else {
        return false;
    };
    match host {
        url::Host::Ipv4(addr) => {
            !(addr.is_loopback()
                || addr.is_private()
                || addr.is_link_local()
                || addr.is_unspecified())
        }
        url::Host::Ipv6(addr) => {
            if let Some(v4) = addr.to_ipv4_mapped() {
                if v4.is_loopback() || v4.is_private() || v4.is_link_local() {
                    return false;
                }
            }
            let seg = addr.segments();
            !(addr.is_loopback()
                || addr.is_unspecified()
                || (seg[0] & 0xffc0) == 0xfe80
                || (seg[0] & 0xfe00) == 0xfc00)
        }
        url::Host::Domain(d) => {
            let lower = d.to_ascii_lowercase();
            !matches!(
                lower.as_str(),
                "localhost"
                    | "ip6-localhost"
                    | "ip6-loopback"
                    | "metadata.google.internal"
                    | "metadata.aws.internal"
            )
        }
    }
}

impl ThirdPartyCaptchaSolver {
    /// Construct a solver pointed at 2captcha. Reads
    /// `CAPTCHAFORGE_THIRDPARTY_API_KEY` and
    /// `CAPTCHAFORGE_THIRDPARTY_ENDPOINT` once at construction time.
    /// If `CAPTCHAFORGE_THIRDPARTY_ENDPOINT` is set, it overrides the
    /// 2captcha base URL (use this when you want env-driven
    /// service-switching without touching code).
    pub fn two_captcha() -> Self {
        Self::for_service(ThirdPartyService::TwoCaptcha)
    }

    /// Construct a solver pointed at CapMonster.
    pub fn cap_monster() -> Self {
        Self::for_service(ThirdPartyService::CapMonster)
    }

    /// Construct a solver pointed at CapSolver.
    pub fn cap_solver() -> Self {
        Self::for_service(ThirdPartyService::CapSolver)
    }

    /// Construct a solver pointed at a custom 2captcha-compatible
    /// endpoint (self-hosted gateway, etc.).
    pub fn custom_endpoint(base_url: impl Into<String>) -> Self {
        Self::for_service(ThirdPartyService::Custom {
            base_url: base_url.into(),
        })
    }

    fn for_service(service: ThirdPartyService) -> Self {
        let service = match std::env::var(ENV_ENDPOINT) {
            Ok(custom) if !custom.is_empty() => {
                // Apply the SAME SSRF policy as `Config::build_third_party_solver`:
                // require http(s) scheme + reject loopback / private /
                // link-local / metadata. Without this gate the env var
                // is a strictly larger surface than the TOML path 
                // CAPTCHAFORGE_THIRDPARTY_ENDPOINT=http://169.254.169.254/...
                // would otherwise route POST traffic to cloud metadata.
                if validate_endpoint_url(&custom) {
                    ThirdPartyService::Custom { base_url: custom }
                } else {
                    tracing::warn!(
                        endpoint = %custom,
                        "CAPTCHAFORGE_THIRDPARTY_ENDPOINT failed SSRF policy. \
                         falling back to declared service"
                    );
                    service
                }
            }
            _ => service,
        };
        let api_key = std::env::var(ENV_API_KEY).ok().filter(|s| !s.is_empty());
        Self {
            client: crate::http_client::timed_client_or_panic(Duration::from_secs(60)),
            service,
            api_key,
            poll_interval_ms: POLL_INTERVAL_MS,
            max_polls: MAX_POLLS,
            key_pool: None,
        }
    }

    /// Override the API key (takes precedence over the env var).
    pub fn with_api_key(mut self, key: impl Into<String>) -> Self {
        self.api_key = Some(key.into());
        self.key_pool = None;
        self
    }

    /// Provide a pool of API keys. The solver round-robins through
    /// them and rotates to the next key on 429 / quota-exceeded
    /// responses. Survives across solver lifetime; rotation index
    /// is in-process only (not persisted).
    ///
    /// When the pool is exhausted (all keys hit rate limit), the
    /// solver falls back to the last key and lets the call surface
    /// the rate-limit error normally.
    #[must_use = "with_api_key_pool returns Self; assign or chain it"]
    pub fn with_api_key_pool<I, S>(mut self, keys: I) -> Self
    where
        I: IntoIterator<Item = S>,
        S: Into<String>,
    {
        let pool: Vec<String> = keys
            .into_iter()
            .map(Into::into)
            .filter(|k| !k.is_empty())
            .collect();
        if pool.is_empty() {
            self.key_pool = None;
            return self;
        }
        // First key seeds api_key; pool drives rotation.
        self.api_key = pool.first().cloned();
        self.key_pool = Some(std::sync::Arc::new(KeyPool::new(pool)));
        self
    }

    /// Rotate to the next API key in the pool. Returns the new
    /// active key on success, or `None` when no pool is configured.
    /// Call after observing a 429 / quota-exceeded response.
    pub fn rotate_api_key(&mut self) -> Option<String> {
        let pool = self.key_pool.as_ref()?;
        let next = pool.advance();
        self.api_key = Some(next.clone());
        Some(next)
    }

    /// Override the polling interval (default 5000ms, services
    /// typically need 10–30s to solve and rate-limit aggressive
    /// polling).
    pub fn with_poll_interval_ms(mut self, ms: u64) -> Self {
        self.poll_interval_ms = ms;
        self
    }

    /// Override the maximum number of poll attempts (default 30 →
    /// 150s with the default interval).
    pub fn with_max_polls(mut self, polls: u32) -> Self {
        self.max_polls = polls;
        self
    }

    /// Whether this solver has an API key configured. `solve()` will
    /// error early without one; the chain checks this via `supports()`
    /// to skip the solver entirely.
    pub fn has_api_key(&self) -> bool {
        self.api_key.as_ref().is_some_and(|k| !k.is_empty())
    }
}

#[async_trait]
impl CaptchaSolver for ThirdPartyCaptchaSolver {
    fn name(&self) -> &'static str {
        "ThirdPartyCaptchaSolver"
    }

    fn method(&self) -> SolveMethod {
        SolveMethod::ThirdPartyService
    }

    fn supports(&self, kind: &DetectedCaptcha) -> bool {
        if !self.has_api_key() {
            return false;
        }
        match kind {
            DetectedCaptcha::Turnstile
            | DetectedCaptcha::RecaptchaV2
            | DetectedCaptcha::RecaptchaV3
            | DetectedCaptcha::HCaptcha => true,
            DetectedCaptcha::Custom(name) => matches!(
                name.as_str(),
                "datadome" | "arkose_funcaptcha" | "geetest_v3" | "geetest_v4"
            ),
            _ => false,
        }
    }

    async fn solve(&self, page: &Page, captcha_info: &CaptchaInfo) -> Result<CaptchaSolveResult> {
        let t0 = Instant::now();
        if !self.has_api_key() {
            return Err(anyhow!("ThirdPartyCaptchaSolver has no API key configured"));
        }

        let params = Self::build_task_params(captcha_info).ok_or_else(|| {
            anyhow!(
                "ThirdPartyCaptchaSolver cannot build task params for {:?}",
                captcha_info.kind
            )
        })?;

        let task_id = self.submit_task(&params).await?;
        let token = self.poll_result(&task_id).await?;

        // Inject the token into the page so the captcha's success-callback
        // can fire. For Turnstile / hCaptcha / reCAPTCHA the standard
        // pattern is to populate the response textarea. The page's own
        // form-submit JS will then pick it up.
        let injection = match &captcha_info.kind {
            DetectedCaptcha::Turnstile => Some(format!(
                "(() => {{ const inp = document.querySelector('[name=\"cf-turnstile-response\"]'); if (inp) inp.value = {}; }})()",
                serde_json::to_string(&token).unwrap_or_else(|_| "''".into())
            )),
            DetectedCaptcha::RecaptchaV2 | DetectedCaptcha::RecaptchaV3 => Some(format!(
                "(() => {{ const inp = document.querySelector('[name=\"g-recaptcha-response\"]'); if (inp) inp.value = {0}; const el = document.getElementById('g-recaptcha-response'); if (el) el.innerHTML = {0}; }})()",
                serde_json::to_string(&token).unwrap_or_else(|_| "''".into())
            )),
            DetectedCaptcha::HCaptcha => Some(format!(
                "(() => {{ const inp = document.querySelector('[name=\"h-captcha-response\"]'); if (inp) inp.value = {}; }})()",
                serde_json::to_string(&token).unwrap_or_else(|_| "''".into())
            )),
            _ => None,
        };
        if let Some(js) = injection {
            // Law 10: the token IS the deliverable (returned in `solution`); we also
            // inject it into the page's response field as a convenience. Surface a
            // failed placement, a caller may rely on it being in the DOM, instead
            // of `let _ =` hiding it. Success stays true: the token was obtained.
            if let Err(e) = page.evaluate(js).await {
                tracing::warn!(
                    "third-party token obtained but injecting it into the page response field failed \
                     ({e}); the token is still returned in `solution` for manual placement"
                );
            }
        }

        let cookies = crate::cookies::capture_from_page(page)
            .await
            .unwrap_or_default();

        Ok(CaptchaSolveResult {
            solution: token,
            confidence: 1.0,
            method: SolveMethod::ThirdPartyService,
            time_ms: t0.elapsed().as_millis() as u64,
            success: true,
            screenshot: None,
            cookies,
            verified_outcome: None,
        })
    }
}