guise 0.1.2

Canonical browser fingerprint bundles, human-behavior timing, and TLS profile re-exports for the Santh fleet
Documentation
//! Firefox `user.js` pref-layer builder.
//!
//! Where [`super::inject`] hides tells at the JS runtime layer, this module
//! emits the launch-time Firefox preferences (UA/platform overrides, the
//! marionette/remote disables, hardware concurrency, notification API) that a
//! profile needs set before the first page loads. [`super::launch_profiled_firefox`]
//! merges the output into the launched profile's `user.js`.

/// The automation-hiding / coherence pref lines, with **no identity override**.
///
/// This is the launch-time pref half of stealth, with the genuine identity left
/// intact:
///
/// - `dom.webdriver.enabled=false`. NOTE: on a **plain BiDi-driven Firefox** an
///   active remote agent (which the CLI `--remote-debugging-port` activates, and
///   which BiDi control requires) overrides this pref, so the **native**
///   `navigator.webdriver` stays `true` regardless — verified empirically in
///   `captchaforge/tests/webdriver_native_pref.rs`. The main-world value is
///   instead masked by the JS getter override in [`super::apply_stealth`]; full
///   native coverage (Workers / fresh iframes / pre-preload re-reads — the
///   `webDriverAdvanced` signal) requires the **reynard engine build**, which
///   patches out the automation→`webdriver` coupling so this pref is honoured.
///   The pref is kept here because it IS load-bearing on that engine path.
/// - The Marionette/remote *default* prefs are disabled (the CLI flag still
///   activates the BiDi remote agent, so the automation connection is
///   unaffected — this is the same set [`build_user_js`] /
///   [`super::launch_profiled_firefox`] already ship).
/// - `privacy.resistFingerprinting=false`: RFP's letterboxing + timer
///   quantisation is itself a measurable tell, and it fights the coherent
///   fingerprint the JS layer presents.
/// - The Notification API is kept present (removing it is a measured tell).
///
/// It deliberately sets **no** `general.useragent.override` / `platform` /
/// `accept_languages` / `dom.maxHardwareConcurrency`, so the browser's genuine
/// identity stays self-consistent across JS/HTTP/TLS. Use this for the
/// real-identity default; use [`build_user_js`] for an explicit persona.
pub fn automation_prefs() -> String {
    [
        r#"user_pref("dom.webdriver.enabled", false);"#,
        r#"user_pref("marionette.defaultPrefs.enabled", false);"#,
        r#"user_pref("remote.enabled", false);"#,
        r#"user_pref("remote.frames.enabled", false);"#,
        r#"user_pref("privacy.resistFingerprinting", false);"#,
        r#"user_pref("dom.webnotifications.enabled", true);"#,
    ]
    .join("\n")
}

