guise 0.1.2

Canonical browser fingerprint bundles, human-behavior timing, and TLS profile re-exports for the Santh fleet
Documentation
//! Differential fingerprint oracle — diff two browsers across the surface
//! catalogue.
//!
//! [`run_for`](super::run_for) probes ONE page against expected real-browser
//! truth. The oracle instead runs the *same* family catalogue against TWO live
//! pages and compares the **raw returned values** surface-by-surface. Any
//! surface where they disagree is a [`Divergence`] carrying the surface name,
//! the catalogue [`Severity`], and both rendered values.
//!
//! This is the validation gate for the `reynard` engine fork: a patched
//! browser is "zero engine-level fingerprint" exactly when it is
//! byte-identical to a stock build across the whole catalogue —
//! `report.is_identical()`. Run against the JS disguise instead and the
//! divergences ARE its residual tells (e.g. an overridden UA version or
//! `hardwareConcurrency` that no longer matches the real binary).
//!
//! The taxonomy is guise's own [`probes_for`](super::probes_for) catalogue (no
//! duplication); the [`Divergence`]/severity shape mirrors sear's
//! `differential::Divergence` so a detector (sear) and an evader (reynard) can
//! later share one surface taxonomy: sear detects against it, reynard evades
//! across it, this oracle gates on it.

use super::{probes_for, Severity};
use anyhow::Result;
use guise_profiles::UserAgentBrowser;
use runtime_foxdriver::Page;
use serde::{Deserialize, Serialize};
use std::collections::BTreeMap;

/// One surface where two browsers returned different values.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct Divergence {
    /// Surface name from the catalogue (e.g. `"webgl.unmasked_renderer"`).
    pub surface: String,
    /// How heavily a fingerprinter weights this surface.
    pub severity: Severity,
    /// Value the first browser (`label_a`) returned, rendered as compact JSON.
    pub a_value: String,
    /// Value the second browser (`label_b`) returned, rendered as compact JSON.
    pub b_value: String,
}

/// Result of diffing two browsers across the surface catalogue.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DifferentialReport {
    /// Label of the first browser (e.g. `"stock-firefox"`).
    pub label_a: String,
    /// Label of the second browser (e.g. `"reynard"` or `"disguise"`).
    pub label_b: String,
    /// Surfaces compared.
    pub surfaces: usize,
    /// Surfaces where both browsers returned the same value.
    pub agreed: usize,
    /// Surfaces where the values diverged.
    pub diverged: usize,
    /// Surfaces where at least one browser failed to evaluate the probe.
    pub errors: usize,
    /// Every divergence, sorted High → Low severity then by name.
    pub divergences: Vec<Divergence>,
}

impl DifferentialReport {
    /// `true` when the two browsers are fingerprint-identical across the whole
    /// catalogue — the bar a patched `reynard` build must clear vs. a stock one.
    pub fn is_identical(&self) -> bool {
        self.diverged == 0 && self.errors == 0
    }

    /// The highest severity among the divergences, if any.
    pub fn worst(&self) -> Option<Severity> {
        self.divergences.iter().map(|d| d.severity).max_by_key(severity_rank)
    }

    /// One-line human summary.
    pub fn summary(&self) -> String {
        format!(
            "{} vs {}: {}/{} surfaces agree ({} diverged, {} errors){}",
            self.label_a,
            self.label_b,
            self.agreed,
            self.surfaces,
            self.diverged,
            self.errors,
            match self.worst() {
                Some(s) => format!(", worst={s:?}"),
                None => String::new(),
            }
        )
    }
}

fn severity_rank(s: &Severity) -> u8 {
    match s {
        Severity::Low => 0,
        Severity::Medium => 1,
        Severity::High => 2,
    }
}

/// Render every surface value of `page` from the `browser` family catalogue.
/// `Ok(json)` for a clean read, `Err(msg)` if the probe failed to evaluate.
async fn capture(
    page: &Page,
    browser: UserAgentBrowser,
) -> Vec<(&'static str, Severity, std::result::Result<String, String>)> {
    let catalogue = probes_for(browser);
    let mut out = Vec::with_capacity(catalogue.len());
    for probe in catalogue {
        let cell = match page.evaluate(probe.js).await {
            Ok(eval) => {
                let v = eval
                    .into_value::<serde_json::Value>()
                    .unwrap_or(serde_json::Value::Null);
                Ok(v.to_string())
            }
            Err(e) => Err(e.to_string()),
        };
        out.push((probe.name, probe.severity, cell));
    }
    out
}

