captchaforge 0.2.39

//! Outcome-verification oracle.
//!
//! A solver returning `success: true` is a *claim*, not a *proof*.
//! Vendor scripts can populate the response field while still gating
//! the actual form submit; sliders can complete the visual animation
//! while the WAF rejects the cookie; PoW workers can return a hash
//! that the server then refuses. This module proves the page actually
//! advanced past the challenge by snapshotting state before the solve
//! and after, then classifying the drift.
//!
//! The contract is intentionally narrow: we don't trust solver output,
//! we trust *observed page state transitions*. A "success" verdict
//! requires the captcha element to be gone OR the URL/title to have
//! advanced OR a session cookie to have been set.
//!
//! # Outcomes
//!
//! - [`OutcomeClassification::Advanced`], captcha is gone AND
//!   (URL changed OR title changed OR a new session cookie appeared).
//!   The page is past the challenge.
//! - [`OutcomeClassification::Recycled`], captcha element still
//!   present, possibly re-rendered. The vendor handed us another
//!   challenge. Solver should retry, not declare victory.
//! - [`OutcomeClassification::HardBlock`], title or body now
//!   contains a known block phrase (`Access denied`, `Sorry, you have
//!   been blocked`, `Request blocked`, `Pardon Our Interruption`).
//!   Retrying is futile until fingerprint changes.
//! - [`OutcomeClassification::SilentFail`], captcha gone, but
//!   nothing else moved (URL/title/cookies identical, no block
//!   marker). Vendor likely shadow-banned or returned 200-with-empty.
//! - [`OutcomeClassification::Unknown`], page state unobservable
//!   （BiDi error, page navigated to opaque doc). Caller decides.
//!
//! # Examples
//!
//! Classify a clean advance, captcha gone, URL changed:
//!
//! ```
//! use captchaforge::solver::oracle::{PageSnapshot, OutcomeClassification, classify};
//!
//! let before = PageSnapshot {
//!     url: "https://target.example/login".into(),
//!     title: "Verify you are human".into(),
//!     body_excerpt: "Please complete the security check".into(),
//!     captcha_present: true,
//!     cookie_names: vec!["__cf_bm".into()],
//! };
//! let after = PageSnapshot {
//!     url: "https://target.example/dashboard".into(),
//!     title: "Dashboard".into(),
//!     body_excerpt: "Welcome back".into(),
//!     captcha_present: false,
//!     cookie_names: vec!["__cf_bm".into(), "session".into()],
//! };
//! assert_eq!(classify(&before, &after), OutcomeClassification::Advanced);
//! ```
//!
//! Classify a recycled challenge, captcha element still rendered:
//!
//! ```
//! use captchaforge::solver::oracle::{PageSnapshot, OutcomeClassification, classify};
//!
//! let before = PageSnapshot {
//!     url: "https://target.example/login".into(),
//!     title: "Verify you are human".into(),
//!     body_excerpt: "Solve the challenge".into(),
//!     captcha_present: true,
//!     cookie_names: vec![],
//! };
//! let after = PageSnapshot {
//!     url: "https://target.example/login".into(),
//!     title: "Verify you are human".into(),
//!     body_excerpt: "Solve the challenge".into(),
//!     captcha_present: true,
//!     cookie_names: vec![],
//! };
//! assert_eq!(classify(&before, &after), OutcomeClassification::Recycled);
//! ```
//!
//! Classify a hard block, body now carries a block marker:
//!
//! ```
//! use captchaforge::solver::oracle::{PageSnapshot, OutcomeClassification, classify};
//!
//! let before = PageSnapshot {
//!     url: "https://target.example/login".into(),
//!     title: "Verify you are human".into(),
//!     body_excerpt: "complete the security check".into(),
//!     captcha_present: true,
//!     cookie_names: vec![],
//! };
//! let after = PageSnapshot {
//!     url: "https://target.example/login".into(),
//!     title: "Access Denied".into(),
//!     body_excerpt: "Sorry, you have been blocked".into(),
//!     captcha_present: false,
//!     cookie_names: vec![],
//! };
//! assert_eq!(classify(&before, &after), OutcomeClassification::HardBlock);
//! ```

use crate::Page;
use serde::{Deserialize, Serialize};

