captchaforge 0.2.26

//! TOML-driven captcha detector rules — community-extensible
//! detection without writing Rust.
//!
//! Most new captcha vendors are detectable from one or more of:
//!   * a CSS selector (`.aws-waf-token`, `[data-datadome]`)
//!   * a `<script src=...>` substring (`awswafcaptcha.com`)
//!   * a `window.<global>` value being defined
//!
//! [`RuleSet`] loads a TOML file describing one provider per
//! `[[provider]]` table. Each rule is converted into a synthetic
//! [`crate::captcha_detect::Detector`] that emits a small,
//! deterministic JS probe — never executes user-supplied JS — and
//! returns a [`DetectedCaptcha::Custom(name)`] match on hit.
//!
//! ## Schema
//!
//! ```toml
//! [[provider]]
//! name = "aws_waf"
//! priority = 12       # ordered with built-in detectors; lower = earlier
//!
//! [provider.triggers]
//! selectors            = [".aws-waf-token", "[data-aws-waf]"]
//! window_globals       = ["awsWafCaptcha"]
//! script_src_contains  = ["awswafcaptcha.com"]
//! ```
//!
//! Any single trigger matching means a positive detection — the rule
//! semantics are OR across categories, OR within each category. To
//! keep generated JS small + safe, EVERY trigger value is escaped
//! before substitution; raw JS payloads are NOT supported on purpose.
//!
//! Operators that need imperative detection logic (CDP probes, async
//! waits, behavioural fingerprints) implement [`Detector`] in Rust
//! the same way the built-in detectors do.
use anyhow::{Context, Result};
use async_trait::async_trait;
use chromiumoxide::Page;
use serde::Deserialize;

use super::{parse_detection_result, CaptchaInfo, DetectedCaptcha, Detector};
use crate::provider::CaptchaProvider;
use crate::solver::{CaptchaType, SolveMethod};

/// One row from a rules TOML file.
#[derive(Debug, Clone, Deserialize)]
pub struct ProviderRule {
    /// Stable identifier; surfaces in logs and as
    /// [`DetectedCaptcha::Custom(name)`] on hit.
    pub name: String,
    /// Priority for the detector registry — lower runs earlier.
    /// Choose a value that doesn't collide with built-in detectors
    /// (5, 10, 20, 30, 40, 50, 60, 65, 75, 85, 90 are taken).
    pub priority: i32,
    /// Solver methods, ordered by recommended preference. Surfaced
    /// to the chain via [`CaptchaProvider::recommended_solver_methods`]
    /// when the rule is registered through [`super::super::provider::
    /// ProviderRegistry::with_built_in_rules`]. Defaults to a
    /// behavioral-first chain when omitted.
    #[serde(default = "default_solver_methods")]
    pub solver_methods: Vec<SolveMethod>,
    /// Solver names (matched against `solver.name()`), ordered by
    /// recommended preference. When non-empty, the chain prefers
    /// this list over `solver_methods` — name-based routing is
    /// precise and avoids collisions when multiple solvers share a
    /// `SolveMethod`. Vendors with dedicated solvers
    /// (`SliderCaptchaSolver`, `CloudflareInterstitialSolver`, etc.)
    /// should use this field. Empty default keeps the legacy
    /// method-based path for back-compat.
    #[serde(default)]
    pub solver_names: Vec<String>,
    /// Triggers for the rule. ANY single trigger matching = detection.
    pub triggers: Triggers,
}

fn default_solver_methods() -> Vec<SolveMethod> {
    vec![
        SolveMethod::BehavioralBypass,
        SolveMethod::ThirdPartyService,
    ]
}

/// One rule's trigger predicates. All fields are optional; an empty
/// triggers block makes the rule a permanent no-match.
#[derive(Debug, Clone, Deserialize, Default)]
pub struct Triggers {
    /// CSS selectors to query against the live document. Any selector
    /// that finds at least one element fires the rule.
    #[serde(default)]
    pub selectors: Vec<String>,
    /// `window.<name>` values that must be defined (typeof != undefined).
    #[serde(default)]
    pub window_globals: Vec<String>,
    /// Substrings to look for in `<script src>` attributes.
    #[serde(default)]
    pub script_src_contains: Vec<String>,
    /// Case-insensitive substrings to match against `document.title`.
    /// Useful for "Checking your browser…" / "DDoS protection by ___"
    /// interstitials that don't ship a stable selector.
    #[serde(default)]
    pub title_contains: Vec<String>,
    /// Cookie names that, when present (regardless of value), indicate
    /// the vendor's challenge cycle is in progress. Lets us recognise
    /// in-flight challenges even when the visible DOM has settled
    /// (e.g. a passive cookie issued by Imperva, Reblaze, Kasada).
    #[serde(default)]
    pub cookie_names: Vec<String>,
}

