Request-Based Turnstile Solving in Pure Rust: Deconstructing `cfsolve`
`cfsolve` is an open-source Rust library and command-line utility designed to solve Cloudflare Turnstile widgets and challenge pages without deploying headless browser engines. By combining protocol reverse-engineering with recorded static browser fingerprint profiles, the project bypasses headless automation overhead to yield Turnstile tokens and clearance cookies directly over native transport stacks.
Protocol-Level Challenge Resolution
Traditional anti-bot evasion relies heavily on headless browser automation via Chromium or WebKit drivers. `cfsolve` removes this execution overhead by implementing a request-based engine that directly negotiates Cloudflare's challenge workflows. The library outputs either a valid Turnstile token for embedded widgets or a `cf_clearance` cookie for full challenge pages.
To evaluate challenge vectors, `cfsolve` impersonates real user-agents through profile definitions, such as an included Safari on iOS configuration (`profiles/safari-26-ios.json`). These JSON profiles encapsulate recorded responses to Cloudflare browser telemetry checks. Generating new profiles requires routing browser traffic through a dedicated `capture-proxy` binary to log and decode incoming and outgoing telemetry payloads. Currently, the project explicitly supports Safari and Chromium profile structures.
Build Requirements and Vendored Transport Stack
Compiling `cfsolve` requires a tightly controlled build environment due to its low-level cryptography and transport dependencies. The project relies on custom modifications to low-level networking crates, requiring callers to explicitly declare Cargo `[patch.crates-io]` entries for three vendored sub-crates: `btls-sys`, `wreq`, and `http2`.
- A pinned Rust toolchain version enforced via `rust-toolchain.toml`
- CMake and a native C/C++ compiler suite
- `libclang` to generate FFI bindings
- Git, utilized during the build phase to fetch and patch BoringSSL within `btls-sys`
Programmatic API and Concurrency Model
The library targets asynchronous Rust applications built on the Tokio runtime. An initialized `Browser` struct acts as the primary thread-safe handle. Applications are intended to instantiate a single `Browser` instance and share it across tasks; concurrent operations auto-allocate isolated network connections and cookie jars without cross-task state pollution.
- `PageSource::Navigate`: Performs an automated HTTP fetch of the target URL to extract challenge metadata.
- `PageSource::Blank`: Skips page ingestion entirely, rendering the widget against a target sitekey, optional `action`, and `cData` parameters.
- `PageSource::Html`: Accepts pre-fetched DOM string data alongside optional response `Referrer-Policy` headers, bypassing the need to pass session cookies when solving widgets located behind authentication walls.
For endpoints where the protection type is ambiguous, `cfsolve` exposes a unified `browser.solve()` method returning an `Outcome` enum matching either `Outcome::Token(String)` or `Outcome::Cleared(Clearance)`.
Transport Constraints and Failure Modes
Because Cloudflare validates challenge solutions against network layer characteristics, any generated `cf_clearance` cookie must be transmitted downstream from the exact IP address and User-Agent string specified by the browser profile. `cfsolve` provides native egress proxy support across all programmatic and CLI operations, accepting `http://`, `https://`, `socks5://`, and `socks5h://` protocols with inline authentication parameters.
- `Error::Network`: Standard socket or protocol-level failure; safe to retry immediately.
- `Error::Rejected`: Cloudflare evaluated the telemetry solution and actively rejected it; safe to retry.
- `Error::Blocked`: The target origin rendered an explicit error page instead of a challenge sequence; fatal state.
- `Error::Challenged`: A token request returned a full challenge page; recoverable by routing through `browser.clear()`.
- `Error::NotChallenged`: A explicit clear operation was initiated against an unprotected page.
The repository, created by developer `chris124567`, has reached 539 stars and 85 forks on GitHub. The author notes that the codebase is currently undergoing updates to account for recent upstream breaking changes deployed to Cloudflare's challenge JavaScript.