rustenium_identity/
lib.rs

1pub mod cdp;
2pub mod error;
3pub mod identity;
4pub mod local_proxy_server;
5pub mod preset;
6pub mod script;
7pub mod tz;
8pub mod ua;
9
10use error::IdentityError;
11use local_proxy_server::start_overlay;
12use rustenium::browsers::{
13    BidiBrowser,
14    chrome::browser::{ChromeBrowser, ChromeConfig},
15};
16
17pub use error::IdentityError as Error;
18pub use identity::*;
19
20/// Configuration for launching an identity-spoofed browser session.
21pub struct IdentityConfig {
22    pub identity: Identity,
23    pub chrome: ChromeConfig,
24}
25
26impl From<Identity> for IdentityConfig {
27    fn from(identity: Identity) -> Self {
28        Self {
29            identity,
30            chrome: ChromeConfig {
31                enable_bidi: false,
32                enable_cdp: true,
33                ..Default::default()
34            },
35        }
36    }
37}
38
39impl IdentityConfig {
40    pub fn new(identity: Identity, chrome: ChromeConfig) -> Self {
41        Self { identity, chrome }
42    }
43}
44
45/// Read the running browser's real Chromium version, before any UA override is in
46/// place. Returns `None` if the version cannot be determined, in which case the
47/// caller keeps the configured value rather than guessing.
48async fn read_chromium_version(browser: &mut ChromeBrowser) -> Option<Vec<u16>> {
49    // `uaFullVersion` first: UA reduction freezes the UA string at `MAJOR.0.0.0`,
50    // while the client hint still carries the true build. Taking the reduced form
51    // would make us answer getHighEntropyValues with `146.0.0.0` — a value no real
52    // Chrome returns, which is a worse tell than the version gap we came to fix.
53    const EXPR: &str = r#"(async () => {
54        try {
55            const d = navigator.userAgentData;
56            if (d && d.getHighEntropyValues) {
57                const v = await d.getHighEntropyValues(['uaFullVersion']);
58                if (v && v.uaFullVersion) return v.uaFullVersion;
59            }
60        } catch (e) {}
61        const m = navigator.userAgent.match(/Chrome\/([\d.]+)/);
62        return m ? m[1] : '';
63    })()"#;
64    // ChromeBrowser implements both browser traits; this is the CDP path.
65    let result =
66        rustenium::browsers::cdp_browser::CdpBrowser::evaluate_script(browser, EXPR, true)
67            .await
68            .ok()?;
69    let version = result.result.value.as_ref()?.as_str()?.to_string();
70    ua::parse_version_parts(&version)
71}
72
73/// Read the real unmasked WebGL vendor/renderer, before any patch is installed.
74///
75/// The renderer *string* is spoofable but the capability profile behind it is not —
76/// `MAX_TEXTURE_SIZE` and friends come from the actual GPU, and known
77/// (brand → capabilities) pairings are checked. Claiming a card whose capabilities
78/// do not follow is the same shape of lie as claiming a browser version the engine
79/// contradicts, so the persona is pinned to the device instead.
80async fn read_gpu_strings(browser: &mut ChromeBrowser) -> Option<(String, String)> {
81    const EXPR: &str = r#"(() => {
82        try {
83            const gl = document.createElement('canvas').getContext('webgl');
84            const ext = gl && gl.getExtension('WEBGL_debug_renderer_info');
85            if (!ext) return '[]';
86            return JSON.stringify([
87                gl.getParameter(ext.UNMASKED_VENDOR_WEBGL),
88                gl.getParameter(ext.UNMASKED_RENDERER_WEBGL),
89            ]);
90        } catch (e) { return '[]'; }
91    })()"#;
92    let result =
93        rustenium::browsers::cdp_browser::CdpBrowser::evaluate_script(browser, EXPR, false)
94            .await
95            .ok()?;
96    let json = result.result.value.as_ref()?.as_str()?;
97    let pair: Vec<String> = serde_json::from_str(json).ok()?;
98    let [vendor, renderer] = <[String; 2]>::try_from(pair).ok()?;
99    if vendor.is_empty() || renderer.is_empty() {
100        return None;
101    }
102    Some((vendor, renderer))
103}
104
105/// A rustenium browser session with an identity applied.
106pub struct IdentitySession {
107    identity: Identity,
108    browser: ChromeBrowser,
109}
110
111impl IdentitySession {
112    /// Launch a new Chromium instance from the given config.
113    /// Applies all CDP emulation overrides and registers the stealth
114    /// bootstrap script before returning.
115    pub async fn launch(config: impl Into<IdentityConfig>) -> Result<Self, IdentityError> {
116        let mut config = config.into();
117        let geo = tz::resolve_geo(
118            config.identity.timezone.as_deref(),
119            config.identity.proxy.as_deref(),
120        )
121        .await?;
122        let timezone = geo.timezone.clone();
123
124        let mut chrome_config = config.chrome;
125        chrome_config.enable_bidi = false;
126        chrome_config.enable_cdp = true;
127
128        // Remove the `navigator.webdriver` tell at the source instead of patching it in JS.
129        let mut flags = chrome_config.browser_flags.take().unwrap_or_default();
130        flags.push("--disable-blink-features=AutomationControlled".to_string());
131        // Keep WebGL alive on a machine with no GPU.
132        //
133        // ANGLE defaults to its bundled SwiftShader over Vulkan, which fails to
134        // initialize on a headless host, and Chrome then blocklists the software
135        // renderer it falls back to — leaving `getContext("webgl")` returning null.
136        // A desktop browser with no WebGL at all is a louder signal than any
137        // renderer string: the vector every detector reads first simply is not
138        // there, and the vendor/renderer substitution below has no context to
139        // apply to. Pointing ANGLE at the system GL and accepting the blocklisted
140        // renderer gives a real context back.
141        //
142        // These say nothing about which card the page sees. That is the identity's
143        // GPU, spoofed on getParameter.
144        flags.push("--use-gl=angle".to_string());
145        flags.push("--use-angle=gl".to_string());
146        flags.push("--ignore-gpu-blocklist".to_string());
147        chrome_config.browser_flags = Some(flags);
148
149        if let Some(ref proxy_url) = config.identity.proxy {
150            if !proxy_url.is_empty() {
151                let local_addr = start_overlay(proxy_url)
152                    .await
153                    .map_err(|e| IdentityError::ProxyError(e.to_string()))?;
154                let mut flags = chrome_config.browser_flags.take().unwrap_or_default();
155                flags.push(format!(
156                    "--proxy-server=http://127.0.0.1:{}",
157                    local_addr.port()
158                ));
159                chrome_config.browser_flags = Some(flags);
160            }
161        }
162
163        let mut browser = ChromeBrowser::new(chrome_config).await;
164
165        // Pin the persona's Chromium version to the binary that is actually running.
166        // The UA is the only part of a version claim we control; the engine leaks the
167        // rest through which CSS properties parse, which `window` members exist and
168        // which JS builtins are present, each of which maps to a release range. A
169        // persona claiming a different major is caught with an exact distance, and a
170        // hardcoded one drifts into that the moment Chrome updates. Only the
171        // Chromium-based personas apply — Safari and iOS carry a WebKit version.
172        if matches!(config.identity.browser, Browser::Chrome | Browser::Edge)
173            && !matches!(config.identity.os, Os::Ios)
174        {
175            match read_chromium_version(&mut browser).await {
176                Some(version) => {if (config.identity.browser_version == version) {tracing::warn!("The chrome version you want to spoof is different from the actual stock chrome version running on")}},
177                None => tracing::warn!(
178                    "could not read the running Chromium version; \
179                     persona keeps its configured browser_version"
180                ),
181            }
182        }
183
184        // Same reasoning for the GPU: the strings are spoofable, the capabilities
185        // behind them are not, so a persona naming a card the capability profile
186        // contradicts is caught by the pairing rather than by the string.
187        match read_gpu_strings(&mut browser).await {
188            Some((vendor, renderer)) => {
189                config.identity.gpu.webgl_vendor = vendor;
190                config.identity.gpu.webgl_renderer = renderer;
191            }
192            None => tracing::warn!(
193                "could not read the real WebGL vendor/renderer; \
194                 persona keeps its configured gpu strings"
195            ),
196        }
197
198        cdp::apply_identity(&mut browser, &config.identity, &timezone).await?;
199
200        Ok(Self {
201            identity: config.identity,
202            browser,
203        })
204    }
205
206    /// Access the underlying rustenium ChromeBrowser.
207    pub fn browser(&self) -> &ChromeBrowser {
208        &self.browser
209    }
210
211    /// Mutable access to the underlying rustenium ChromeBrowser.
212    pub fn browser_mut(&mut self) -> &mut ChromeBrowser {
213        &mut self.browser
214    }
215
216    /// Get the identity.
217    pub fn identity(&self) -> &Identity {
218        &self.identity
219    }
220
221    pub async fn close(self) -> bool {
222        self.browser.close().await.map_err(|_| false).is_ok()
223    }
224}
rustenium_identity/lib.rs

rustenium_identity/
lib.rs
