captchaforge 0.2.28

//! 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
//!   (CDP 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 chromiumoxide::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,
    /// `true` if any captcha widget selector was found in the DOM
    /// at snapshot time.
    pub captcha_present: 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
    /// (CDP 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: false,
            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 CDP. Trivially testable. The CDP-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;
    }

    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;
    }

    if after.captcha_present {
        return OutcomeClassification::Recycled;
    }

    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
    }
}

/// Capture the live page state via CDP.
///
/// 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 is conservative: it checks the same
/// selector families [`crate::detect::detect`] checks, but only as a
/// boolean fast-path. We deliberately don't re-run full detection
/// here — that would double the per-solve cost and we only need
/// "is something captcha-shaped on the page right now".
pub async fn take_snapshot(page: &Page) -> PageSnapshot {
    let url = page.url().await.ok().flatten().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 = page
        .evaluate(
            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);
            })()"#,
        )
        .await
        .ok()
        .and_then(|v| v.into_value::<bool>().ok())
        .unwrap_or(false);

    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: captcha,
            cookie_names: cookies.iter().map(|s| (*s).to_string()).collect(),
        }
    }

    #[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 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_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);
    }
}