captchaforge 0.2.39

//! Tier-A operational configuration loaded from `.captchaforge.toml`.
//!
//! Per the CLAUDE.md two-tier configurability rule, captchaforge has
//! two distinct config layers:
//!
//! - **Tier A, operational config (this module)**: timeouts,
//!   concurrency, cache TTL, VLM endpoint/model, third-party service
//!   selection. CLI flags + TOML defaults; CLI wins. Compiled
//!   defaults → `captchaforge.toml` → CLI flags.
//! - **Tier B, community knowledge (`detect::rules`)**: vendor
//!   detection rules, never CLI-flagged. Lives in TOML data files.
//!
//! This module owns Tier A. The shape mirrors the runtime types so
//! callers materialise a config once and apply it to chain / solver /
//! cache constructors.
//!
//! # Search path
//!
//! [`Config::discover`] looks in this order, returning the first hit:
//! 1. `$CAPTCHAFORGE_CONFIG` (explicit path; if unset is skipped)
//! 2. `./.captchaforge.toml` (project-local)
//! 3. `./captchaforge.toml`
//! 4. `$XDG_CONFIG_HOME/captchaforge/config.toml`
//!    (fallback `~/.config/captchaforge/config.toml`)
//!
//! Missing-file is NOT an error from `discover`: it returns
//! [`Config::default`]. Use [`Config::load_from_path`] when you want
//! the strict "must exist" behaviour.
//!
//! # Example file
//!
//! ```toml
//! # Per-solver timeout for the chain. Default 180_000.
//! per_solver_timeout_ms = 60000
//! # Whether to capture a screenshot on full chain failure. Default true.
//! screenshot_on_failure = true
//!
//! [cache]
//! # TTL in seconds for cached solved tokens. Default 60.
//! ttl_seconds = 90
//!
//! [vlm]
//! # Override Ollama endpoint. Beats the CAPTCHAFORGE_VLM_ENDPOINT env var.
//! endpoint = "http://gpu-host:11434"
//! model    = "qwen3-vl:30b"
//!
//! [third_party]
//! # Pick one: "two_captcha" | "cap_monster" | "cap_solver" | "custom"
//! service  = "two_captcha"
//! # Required when service = "custom".
//! base_url = "https://my-gateway.example/2captcha"
//! # API key (or leave blank and use CAPTCHAFORGE_THIRDPARTY_API_KEY env var).
//! api_key  = ""
//! poll_interval_ms = 5000
//! max_polls = 30
//!
//! [solve]
//! # All SolveConfig fields are overridable individually.
//! checkbox_max_attempts = 20
//! token_max_attempts    = 24
//! ```

use serde::{Deserialize, Serialize};
use std::path::{Path, PathBuf};

use std::sync::Arc;

use crate::provider::ProviderRegistry;
use crate::solver::{
    CaptchaSolverChain, ChainConfig, MultiStepCaptchaSolver, OcrCaptchaSolver, SolveConfig,
    ThirdPartyCaptchaSolver, ThirdPartyService, TokenCache, VlmCaptchaSolver,
};

const DEFAULT_CACHE_TTL_SECONDS: u64 = 60;

const ENV_CONFIG_PATH: &str = "CAPTCHAFORGE_CONFIG";

/// Top-level Tier-A config. All fields are optional; absent fields
/// fall back to compiled defaults.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct Config {
    pub per_solver_timeout_ms: Option<u64>,
    pub screenshot_on_failure: Option<bool>,
    /// Override `ChainConfig::verify_outcome`. Default `None` ⇒
    /// chain default (`true`). Set to `false` to skip the
    /// before/after page snapshot, useful for synthetic fixtures
    /// where a green-checkmark token is the only signal.
    pub verify_outcome: Option<bool>,
    pub cache: CacheConfig,
    pub vlm: VlmConfig,
    pub third_party: ThirdPartyConfig,
    pub solve: SolveOverrides,
}

#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct CacheConfig {
    pub ttl_seconds: Option<u64>,
}

#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct VlmConfig {
    pub endpoint: Option<String>,
    pub model: Option<String>,
}

#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct ThirdPartyConfig {
    /// One of `two_captcha`, `cap_monster`, `cap_solver`, `custom`.
    pub service: Option<String>,
    /// Required when `service = "custom"`. Ignored otherwise.
    pub base_url: Option<String>,
    /// API key. Leave None to fall back to the
    /// `CAPTCHAFORGE_THIRDPARTY_API_KEY` env var.
    pub api_key: Option<String>,
    pub poll_interval_ms: Option<u64>,
    pub max_polls: Option<u32>,
}

