guise 0.1.2

Canonical browser fingerprint bundles, human-behavior timing, and TLS profile re-exports for the Santh fleet
Documentation
//! Canonical profile rotation for cross-plane stealth identity.
//!
//! Rotation is intentionally profile-level: HTTP headers, TLS impersonation,
//! viewport, WebGL, and browser JS overrides all derive from the selected
//! [`StealthProfile`] instead of rotating one surface independently.

use crate::fingerprint::{
    StealthProfile, ALL_PROFILES, DEFAULT_STEALTH_PROFILE, ROTATION_PROFILES,
};
use guise_profiles as profile_catalog;

const DESKTOP_HTTP_PROFILE_CYCLE: &[StealthProfile] = &[
    DEFAULT_STEALTH_PROFILE,
    StealthProfile::ChromeMacStable,
    StealthProfile::SafariMacStable,
    StealthProfile::FirefoxLinux,
    StealthProfile::EdgeWindowsStable,
    StealthProfile::ChromeLinux,
];

const CHROMIUM_DESKTOP_PROFILE_CYCLE: &[StealthProfile] = &[
    DEFAULT_STEALTH_PROFILE,
    StealthProfile::ChromeMacStable,
    StealthProfile::ChromeLinux,
];

/// Profiles used by deterministic fleet rotation.
#[must_use]
pub const fn profiles() -> &'static [StealthProfile] {
    ROTATION_PROFILES
}

/// Every named profile in the canonical catalog.
///
/// Legacy compatibility personas are returned here even when they are excluded
/// from deterministic rotation.
#[must_use]
pub const fn all_profiles() -> &'static [StealthProfile] {
    ALL_PROFILES
}

/// Conservative desktop HTTP profiles for scanners that only rotate headers.
///
/// This avoids mobile/touch surfaces and uncommon Chromium derivative brands
/// while still covering Chrome, Edge, Safari, Firefox, Windows, macOS, and Linux.
#[must_use]
pub const fn desktop_http_profiles() -> &'static [StealthProfile] {
    DESKTOP_HTTP_PROFILE_CYCLE
}

/// Randomly select a conservative desktop HTTP profile.
///
/// This is the canonical selector for scanner `--random-user-agent` style
/// behavior: callers rotate whole browser profiles, not independent UA strings.
#[must_use]
pub fn random_desktop_http_profile() -> StealthProfile {
    crate::choice::random_item(desktop_http_profiles())
        .copied()
        .unwrap_or(DEFAULT_STEALTH_PROFILE)
}

/// Chromium desktop profiles safe for CDP `Network.setUserAgentOverride` paths.
#[must_use]
pub const fn chromium_desktop_profiles() -> &'static [StealthProfile] {
    CHROMIUM_DESKTOP_PROFILE_CYCLE
}

/// Stable lowercase profile name for operator-facing config.
#[must_use]
pub const fn profile_name(profile: StealthProfile) -> &'static str {
    profile_catalog::profile_name(profile)
}

/// Stable enum-style profile name for human-readable listings.
#[must_use]
pub const fn profile_display_name(profile: StealthProfile) -> &'static str {
    profile_catalog::profile_display_name(profile)
}

/// Resolve a config profile name or common alias to a canonical profile.
#[must_use]
pub fn named_profile(name: &str) -> Option<StealthProfile> {
    profile_catalog::named_profile(name)
}

/// Deterministically select a profile by index.
#[must_use]
pub fn profile_at(index: usize) -> StealthProfile {
    let profiles = profiles();
    profiles[index % profiles.len()]
}

/// Resolve an optional named profile, falling back to deterministic rotation.
#[must_use]
pub fn named_or_rotated(name: Option<&str>, index: usize) -> StealthProfile {
    name.and_then(named_profile)
        .unwrap_or_else(|| profile_at(index))
}

/// Infinite deterministic profile cycle.
#[derive(Debug, Clone)]
pub struct ProfileCycle {
    next_index: usize,
}

impl ProfileCycle {
    /// Start cycling at the beginning of the canonical profile list.
    #[must_use]
    pub const fn new() -> Self {
        Self { next_index: 0 }
    }

    /// Start cycling from a caller-provided offset.
    #[must_use]
    pub const fn from_index(next_index: usize) -> Self {
        Self { next_index }
    }
}

impl Default for ProfileCycle {
    fn default() -> Self {
        Self::new()
    }
}

impl Iterator for ProfileCycle {
    type Item = StealthProfile;

