captchaforge 0.2.39

//! reCAPTCHA v2 (audio-challenge fallback solver).
//!
//! When the v2 checkbox click is rejected (low-trust IP, headless
//! signal residue, mouse pattern flagged), Google falls back to a
//! visual image-grid challenge inside the `api2/bframe` iframe. The
//! grid carries a small accessibility shortcut: an audio button that
//! switches the same challenge to a single-clip speech-to-text task.
//!
//! The audio path is DRAMATICALLY easier than vision for a bot:
//!
//! - No multi-tile click loop, no "select more squares" reprompt.
//! - One MP3 download, one STT call, one text submission.
//! - The audio clips are unaltered English numbers / words; modern
//!   STT (Whisper-tiny on CPU, Whisper-large on GPU) hits ~98%
//!   transcription accuracy on the corpus.
//!
//! Why this lives in `vendors/` and not the generic
//! [`super::super::AudioCaptchaSolver`]:
//!
//! 1. The whole audio widget is inside a cross-origin iframe (the
//!    `api2/bframe`). The generic solver calls `page.find_element`
//!    which only sees the main document, so it would always miss
//!    the controls in production.
//! 2. reCAPTCHA throttles the audio path aggressively. After ~3
//!    same-IP attempts in a short window, the audio button serves a
//!    "Try again later" interstitial with no audio src. Detecting
//!    that surface deterministically (rather than waiting on a
//!    timeout) is vendor-specific.
//! 3. The verify button has both a "submit answer" and a "reload"
//!    role depending on widget state; a generic solver doesn't know
//!    when to retry vs give up.
//!
//! # Strategy
//!
//! 1. Walk the bframe via [`crate::frame`] helpers, the shared
//!    cross-origin iframe-evaluation layer used by the Turnstile,
//!    behavioural and other solvers.
//! 2. Click `#recaptcha-audio-button` with mouse-on-iframe geometry
//!    and realistic timing. If the button isn't found, the bframe
//!    isn't open yet (someone needs to click the v2 checkbox first
//!, that's the BehavioralCaptchaSolver's job, this one runs
//!    after) and we yield with failure.
//! 3. Wait for `audio` element `src` to populate. Detect the
//!    "Try again later" rate-limit interstitial and yield without
//!    burning more attempts at it.
//! 4. Download the MP3 with the page's User-Agent + cookies replayed,
//!    so Google's edge sees a session-coherent request rather than
//!    a bare reqwest fetch.
//! 5. POST audio to the STT endpoint. Default points at a local
//!    Whisper-compatible API but is reconfigurable per-instance.
//! 6. Clean the transcript (lowercase, collapse whitespace, strip
//!    leading/trailing punctuation that STT loves to add).
//! 7. Type the transcript into `#audio-response` with the realistic
//!    keystroke cadence helper, bots that paste with `set value`
//!    are caught by reCAPTCHA's input-event timing model.
//! 8. Click `#recaptcha-verify-button`. Poll
//!    `g-recaptcha-response` across all frames; if it populates we
//!    succeed; if a fresh audio clip appears (multi-clip retry),
//!    loop with a short ceiling.
//!
//! Failure modes returned without retrying:
//!
//! - Bframe absent → [`SolveMethod::AudioBypass`] failure with empty
//!   solution. Lets BehavioralCaptchaSolver have a turn.
//! - Rate-limit interstitial → solution literal `"recaptcha:rate_limited"`
//!   in the failure result so callers can surface it.
//! - STT endpoint unreachable / empty transcript → failure; chain
//!   may try VLM next.

use rand::{rngs::StdRng, Rng, SeedableRng};
use tracing::{debug, info, warn};

use super::super::*;

/// Selector matching the v2 challenge bframe (the iframe containing
/// the image-grid OR audio widget after the user has clicked the v2
/// checkbox). Stable since v2 GA in 2014; google.com/recaptcha/api2
/// is the canonical host.
pub const RECAPTCHA_BFRAME_SELECTOR: &str = r#"iframe[src*="google.com/recaptcha/api2/bframe"]"#;

/// In-bframe selector for the "play audio challenge" button.
pub const AUDIO_BUTTON_SELECTOR: &str = "#recaptcha-audio-button";

/// In-bframe selector for the audio element holding the MP3 src after
/// the audio button is clicked.
pub const AUDIO_ELEMENT_SELECTOR: &str = "#audio-source, audio";