/// Run the `browser` family catalogue against both pages and diff the raw
/// values surface-by-surface.
///
/// Surfaces are matched by name (robust to any catalogue reordering). A surface
/// counts as an error — not a divergence — if either browser fails to evaluate
/// it, so a transport hiccup never masquerades as a fingerprint tell.
pub async fn diff_pages(
    a: &Page,
    b: &Page,
    browser: UserAgentBrowser,
    label_a: &str,
    label_b: &str,
) -> Result<DifferentialReport> {
    let cap_a = capture(a, browser).await;
    let cap_b = capture(b, browser).await;

    let b_by_name: BTreeMap<&str, &std::result::Result<String, String>> =
        cap_b.iter().map(|(n, _, v)| (*n, v)).collect();

    let mut report = DifferentialReport {
        label_a: label_a.to_string(),
        label_b: label_b.to_string(),
        surfaces: 0,
        agreed: 0,
        diverged: 0,
        errors: 0,
        divergences: Vec::new(),
    };

    for (name, severity, va) in &cap_a {
        let Some(vb) = b_by_name.get(name) else {
            // Surface only present in A's catalogue — treat as an error rather
            // than a silent drop so coverage gaps are visible.
            report.errors += 1;
            report.surfaces += 1;
            continue;
        };
        report.surfaces += 1;
        match (va, vb) {
            (Ok(x), Ok(y)) if x == y => report.agreed += 1,
            (Ok(x), Ok(y)) => {
                report.diverged += 1;
                report.divergences.push(Divergence {
                    surface: (*name).to_string(),
                    severity: *severity,
                    a_value: x.clone(),
                    b_value: y.clone(),
                });
            }
            _ => report.errors += 1,
        }
    }

    // Surfaces unique to B's catalogue (shouldn't happen for one family, but
    // keep the accounting honest).
    let a_names: std::collections::HashSet<&str> = cap_a.iter().map(|(n, _, _)| *n).collect();
    for (name, _, _) in &cap_b {
        if !a_names.contains(name) {
            report.errors += 1;
            report.surfaces += 1;
        }
    }

    report
        .divergences
        .sort_by(|x, y| severity_rank(&y.severity).cmp(&severity_rank(&x.severity)).then(x.surface.cmp(&y.surface)));

    Ok(report)
}

/// Render the differential report as a human-readable table (High severity
/// first — the surfaces a fingerprinter weights most).
pub fn render_differential(report: &DifferentialReport) -> String {
    use std::fmt::Write;
    let mut out = String::with_capacity(report.divergences.len() * 120 + 128);
    let _ = writeln!(out, "DIFFERENTIAL ORACLE — {}", report.summary());
    let _ = writeln!(out, "{:-^100}", "");
    if report.divergences.is_empty() {
        let _ = writeln!(out, "  ✓ fingerprint-identical across {} surfaces", report.surfaces);
        return out;
    }
    for d in &report.divergences {
        let _ = writeln!(
            out,
            "  ✘ [{:?}] {}\n      {} = {}\n      {} = {}",
            d.severity, d.surface, report.label_a, d.a_value, report.label_b, d.b_value
        );
    }
    out
}

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

    fn rep(divs: Vec<Divergence>, errors: usize) -> DifferentialReport {
        DifferentialReport {
            label_a: "a".into(),
            label_b: "b".into(),
            surfaces: 10,
            agreed: 10 - divs.len() - errors,
            diverged: divs.len(),
            errors,
            divergences: divs,
        }
    }

    fn div(surface: &str, sev: Severity) -> Divergence {
        Divergence {
            surface: surface.into(),
            severity: sev,
            a_value: "1".into(),
            b_value: "2".into(),
        }
    }

    #[test]
    fn identical_requires_zero_diverged_and_zero_errors() {
        assert!(rep(vec![], 0).is_identical());
        assert!(!rep(vec![div("x", Severity::Low)], 0).is_identical());
        assert!(!rep(vec![], 1).is_identical());
    }

    #[test]
    fn worst_picks_highest_severity() {
        let r = rep(
            vec![
                div("a", Severity::Low),
                div("b", Severity::High),
                div("c", Severity::Medium),
            ],
            0,
        );
        assert_eq!(r.worst(), Some(Severity::High));
    }

    #[test]
    fn worst_is_none_when_identical() {
        assert_eq!(rep(vec![], 0).worst(), None);
    }

    #[test]
    fn render_reports_identical_when_no_divergences() {
        let out = render_differential(&rep(vec![], 0));
        assert!(out.contains("fingerprint-identical"));
    }

    #[test]
    fn render_lists_each_divergence_with_both_values() {
        let out = render_differential(&rep(vec![div("webgl.renderer", Severity::High)], 0));
        assert!(out.contains("webgl.renderer"));
        assert!(out.contains("a = 1"));
        assert!(out.contains("b = 2"));
    }

    #[test]
    fn summary_names_both_browsers() {
        let s = rep(vec![], 0).summary();
        assert!(s.contains("a vs b"));
        assert!(s.contains("10/10"));
    }
}