#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct SolveOverrides {
    pub checkbox_poll_interval_ms: Option<u64>,
    pub checkbox_max_attempts: Option<u32>,
    pub token_poll_interval_ms: Option<u64>,
    pub token_max_attempts: Option<u32>,
    pub audio_button_delay_ms: Option<u64>,
    pub audio_submit_delay_ms: Option<u64>,
    pub vlm_http_timeout_ms: Option<u64>,
    pub client_http_timeout_ms: Option<u64>,
}

impl Config {
    /// Walk the search path and return the first config found, or
    /// `Config::default()` if none exists. Errors only on a malformed
    /// TOML in a found file.
    pub fn discover() -> anyhow::Result<Self> {
        for path in Self::search_paths() {
            if path.is_file() {
                return Self::load_from_path(&path);
            }
        }
        Ok(Self::default())
    }

    /// The ordered candidate paths Self::discover walks. Public so
    /// CLIs can show users where the file is expected to live.
    pub fn search_paths() -> Vec<PathBuf> {
        Self::search_paths_with_env(|n| std::env::var(n).ok())
    }

    /// Like [`Self::search_paths`] but with an injectable env lookup
    /// so unit tests don't have to mutate process env.
    pub(crate) fn search_paths_with_env<F>(env: F) -> Vec<PathBuf>
    where
        F: Fn(&str) -> Option<String>,
    {
        let mut out = Vec::new();
        if let Some(p) = env(ENV_CONFIG_PATH).filter(|s| !s.is_empty()) {
            out.push(PathBuf::from(p));
        }
        out.push(PathBuf::from(".captchaforge.toml"));
        out.push(PathBuf::from("captchaforge.toml"));
        let xdg = env("XDG_CONFIG_HOME")
            .filter(|s| !s.is_empty())
            .map(PathBuf::from)
            .or_else(|| env("HOME").map(|h| PathBuf::from(h).join(".config")));
        if let Some(base) = xdg {
            out.push(base.join("captchaforge").join("config.toml"));
        }
        out
    }

    /// Read + parse a TOML file at `path`. Errors propagate so callers
    /// can distinguish "no config" from "bad config."
    ///
    /// Emits a `tracing::warn!` if the loaded file commits a
    /// third-party API key inline, those keys belong in
    /// `CAPTCHAFORGE_THIRDPARTY_API_KEY` (env var) or a secrets
    /// store, not in a file that gets committed alongside source.
    pub fn load_from_path(path: impl AsRef<Path>) -> anyhow::Result<Self> {
        let path = path.as_ref();
        let body = std::fs::read_to_string(path)
            .map_err(|e| anyhow::anyhow!("reading {}: {e}", path.display()))?;
        let cfg = Self::from_toml_str(&body)
            .map_err(|e| anyhow::anyhow!("parsing {}: {e}", path.display()))?;
        cfg.warn_on_inline_secrets(path);
        Ok(cfg)
    }

    /// Print a `tracing::warn!` for any plaintext secret present in a
    /// loaded config file. Called by [`Self::load_from_path`].
    /// Currently flags `[third_party] api_key`; kept as a separate
    /// method so future secrets gain warnings here without touching
    /// the load-path itself.
    pub fn warn_on_inline_secrets(&self, source: &Path) {
        if self
            .third_party
            .api_key
            .as_deref()
            .is_some_and(|k| !k.is_empty())
        {
            tracing::warn!(
                config = %source.display(),
                "captchaforge: third_party.api_key is set inline. \
                 prefer the CAPTCHAFORGE_THIRDPARTY_API_KEY env var \
                 (or a secrets store) so the key doesn't get committed \
                 to git alongside the config file"
            );
        }
    }

    /// Parse from a TOML string (no I/O (useful in tests)).
    pub fn from_toml_str(s: &str) -> Result<Self, toml::de::Error> {
        toml::from_str(s)
    }

    /// Materialise a [`ChainConfig`] from this config, defaulting any
    /// absent field.
    pub fn chain_config(&self) -> ChainConfig {
        let mut c = ChainConfig::default();
        if let Some(v) = self.per_solver_timeout_ms {
            c.per_solver_timeout_ms = v;
        }
        if let Some(v) = self.screenshot_on_failure {
            c.screenshot_on_failure = v;
        }
        if let Some(v) = self.verify_outcome {
            c.verify_outcome = v;
        }
        c
    }