/// State of the page captured at one moment in time.
///
/// Cheap to take (single eval + cookie read), cheap to compare
/// (string/Vec equality). Body excerpt is bounded so a 50MB SPA
/// doesn't blow up the snapshot.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct PageSnapshot {
    pub url: String,
    pub title: String,
    /// First 4KB of `document.body.innerText`, lowercased and
    /// whitespace-collapsed. Long enough to catch block phrases,
    /// short enough not to balloon the result.
    pub body_excerpt: String,
    /// Whether a captcha widget selector was found in the DOM at snapshot time.
    ///
    /// Tri-state on purpose (Law 10): `Some(true)` = a widget was confirmed
    /// present, `Some(false)` = confirmed absent, **`None` = the presence probe
    /// could not be evaluated** (BiDi hiccup, eval error, non-bool result). The
    /// prior `bool` collapsed a failed probe to `false`, so a still-present
    /// captcha whose probe hiccuped looked "gone" and [`classify`] upgraded it to
    /// `Advanced`: a fabricated success. `None` now forces `Unknown` instead of
    /// ever claiming the captcha cleared.
    pub captcha_present: Option<bool>,
    /// Names of cookies on the page at snapshot time. Values
    /// deliberately excluded, we only care about *which* session
    /// cookies exist, not their contents (security + size).
    pub cookie_names: Vec<String>,
}

impl PageSnapshot {
    /// Empty snapshot, useful when the caller can't capture state
    /// （BiDi closed, page navigated). Classification of `(empty, x)`
    /// always returns `Unknown`.
    pub fn empty() -> Self {
        Self {
            url: String::new(),
            title: String::new(),
            body_excerpt: String::new(),
            captcha_present: None,
            cookie_names: Vec::new(),
        }
    }
}

/// What the page state transition tells us about the solve.
///
/// Matches the documented set in this module's docs. `#[non_exhaustive]`
/// so we can add categories (e.g. `RateLimited`, `OriginError`) without
/// breaking downstream `match`es.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum OutcomeClassification {
    Advanced,
    Recycled,
    HardBlock,
    SilentFail,
    Unknown,
}

/// Phrases that indicate a hard block in the post-solve page.
///
/// Lowercased and substring-matched against `body_excerpt` and `title`.
/// Curated from observed Cloudflare / Akamai / Imperva / AWS WAF /
/// PerimeterX / DataDome / Kasada block pages. Adding entries here
/// improves precision; mis-classifying a benign page as a block only
/// downgrades a successful solve to `HardBlock`, which is annoying
/// but not silent (caller will see and can override).
pub const BLOCK_PHRASES: &[&str] = &[
    "access denied",
    "sorry, you have been blocked",
    "request blocked",
    "pardon our interruption",
    "your request has been blocked",
    "this request has been blocked",
    "you have been rate limited",
    "rate limit exceeded",
    "the owner of this website",
    "blocked by",
    "security policy",
    "permission denied",
    "forbidden",
    "request unsuccessful",
    "you don't have permission",
    "automated access",
    "bot detected",
    "suspicious activity",
];

/// Classify the transition from `before` to `after`.
///
/// Pure function, no IO, no BiDi. Trivially testable. The BiDi-bound
/// counterpart is [`take_snapshot`] which produces the inputs.
///
/// Decision order matters:
///   1. Empty before/after → Unknown.
///   2. Block markers in `after.title` or `after.body_excerpt` → HardBlock.
///   3. Captcha still present → Recycled.
///   4. Captcha gone + (URL changed OR title changed OR new cookie) → Advanced.
///   5. Captcha gone + nothing moved → SilentFail.
pub fn classify(before: &PageSnapshot, after: &PageSnapshot) -> OutcomeClassification {
    if after.url.is_empty() && after.title.is_empty() && after.body_excerpt.is_empty() {
        return OutcomeClassification::Unknown;
    }
    // Symmetric defence: an empty `before` snapshot (BiDi hiccup,
    // skipped pre-solve snapshot, failure to evaluate any of
    // url/title/body) is just as unrecoverable as an empty `after`.
    // Without it, `url_changed` / `title_changed` below compare
    // populated post-state against an empty baseline and report
    // `Advanced` for every solver attempt, letting decoy / silent-
    // fail outcomes through as success.
    if before.url.is_empty() && before.title.is_empty() && before.body_excerpt.is_empty() {
        return OutcomeClassification::Unknown;
    }

    let title_lower = after.title.to_lowercase();
    if BLOCK_PHRASES
        .iter()
        .any(|p| title_lower.contains(p) || after.body_excerpt.contains(p))
    {
        return OutcomeClassification::HardBlock;
    }

    match after.captcha_present {
        // Captcha still on the page → the solve recycled the challenge, not solved.
        Some(true) => return OutcomeClassification::Recycled,
        // Law 10: the presence probe could not be evaluated. We CANNOT confirm the
        // captcha cleared, so we must not let the url/title/cookie check below
        // upgrade this to `Advanced`: a still-present captcha whose probe hiccuped
        // would otherwise read as a fabricated success. Report `Unknown`.
        None => return OutcomeClassification::Unknown,
        // Confirmed absent → fall through to the movement check.
        Some(false) => {}
    }

    let url_changed = before.url != after.url;
    let title_changed = before.title != after.title;
    let new_cookies = after
        .cookie_names
        .iter()
        .any(|c| !before.cookie_names.contains(c));

    if url_changed || title_changed || new_cookies {
        OutcomeClassification::Advanced
    } else {
        OutcomeClassification::SilentFail
    }
}