/// In-bframe selector for the typed-answer input.
pub const RESPONSE_INPUT_SELECTOR: &str = "#audio-response";

/// In-bframe selector for the submit-answer button.
pub const VERIFY_BUTTON_SELECTOR: &str = "#recaptcha-verify-button";

/// Hidden token field reCAPTCHA populates on success, lives in the
/// PARENT page, not the bframe.
pub const TOKEN_INPUT_NAME: &str = "g-recaptcha-response";

/// Maximum number of audio-clip retries within a single solve call.
/// Google occasionally serves "submit answer to additional audio"
/// follow-ups; retrying twice covers the legitimate cases without
/// burning IP reputation on a hard-throttled session.
pub const MAX_AUDIO_RETRIES: usize = 2;

/// Phrases that appear in the bframe body when reCAPTCHA decides the
/// session is exhausted. Matched case-insensitively as substrings.
pub const RATE_LIMIT_PHRASES: &[&str] = &[
    "Your computer or network may be sending automated queries",
    "Try again later",
    "we have detected unusual traffic",
];

/// Solver for reCAPTCHA v2 via the audio-fallback path.
pub struct RecaptchaAudioSolver {
    client: reqwest::Client,
    /// Single-endpoint speech-to-text URL. Used when
    /// [`Self::stt_pipeline`] is `None`. Defaults to a local
    /// Whisper-compatible HTTP server.
    pub stt_endpoint: String,
    /// Multi-endpoint STT ladder. When set, takes precedence over
    /// [`Self::stt_endpoint`], the solver tries each endpoint in order
    /// until one returns a non-empty transcript. Lets a deployment
    /// configure local Whisper → OpenAI Whisper → 2captcha audio as
    /// a fault-tolerant chain rather than a single point of failure.
    pub stt_pipeline: Option<crate::stt::SttPipeline>,
    pub config: SolveConfig,
}

impl Default for RecaptchaAudioSolver {
    fn default() -> Self {
        Self::new()
    }
}

impl RecaptchaAudioSolver {
    pub fn new() -> Self {
        let config = SolveConfig::default();
        Self {
            client: recaptcha_audio_client(Duration::from_millis(config.client_http_timeout_ms)),
            stt_endpoint: "http://localhost:9000/asr".to_string(),
            stt_pipeline: None,
            config,
        }
    }

    pub fn with_stt_endpoint(mut self, url: impl Into<String>) -> Self {
        self.stt_endpoint = url.into();
        self
    }

    /// Install an STT fallback ladder. The ladder takes precedence
    /// over the single-endpoint URL when both are set.
    pub fn with_stt_pipeline(mut self, pipeline: crate::stt::SttPipeline) -> Self {
        self.stt_pipeline = Some(pipeline);
        self
    }

    pub fn with_config(mut self, config: SolveConfig) -> Self {
        self.config = config;
        self
    }

    /// Locate a control inside ANY frame (the helper handles iframe
    /// origin walks). Returns `None` after polling for
    /// `checkbox_max_attempts`.
    async fn poll_for_control(&self, page: &Page, selector: &str) -> Option<(f64, f64)> {
        for _ in 0..self.config.checkbox_max_attempts {
            if let Ok(Some(c)) = crate::frame::find_element_centre_in_frames(page, selector).await {
                return Some(c);
            }
            tokio::time::sleep(Duration::from_millis(self.config.checkbox_poll_interval_ms)).await;
        }
        None
    }

    /// Poll bframe text for a known rate-limit phrase. Returns `true`
    /// on the first match. Cheap (one BiDi eval per attempt).
    async fn rate_limited(&self, page: &Page) -> bool {
        let js = r#"(() => document.body ? document.body.innerText || '' : '')()"#;
        let texts: Vec<String> = crate::frame::evaluate_in_all_frames(page, js)
            .await
            .unwrap_or_default();
        texts.iter().any(|t| is_rate_limited(t))
    }

