Wire Formats and Impersonation

What is measured, and what is refused#

Every wire value this crate imitates was measured from a real browser by a capture tool and stored as JSON in crates/codec/src/measured. Nothing is typed by hand. The files are embedded with include_str!, parsed once, and looked up by browser and operating system.

Today there is one entry: Chrome 155.0.8059.40 on macOS, captured on 2026-10-11. Its record holds the user agent, the TLS spec (and the one Chrome uses for WebSocket), the HTTP/2 start, the header lists and their order, the client hints, and where it came from:

use seleniumbase_rs::stealth::fingerprint::OsType;use seleniumbase_rs_codec::emulation::{self, EmulationError};use seleniumbase_rs_codec::BrowserKind;# fn demo() -> Result<(), EmulationError> {let chrome = emulation::get(BrowserKind::Chrome, OsType::Macos)?;assert_eq!(chrome.major, 155);println!("{} captured on {}", chrome.provenance.browser, chrome.provenance.captured_on);// The JA4 of the measured hello. The capture recorded t13d1517h2_8daaf6152771_cb7bf5808d99// for it, in the file's `capture` evidence.println!("{}", chrome.tls.ja4());// A system nobody measured is an error, never a nearby guess.let windows = emulation::get(BrowserKind::Chrome, OsType::Windows);assert!(matches!(windows, Err(EmulationError::NotMeasured { .. })));# Ok(())# }

EmulationError::NotMeasured { kind, os } is the error the design plan calls SpecError::NotMeasured; codec::emulation::SpecError is an alias for EmulationError. The TLS and HTTP/2 refusals live in two other enums with the same name, codec::tls_spec::SpecError and codec::h2_spec::SpecError.

The same rule shows up higher up:

• ImpersonationProfile::for_system(BrowserKind::Chrome, OsType::Windows) and ImpersonationProfile::from_fingerprint of a Windows Fingerprint return ImpersonateError::Emulation(EmulationError::NotMeasured { .. }).
• ImpersonationProfile::from_fingerprint of a fingerprint whose user agent claims another Chrome major than the measured one returns ImpersonateError::VersionMismatch: Chrome 155’s handshake under a Chrome 153 user agent is a contradiction too.
• ImpersonationProfile::random(seed) only draws from measured entries, and the identity it builds claims the measured major (Fingerprint::randomized_with_major).

Re-measuring when Chrome updates#

To add the new version:

cargo run -p seleniumbase-rs-scrape      --example capture_tlscargo run -p seleniumbase-rs-scrape      --example capture_hintscargo run -p seleniumbase-rs-mimic --example capture_h2

A new Windows or Linux entry comes the same way: run the tools on that system. Safari has no tool yet beyond the capture_hints console snippet.

Reading the wire formats#

All of seleniumbase_rs_codec is pure: no sockets, no clock, no files, and #![forbid(unsafe_code)]. Every parser bounds its input and returns an error for hostile or truncated bytes instead of panicking.

Only JA4 itself is implemented. JA4H, JA4S, JA4X and the other JA4+ methods carry a different licence and are not part of this crate.

use seleniumbase_rs_codec::akamai::Akamai;use seleniumbase_rs_codec::ja3::Ja3;use seleniumbase_rs_codec::ja4::Ja4;# fn demo() -> Result<(), Box<dyn std::error::Error>> {// The Akamai string measured from Chrome 155 on macOS.let akamai: Akamai = "1:65536;2:0;4:6291456;6:262144|15663105|0|m,a,s,p".parse()?;assert_eq!(akamai.settings, vec![(1, 65536), (2, 0), (4, 6_291_456), (6, 262_144)]);assert_eq!(akamai.window_update, 15_663_105);// One JA4 and one JA3 measured from the same browser.let ja4: Ja4 = "t13d1517h2_8daaf6152771_cb7bf5808d99".parse()?;assert_eq!(ja4.a, "t13d1517h2");let ja3: Ja3 = "771,4865-4866-4867-49195-49199-49196-49200-52393-52392-49171-49172-156-157-47-53,\                13-10-35-18-65281-27-45-65037-5-0-23-17613-51-51764-43-11-16,4588-29-23-24,0"    .parse()?;assert_eq!(ja3.version, 771);# Ok(())# }