/// JS that returns `true` iff the *current document* contains a
/// captcha-shaped element. Same selector families [`crate::detect::detect`]
/// checks, boolean fast-path only. Run in EVERY frame's realm by
/// [`captcha_present_across_frames`], modern captchas (Turnstile, hCaptcha,
/// reCAPTCHA) render their widget inside a cross-origin, often nested,
/// iframe the top document cannot `querySelector` into.
const CAPTCHA_PRESENCE_JS: &str = r#"(() => {
    const sel = [
        'iframe[src*="challenges.cloudflare.com"]',
        'iframe[src*="recaptcha"]',
        'iframe[src*="hcaptcha"]',
        'iframe[src*="arkoselabs"]',
        'iframe[src*="datadome"]',
        'iframe[src*="geetest"]',
        'iframe[src*="perimeterx"]',
        'iframe[src*="kasada"]',
        'iframe[src*="incapsula"]',
        '.cf-turnstile',
        '.h-captcha',
        '.g-recaptcha',
        '#challenge-form',
        '#challenge-stage',
        '#cf-please-wait',
        '#px-captcha',
        '[id^="captcha"]',
        '[class*="captcha" i]',
        '[class*="challenge" i]'
    ];
    return sel.some(s => document.querySelector(s) !== null);
})()"#;

/// Determine captcha presence across the WHOLE frame tree, soundly.
///
/// The old probe ran [`CAPTCHA_PRESENCE_JS`] in the top document only. But a
/// reCAPTCHA challenge lives in `api2/bframe` nested inside the cross-origin
/// `api2/anchor`; an hCaptcha challenge nests likewise. A widget still present
/// in such a frame is invisible to a top-document `querySelector`, so the old
/// probe reported "gone" and [`classify`] upgraded the transition to a
/// fabricated `Advanced`. We now walk every browsing context via
/// [`Page::frame_tree`] (which recovers the real cross-origin nesting over
/// BiDi `getTree`) and evaluate the probe in each frame's own realm.
///
/// Tri-state (Law 10), conservative toward "not gone":
/// - `Some(true)` the instant any frame confirms a widget (short-circuits).
/// - `Some(false)` only when *every* frame confirms absence.
/// - `None` when the frame tree can't be read, or any frame's probe failed 
///   a frame we couldn't read might be hiding a present widget, so we must not
///   claim the captcha cleared. `None` forces [`classify`] to `Unknown` rather
///   than ever fabricating a solve.
async fn captcha_present_across_frames(page: &Page) -> Option<bool> {
    // Tree unreadable → we cannot enumerate frames → Unknown (never "absent").
    let frames = page.frame_tree().await.ok()?;

    let mut probed_any = false;
    let mut saw_failure = false;
    for node in &frames {
        probed_any = true;
        match page
            .evaluate_in_context(CAPTCHA_PRESENCE_JS, &node.id)
            .await
        {
            Ok(v) => match v.into_value::<bool>() {
                Ok(true) => return Some(true), // confirmed present, done
                Ok(false) => {}                // confirmed absent in this frame
                Err(_) => saw_failure = true,  // non-bool result, inconclusive
            },
            Err(_) => saw_failure = true, // eval failed (raced/closed), inconclusive
        }
    }

    if !probed_any {
        // `getTree` returned no contexts at all (it always includes at least the
        // active document, so this is defensive). Probe the active context
        // directly rather than claim absence on zero evidence.
        return page
            .evaluate(CAPTCHA_PRESENCE_JS)
            .await
            .ok()
            .and_then(|v| v.into_value::<bool>().ok());
    }

    // Every frame answered: absent everywhere, unless a probe failed (in which
    // case a present widget could be hiding behind the failure → Unknown).
    if saw_failure {
        None
    } else {
        Some(false)
    }
}

