Design: fingerprint API v2

Why#

Version 1 kept every setting twice: a value (screen_width: Option<u32>) and a mode that said whether to use it (flags.screen_masking: MaskingMode). That allowed states that mean nothing, and it made callers say one thing in two places:

// before: the intent is spread over a value, a flag and a mutation after buildlet mut fp = Fingerprint::builder().screen(1920, 1080).build();fp.flags.screen_masking = MaskingMode::Custom;

The model#

One field per setting, four states:

pub enum Spoof<T> {    Natural,    // the browser's own value (the default)    Random,     // a random valid value, coherent with the rest, seeded by .seed(u64)    Value(T),   // exactly this    Off,        // the API is turned off: unavailable, or denied}

• The value and the mode are one field, so they cannot disagree.
• Random is resolved by build(): the built Fingerprint holds Natural, Value or Off. A random value is drawn together with the rest of the identity (same operating system, same region, same locale), so it never contradicts a value the caller gave.
• build() returns an error naming any setting outside the list above that was given Off.
• Behaviour that is not a per-setting value (WebRTC IP policy, canvas and audio noise, native toString, granted permissions, blocked ports, …) is a StealthPolicy. A policy preset never changes a setting’s Spoof.
• The built Fingerprint has private fields and read accessors. To change one, fp.to_builder(), change it, build().

Before and after (public signatures)#

Setting a value#

FingerprintBuilder::user_agent(self, v: impl Into<String>) -> SelfFingerprintBuilder::screen(self, width: u32, height: u32) -> SelfFingerprintBuilder::geolocation(self, latitude: f64, longitude: f64) -> SelfFingerprintBuilder::webgl(self, vendor: impl Into<String>, renderer: impl Into<String>) -> SelfFingerprintBuilder::timezone(self, v: impl Into<String>) -> SelfFingerprintBuilder::build(self) -> Fingerprint

FingerprintBuilder::user_agent(self, v: impl Into<Spoof<String>>) -> SelfFingerprintBuilder::screen(self, width: u32, height: u32) -> Self            // the common caseFingerprintBuilder::screen_spoof(self, v: impl Into<Spoof<ScreenSize>>) -> SelfFingerprintBuilder::geolocation(self, v: impl Into<Spoof<Geolocation>>) -> Self   // (lat, lon) worksFingerprintBuilder::webgl(self, v: impl Into<Spoof<WebGl>>) -> Self               // (vendor, renderer) worksFingerprintBuilder::timezone(self, v: impl Into<Spoof<String>>) -> SelfFingerprintBuilder::webrtc(self, v: impl Into<Spoof<WebRtcAddresses>>) -> SelfFingerprintBuilder::build(self) -> Result<Fingerprint, FingerprintError>

A plain value is Value. Spoof::Random, Spoof::Natural and Spoof::Off are accepted everywhere (Off is rejected by build() where it means nothing). Every other setter follows the same shape: platform, hardware_concurrency, device_memory, max_touch_points, vendor, locale, languages, accept_languages, pixel_ratio, color_depth, avail_screen, fonts, media_devices, proxy, battery, connection, speech_voices, bluetooth, client_hints.

Policy#

// a bag of flags on the fingerprint, mutated after the buildpub struct StealthFlags { pub navigator_masking: MaskingMode, /* 20 more modes */, pub native_spoofing: bool, .. }fp.flags.native_spoofing = true;Fingerprint::builder().flags(StealthFlags::balanced()).with_flags(|f| f.grant_permissions = true)

// a separate policy type, set only through the builderpub struct StealthPolicy { /* webrtc_policy, canvas_noise, audio_noise, native_spoofing,                              native_tostring, chrome_runtime, headless_fixes, grant_permissions,                              block_trackers, blocked_trackers, blocked_ports, quic, disable_csp,                              open_shadow_roots */ }StealthPolicy::{default(), balanced(), native_only(), max()}StealthPolicy::grant_permissions(self, bool) -> Self      // and one setter per fieldFingerprintBuilder::policy(self, p: StealthPolicy) -> SelfFingerprintBuilder::with_policy(self, f: impl Fn(StealthPolicy) -> StealthPolicy + Send + Sync + 'static) -> SelfFingerprintBuilder::{webrtc_policy, canvas_noise, audio_noise, native_spoofing, grant_permissions,                     block_trackers, blocked_trackers, blocked_ports, disable_csp, quic} // shortcutsFingerprint::policy(&self) -> &StealthPolicy

StealthFlags stays as a #[deprecated] alias of StealthPolicy.

Reading and editing#

fp.user_agent: Option<String>          fp.flags.screen_masking: MaskingModefp.screen_width: Option<u32>           fp.is_masked(Dimension::Screen)fp.fills_defaults(Dimension::Screen)   fp.geolocation_popup() -> PopupMode

// fields are privatefp.user_agent() -> &Spoof<String>      fp.screen() -> &Spoof<ScreenSize>fp.geolocation() -> &Spoof<Geolocation>   fp.policy() -> &StealthPolicyfp.is_masked(Dimension::Screen)        // kept: true when the setting is not Naturalfp.to_builder() -> FingerprintBuilderSpoof::{value(), is_natural(), is_random(), is_value(), is_off(), is_set(), as_str(), map()}

Removed#

The example that must compile#

use seleniumbase_rs::stealth::fingerprint::{CanvasNoise, Fingerprint, Spoof, StealthPolicy};let fp = Fingerprint::builder()    .timezone("Europe/Berlin")    .screen(1920, 1080)    .geolocation(Spoof::Random)    .webrtc(Spoof::Off)    .policy(StealthPolicy::balanced())    .canvas_noise(CanvasNoise::Random)    .build()?;

Random: how it stays coherent#

build() works out the operating system (the explicit one, else the one the user agent names, else Windows), then the place: the region of a Value time zone, else of a Value locale, else a drawn one. Every Random setting is taken from one seeded draw of that machine and that place (stealth::randomize), so a random locale agrees with a Value time zone, a random position is inside that time zone’s main city, and a random graphics adapter is one the operating system reports. build() returns FingerprintError when no coherent value exists (a random locale next to a time zone the place table does not know).

.seed(u64) seeds the draw and the canvas and audio noise, so the same calls give the same fingerprint. Without it the draw uses fresh entropy, and the seed it used is kept in the fingerprint.

JSON#

Spoof<T> serialises as "natural", "random", "off" or the value itself. Natural fields are left out. null reads as Natural. A fingerprint that holds "random" is resolved when it is read, the same way build() does it.

ProfileParams (external profile payloads) keeps its string flags, because the format is another tool’s, and reads the same words for every key:

The policy keys (canvas_noise, audio_masking, native_spoofing, grant_permissions, disable_csp, quic_mode, ports_masking) map to the policy. The full table is in Fingerprints: words every key reads.

As built#

See also#