    /// Pull the audio src from any frame. Returns `None` until the
    /// element is present AND its `src` is non-empty.
    async fn poll_for_audio_src(&self, page: &Page) -> Option<String> {
        let js = format!(
            r#"(() => {{
                const el = document.querySelector({sel});
                if (!el) return null;
                const s = el.getAttribute('src') || '';
                return s.length > 0 ? s : null;
            }})()"#,
            sel = serde_json::to_string(AUDIO_ELEMENT_SELECTOR).unwrap(),
        );
        for _ in 0..self.config.token_max_attempts {
            tokio::time::sleep(Duration::from_millis(self.config.token_poll_interval_ms)).await;
            let urls: Vec<String> = crate::frame::evaluate_in_all_frames(page, &js)
                .await
                .unwrap_or_default();
            if let Some(u) = urls.into_iter().find(|s| looks_like_audio_url(s)) {
                return Some(u);
            }
        }
        None
    }
}

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

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

    fn supports(&self, kind: &crate::captcha_detect::DetectedCaptcha) -> bool {
        use crate::captcha_detect::DetectedCaptcha;
        matches!(
            kind,
            DetectedCaptcha::RecaptchaV2 | DetectedCaptcha::AudioCaptcha
        )
    }

    async fn solve(
        &self,
        page: &Page,
        _info: &crate::captcha_detect::CaptchaInfo,
    ) -> Result<CaptchaSolveResult> {
        let t0 = Instant::now();
        let mut rng = StdRng::from_entropy();

        // Step 0 (token may already be there (passive auto-pass)).
        if crate::frame::verify_token_in_frames(page, TOKEN_INPUT_NAME)
            .await
            .unwrap_or(false)
        {
            info!("reCAPTCHA token already populated, no audio path needed");
            return Ok(CaptchaSolveResult {
                solution: "recaptcha:passive".into(),
                confidence: 0.95,
                method: SolveMethod::AutoPass,
                time_ms: t0.elapsed().as_millis() as u64,
                success: true,
                screenshot: None,
                cookies: crate::cookies::capture_from_page(page)
                    .await
                    .unwrap_or_default(),
                verified_outcome: None,
            });
        }

        // Step 1 (click the audio button).
        let (ax, ay) = match self.poll_for_control(page, AUDIO_BUTTON_SELECTOR).await {
            Some(c) => c,
            None => {
                debug!("audio button not found, bframe not open / wrong vendor");
                return Ok(CaptchaSolveResult::failure(
                    SolveMethod::AudioBypass,
                    t0.elapsed().as_millis() as u64,
                ));
            }
        };
        let approach_x = ax + rng.gen_range(-120.0..120.0);
        let approach_y = ay + rng.gen_range(-60.0..60.0);
        crate::behavior::mouse_move_human(page, approach_x, approach_y, ax, ay).await?;
        crate::behavior::click_realistic(page, ax, ay).await?;
        tokio::time::sleep(Duration::from_millis(self.config.audio_button_delay_ms)).await;

        // Step 2, audio retry loop. reCAPTCHA sometimes asks for a
        // second clip after a correct first answer; we loop a small
        // bounded number of times.
        for attempt in 0..MAX_AUDIO_RETRIES {
            // Rate-limit short-circuit before paying for STT.
            if self.rate_limited(page).await {
                warn!(attempt, "reCAPTCHA audio path is rate-limited, yielding");
                return Ok(CaptchaSolveResult {
                    solution: "recaptcha:rate_limited".into(),
                    confidence: 0.0,
                    method: SolveMethod::AudioBypass,
                    time_ms: t0.elapsed().as_millis() as u64,
                    success: false,
                    screenshot: super::super::screenshot_b64(page).await.ok(),
                    cookies: Vec::new(),
                    verified_outcome: None,
                });
            }

            let audio_src = match self.poll_for_audio_src(page).await {
                Some(u) => u,
                None => {
                    debug!(attempt, "no audio src after click");
                    return Ok(CaptchaSolveResult::failure(
                        SolveMethod::AudioBypass,
                        t0.elapsed().as_millis() as u64,
                    ));
                }
            };

            // Step 3, fetch the MP3 with the same browser-shaped
            // request surface and URL-scoped cookie state the page
            // would expose to an audio element.
            let audio_url = match reqwest::Url::parse(&audio_src) {
                Ok(url) => url,
                Err(e) => {
                    warn!(attempt, error = %e, "audio src is not a valid URL");
                    return Ok(CaptchaSolveResult::failure(
                        SolveMethod::AudioBypass,
                        t0.elapsed().as_millis() as u64,
                    ));
                }
            };
            let mut audio_request = self.client.get(audio_url.clone());
            match crate::cookies::capture_from_page(page).await {
                Ok(cookies) => {
                    if let Some(cookie_header) = recaptcha_audio_cookie_header(&cookies, &audio_url)
                    {
                        audio_request =
                            audio_request.header(reqwest::header::COOKIE, cookie_header);
                    }
                }
                Err(e) => warn!(
                    attempt,
                    error = %e,
                    "could not capture page cookies for reCAPTCHA audio download"
                ),
            }
            let bytes = match audio_request.send().await {
                Ok(r) if r.status().is_success() => r.bytes().await.ok(),
                Ok(r) => {
                    warn!(status = r.status().as_u16(), "audio download non-2xx");
                    None
                }
                Err(e) => {
                    warn!(error = %e, "audio download failed");
                    None
                }
            };
            let Some(bytes) = bytes else {
                return Ok(CaptchaSolveResult::failure(
                    SolveMethod::AudioBypass,
                    t0.elapsed().as_millis() as u64,
                ));
            };

            // Step 4: STT. Pipeline takes precedence over the
            // single-endpoint URL when configured.
            let transcript_raw = if let Some(pipeline) = &self.stt_pipeline {
                match pipeline.transcribe(bytes.to_vec()).await {
                    Ok(t) => t,
                    Err(e) => {
                        warn!(attempt, error = %e, "STT pipeline exhausted");
                        String::new()
                    }
                }
            } else {
                let stt = self
                    .client
                    .post(&self.stt_endpoint)
                    .header("Content-Type", "audio/mpeg")
                    .body(bytes)
                    .send()
                    .await;
                match stt {
                    Ok(r) if r.status().is_success() => r.text().await.unwrap_or_default(),
                    _ => String::new(),
                }
            };
            let transcript = clean_transcript(&transcript_raw);
            if transcript.is_empty() {
                warn!(attempt, "STT returned empty transcript");
                return Ok(CaptchaSolveResult::failure(
                    SolveMethod::AudioBypass,
                    t0.elapsed().as_millis() as u64,
                ));
            }
            debug!(attempt, len = transcript.len(), "got STT transcript");

            // Step 5 (type the answer).
            let (rx, ry) = match self.poll_for_control(page, RESPONSE_INPUT_SELECTOR).await {
                Some(c) => c,
                None => {
                    return Ok(CaptchaSolveResult::failure(
                        SolveMethod::AudioBypass,
                        t0.elapsed().as_millis() as u64,
                    ));
                }
            };
            crate::behavior::mouse_move_human(page, ax, ay, rx, ry).await?;
            crate::behavior::click_realistic(page, rx, ry).await?;
            crate::behavior::type_human(page, &transcript).await?;
            tokio::time::sleep(Duration::from_millis(self.config.audio_submit_delay_ms)).await;

            // Step 6 (submit).
            let (vx, vy) = match self.poll_for_control(page, VERIFY_BUTTON_SELECTOR).await {
                Some(c) => c,
                None => {
                    return Ok(CaptchaSolveResult::failure(
                        SolveMethod::AudioBypass,
                        t0.elapsed().as_millis() as u64,
                    ));
                }
            };
            crate::behavior::mouse_move_human(page, rx, ry, vx, vy).await?;
            crate::behavior::click_realistic(page, vx, vy).await?;

            // Step 7 (poll for the parent-page token).
            for _ in 0..self.config.token_max_attempts {
                tokio::time::sleep(Duration::from_millis(self.config.token_poll_interval_ms)).await;
                if crate::frame::verify_token_in_frames(page, TOKEN_INPUT_NAME)
                    .await
                    .unwrap_or(false)
                {
                    info!(attempt, "g-recaptcha-response populated");
                    return Ok(CaptchaSolveResult {
                        solution: transcript,
                        confidence: 0.9,
                        method: SolveMethod::AudioBypass,
                        time_ms: t0.elapsed().as_millis() as u64,
                        success: true,
                        screenshot: None,
                        cookies: crate::cookies::capture_from_page(page)
                            .await
                            .unwrap_or_default(),
                        verified_outcome: None,
                    });
                }
            }

            // No token yet. If reCAPTCHA queued a follow-up clip the
            // audio src will rotate; the next loop iteration will pick
            // it up. If the answer was rejected outright, the bframe
            // re-renders the same widget (same loop handles both).
            debug!(attempt, "no token after submit, retrying");
        }

        Ok(CaptchaSolveResult::failure(
            SolveMethod::AudioBypass,
            t0.elapsed().as_millis() as u64,
        ))
    }
}

#[path = "recaptcha_audio/http.rs"]
mod http;
use http::{recaptcha_audio_client, recaptcha_audio_cookie_header};

#[path = "recaptcha_audio/text.rs"]
mod text;
pub use text::{clean_transcript, is_rate_limited, looks_like_audio_url};

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