/// Capture the live page state via BiDi.
///
/// Best-effort, any single read failure (URL, title, body, cookies)
/// degrades that field rather than aborting, since a partial snapshot
/// still classifies more usefully than `Unknown`.
///
/// The captcha-presence probe checks the same selector families
/// [`crate::detect::detect`] checks (boolean fast-path only, we don't re-run
/// full detection), but across EVERY frame via
/// [`captcha_present_across_frames`], because modern captchas render inside
/// cross-origin / nested iframes the top document cannot see.
pub async fn take_snapshot(page: &Page) -> PageSnapshot {
    let url = page.url().await.unwrap_or_default();

    let title = page
        .evaluate("document.title || ''")
        .await
        .ok()
        .and_then(|v| v.into_value::<String>().ok())
        .unwrap_or_default();

    let body_excerpt = page
        .evaluate(
            r#"(() => {
                const t = (document.body && document.body.innerText) || '';
                return t.slice(0, 4096).toLowerCase().replace(/\s+/g, ' ').trim();
            })()"#,
        )
        .await
        .ok()
        .and_then(|v| v.into_value::<String>().ok())
        .unwrap_or_default();

    let captcha_present = captcha_present_across_frames(page).await;

    let cookie_names = page
        .get_cookies()
        .await
        .ok()
        .map(|cs| cs.into_iter().map(|c| c.name).collect())
        .unwrap_or_default();

    PageSnapshot {
        url,
        title,
        body_excerpt,
        captcha_present,
        cookie_names,
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn snap(url: &str, title: &str, body: &str, captcha: bool, cookies: &[&str]) -> PageSnapshot {
        PageSnapshot {
            url: url.into(),
            title: title.into(),
            body_excerpt: body.into(),
            captcha_present: Some(captcha),
            cookie_names: cookies.iter().map(|s| (*s).to_string()).collect(),
        }
    }

    /// Build a snapshot whose captcha-presence probe could not be evaluated.
    fn snap_unprobed(url: &str, title: &str, body: &str, cookies: &[&str]) -> PageSnapshot {
        PageSnapshot {
            captcha_present: None,
            ..snap(url, title, body, false, cookies)
        }
    }

    #[test]
    fn classify_advanced_url_change() {
        let before = snap("/login", "Verify", "check", true, &[]);
        let after = snap("/dashboard", "Verify", "welcome", false, &[]);
        assert_eq!(classify(&before, &after), OutcomeClassification::Advanced);
    }

    #[test]
    fn unconfirmed_captcha_presence_never_overclaims_advanced() {
        // The URL moved AND a new session cookie appeared, the exact signals that
        // classify `Advanced`: but the captcha-presence probe could not be
        // evaluated (`None`). We must NOT claim the captcha cleared: a still-present
        // captcha whose probe hiccuped would be a fabricated success. Law 10 /
        // Screwdriver, never overclaim a solve. Regression fence for the prior
        // `captcha_present: bool` that collapsed a failed probe to `false`.
        let before = snap("/login", "Verify", "check", true, &[]);
        let after = snap_unprobed("/dashboard", "Welcome", "welcome", &["session"]);
        assert_eq!(classify(&before, &after), OutcomeClassification::Unknown);
    }

    #[test]
    fn confirmed_captcha_absence_still_advances_on_movement() {
        // The positive twin: when the probe CONFIRMS the captcha is gone
        // (`Some(false)`) and the page moved, the verdict is still `Advanced`: the
        // overclaim fix must not suppress genuine successes.
        let before = snap("/login", "Verify", "check", true, &[]);
        let after = snap("/dashboard", "Welcome", "welcome", false, &["session"]);
        assert_eq!(classify(&before, &after), OutcomeClassification::Advanced);
    }

    #[test]
    fn classify_advanced_new_session_cookie() {
        let before = snap("/x", "T", "b", true, &["__cf_bm"]);
        let after = snap("/x", "T", "b", false, &["__cf_bm", "session"]);
        assert_eq!(classify(&before, &after), OutcomeClassification::Advanced);
    }

    #[test]
    fn classify_advanced_title_change() {
        let before = snap("/x", "Verify you are human", "challenge", true, &[]);
        let after = snap("/x", "Welcome", "home", false, &[]);
        assert_eq!(classify(&before, &after), OutcomeClassification::Advanced);
    }

    #[test]
    fn classify_recycled_captcha_still_present() {
        let before = snap("/x", "T", "b", true, &[]);
        let after = snap("/x", "T", "b", true, &[]);
        assert_eq!(classify(&before, &after), OutcomeClassification::Recycled);
    }

    #[test]
    fn classify_hard_block_body_marker() {
        let before = snap("/x", "Verify", "check", true, &[]);
        let after = snap("/x", "Blocked", "sorry, you have been blocked", false, &[]);
        assert_eq!(classify(&before, &after), OutcomeClassification::HardBlock);
    }

    #[test]
    fn classify_hard_block_title_marker() {
        let before = snap("/x", "Verify", "check", true, &[]);
        let after = snap("/x", "Access Denied", "we apologize", false, &[]);
        assert_eq!(classify(&before, &after), OutcomeClassification::HardBlock);
    }

    #[test]
    fn classify_hard_block_beats_advanced() {
        // Block markers are checked BEFORE captcha-present; a page
        // that took us to /blocked with no captcha widget still gets
        // HardBlock, never Advanced.
        let before = snap("/login", "Verify", "check", true, &[]);
        let after = snap(
            "/blocked",
            "Request blocked",
            "your request has been blocked",
            false,
            &["session"],
        );
        assert_eq!(classify(&before, &after), OutcomeClassification::HardBlock);
    }

    #[test]
    fn classify_silent_fail_no_movement() {
        let before = snap("/x", "T", "b", true, &["a"]);
        let after = snap("/x", "T", "b", false, &["a"]);
        assert_eq!(classify(&before, &after), OutcomeClassification::SilentFail);
    }

    #[test]
    fn classify_unknown_for_empty_after() {
        let before = snap("/x", "T", "b", true, &[]);
        let after = PageSnapshot::empty();
        assert_eq!(classify(&before, &after), OutcomeClassification::Unknown);
    }

    #[test]
    fn classify_unknown_for_empty_before() {
        // Symmetric defence: a failed pre-solve baseline (BiDi hiccup,
        // skipped snapshot) must NOT report Advanced just because the
        // post-state happens to have populated url/title/body. Empty
        // before → Unknown so the chain doesn't accept the solve.
        let before = PageSnapshot::empty();
        let after = snap("/y", "Real Title", "real page body", false, &["sessionid"]);
        assert_eq!(classify(&before, &after), OutcomeClassification::Unknown);
    }

    #[test]
    fn classify_does_not_trigger_block_on_phrase_in_before() {
        // A block phrase already present in `before` doesn't poison
        // classification (only `after` is consulted for blocks).
        // The after-state also has a new session cookie so the
        // (no-block + captcha-gone + cookie-changed) path lands on
        // Advanced rather than SilentFail.
        let before = snap("/x", "T", "access denied previously", true, &[]);
        let after = snap("/x", "T", "all clear now", false, &["session"]);
        assert_eq!(classify(&before, &after), OutcomeClassification::Advanced);
    }

    #[test]
    fn classify_advanced_when_old_cookies_subset_of_new() {
        let before = snap("/x", "T", "b", true, &["__cf_bm", "datr"]);
        let after = snap("/x", "T", "b", false, &["__cf_bm", "datr", "sessionid"]);
        assert_eq!(classify(&before, &after), OutcomeClassification::Advanced);
    }

    #[test]
    fn empty_snapshot_constructor_yields_unknown_classification() {
        let before = PageSnapshot::empty();
        let after = PageSnapshot::empty();
        assert_eq!(classify(&before, &after), OutcomeClassification::Unknown);
    }
}