/// Build a `user.js` string from [`crate::ProfileOverrides`].
///
/// Identity overrides (UA / platform / languages / hardwareConcurrency) plus the
/// shared [`automation_prefs`] block. This is the explicit-persona path; for the
/// real-identity default, write only [`automation_prefs`] (no identity override).
pub fn build_user_js(overrides: &crate::ProfileOverrides) -> String {
    let mut lines = Vec::new();
    lines.push(format!(
        r#"user_pref("general.useragent.override", "{}");"#,
        overrides.user_agent.replace('"', "\\\"")
    ));
    lines.push(format!(
        r#"user_pref("general.platform.override", "{}");"#,
        overrides.platform.replace('"', "\\\"")
    ));
    lines.push(format!(
        r#"user_pref("intl.accept_languages", "{}");"#,
        overrides.languages.join(",").replace('"', "\\\"")
    ));
    // Shared automation-hiding / coherence prefs (incl. the Notification API
    // rationale documented on `automation_prefs`).
    lines.push(automation_prefs());
    lines.push(format!(
        r#"user_pref("dom.maxHardwareConcurrency", {});"#,
        overrides.hardware_concurrency
    ));
    lines.join("\n")
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn automation_prefs_sets_webdriver_disable_pref() {
        // Pin the pref STRING is emitted. (Runtime effect on plain BiDi is nil —
        // the remote agent overrides it; it is honoured only on the reynard
        // engine build. See webdriver_native_pref.rs for the live proof.)
        let p = automation_prefs();
        assert!(p.contains(r#"user_pref("dom.webdriver.enabled", false);"#));
    }

    #[test]
    fn automation_prefs_has_no_identity_overrides() {
        // The max-coherence contract: this block must NOT pin UA / platform /
        // languages / hardwareConcurrency — those would desync the genuine
        // identity from HTTP/TLS.
        let p = automation_prefs();
        assert!(!p.contains("general.useragent.override"), "must not pin UA");
        assert!(!p.contains("general.platform.override"), "must not pin platform");
        assert!(!p.contains("intl.accept_languages"), "must not pin languages");
        assert!(
            !p.contains("dom.maxHardwareConcurrency"),
            "must not pin hardwareConcurrency"
        );
    }

    #[test]
    fn automation_prefs_disables_marionette_and_remote_defaults() {
        let p = automation_prefs();
        assert!(p.contains("marionette.defaultPrefs.enabled"));
        assert!(p.contains("remote.enabled"));
        assert!(p.contains("privacy.resistFingerprinting"));
        assert!(p.contains("dom.webnotifications.enabled"));
    }

    #[test]
    fn automation_prefs_lines_are_valid_pref_format() {
        for line in automation_prefs().lines() {
            assert!(
                line.starts_with("user_pref(") && line.ends_with(");"),
                "invalid pref line: {line}"
            );
        }
    }

    #[test]
    fn build_user_js_includes_automation_prefs_block() {
        // build_user_js must keep shipping the shared automation block (it is the
        // launch-time half of stealth; a regression here re-exposes webdriver).
        let overrides = crate::profile_to_overrides(&crate::StealthProfile::FirefoxLinux);
        let js = build_user_js(&overrides);
        for line in automation_prefs().lines() {
            assert!(js.contains(line), "build_user_js missing automation pref: {line}");
        }
    }

    #[test]
    fn build_user_js_contains_useragent_override() {
        let overrides = crate::profile_to_overrides(&crate::StealthProfile::FirefoxLinux);
        let js = build_user_js(&overrides);
        assert!(js.contains("general.useragent.override"));
    }

    #[test]
    fn build_user_js_contains_platform_override() {
        let overrides = crate::profile_to_overrides(&crate::StealthProfile::FirefoxLinux);
        let js = build_user_js(&overrides);
        assert!(js.contains("general.platform.override"));
    }

    #[test]
    fn build_user_js_contains_languages() {
        let overrides = crate::profile_to_overrides(&crate::StealthProfile::FirefoxLinux);
        let js = build_user_js(&overrides);
        assert!(js.contains("intl.accept_languages"));
    }

    #[test]
    fn build_user_js_disables_webdriver() {
        let overrides = crate::profile_to_overrides(&crate::StealthProfile::FirefoxLinux);
        let js = build_user_js(&overrides);
        assert!(js.contains("dom.webdriver.enabled"));
        assert!(js.contains("false"));
    }

    #[test]
    fn build_user_js_disables_marionette() {
        let overrides = crate::profile_to_overrides(&crate::StealthProfile::FirefoxLinux);
        let js = build_user_js(&overrides);
        assert!(js.contains("marionette.defaultPrefs.enabled"));
    }

    #[test]
    fn build_user_js_disables_resist_fingerprinting() {
        let overrides = crate::profile_to_overrides(&crate::StealthProfile::FirefoxLinux);
        let js = build_user_js(&overrides);
        assert!(js.contains("privacy.resistFingerprinting"));
    }

    #[test]
    fn build_user_js_contains_webnotifications_pref() {
        let overrides = crate::profile_to_overrides(&crate::StealthProfile::FirefoxLinux);
        let js = build_user_js(&overrides);
        assert!(js.contains("dom.webnotifications.enabled"));
    }

    #[test]
    fn build_user_js_contains_hardware_concurrency() {
        let overrides = crate::profile_to_overrides(&crate::StealthProfile::FirefoxLinux);
        let js = build_user_js(&overrides);
        assert!(js.contains("dom.maxHardwareConcurrency"));
    }

    #[test]
    fn build_user_js_lines_are_valid_pref_format() {
        let overrides = crate::profile_to_overrides(&crate::StealthProfile::FirefoxLinux);
        let js = build_user_js(&overrides);
        for line in js.lines() {
            if line.trim().is_empty() {
                continue;
            }
            assert!(
                line.starts_with("user_pref(") && line.ends_with(");"),
                "invalid pref line: {}",
                line
            );
        }
    }

    #[test]
    fn build_user_js_escapes_quotes() {
        let mut overrides = crate::profile_to_overrides(&crate::StealthProfile::FirefoxLinux);
        overrides.user_agent = r#"Mozilla/5.0 "test" browser"#.into();
        let js = build_user_js(&overrides);
        assert!(js.contains(r#"\"test\""#));
    }

    #[test]
    fn build_user_js_empty_languages_does_not_panic() {
        let mut overrides = crate::profile_to_overrides(&crate::StealthProfile::FirefoxLinux);
        overrides.languages.clear();
        let _ = build_user_js(&overrides);
    }

    #[test]
    fn build_user_js_firefox_windows_profile() {
        let overrides = crate::profile_to_overrides(&crate::StealthProfile::FirefoxWindows);
        let js = build_user_js(&overrides);
        assert!(js.contains("Windows") || js.contains("Win32"));
        assert!(js.contains("general.useragent.override"));
    }

    #[test]
    fn build_user_js_chrome_profile_contains_chrome_ua() {
        let overrides = crate::profile_to_overrides(&crate::StealthProfile::ChromeWindowsStable);
        let js = build_user_js(&overrides);
        assert!(js.contains("Chrome/") || js.contains("Chromium"));
    }

    #[test]
    fn build_user_js_empty_user_agent() {
        let mut overrides = crate::profile_to_overrides(&crate::StealthProfile::FirefoxLinux);
        overrides.user_agent.clear();
        let js = build_user_js(&overrides);
        assert!(js.contains(r#"user_pref("general.useragent.override", "");"#));
    }

    #[test]
    fn build_user_js_newline_in_user_agent_is_literal() {
        // Current impl only escapes quotes, not newlines.
        // This documents the behaviour — a real newline in the pref file
        // would break Firefox parsing, but the replace logic doesn't handle it.
        let mut overrides = crate::profile_to_overrides(&crate::StealthProfile::FirefoxLinux);
        overrides.user_agent = "line1\nline2".into();
        let js = build_user_js(&overrides);
        assert!(js.contains("line1\nline2"));
    }

    #[test]
    fn build_user_js_zero_hardware_concurrency() {
        let mut overrides = crate::profile_to_overrides(&crate::StealthProfile::FirefoxLinux);
        overrides.hardware_concurrency = 0;
        let js = build_user_js(&overrides);
        assert!(js.contains("user_pref(\"dom.maxHardwareConcurrency\", 0);"));
    }
}