    /// Materialise a [`SolveConfig`] from this config, defaulting any
    /// absent field.
    pub fn solve_config(&self) -> SolveConfig {
        let mut c = SolveConfig::default();
        let s = &self.solve;
        if let Some(v) = s.checkbox_poll_interval_ms {
            c.checkbox_poll_interval_ms = v;
        }
        if let Some(v) = s.checkbox_max_attempts {
            c.checkbox_max_attempts = v;
        }
        if let Some(v) = s.token_poll_interval_ms {
            c.token_poll_interval_ms = v;
        }
        if let Some(v) = s.token_max_attempts {
            c.token_max_attempts = v;
        }
        if let Some(v) = s.audio_button_delay_ms {
            c.audio_button_delay_ms = v;
        }
        if let Some(v) = s.audio_submit_delay_ms {
            c.audio_submit_delay_ms = v;
        }
        if let Some(v) = s.vlm_http_timeout_ms {
            c.vlm_http_timeout_ms = v;
        }
        if let Some(v) = s.client_http_timeout_ms {
            c.client_http_timeout_ms = v;
        }
        c
    }

    /// Build a [`TokenCache`] honouring the configured TTL (default 60s).
    pub fn build_token_cache(&self) -> TokenCache {
        let ttl = self.cache.ttl_seconds.unwrap_or(DEFAULT_CACHE_TTL_SECONDS);
        TokenCache::with_ttl(std::time::Duration::from_secs(ttl))
    }

    /// Build a [`VlmCaptchaSolver`] with TOML overrides applied. TOML
    /// values beat env vars (which beat defaults).
    pub fn build_vlm_solver(&self) -> VlmCaptchaSolver {
        let mut s = VlmCaptchaSolver::new();
        if let Some(ep) = &self.vlm.endpoint {
            s = s.with_endpoint(ep.clone());
        }
        if let Some(m) = &self.vlm.model {
            s = s.with_model(m.clone());
        }
        s.with_config(self.solve_config())
    }

    /// Build a [`ThirdPartyCaptchaSolver`] from the config. Returns
    /// `None` when the [`ThirdPartyConfig`] is fully empty (no
    /// service selected, no key, no overrides), a signal that the
    /// caller should leave third-party out of the chain entirely.
    pub fn build_third_party_solver(&self) -> Option<ThirdPartyCaptchaSolver> {
        let tp = &self.third_party;
        if tp.service.is_none()
            && tp.base_url.is_none()
            && tp.api_key.is_none()
            && tp.poll_interval_ms.is_none()
            && tp.max_polls.is_none()
        {
            return None;
        }

        let service = match tp.service.as_deref().unwrap_or("two_captcha") {
            "two_captcha" => ThirdPartyService::TwoCaptcha,
            "cap_monster" => ThirdPartyService::CapMonster,
            "cap_solver" => ThirdPartyService::CapSolver,
            // SSRF defence: only the literal `service = "custom"` plus
            // an explicit `base_url` accepts a freeform endpoint.
            // Previously any unrecognised service string was silently
            // mapped to `Custom { base_url: that_string }`, so a typo
            // ("twocaptcha" without underscore) or untrusted config
            // could redirect the captchaforge worker's HTTP traffic to
            // an arbitrary host, including 169.254.169.254 or other
            // internal-only addresses.
            "custom" => {
                let base_url = tp
                    .base_url
                    .as_deref()
                    .filter(|u| !u.is_empty())
                    .ok_or_else(|| {
                        anyhow::anyhow!(
                            "third_party.service = \"custom\" requires \
                         third_party.base_url to be set (got empty / missing)"
                        )
                    })
                    .ok()?;
                // Reject anything that doesn't parse as an http(s) URL
                // OR that points at a private/loopback/metadata host.
                // Previously only the scheme was checked, so a config
                // typo (or untrusted config file) could still route
                // POST traffic to 169.254.169.254 / 10.x / [::1].
                let parsed = url::Url::parse(base_url).ok()?;
                if !matches!(parsed.scheme(), "http" | "https") {
                    tracing::warn!(
                        scheme = %parsed.scheme(),
                        "rejecting custom third-party service: non-http(s) scheme"
                    );
                    return None;
                }
                if !host_is_safe_for_outbound(&parsed) {
                    tracing::warn!(
                        url = %parsed,
                        "rejecting custom third-party service: host failed SSRF policy \
                         (loopback / private / link-local / metadata)"
                    );
                    return None;
                }
                ThirdPartyService::Custom {
                    base_url: base_url.to_string(),
                }
            }
            other => {
                tracing::warn!(
                    service = %other,
                    "unrecognised third_party.service, refusing to fall back to \
                     freeform URL (SSRF protection). Set service = \"custom\" + \
                     base_url to use a non-built-in endpoint."
                );
                return None;
            }
        };
        let mut s = match service {
            ThirdPartyService::TwoCaptcha => ThirdPartyCaptchaSolver::two_captcha(),
            ThirdPartyService::CapMonster => ThirdPartyCaptchaSolver::cap_monster(),
            ThirdPartyService::CapSolver => ThirdPartyCaptchaSolver::cap_solver(),
            ThirdPartyService::Custom { base_url } => {
                ThirdPartyCaptchaSolver::custom_endpoint(base_url)
            }
        };
        if let Some(key) = tp.api_key.as_deref().filter(|k| !k.is_empty()) {
            s = s.with_api_key(key);
        }
        if let Some(v) = tp.poll_interval_ms {
            s = s.with_poll_interval_ms(v);
        }
        if let Some(v) = tp.max_polls {
            s = s.with_max_polls(v);
        }
        Some(s)
    }

