ClientX

A modern, high-performance Rust HTTP client library that combines enterprise-grade security with advanced browser fingerprint spoofing capabilities.

Features

• 🔒 Enterprise Security

  • Encrypted DNS (DoH/DoQ) by default
  • Certificate Transparency validation
  • OCSP stapling and CRL checking
  • TLS 1.3 with secure cipher suites

• 🎭 Browser Fingerprint Spoofing

  • JA3 and JA4 TLS fingerprinting
  • HTTP/2 frame characteristic control
  • QUIC/HTTP/3 transport parameters
  • Pre-configured browser presets (Chrome, Firefox, Safari, Edge)

• 🚀 Modern HTTP Client

  • Synchronous and asynchronous APIs
  • Connection pooling and keep-alive
  • Automatic retry with exponential backoff
  • Cookie persistence
  • Redirect handling
  • Proxy support (HTTP, SOCKS5)

• 🌐 Protocol Support

  • HTTP/1.1, HTTP/2, HTTP/3
  • WebSocket (RFC 6455)
  • Server-Sent Events (SSE)
  • Streaming requests and responses

Installation

Add ClientX to your Cargo.toml:

[dependencies]
clientx = "0.1.0"

For async support, ensure you have a Tokio runtime:

[dependencies]
clientx = "0.1.0"
tokio = { version = "1", features = ["full"] }

Quick Start

Basic GET Request

use clientx::{Client, FingerprintPreset};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a client with Chrome 130 fingerprint
    let client = Client::builder()
        .fingerprint_preset(FingerprintPreset::Chrome130)
        .build()?;

    // Make a GET request
    let response = client.get("https://httpbin.org/get").send()?;
    
    println!("Status: {}", response.status());
    println!("Body: {}", response.text()?);

    Ok(())
}

POST Request with JSON

use clientx::{Client, FingerprintPreset};
use serde::{Deserialize, Serialize};

#[derive(Serialize)]
struct User {
    name: String,
    email: String,
}

#[derive(Deserialize)]
struct ApiResponse {
    json: User,
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::builder()
        .fingerprint_preset(FingerprintPreset::Firefox132)
        .build()?;

    let user = User {
        name: "Alice".to_string(),
        email: "[email protected]".to_string(),
    };

    let response = client
        .post("https://httpbin.org/post")
        .json(&user)?
        .send()?;

    let api_response: ApiResponse = response.json()?;
    println!("Response: {:?}", api_response.json);

    Ok(())
}

Async Client

use clientx::{AsyncClient, FingerprintPreset};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = AsyncClient::builder()
        .fingerprint_preset(FingerprintPreset::Chrome130)
        .build()
        .await?;

    let response = client
        .get("https://httpbin.org/get")
        .send()
        .await?;

    println!("Status: {}", response.status());

    Ok(())
}

Browser Fingerprint Presets

ClientX includes pre-configured fingerprints for popular browsers, verified against tls.peet.ws:

use clientx::FingerprintPreset;

// Chrome versions 124-130
FingerprintPreset::Chrome130

// Firefox 132+
FingerprintPreset::Firefox132

// Safari 18+
FingerprintPreset::Safari18

// Microsoft Edge
FingerprintPreset::Edge

// Mobile browsers
FingerprintPreset::IOSSafari
FingerprintPreset::AndroidChrome

Custom Fingerprints

For advanced use cases, create custom fingerprints with full control:

use clientx::{
    Client, FingerprintConfig, TlsVersion, CipherSuite,
    ExtensionType, NamedGroup, SignatureScheme,
};

let fingerprint = FingerprintConfig {
    tls_version_min: TlsVersion::Tls12,
    tls_version_max: TlsVersion::Tls13,
    cipher_suites: vec![
        CipherSuite::TLS_AES_128_GCM_SHA256,
        CipherSuite::TLS_AES_256_GCM_SHA384,
    ],
    extension_order: vec![
        ExtensionType::ServerName,
        ExtensionType::SupportedGroups,
        ExtensionType::SignatureAlgorithms,
    ],
    // ... more configuration
    ..Default::default()
};

let client = Client::builder()
    .fingerprint_custom(fingerprint)
    .build()?;

Security Features

Encrypted DNS

ClientX uses encrypted DNS (DoH/DoQ) by default:

use clientx::{Client, SecurityConfig, DnsMode};

let security = SecurityConfig {
    dns_mode: DnsMode::EncryptedOnly,
    doh_servers: vec![
        "https://cloudflare-dns.com/dns-query".to_string(),
        "https://dns.google/dns-query".to_string(),
    ],
    dnssec_validation: true,
    ..Default::default()
};

let client = Client::builder()
    .security(security)
    .build()?;

Certificate Validation

Full certificate validation with OCSP, Certificate Transparency, and SCT:

let security = SecurityConfig {
    ocsp_stapling: true,
    certificate_transparency: true,
    sct_validation: true,
    crl_fallback: true,
    ..Default::default()
};

Security Debugging

Inspect security configuration and certificate chains:

let security_info = client.security_debug();
println!("DNS Mode: {:?}", security_info.dns_encryption.mode);
println!("Certificate Chain: {:#?}", security_info.certificate_chain);

Advanced Features

