http_quik/
lib.rs

1//! # http-quik
2//!
3//! High-fidelity stealth transport engine for Chrome network identity parity.
4//!
5//! `http-quik` provides low-level control over the entire protocol stack — from
6//! TLS handshakes through HTTP/2 frame signaling — to make every outbound
7//! connection indistinguishable from a genuine Chrome browser. It is the
8//! transport layer of the [Phantom Engine](https://github.com/polymit/phantom-engine)
9//! and is designed for production agentic navigation at scale.
10//!
11//! ## The Problem
12//!
13//! Modern anti-bot systems (Cloudflare, Akamai, DataDome) perform passive
14//! fingerprinting at multiple protocol layers:
15//!
16//! 1. **TLS (JA3/JA4)** — cipher suite order, extension IDs, elliptic curves.
17//! 2. **HTTP/2 (Akamai)** — SETTINGS values, pseudo-header ordering, stream priority.
18//! 3. **Client Hints** — `sec-ch-ua-platform` cross-checked against the TLS handshake.
19//!
20//! Standard HTTP libraries (`reqwest`, `hyper`) fail these checks because they
21//! use generic TLS stacks and default H2 settings. `http-quik` solves this with
22//! a BoringSSL backend and forensic-level protocol replication.
23//!
24//! ## Core Features
25//!
26//! - **BoringSSL Integration** — Full ClientHello control including GREASE, ECH,
27//!   and extension permutation via raw FFI calls.
28//! - **Cross-Platform Profiles** — Pre-configured identities for Chrome 148 on
29//!   macOS, Windows, and Linux with OS-specific ALPS payloads and Client Hints.
30//! - **OS Auto-Detection** — [`Client::new()`] selects a profile matched to the
31//!   host kernel, eliminating p0f mismatch flags without configuration.
32//! - **Connection Pooling** — Managed H2 session reuse to maintain consistent
33//!   behavioral fingerprints across request chains.
34//! - **Stealth Redirects** — A redirect state machine that handles `sec-fetch-*`
35//!   headers and method rotation identical to Chromium.
36//! - **Rich Fetch Contexts** — Supports 11 distinct [`client::RequestContext`] variants
37//!   (e.g., `NoCorsImage`, `Worker`, `Iframe`) to ensure secondary resource requests
38//!   generate the exact matching `sec-fetch-*` and accept headers.
39//! - **Stateful Client Hints** — Features an automated `hint_cache` on the `Client` to statefully
40//!   track and respond to server `Accept-CH` platform hints on subsequent origin calls.
41//!
42//! ## Getting Started
43//!
44//! ```rust
45//! use http_quik::Client;
46//!
47//! #[tokio::main]
48//! async fn main() -> Result<(), http_quik::Error> {
49//!     // Auto-detects host OS and uses the matching Chrome 148 profile.
50//! #   let client = Client::builder().danger_accept_invalid_certs(true).build()?;
51//! #   if false {
52//!     let client = Client::new();
53//! #   }
54//!
55//!     let response = client.get("https://example.com").await?;
56//!     println!("Status: {}", response.status());
57//!
58//!     Ok(())
59//! }
60//! ```
61//!
62//! > [!NOTE]
63//! > For local development, testing, or proxying (e.g., mitmproxy), you can
64//! > use [`Client::builder()`] with `.danger_accept_invalid_certs(true)` to
65//! > bypass TLS verification.
66//!
67//!
68//! ## Safety & FFI
69//!
70//! This crate uses `boring` and `boring-sys` for low-level TLS control. All
71//! `unsafe` blocks are localized to the `tls` and `client::connector` modules
72//! and carry `// SAFETY:` annotations documenting the invariants they rely on.
73//!
74//! ## Changelog
75//!
76//! See [CHANGELOG.md](https://github.com/polymit/quik/blob/main/CHANGELOG.md)
77//! for versioned release notes.
78
79/// High-level client, connection pooling, and request execution.
80pub mod client;
81
82/// Crate-wide error types.
83pub mod error;
84
85/// Low-level HTTP/2 frame builder configuration.
86///
87/// Provides internal utilities for overriding the default H2 handshake
88/// to replicate Chromium's SETTINGS order, WINDOW_UPDATE values, and
89/// pseudo-header sequencing.
90pub(crate) mod http2;
91
92/// Chrome transport identity profiles.
93///
94/// Contains the data-only configuration schemas and pre-built profile
95/// constructors for each supported Chrome version and platform.
96pub mod profile;
97
98/// TLS connector construction and BoringSSL FFI bindings.
99///
100/// Handles bit-perfect replication of Chrome's TLS handshake, including
101/// post-quantum key shares (X25519MLKEM768), ALPS injection, and
102/// extension permutation.
103pub(crate) mod tls;
104
105pub use crate::client::{connect, Client, ClientBuilder, RequestContext, Response};
106pub use crate::error::{Error, Result};
107pub use crate::profile::chrome_148::AKAMAI_FINGERPRINT;
108pub use crate::profile::chrome_148::JA3_HASH;
109pub use crate::profile::{ChromeProfile, Platform};
http_quik/lib.rs

http_quik/
lib.rs