    fn next(&mut self) -> Option<Self::Item> {
        let profile = profile_at(self.next_index);
        self.next_index = self.next_index.wrapping_add(1);
        Some(profile)
    }
}

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

    #[test]
    fn profile_at_wraps_at_cycle_len() {
        assert_eq!(profile_at(0), profile_at(profiles().len()));
        assert_ne!(profile_at(0), profile_at(1));
    }

    #[test]
    fn aliases_resolve_to_stable_profiles() {
        assert_eq!(
            named_profile("chrome_131_windows"),
            Some(StealthProfile::ChromeWindowsStable)
        );
        assert_eq!(
            named_profile("safari"),
            Some(StealthProfile::SafariMacStable)
        );
        assert_eq!(
            named_profile("firefox-windows"),
            Some(StealthProfile::FirefoxWindows)
        );
        assert_eq!(
            named_profile("chrome-win"),
            Some(StealthProfile::ChromeWindowsStable)
        );
        assert_eq!(
            named_profile("ChromeMacStable"),
            Some(StealthProfile::ChromeMacStable)
        );
        assert_eq!(named_profile("ie11"), Some(StealthProfile::Ie11Windows));
        assert_eq!(
            named_profile("chrome-windows-legacy-96"),
            Some(StealthProfile::ChromeWindowsLegacy96)
        );
        assert_eq!(named_profile("unknown"), None);
    }

    #[test]
    fn every_profile_has_names_that_resolve() {
        for profile in all_profiles() {
            assert_eq!(named_profile(profile_name(*profile)), Some(*profile));
            assert!(!profile_display_name(*profile).is_empty());
        }
    }

    #[test]
    fn full_catalog_includes_explicit_only_legacy_profiles() {
        assert!(all_profiles().contains(&StealthProfile::ChromeWindowsLegacy96));
        assert!(all_profiles().contains(&StealthProfile::Ie11Windows));
        assert!(!profiles().contains(&StealthProfile::ChromeWindowsLegacy96));
        assert!(!profiles().contains(&StealthProfile::Ie11Windows));
    }

    #[test]
    fn constrained_rotation_pools_are_subsets_of_full_rotation() {
        for profile in desktop_http_profiles() {
            assert!(profiles().contains(profile));
        }
        for profile in chromium_desktop_profiles() {
            assert!(desktop_http_profiles().contains(profile));
        }
    }

    #[test]
    fn random_desktop_http_profile_stays_in_constrained_pool() {
        for _ in 0..128 {
            assert!(desktop_http_profiles().contains(&random_desktop_http_profile()));
        }
    }

    #[test]
    fn cycle_is_infinite_and_ordered() {
        let mut cycle = ProfileCycle::from_index(profiles().len() - 1);
        assert_eq!(cycle.next(), Some(StealthProfile::SamsungInternetAndroid));
        assert_eq!(cycle.next(), Some(DEFAULT_STEALTH_PROFILE));
    }

    #[test]
    fn cycle_default_starts_at_zero() {
        let cycle = ProfileCycle::default();
        assert_eq!(cycle.next_index, 0);
    }

    #[test]
    fn cycle_new_starts_at_zero() {
        let cycle = ProfileCycle::new();
        assert_eq!(cycle.next_index, 0);
    }

    #[test]
    fn cycle_from_index_wraps_on_next() {
        let mut cycle = ProfileCycle::from_index(usize::MAX);
        // usize::MAX + 1 wraps to 0
        let first = cycle.next().unwrap();
        assert_eq!(first, profile_at(usize::MAX));
        let second = cycle.next().unwrap();
        assert_eq!(second, profile_at(0));
    }

    #[test]
    fn named_or_rotated_prefers_name_when_given() {
        let rotated = named_or_rotated(None, 0);
        let named = named_or_rotated(Some("safari"), 0);
        assert_eq!(named, StealthProfile::SafariMacStable);
        assert_ne!(Some(rotated), named_profile("safari"));
    }

    #[test]
    fn named_or_rotated_falls_back_on_bad_name() {
        let fallback = named_or_rotated(Some("totally-invalid"), 3);
        assert_eq!(fallback, profile_at(3));
    }

    #[test]
    fn profile_name_is_lowercase_snake() {
        let name = profile_name(StealthProfile::ChromeWindowsStable);
        assert!(name.chars().all(|c| c.is_lowercase() || c == '_'));
    }

    #[test]
    fn profile_display_name_contains_browser_name() {
        let display = profile_display_name(StealthProfile::FirefoxLinux);
        assert!(display.contains("Firefox") || display.contains("firefox"));
    }

    #[test]
    fn desktop_http_profiles_excludes_mobile() {
        for profile in desktop_http_profiles() {
            let display = profile_display_name(*profile).to_lowercase();
            assert!(!display.contains("iphone"), "desktop pool should not contain iPhone");
            assert!(!display.contains("ipad"), "desktop pool should not contain iPad");
            assert!(!display.contains("android"), "desktop pool should not contain Android");
        }
    }

    #[test]
    fn chromium_desktop_profiles_are_all_chromium() {
        for profile in chromium_desktop_profiles() {
            let display = profile_display_name(*profile).to_lowercase();
            assert!(
                display.contains("chrome") || display.contains("chromium"),
                "{display} is not a Chromium profile"
            );
        }
    }

    #[test]
    fn all_profiles_is_nonempty() {
        assert!(!all_profiles().is_empty());
    }

    #[test]
    fn profiles_is_nonempty() {
        assert!(!profiles().is_empty());
    }

    #[test]
    fn named_profile_case_insensitive_aliases() {
        assert_eq!(named_profile("CHROME"), named_profile("chrome"));
        assert_eq!(named_profile("Firefox"), named_profile("firefox"));
    }

    #[test]
    fn profile_at_zero_is_first_in_profiles() {
        assert_eq!(profile_at(0), profiles()[0]);
    }
}