    /// Build a fully-wired [`CaptchaSolverChain`] from this config:
    /// chain config + token cache + provider registry (with bundled
    /// rules) + Behavioral + VLM (configured) + Audio + third-party
    /// (only when the `[third_party]` section is non-empty OR the
    /// API key env var is set).
    ///
    /// Single entry point used by [`crate::auto_solve`] and the CLI's
    /// `solve` subcommand so they share the same chain shape.
    pub fn build_chain(&self) -> anyhow::Result<CaptchaSolverChain> {
        let registry = Arc::new(ProviderRegistry::with_built_in_rules()?);
        // Start from `default_chain` so all 17 production solvers
        // (Akamai/DataDome/PerimeterX/GeeTest/AwsWaf/Arkose/
        // TurnstileInteractive/VLM/RecaptchaAudio etc.) are wired in.
        // Previously `build_chain` open-coded an 11-solver subset,
        // so `auto_solve` / `solve_url` silently lacked dedicated
        // strategies for those vendors and fell through to the
        // generic behavioural solver, a 30%+ reduction in vendor
        // coverage versus the documented default chain.
        let mut chain = CaptchaSolverChain::default_chain()
            .with_config(self.chain_config())
            .with_provider_registry(registry)
            .with_token_cache(Arc::new(self.build_token_cache()));

        // Layer config-driven extensions on top of the base chain:
        //
        // 1. MultiStepCaptchaSolver, wizard / multi-screen captchas
        //    (math → grid → text). Not in the base chain because it's
        //    config-aware (depends on chain-config timeouts).
        chain.add_solver(MultiStepCaptchaSolver::new());

        // 2. OCR fallback. Solver is inert when tesseract isn't on
        //    PATH (`supports()` returns false), so adding it is free
        //    for users without tesseract installed.
        chain.add_solver(OcrCaptchaSolver::new());

        // 3. Override the default VLM solver with the config-driven
        //    one (endpoint + model from TOML). The base chain's VLM
        //    is at a known position; we just append the configured
        //    one, solver chain dispatch picks the first `supports()`
        //    so duplicates don't hurt, and the configured one is
        //    closer to the tail (lower priority by position) than
        //    the default. Acceptable trade-off; the config VLM gets
        //    its turn after the default fails.
        chain.add_solver(self.build_vlm_solver());

        // 4. Third-party, replace the default chain's
        //    two_captcha-with-no-key with the configured version
        //    (which honors api_key + service selection + endpoints).
        if let Some(tp) = self.build_third_party_solver() {
            chain.add_solver(tp);
        }
        // The base chain already includes a no-key ThirdPartyCaptchaSolver,
        // so we don't need to add another one when config is empty.

        Ok(chain)
    }
}

/// SSRF guard for outbound third-party endpoints. Returns true iff
/// the URL's host is safe for outbound HTTP, public IP / public
/// hostname, no loopback / RFC-1918 / link-local / metadata.
/// Mirrors `validate_endpoint_url` in `solver/third_party.rs` and
/// `validate_public_url` in the CLI.
fn host_is_safe_for_outbound(parsed: &url::Url) -> bool {
    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"
            )
        }
    }
}

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