/// Parsed rules file — a flat collection of [`ProviderRule`]s.
#[derive(Debug, Clone, Deserialize, Default)]
pub struct RuleSet {
    #[serde(default, rename = "provider")]
    pub providers: Vec<ProviderRule>,
}

/// The community-contributed rule pack bundled with the crate. Covers
/// DataDome, Akamai Bot Manager, PerimeterX/HUMAN, Arkose/FunCaptcha,
/// Geetest v3 + v4, AWS WAF Captcha, Friendly Captcha, MTCaptcha, and
/// WordPress math captchas.
///
/// Use [`built_in_rules`] to materialise the parsed [`RuleSet`] and
/// register its detectors:
///
/// ```rust
/// use captchaforge::detect::rules::built_in_rules;
///
/// let rules = built_in_rules().expect("bundled rules parse");
/// assert!(rules.providers.iter().any(|p| p.name == "datadome"));
/// ```
pub const BUILT_IN_RULES_TOML: &str = include_str!("../../rules/community.toml");

/// Parse the bundled community rule pack — see [`BUILT_IN_RULES_TOML`].
///
/// Always succeeds for a clean checkout; returns `Err` only if the
/// bundled TOML has been corrupted, which would also fail the
/// `rules::tests::built_in_rules_parse` regression.
pub fn built_in_rules() -> Result<RuleSet> {
    RuleSet::parse(BUILT_IN_RULES_TOML)
}

impl RuleSet {
    /// Parse a rules TOML string. Use [`Self::load_from_path`] when
    /// reading from disk.
    pub fn parse(input: &str) -> Result<Self> {
        toml::from_str(input).context("parsing TOML rules")
    }

    /// Load a rules file from disk.
    pub fn load_from_path(path: impl AsRef<std::path::Path>) -> Result<Self> {
        let text = std::fs::read_to_string(path.as_ref())
            .with_context(|| format!("reading {}", path.as_ref().display()))?;
        Self::parse(&text)
    }

    /// Build [`Detector`]s for every rule. Returned in insertion order;
    /// the [`crate::captcha_detect::DetectorRegistry`] sorts them by
    /// priority when added.
    pub fn into_detectors(self) -> Vec<Box<dyn Detector>> {
        self.providers
            .into_iter()
            .map(|r| Box::new(RuleDetector::from(r)) as Box<dyn Detector>)
            .collect()
    }
}

/// Runtime detector built from a [`ProviderRule`]. Owns the rule + a
/// pre-computed `&'static`-style JS probe so per-detect calls are
/// allocation-free in the hot path.
pub struct RuleDetector {
    rule: ProviderRule,
    js: String,
    // We need a 'static name for the Detector trait, so we leak the
    // rule name on construction. Rules live for the program's
    // lifetime, so this is correct (and matches the source_scan
    // pattern in wptrace).
    leaked_name: &'static str,
    /// `Box::leak`-ed copy of the rule's solver_methods so we can
    /// satisfy [`CaptchaProvider::recommended_solver_methods`]'s
    /// `&'static [SolveMethod]` return type without allocating per
    /// call. Lives for the program's lifetime, same rationale as
    /// `leaked_name`.
    leaked_methods: &'static [SolveMethod],
    /// `Box::leak`-ed copy of the rule's solver_names so we can
    /// satisfy [`CaptchaProvider::recommended_solver_names`]'s
    /// `&'static [&'static str]` return type. Each name string is
    /// also leaked individually.
    leaked_names: &'static [&'static str],
}