WebSocket Support

use clientx::{Client, Message};
use std::time::Duration;

let client = Client::builder().build()?;

let mut ws = client
    .websocket("wss://echo.websocket.org")
    .heartbeat(Duration::from_secs(30))
    .connect()?;

ws.send(Message::Text("Hello!".to_string()))?;
let message = ws.recv()?;
ws.close()?;

Server-Sent Events (SSE)

let client = Client::builder().build()?;

let mut events = client
    .sse("https://example.com/events")
    .reconnect_delay(Duration::from_secs(5))
    .connect()?;

while let Some(event) = events.next()? {
    println!("Event: {}", event.data);
}

Proxy Support

use clientx::ProxyConfig;

// HTTP proxy
let proxy = ProxyConfig::http("http://proxy.example.com:8080")?;

// HTTP proxy with authentication
let proxy = ProxyConfig::http_with_auth(
    "http://proxy.example.com:8080",
    "username",
    "password",
)?;

// SOCKS5 proxy
let proxy = ProxyConfig::socks5("socks5://proxy.example.com:1080")?;

let client = Client::builder()
    .proxy(proxy)
    .build()?;

Cookie Persistence

use std::sync::Arc;
use clientx::CookieStore;

let cookie_store = Arc::new(CookieStore::new());

let client = Client::builder()
    .cookie_store(cookie_store)
    .build()?;

// Cookies are automatically stored and sent

Redirect Handling

use clientx::RedirectPolicy;

// Follow up to 10 redirects (default)
let client = Client::builder()
    .redirect_policy(RedirectPolicy::Limited(10))
    .build()?;

// Don't follow redirects
let client = Client::builder()
    .redirect_policy(RedirectPolicy::None)
    .build()?;

Timeouts and Retries

use std::time::Duration;

let client = Client::builder()
    .timeout(Duration::from_secs(30))
    .build()?;

Fingerprint Debugging

Inspect TLS and HTTP fingerprints:

if let Some(debug_info) = client.fingerprint_debug() {
    println!("JA3 Hash: {}", debug_info.ja3_hash);
    println!("JA4 String: {}", debug_info.ja4_string);
    println!("JA4_r: {}", debug_info.ja4_r);
    println!("JA4H: {}", debug_info.ja4h);
    println!("HTTP/2 Settings: {:#?}", debug_info.h2_fingerprint);
}

Examples

The examples/ directory contains comprehensive examples:

• basic_get.rs - Simple GET request
• post_json.rs - POST with JSON body
• custom_fingerprint.rs - Custom TLS fingerprint
• websocket.rs - WebSocket connection
• sse_stream.rs - Server-Sent Events
• proxy_usage.rs - Proxy configuration
• async_client.rs - Async client usage
• security_features.rs - Security configuration
• advanced_requests.rs - Headers, auth, cookies, redirects

Run an example:

cargo run --example basic_get

Architecture

ClientX is built on a three-layer architecture:

1. Low-Level Transport Layer

   • BoringSSL for TLS (via boring crate)
   • Hyper 1.x for HTTP
   • Hickory DNS for encrypted DNS resolution

2. Mid-Level Security & Fingerprinting Layer

   • Fingerprint controller (JA3, JA4, HTTP/2, QUIC)
   • Security controller (DNS, certificates, OCSP, CT)
   • Protocol handlers (WebSocket, SSE)

3. High-Level API Layer

   • Synchronous client (requests-like API)
   • Asynchronous client (httpx-like API)
   • Builder pattern with fluent interface

Performance

• Connection pooling (default: 10 connections per host)
• HTTP/2 multiplexing
• Keep-alive connections (90s idle timeout)
• Zero-copy where possible
• Efficient async runtime integration (Tokio)

Security Considerations

ClientX is designed with security-by-default:

• ✅ Encrypted DNS enabled by default
• ✅ Certificate Transparency validation
• ✅ OCSP stapling and CRL checking
• ✅ TLS 1.3 preferred
• ✅ Strong cipher suites only

Responsible Use

While ClientX enables fingerprint spoofing for legitimate use cases (testing, research, privacy), users must:

1. Comply with website Terms of Service
2. Respect robots.txt and rate limits
3. Use responsibly and ethically

The library includes rate limiting by default to prevent abuse.

Requirements

• Rust 1.70 or later
• BoringSSL (automatically built via boring-sys)
• Tokio runtime (for async client)

Platform Support

• ✅ Linux (x86_64, aarch64)
• ✅ macOS (x86_64, aarch64)
• ✅ Windows (x86_64)

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Acknowledgments

• BoringSSL - Google's fork of OpenSSL
• Hyper - Fast HTTP implementation
• Hickory DNS - Modern DNS resolver
• JA3/JA4 - TLS fingerprinting specifications

Related Projects

• curl-impersonate - curl with browser TLS fingerprints
• tls-client - Go HTTP client with fingerprinting
• requests - Python HTTP library (inspiration for sync API)
• httpx - Python async HTTP library (inspiration for async API)

Support

• 📖 Documentation
• 💬 Discussions
• 🐛 Issue Tracker

---

Note: This library is for educational and research purposes. Always ensure you have permission to test against target systems and comply with all applicable laws and regulations.