The spec types sit on top of the parsers. A TlsSpec (TlsSpec::from_client_hello) is the whole TLS profile as plain data, and an H2Spec (alias Http2Spec; H2Spec::from_capture, H2Spec::from_akamai) is the HTTP/2 start. Each has check_reproducible(), which says whether the BoringSSL and wreq stack can send it, and names what it cannot.

An impersonating client#

The mimic crate turns a measured profile into a wreq client:

use seleniumbase_rs_mimic::client::{    impersonation_client, ImpersonationProfile, WireProtocol,};use seleniumbase_rs_codec::header_spec::RequestShape;use seleniumbase_rs_codec::BrowserKind;# async fn demo() -> Result<(), Box<dyn std::error::Error>> {let profile = ImpersonationProfile::measured(BrowserKind::Chrome)?;let client = impersonation_client(&profile)?.build()?;let request = client.get("https://example.com/");let request = profile.apply(request, RequestShape::Document, None, WireProtocol::Http2)?;let response = request.send().await?;# drop(response);# Ok(())# }

• impersonation_client returns a wreq::ClientBuilder with the profile’s ClientHello, HTTP/2 start and default headers. You add proxies, timeouts and a trust store, then build. Certificate verification stays on: trust a private root with tls_cert_store, never by turning verification off.
• profile.apply gives one request the headers of its shape (RequestShape::Document for a navigation, RequestShape::Fetch for a script-issued request) in the measured order and spelling. The identity headers (User-Agent, Sec-CH-UA*, Accept-Language, Cookie) are filled in per request, so rotating an identity needs no new connection setup. The cookie is passed in and never stored. On HTTP/2 the list ends with the priority header of the measured table for the request’s Sec-Fetch-Dest; Chrome sends it on HTTP/2 only.
• The profile carries the measured TLS without its known gaps (see Limits) and keeps extension permutation on, as Chrome does.
• Cookies, redirects, body limits and the hand-over from a browser are not part of this client. That is what HttpSession is for.

Other ways to get a profile: ImpersonationProfile::for_system(kind, os), ImpersonationProfile::from_fingerprint(&fp) (a Chromium identity that claims the measured major), ImpersonationProfile::random(seed), and .with_locale(&locale) to change the Accept-Language.

Custom inputs#

Every part of a profile can be supplied by the caller. CustomProfileBuilder starts from the newest measured Chrome (or base/base_on another measured entry) and layers your inputs over it. What an input does not carry comes from the base: a JA3 has no signature algorithms, an Akamai string has no HEADERS priority, a header list has no TLS.

use seleniumbase_rs_mimic::client::ImpersonationProfile;# fn demo() -> Result<(), Box<dyn std::error::Error>> {let profile = ImpersonationProfile::custom()    .akamai("1:65536;2:0;4:6291456;6:262144|15663105|0|m,a,s,p")?    .user_agent("Mozilla/5.0 (custom)")    .accept_language("de-DE,de;q=0.9")    .build()?;assert_eq!(profile.user_agent(), "Mozilla/5.0 (custom)");# Ok(())# }

The inputs that need the base to be judged (ja3, ja4_r, ja4_ro, peetprint, signature_algorithms, akamai) return their error at once. The identity and header inputs are checked in build(). Nothing is sent before a client exists.

What is refused#

BoringSSL and wreq cannot emit everything a browser can. Anything they cannot reproduce is refused with a named error before a client exists, and crates/mimic/tests/impersonate_wire.rs proves on the wire that an accepted input arrives as given. The errors are variants of ImpersonateError: Tls(..) wraps codec::tls_spec::SpecError, Http2(..) wraps codec::h2_spec::SpecError, Convert(..) wraps the rules that belong to the client stack itself. A string that is not well formed at all is Ja3(..), Ja4(..), Peetprint(..) or Akamai(..).

For example, a JA3 that adds trust_anchors and a signature algorithm BoringSSL cannot write:

use seleniumbase_rs_mimic::client::{ImpersonateError, ImpersonationProfile};use seleniumbase_rs_codec::tls_spec::SpecError;# fn demo(ja3_with_trust_anchors: &str) {let refused = ImpersonationProfile::custom().ja3(ja3_with_trust_anchors);assert!(matches!(    refused,    Err(ImpersonateError::Tls(SpecError::UnsupportedExtension { id: 0xCA34, .. }))));let refused = ImpersonationProfile::custom().signature_algorithms(&[0x0904]);assert!(matches!(    refused,    Err(ImpersonateError::Tls(SpecError::UnsupportedSigalg { id: 0x0904, .. }))));# }