impl From<ProviderRule> for RuleDetector {
    fn from(rule: ProviderRule) -> Self {
        let js = build_probe_js(&rule);
        let leaked_name: &'static str = Box::leak(rule.name.clone().into_boxed_str());
        let leaked_methods: &'static [SolveMethod] =
            Box::leak(rule.solver_methods.clone().into_boxed_slice());
        // Two-stage leak for &'static [&'static str]: leak each
        // string, collect the &'static refs, then leak the slice.
        let name_refs: Vec<&'static str> = rule
            .solver_names
            .iter()
            .map(|n| -> &'static str { Box::leak(n.clone().into_boxed_str()) })
            .collect();
        let leaked_names: &'static [&'static str] = Box::leak(name_refs.into_boxed_slice());
        Self {
            rule,
            js,
            leaked_name,
            leaked_methods,
            leaked_names,
        }
    }
}

impl RuleDetector {
    /// Borrow the underlying rule (for diagnostics / tests).
    pub fn rule(&self) -> &ProviderRule {
        &self.rule
    }
    /// Borrow the generated JS probe.
    pub fn js(&self) -> &str {
        &self.js
    }
}

#[async_trait]
impl Detector for RuleDetector {
    fn name(&self) -> &'static str {
        self.leaked_name
    }
    fn priority(&self) -> i32 {
        self.rule.priority
    }
    async fn detect(&self, page: &Page) -> Result<Option<CaptchaInfo>> {
        let raw = page.evaluate(self.js.as_str()).await?;
        let val = raw.into_value::<serde_json::Value>()?;
        // parse_detection_result lands the JS-side `kind: "custom:<name>"`
        // string into DetectedCaptcha::Custom, so the returned info.kind
        // is already correct — pass through.
        Ok(parse_detection_result(val))
    }
}

impl CaptchaProvider for RuleDetector {
    fn name(&self) -> &'static str {
        <Self as Detector>::name(self)
    }
    fn detected_kind(&self) -> DetectedCaptcha {
        DetectedCaptcha::Custom(self.rule.name.clone())
    }
    fn captcha_type(&self) -> CaptchaType {
        CaptchaType::Custom(self.rule.name.clone())
    }
    fn recommended_solver_methods(&self) -> &'static [SolveMethod] {
        self.leaked_methods
    }
    fn recommended_solver_names(&self) -> &'static [&'static str] {
        self.leaked_names
    }
    fn detector(&self) -> &dyn Detector {
        self
    }
}

/// Generate a small, escaped JS IIFE that probes every trigger of the
/// rule. The payload is deterministic: same rule → same string.
///
/// Every interpolated value is JSON-escaped (`json_str`) so a hostile
/// rule can't break out of the string context — the rules layer is a
/// data layer, never a code-execution surface.
fn build_probe_js(rule: &ProviderRule) -> String {
    let kind_str = json_str(&format!("custom:{}", rule.name));
    let container_str = json_str("(rule-derived)");

    let mut body = String::from("(function(){");

    // Selectors: one querySelector per entry.
    for sel in &rule.triggers.selectors {
        let sel_lit = json_str(sel);
        body.push_str(&format!(
            "if(document.querySelector({sel_lit})){{return {{kind:{kind_str},site_key:null,container:{container_str}}};}}",
        ));
    }

    // Window globals: typeof check so we don't trigger ReferenceError.
    for global in &rule.triggers.window_globals {
        let g_lit = json_str(global);
        body.push_str(&format!(
            "if(typeof window[{g_lit}]!=='undefined'){{return {{kind:{kind_str},site_key:null,container:{container_str}}};}}",
        ));
    }

    // Script src substrings: scan all script[src] for substring match.
    if !rule.triggers.script_src_contains.is_empty() {
        body.push_str("var __cfg_scripts=document.querySelectorAll('script[src]');");
        body.push_str("for(var __i=0;__i<__cfg_scripts.length;__i++){var __src=__cfg_scripts[__i].getAttribute('src')||'';");
        for sub in &rule.triggers.script_src_contains {
            let s_lit = json_str(sub);
            body.push_str(&format!(
                "if(__src.indexOf({s_lit})>=0){{return {{kind:{kind_str},site_key:null,container:{container_str}}};}}",
            ));
        }
        body.push('}');
    }

    // document.title substring matches — case-insensitive. Useful for
    // interstitial pages whose only stable signal is the title bar.
    if !rule.triggers.title_contains.is_empty() {
        body.push_str("var __cfg_title=(document.title||'').toLowerCase();");
        for sub in &rule.triggers.title_contains {
            let s_lit = json_str(&sub.to_lowercase());
            body.push_str(&format!(
                "if(__cfg_title.indexOf({s_lit})>=0){{return {{kind:{kind_str},site_key:null,container:{container_str}}};}}",
            ));
        }
    }

    // Cookie-name presence: split document.cookie on `;`, trim, match
    // against each named cookie. Doesn't read the value — presence is
    // the signal.
    if !rule.triggers.cookie_names.is_empty() {
        body.push_str("var __cfg_cookies=(document.cookie||'').split(';').map(function(c){return c.trim().split('=')[0]||'';});");
        for cookie in &rule.triggers.cookie_names {
            let c_lit = json_str(cookie);
            body.push_str(&format!(
                "if(__cfg_cookies.indexOf({c_lit})>=0){{return {{kind:{kind_str},site_key:null,container:{container_str}}};}}",
            ));
        }
    }

    body.push_str("return {kind:'none',site_key:null,container:null};})()");
    body
}

/// JSON-quote an arbitrary string so it's safe to embed in a JS
/// expression. Uses `serde_json::to_string` rather than hand-rolling
/// escapes — there is no scenario where a serialised string fails.
fn json_str(s: &str) -> String {
    serde_json::to_string(s).expect("serde_json never fails on &str")
}

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

    #[test]
    fn parses_minimal_rule() {
        let toml = r#"
            [[provider]]
            name = "aws_waf"
            priority = 12

            [provider.triggers]
            selectors = [".aws-waf-token"]
        "#;
        let set = RuleSet::parse(toml).unwrap();
        assert_eq!(set.providers.len(), 1);
        assert_eq!(set.providers[0].name, "aws_waf");
        assert_eq!(set.providers[0].priority, 12);
        assert_eq!(set.providers[0].triggers.selectors, vec![".aws-waf-token"]);
    }

    #[test]
    fn parses_title_and_cookie_triggers() {
        let toml = r#"
            [[provider]]
            name = "ddos_screen"
            priority = 50

            [provider.triggers]
            title_contains = ["DDoS protection", "Checking your browser"]
            cookie_names = ["__cf_bm", "_dd_jwt"]
        "#;
        let set = RuleSet::parse(toml).unwrap();
        assert_eq!(set.providers[0].triggers.title_contains.len(), 2);
        assert_eq!(set.providers[0].triggers.cookie_names.len(), 2);
        let det: RuleDetector = set.providers[0].clone().into();
        let js = det.js();
        // The probe must reference both kinds of triggers.
        assert!(js.contains("document.title"), "title trigger missing from JS: {js}");
        assert!(js.contains("document.cookie"), "cookie trigger missing from JS: {js}");
        // Title is lowercased before substring-matching, so the
        // generated literal must be lowercase.
        assert!(js.contains("ddos protection"));
    }

    #[test]
    fn parses_multiple_rules() {
        let toml = r#"
            [[provider]]
            name = "aws_waf"
            priority = 12
            [provider.triggers]
            selectors = [".aws-waf-token"]
            window_globals = ["awsWafCaptcha"]

            [[provider]]
            name = "datadome"
            priority = 13
            [provider.triggers]
            selectors = ["[data-datadome]"]
            script_src_contains = ["js.datadome.co"]
        "#;
        let set = RuleSet::parse(toml).unwrap();
        assert_eq!(set.providers.len(), 2);
        assert_eq!(set.providers[1].name, "datadome");
    }

    #[test]
    fn empty_rules_block_yields_no_providers() {
        let set = RuleSet::parse("").unwrap();
        assert!(set.providers.is_empty());
    }

    #[test]
    fn missing_required_field_is_an_error() {
        // No `name` → must fail. (priority is required too.)
        let toml = r#"
            [[provider]]
            priority = 10
            [provider.triggers]
        "#;
        assert!(RuleSet::parse(toml).is_err());
    }

    #[test]
    fn build_probe_js_escapes_selector_with_quotes() {
        let rule = ProviderRule {
            name: "evil".into(),
            priority: 99,
            solver_methods: default_solver_methods(),
            solver_names: Vec::new(),
            triggers: Triggers {
                selectors: vec!["[data-x=\"a\"]".into()],
                window_globals: vec![],
                script_src_contains: vec![],
                title_contains: vec![],
                cookie_names: vec![],
            },
        };
        let js = build_probe_js(&rule);
        // Embedded quote must NOT appear unescaped in the produced JS.
        // serde_json escapes `"` as `\"` inside the JSON string literal.
        assert!(
            js.contains("\\\""),
            "expected an escaped quote in generated JS; got: {js}"
        );
    }

    #[test]
    fn build_probe_js_handles_all_three_trigger_types() {
        let rule = ProviderRule {
            name: "aws_waf".into(),
            priority: 12,
            solver_methods: default_solver_methods(),
            solver_names: Vec::new(),
            triggers: Triggers {
                selectors: vec![".aws-waf-token".into()],
                window_globals: vec!["awsWafCaptcha".into()],
                script_src_contains: vec!["awswafcaptcha.com".into()],
                title_contains: vec![],
                cookie_names: vec![],
            },
        };
        let js = build_probe_js(&rule);
        assert!(js.contains("querySelector(\".aws-waf-token\")"));
        assert!(js.contains("typeof window[\"awsWafCaptcha\"]"));
        assert!(js.contains("document.querySelectorAll('script[src]')"));
        assert!(js.contains("\"awswafcaptcha.com\""));
        assert!(js.contains("\"custom:aws_waf\""));
    }

    #[test]
    fn rule_detector_round_trips_name_and_priority() {
        let rule = ProviderRule {
            name: "datadome".into(),
            priority: 13,
            solver_methods: default_solver_methods(),
            solver_names: Vec::new(),
            triggers: Triggers::default(),
        };
        let det = RuleDetector::from(rule);
        // RuleDetector implements both Detector and CaptchaProvider —
        // both define `name(&self)`, so disambiguate at the call site.
        assert_eq!(<RuleDetector as Detector>::name(&det), "datadome");
        assert_eq!(det.priority(), 13);
    }

    #[test]
    fn built_in_rules_parse_and_cover_expected_vendors() {
        let set = built_in_rules().expect("bundled community.toml parses");
        let names: Vec<&str> = set.providers.iter().map(|p| p.name.as_str()).collect();
        // Anchor: every vendor we ship coverage for. Removing one of
        // these without an explicit decision should fail the test so
        // the regression is loud.
        for expected in [
            "datadome",
            "akamai_bot_manager",
            "perimeterx_human",
            "arkose_funcaptcha",
            "geetest_v3",
            "geetest_v4",
            "aws_waf_captcha",
            "friendly_captcha",
            "mtcaptcha",
            "wp_math_captcha",
        ] {
            assert!(
                names.contains(&expected),
                "bundled community.toml is missing rule: {expected}",
            );
        }
    }

    #[test]
    fn built_in_rules_priorities_dont_collide_with_each_other() {
        let set = built_in_rules().unwrap();
        let mut prios: Vec<i32> = set.providers.iter().map(|p| p.priority).collect();
        prios.sort_unstable();
        let mut deduped = prios.clone();
        deduped.dedup();
        assert_eq!(prios, deduped, "priorities must be unique within the pack");
    }

    #[test]
    fn built_in_rules_become_detectors_with_valid_js_probes() {
        let set = built_in_rules().unwrap();
        assert!(set.providers.len() >= 10);
        // Build each detector directly so we can inspect the
        // generated JS (the `Box<dyn Detector>` returned by
        // `into_detectors` erases the concrete RuleDetector type).
        for rule in set.providers {
            let det = RuleDetector::from(rule);
            let js = det.js();
            let name = <RuleDetector as Detector>::name(&det);
            assert!(js.starts_with("(function()"), "{name}: bad prefix");
            assert!(js.ends_with("})()"), "{name}: bad suffix");
            assert!(js.contains("custom:"), "{name}: missing custom-kind tag");
        }
    }

    #[test]
    fn into_detectors_keeps_insertion_order() {
        let toml = r#"
            [[provider]]
            name = "a"
            priority = 100
            [provider.triggers]
            selectors = [".a"]

            [[provider]]
            name = "b"
            priority = 5
            [provider.triggers]
            selectors = [".b"]
        "#;
        let dets = RuleSet::parse(toml).unwrap().into_detectors();
        assert_eq!(dets.len(), 2);
        assert_eq!(dets[0].name(), "a");
        assert_eq!(dets[1].name(), "b");
    }
}