Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

57.5 KB
Raw Blame
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 Cua AI, Inc.

//! Linux identity and endpoint evidence for the first-class browser tools.

use std::collections::{HashMap, HashSet, VecDeque};
use std::os::unix::fs::MetadataExt;
use std::path::PathBuf;
use std::sync::{Arc, Mutex};
use std::time::Duration;

use async_trait::async_trait;
use cua_driver_core::browser::platform::{
    select_isolated_browser_executable, BrowserConsentOutcome, BrowserConsentRequest,
    BrowserPlatform, BrowserVisualAction, BrowserVisualActionKind, ExistingProfileSetupOutcome,
    ExistingProfileSetupRequest, PrepareAction, PrepareOutcome, PrepareRequest,
};
use cua_driver_core::browser::refusal::{BrowserRefusal, BrowserRefusalCode};
use cua_driver_core::browser::types::{
    BrowserClassification, BrowserEngineFamily, BrowserProcessRole, BrowserProduct,
    EndpointOwnershipMethod, EndpointOwnershipProof, EndpointTransport, NativeOwnershipMethod,
    NativeOwnershipProof, NativeWindowInfo, OwnedEndpoint, ProcessFingerprint, Rect,
};
use cua_driver_core::browser::{
    existing_profile_setup_descriptor, fetch_json_version_ws_url, is_firefox,
    loopback_websocket_port, parse_devtools_active_port, BrowserCursorTracker,
};

pub struct LinuxBrowserPlatform {
    cursor_registry: Arc<cursor_overlay::CursorRegistry>,
    browser_cursors: Mutex<BrowserCursorTracker>,
}

impl LinuxBrowserPlatform {
    pub fn new(cursor_registry: Arc<cursor_overlay::CursorRegistry>) -> Self {
        Self {
            cursor_registry,
            browser_cursors: Mutex::new(BrowserCursorTracker::default()),
        }
    }
}

impl Default for LinuxBrowserPlatform {
    fn default() -> Self {
        Self::new(Arc::new(cursor_overlay::CursorRegistry::new()))
    }
}

async fn x11_native_window(pid: i64, window_id: u64) -> Option<(NativeWindowInfo, bool)> {
    let pid_u32 = u32::try_from(pid).ok()?;
    tokio::task::spawn_blocking(move || {
        select_x11_window(pid, window_id, crate::x11::list_windows(Some(pid_u32)))
    })
    .await
    .ok()
    .flatten()
}

fn select_x11_window(
    pid: i64,
    window_id: u64,
    windows: Vec<crate::x11::WindowInfo>,
) -> Option<(NativeWindowInfo, bool)> {
    let only = windows.len() == 1;
    let window = windows
        .into_iter()
        .find(|w| w.xid == window_id && w.pid.map(i64::from) == Some(pid))?;
    Some((
        NativeWindowInfo {
            pid,
            window_id,
            title: window.title,
            bounds: Rect::new(
                f64::from(window.x),
                f64::from(window.y),
                f64::from(window.width),
                f64::from(window.height),
            ),
            geometry_exact: true,
            ownership: NativeOwnershipProof {
                method: NativeOwnershipMethod::PlatformAttested,
                owner_pid: pid,
                detail: Some(
                    "X11 _NET_WM_PID corroborated independently by the owned endpoint pid"
                        .to_owned(),
                ),
            },
        },
        only,
    ))
}

fn hyprland_identity_matches(pid: u32, window_id: u64, owner_pid: u32, address: u64) -> bool {
    pid != 0 && window_id != 0 && owner_pid == pid && address == window_id
}

fn hyprland_is_only_owned_window(
    pid: u32,
    window_id: u64,
    identities: impl IntoIterator<Item = (u32, u64)>,
) -> bool {
    let mut owned = identities.into_iter().filter(|(owner, _)| *owner == pid);
    let Some((owner, address)) = owned.next() else {
        return false;
    };
    hyprland_identity_matches(pid, window_id, owner, address) && owned.next().is_none()
}

fn run_existing_profile_cleanup<T: Send + 'static>(
    cleanup: impl FnOnce() -> T + Send + 'static,
) -> Result<T, BrowserRefusal> {
    std::thread::Builder::new()
        .name("cua-browser-cleanup".into())
        .spawn(cleanup)
        .map_err(|error| {
            BrowserRefusal::new(
                BrowserRefusalCode::BrowserRouteUnavailable,
                format!("could not start exact browser cleanup: {error}"),
            )
        })?
        .join()
        .map_err(|_| {
            BrowserRefusal::new(
                BrowserRefusalCode::BrowserRouteUnavailable,
                "exact browser cleanup worker panicked",
            )
        })
}

pub(crate) fn is_chromium_identity(name: &str) -> bool {
    let name = name.to_ascii_lowercase();
    let products = [
        "chrome", "chromium", "electron", "brave", "edge", "msedge", "vivaldi", "opera", "arc",
        "thorium", "iridium", "yandex",
    ];
    name.split(|ch: char| !ch.is_ascii_alphanumeric())
        .any(|token| products.contains(&token))
}

fn is_chromium(name: &str) -> bool {
    is_chromium_identity(name)
}

fn browser_product(identity: &str) -> BrowserProduct {
    let tokens = identity
        .to_ascii_lowercase()
        .split(|ch: char| !ch.is_ascii_alphanumeric())
        .filter(|token| !token.is_empty())
        .map(str::to_owned)
        .collect::<Vec<_>>();
    let has = |values: &[&str]| tokens.iter().any(|token| values.contains(&token.as_str()));
    if has(&["google"]) && has(&["chrome"]) {
        BrowserProduct::GoogleChrome
    } else if has(&["msedge"]) || (has(&["microsoft"]) && has(&["edge"])) {
        BrowserProduct::MicrosoftEdge
    } else if has(&["chromium"]) {
        BrowserProduct::Chromium
    } else if has(&["brave"]) {
        BrowserProduct::Brave
    } else if has(&["vivaldi"]) {
        BrowserProduct::Vivaldi
    } else if has(&["opera"]) {
        BrowserProduct::Opera
    } else if has(&["electron"]) {
        BrowserProduct::Electron
    } else if has(&["firefox"]) {
        BrowserProduct::Firefox
    } else {
        BrowserProduct::Other
    }
}

fn isolated_browser_candidates() -> Vec<PathBuf> {
    // These are the root-managed payload locations of supported Linux
    // packages, not PATH shims. Core additionally rejects symlinked paths, so
    // an isolated-launch grant cannot be redirected to a user-controlled file.
    [
        "/opt/google/chrome/google-chrome",
        "/usr/lib/chromium/chromium",
        "/usr/lib/chromium-browser/chromium-browser",
        "/opt/microsoft/msedge/msedge",
    ]
    .into_iter()
    .map(PathBuf::from)
    .collect()
}

fn trusted_root_owned_installation(executable: &std::path::Path) -> bool {
    if !executable.is_absolute() {
        return false;
    }
    let mut current = Some(executable);
    while let Some(path) = current {
        let Ok(metadata) = std::fs::symlink_metadata(path) else {
            return false;
        };
        if metadata.file_type().is_symlink() || metadata.uid() != 0 || metadata.mode() & 0o022 != 0
        {
            return false;
        }
        current = path.parent();
    }
    std::fs::metadata(executable)
        .is_ok_and(|metadata| metadata.is_file() && metadata.mode() & 0o111 != 0)
}

fn process_role_for_pid(pid: i64, product: BrowserProduct) -> BrowserProcessRole {
    let helper = std::fs::read(format!("/proc/{pid}/cmdline"))
        .ok()
        .is_some_and(|bytes| {
            bytes.split(|byte| *byte == 0).any(|arg| {
                arg.starts_with(b"--type=") && arg.get(7..).is_some_and(|kind| !kind.is_empty())
            })
        });
    if helper {
        BrowserProcessRole::Helper
    } else if product == BrowserProduct::Electron {
        BrowserProcessRole::EmbeddedApplication
    } else if matches!(
        product,
        BrowserProduct::GoogleChrome
            | BrowserProduct::Chromium
            | BrowserProduct::MicrosoftEdge
            | BrowserProduct::Brave
            | BrowserProduct::Vivaldi
            | BrowserProduct::Opera
            | BrowserProduct::Arc
    ) {
        BrowserProcessRole::StandaloneConsumer
    } else {
        BrowserProcessRole::Unknown
    }
}

fn parse_proc_net_loopback_listeners(text: &str) -> Vec<(u16, u64)> {
    text.lines()
        .skip(1)
        .filter_map(|line| {
            let fields = line.split_whitespace().collect::<Vec<_>>();
            if fields.len() < 10 || fields[3] != "0A" {
                return None;
            }
            let (address, port) = fields[1].split_once(':')?;
            let loopback = address == "0100007F" || address == "00000000000000000000000001000000";
            if !loopback {
                return None;
            }
            Some((
                u16::from_str_radix(port, 16).ok()?,
                fields[9].parse::<u64>().ok()?,
            ))
        })
        .collect()
}

fn descendant_pids(root: i64, relationships: impl IntoIterator<Item = (i64, i64)>) -> HashSet<i64> {
    let mut children = HashMap::<i64, Vec<i64>>::new();
    for (pid, parent) in relationships {
        children.entry(parent).or_default().push(pid);
    }
    let mut family = HashSet::from([root]);
    let mut pending = VecDeque::from([root]);
    while let Some(parent) = pending.pop_front() {
        for child in children.get(&parent).into_iter().flatten() {
            if family.insert(*child) {
                pending.push_back(*child);
            }
        }
    }
    family
}

fn process_family_pids(root: i64) -> Result<HashSet<i64>, BrowserRefusal> {
    if !std::path::Path::new(&format!("/proc/{root}")).exists() {
        return Err(BrowserRefusal::new(
            BrowserRefusalCode::BrowserBindingStale,
            format!("browser process {root} is no longer available"),
        ));
    }
    let relationships = std::fs::read_dir("/proc")
        .into_iter()
        .flatten()
        .flatten()
        .filter_map(|entry| {
            let pid = entry.file_name().to_string_lossy().parse::<i64>().ok()?;
            let status = std::fs::read_to_string(entry.path().join("status")).ok()?;
            let parent = status
                .lines()
                .find_map(|line| line.strip_prefix("PPid:"))?
                .trim()
                .parse::<i64>()
                .ok()?;
            Some((pid, parent))
        });
    Ok(descendant_pids(root, relationships))
}

fn socket_inodes_for_process_tree(pid: i64) -> Result<HashSet<u64>, BrowserRefusal> {
    let process_family = process_family_pids(pid)?;
    let mut inodes = HashSet::new();
    for owner_pid in process_family {
        let Ok(directory) = std::fs::read_dir(format!("/proc/{owner_pid}/fd")) else {
            continue;
        };
        inodes.extend(
            directory
                .flatten()
                .filter_map(|entry| std::fs::read_link(entry.path()).ok())
                .filter_map(|target| {
                    let target = target.to_string_lossy();
                    target
                        .strip_prefix("socket:[")
                        .and_then(|value| value.strip_suffix(']'))
                        .and_then(|value| value.parse::<u64>().ok())
                }),
        );
    }
    Ok(inodes)
}

fn loopback_ports_for_pid(pid: i64) -> Result<Vec<u16>, BrowserRefusal> {
    // Chromium may delegate its DevTools listener to a utility child. Core's
    // ownership contract explicitly accepts the approved browser PID or one
    // of its children, so inspect the bounded descendant tree as well as the
    // root process while still attributing the result to the approved root.
    let owned = socket_inodes_for_process_tree(pid)?;
    let mut listeners = Vec::new();
    for path in ["/proc/net/tcp", "/proc/net/tcp6"] {
        if let Ok(text) = std::fs::read_to_string(path) {
            listeners.extend(
                parse_proc_net_loopback_listeners(&text)
                    .into_iter()
                    .filter(|(_, inode)| owned.contains(inode))
                    .map(|(port, _)| port),
            );
        }
    }
    listeners.sort_unstable();
    listeners.dedup();
    Ok(listeners)
}

fn default_user_data_dir(product: BrowserProduct) -> Option<PathBuf> {
    let home = std::env::var_os("HOME").map(PathBuf::from)?;
    let relative = match product {
        BrowserProduct::GoogleChrome => ".config/google-chrome",
        BrowserProduct::MicrosoftEdge => ".config/microsoft-edge",
        BrowserProduct::Chromium => ".config/chromium",
        _ => return None,
    };
    Some(home.join(relative))
}

fn user_data_dir_for_pid(pid: i64) -> Result<Option<PathBuf>, BrowserRefusal> {
    let bytes = std::fs::read(format!("/proc/{pid}/cmdline")).map_err(|_| {
        BrowserRefusal::new(
            BrowserRefusalCode::BrowserBindingStale,
            format!("browser process {pid} is no longer available"),
        )
    })?;
    let args = bytes
        .split(|byte| *byte == 0)
        .filter(|arg| !arg.is_empty())
        .map(|arg| String::from_utf8_lossy(arg).into_owned())
        .collect::<Vec<_>>();
    let mut directories = Vec::new();
    for (index, arg) in args.iter().enumerate() {
        if let Some(path) = arg.strip_prefix("--user-data-dir=") {
            if !path.is_empty() {
                directories.push(PathBuf::from(path));
            }
        } else if arg == "--user-data-dir" {
            if let Some(path) = args.get(index + 1).filter(|path| !path.is_empty()) {
                directories.push(PathBuf::from(path));
            }
        }
    }
    directories.sort();
    directories.dedup();
    match directories.as_slice() {
        [] => {
            let Some(executable) = std::fs::read_link(format!("/proc/{pid}/exe"))
                .ok()
                .map(|path| path.to_string_lossy().into_owned())
            else {
                return Ok(None);
            };
            Ok(default_user_data_dir(browser_product(&executable)))
        }
        [path] if path.is_absolute() => Ok(Some(path.clone())),
        [path] => {
            let cwd = std::fs::read_link(format!("/proc/{pid}/cwd")).map_err(|_| {
                BrowserRefusal::new(
                    BrowserRefusalCode::BrowserBindingStale,
                    format!("browser process {pid} working directory is unavailable"),
                )
            })?;
            Ok(Some(cwd.join(path)))
        }
        _ => Err(BrowserRefusal::new(
            BrowserRefusalCode::BrowserBindingAmbiguous,
            "browser process has multiple distinct --user-data-dir arguments",
        )),
    }
}

fn active_port_endpoint(pid: i64) -> Result<Option<OwnedEndpoint>, BrowserRefusal> {
    let Some(user_data_dir) = user_data_dir_for_pid(pid)? else {
        return Ok(None);
    };
    let text = match std::fs::read_to_string(user_data_dir.join("DevToolsActivePort")) {
        Ok(text) => text,
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(None),
        Err(error) => {
            return Err(BrowserRefusal::new(
                BrowserRefusalCode::BrowserRouteUnavailable,
                format!("could not read the browser's DevToolsActivePort file: {error}"),
            ))
        }
    };
    let Some((port, path)) = parse_devtools_active_port(&text) else {
        return Err(BrowserRefusal::new(
            BrowserRefusalCode::BrowserEndpointOwnerMismatch,
            "the browser's DevToolsActivePort file did not contain one exact browser endpoint",
        ));
    };
    if !loopback_ports_for_pid(pid)?.contains(&port) {
        return Ok(None);
    }
    Ok(Some(OwnedEndpoint {
        ws_url: format!("ws://127.0.0.1:{port}{path}"),
        http_port: Some(port),
        transport: EndpointTransport::DevToolsActivePort,
        ownership: EndpointOwnershipProof {
            method: EndpointOwnershipMethod::DevtoolsActivePortsFile,
            owner_pid: pid,
            listener_pid: None,
            detail: Some(
                "exact /proc argv profile port file plus loopback socket inode owner".to_owned(),
            ),
        },
    }))
}

fn process_identity(pid: i64) -> Result<(u64, Option<String>), BrowserRefusal> {
    let stat = std::fs::read_to_string(format!("/proc/{pid}/stat")).map_err(|_| {
        BrowserRefusal::new(
            BrowserRefusalCode::BrowserBindingStale,
            format!("browser process {pid} is no longer available"),
        )
    })?;
    let started = crate::proc_fs::process_start_time_from_stat(&stat).ok_or_else(|| {
        BrowserRefusal::new(
            BrowserRefusalCode::BrowserRouteUnavailable,
            format!("could not parse process start time for pid {pid}"),
        )
    })?;
    let executable = std::fs::read_link(format!("/proc/{pid}/exe"))
        .ok()
        .map(|path| path.to_string_lossy().into_owned());
    Ok((started, executable))
}

async fn browser_websocket_url(port: u16) -> Option<String> {
    let url = fetch_json_version_ws_url(port).await?;
    (loopback_websocket_port(&url) == Some(port)).then_some(url)
}

#[async_trait]
impl BrowserPlatform for LinuxBrowserPlatform {
    fn isolated_browser_executable(&self) -> Result<String, BrowserRefusal> {
        for candidate in isolated_browser_candidates() {
            let Ok(executable) = select_isolated_browser_executable([candidate]) else {
                continue;
            };
            if trusted_root_owned_installation(std::path::Path::new(&executable)) {
                return Ok(executable);
            }
        }
        Err(BrowserRefusal::new(
            BrowserRefusalCode::BrowserRouteUnavailable,
            "no root-owned, non-writable system Chromium executable is available for isolated launch",
        ))
    }

    fn standalone_trusted_input_background_limitation(&self) -> Option<&'static str> {
        Some("Chromium's trusted CDP Input route activates its standalone browser window on Linux")
    }

    async fn visualize_browser_action(&self, action: BrowserVisualAction) {
        if action.session.is_empty()
            || action.cdp_target_id.is_empty()
            || cua_driver_core::session::is_session_ended(&action.session)
        {
            return;
        }

        let visibility_updates = self.browser_cursors.lock().unwrap().update(
            &action.session,
            action.window_id,
            &action.cdp_target_id,
            action.tab_is_active,
        );
        let cursor_enabled = self
            .cursor_registry
            .get_or_create(&action.session)
            .config
            .enabled;
        for (key, visible) in visibility_updates {
            let enabled = if key == action.session {
                visible && cursor_enabled
            } else {
                visible
                    && self
                        .cursor_registry
                        .get(&key)
                        .is_some_and(|state| state.config.enabled)
            };
            crate::overlay::send_command_for(
                key,
                cursor_overlay::OverlayCommand::SetEnabled(enabled),
            );
        }
        if !action.tab_is_active || !cursor_enabled {
            return;
        }
        let (Some(screen_x), Some(screen_y)) = (action.screen_x, action.screen_y) else {
            return;
        };
        if !screen_x.is_finite() || !screen_y.is_finite() {
            return;
        }

        crate::overlay::send_command_for(
            action.session.clone(),
            cursor_overlay::OverlayCommand::PinAbove(action.window_id),
        );
        crate::overlay::animate_cursor_to_for(action.session.clone(), screen_x, screen_y).await;
        self.cursor_registry
            .update_position(&action.session, screen_x, screen_y);

        if matches!(
            action.kind,
            BrowserVisualActionKind::Click
                | BrowserVisualActionKind::Type
                | BrowserVisualActionKind::RightClick
                | BrowserVisualActionKind::DoubleClick
                | BrowserVisualActionKind::Drag
        ) {
            crate::overlay::send_command_for(
                action.session,
                cursor_overlay::OverlayCommand::ClickPulse {
                    x: screen_x,
                    y: screen_y,
                },
            );
        }
    }

    async fn classify_browser(&self, pid: i64) -> Result<BrowserClassification, BrowserRefusal> {
        let pid_u32 = u32::try_from(pid).map_err(|_| {
            BrowserRefusal::new(
                BrowserRefusalCode::BrowserWrongTargetRefused,
                format!("pid {pid} is outside the Linux process-id range"),
            )
        })?;
        let (process, executable) = tokio::task::spawn_blocking(move || {
            let process = crate::proc_fs::list_processes()
                .into_iter()
                .find(|process| process.pid == pid_u32);
            let executable = std::fs::read_link(format!("/proc/{pid}/exe"))
                .ok()
                .map(|path| path.to_string_lossy().into_owned());
            (process, executable)
        })
        .await
        .ok()
        .and_then(|(process, executable)| process.map(|process| (process, executable)))
        .ok_or_else(|| {
            BrowserRefusal::new(
                BrowserRefusalCode::BrowserBindingStale,
                format!("browser process {pid} is no longer available"),
            )
        })?;
        let identity = executable
            .filter(|path| !path.is_empty())
            .unwrap_or_else(|| process.name.clone());
        let chromium = is_chromium(&identity);
        let gecko = is_firefox(&identity);
        let product_kind = browser_product(&identity);
        Ok(BrowserClassification {
            is_browser: chromium || gecko,
            engine: if chromium {
                BrowserEngineFamily::Chromium
            } else if gecko {
                BrowserEngineFamily::Gecko
            } else {
                BrowserEngineFamily::Unknown
            },
            product_kind,
            product: Some(process.name),
            channel: None,
            process_role: process_role_for_pid(pid, product_kind),
            supports_cdp: chromium,
        })
    }

    async fn native_window(
        &self,
        pid: i64,
        window_id: u64,
    ) -> Result<NativeWindowInfo, BrowserRefusal> {
        if let Some((window, _)) = x11_native_window(pid, window_id).await {
            return Ok(window);
        }
        let pid_u32 = u32::try_from(pid).map_err(|_| {
            BrowserRefusal::new(
                BrowserRefusalCode::BrowserWrongTargetRefused,
                format!("pid {pid} is outside the Linux process-id range"),
            )
        })?;
        if std::env::var_os("WAYLAND_DISPLAY").is_some() {
            if crate::wayland::hyprland::is_session() {
                let window = tokio::task::spawn_blocking(move || {
                    crate::wayland::hyprland::window_for_address(window_id)
                })
                .await
                .ok()
                .flatten()
                .ok_or_else(|| {
                    BrowserRefusal::new(
                        BrowserRefusalCode::BrowserRouteUnavailable,
                        "Hyprland could not attest the exact mapped browser window",
                    )
                })?;
                if !hyprland_identity_matches(pid_u32, window_id, window.pid, window.address) {
                    return Err(BrowserRefusal::new(
                        BrowserRefusalCode::BrowserWrongTargetRefused,
                        "Hyprland browser window does not match the requested pid and full address",
                    ));
                }
                return Ok(NativeWindowInfo {
                    pid,
                    window_id,
                    title: window.title,
                    bounds: Rect::new(
                        f64::from(window.x),
                        f64::from(window.y),
                        f64::from(window.width),
                        f64::from(window.height),
                    ),
                    geometry_exact: true,
                    ownership: NativeOwnershipProof {
                        method: NativeOwnershipMethod::WindowServerOwner,
                        owner_pid: pid,
                        detail: Some(
                            "authenticated Hyprland IPC pid, full address, and mapped window rect"
                                .to_owned(),
                        ),
                    },
                });
            }
            if let Some(window) = crate::wayland::sway_ipc::window_for_id(window_id) {
                if window.pid != pid_u32 {
                    return Err(BrowserRefusal::new(
                        BrowserRefusalCode::BrowserWrongTargetRefused,
                        format!("Sway window {window_id} is not owned by pid {pid}"),
                    ));
                }
                return Ok(NativeWindowInfo {
                    pid,
                    window_id,
                    title: window.title,
                    bounds: Rect::new(
                        f64::from(window.x),
                        f64::from(window.y),
                        f64::from(window.width),
                        f64::from(window.height),
                    ),
                    geometry_exact: true,
                    ownership: NativeOwnershipProof {
                        method: NativeOwnershipMethod::WindowServerOwner,
                        owner_pid: pid,
                        detail: Some("Sway IPC pid and rect".to_owned()),
                    },
                });
            }
            if let Some(window) =
                crate::wayland::shell_helper::trusted_window_for_id(pid_u32, window_id)
            {
                return Ok(NativeWindowInfo {
                    pid,
                    window_id,
                    title: window.title,
                    bounds: Rect::new(
                        f64::from(window.x),
                        f64::from(window.y),
                        f64::from(window.width),
                        f64::from(window.height),
                    ),
                    geometry_exact: true,
                    ownership: NativeOwnershipProof {
                        method: NativeOwnershipMethod::PlatformAttested,
                        owner_pid: pid,
                        detail: Some(
                            "verified GNOME Shell helper owner, stable window id, pid, and frame rect"
                                .to_owned(),
                        ),
                    },
                });
            }
            let window = tokio::task::spawn_blocking(move || {
                crate::wayland::list_windows_dispatch(Some(pid_u32))
                    .into_iter()
                    .find(|window| window.xid == window_id)
            })
            .await
            .ok()
            .flatten()
            .ok_or_else(|| {
                BrowserRefusal::new(
                    BrowserRefusalCode::BrowserRouteUnavailable,
                    "the active Wayland compositor cannot prove this window's pid and geometry",
                )
            })?;
            return Ok(NativeWindowInfo {
                pid,
                window_id,
                title: window.title,
                bounds: Rect::new(
                    f64::from(window.x),
                    f64::from(window.y),
                    f64::from(window.width),
                    f64::from(window.height),
                ),
                geometry_exact: false,
                ownership: NativeOwnershipProof {
                    method: NativeOwnershipMethod::PlatformAttested,
                    owner_pid: pid,
                    detail: Some(
                        "Wayland shell/AT-SPI metadata; geometry may be unavailable, so core permits read-only heuristic binding only"
                            .to_owned(),
                    ),
                },
            });
        }

        Err({
            BrowserRefusal::new(
                BrowserRefusalCode::BrowserBindingStale,
                format!("X11 window {window_id} is not owned by pid {pid}"),
            )
        })
    }

    async fn is_only_exact_native_window(
        &self,
        pid: i64,
        window_id: u64,
    ) -> Result<Option<bool>, BrowserRefusal> {
        if let Some((_, only)) = x11_native_window(pid, window_id).await {
            return Ok(Some(only));
        }
        let pid_u32 = u32::try_from(pid).map_err(|_| {
            BrowserRefusal::new(
                BrowserRefusalCode::BrowserWrongTargetRefused,
                format!("pid {pid} is outside the Linux process-id range"),
            )
        })?;
        if std::env::var_os("WAYLAND_DISPLAY").is_some() {
            if crate::wayland::hyprland::is_session() {
                let windows = tokio::task::spawn_blocking(crate::wayland::hyprland::list_windows)
                    .await
                    .ok()
                    .and_then(Result::ok)
                    .ok_or_else(|| {
                        BrowserRefusal::new(
                            BrowserRefusalCode::BrowserRouteUnavailable,
                            "Hyprland could not attest browser window cardinality",
                        )
                    })?;
                // Count every mapped client owned by the PID, including hidden
                // and off-workspace clients; visibility cannot prove uniqueness.
                return Ok(Some(hyprland_is_only_owned_window(
                    pid_u32,
                    window_id,
                    windows
                        .into_iter()
                        .map(|window| (window.pid, window.address)),
                )));
            }
            let Some(windows) = crate::wayland::sway_ipc::list_windows() else {
                if let Some(owned) =
                    crate::wayland::shell_helper::trusted_window_ids_for_pid(pid_u32)
                {
                    return Ok(Some(owned.len() == 1 && owned[0] == window_id));
                }
                if crate::wayland::is_inject_mode() {
                    // The private cua-compositor route owns both the native
                    // toplevel enumeration and its PID correlation. Unlike a
                    // generic AT-SPI-only Wayland session, that is sufficient
                    // to attest singleton native-window cardinality for an
                    // embedded Chromium endpoint.
                    let owned = tokio::task::spawn_blocking(move || {
                        crate::wayland::list_windows_dispatch(Some(pid_u32))
                            .into_iter()
                            .filter(|window| window.pid == Some(pid_u32))
                            .map(|window| window.xid)
                            .collect::<Vec<_>>()
                    })
                    .await
                    .map_err(|error| {
                        BrowserRefusal::new(
                            BrowserRefusalCode::BrowserRouteUnavailable,
                            format!("could not enumerate cua-compositor browser windows: {error}"),
                        )
                    })?;
                    return Ok(Some(owned.len() == 1 && owned[0] == window_id));
                }
                return Ok(None);
            };
            let owned = windows
                .into_iter()
                .filter(|window| window.pid == pid_u32)
                .map(|window| window.id)
                .collect::<Vec<_>>();
            return Ok(Some(owned.len() == 1 && owned[0] == window_id));
        }
        Ok(Some(false))
    }

    async fn discover_owned_endpoint(
        &self,
        pid: i64,
    ) -> Result<Option<OwnedEndpoint>, BrowserRefusal> {
        let ports = tokio::task::spawn_blocking(move || loopback_ports_for_pid(pid))
            .await
            .map_err(|error| {
                BrowserRefusal::new(
                    BrowserRefusalCode::BrowserRouteUnavailable,
                    format!("listener inspection task failed: {error}"),
                )
            })??;
        for port in ports {
            if let Some(ws_url) = browser_websocket_url(port).await {
                return Ok(Some(OwnedEndpoint {
                    ws_url,
                    http_port: Some(port),
                    transport: EndpointTransport::LegacyJsonVersion,
                    ownership: EndpointOwnershipProof {
                        method: EndpointOwnershipMethod::ListeningSocketPid,
                        owner_pid: pid,
                        listener_pid: None,
                        detail: Some("/proc socket inode owner".to_owned()),
                    },
                }));
            }
        }
        Ok(None)
    }

    async fn discover_existing_profile_endpoint(
        &self,
        pid: i64,
    ) -> Result<Option<OwnedEndpoint>, BrowserRefusal> {
        if let Some(endpoint) = active_port_endpoint(pid)? {
            return Ok(Some(endpoint));
        }
        let ports = tokio::task::spawn_blocking(move || loopback_ports_for_pid(pid))
            .await
            .map_err(|error| {
                BrowserRefusal::new(
                    BrowserRefusalCode::BrowserRouteUnavailable,
                    format!("listener inspection task failed: {error}"),
                )
            })??;
        let mut discovered = Vec::new();
        for port in ports {
            if let Some(ws_url) = browser_websocket_url(port).await {
                discovered.push((port, ws_url));
            }
        }
        match discovered.as_slice() {
            [] => Ok(None),
            [(port, ws_url)] => Ok(Some(OwnedEndpoint {
                ws_url: ws_url.clone(),
                http_port: Some(*port),
                transport: EndpointTransport::LegacyJsonVersion,
                ownership: EndpointOwnershipProof {
                    method: EndpointOwnershipMethod::ListeningSocketPid,
                    owner_pid: pid,
                    listener_pid: None,
                    detail: Some("/proc owner plus /json/version".to_owned()),
                },
            })),
            _ => Err(BrowserRefusal::new(
                BrowserRefusalCode::BrowserBindingAmbiguous,
                "multiple browser-level DevTools endpoints are owned by the approved process",
            )),
        }
    }

    async fn reprove_existing_profile_endpoint(
        &self,
        pid: i64,
        expected_ws_url: &str,
    ) -> Result<Option<OwnedEndpoint>, BrowserRefusal> {
        let Some(port) = loopback_websocket_port(expected_ws_url) else {
            return Err(BrowserRefusal::new(
                BrowserRefusalCode::BrowserEndpointOwnerMismatch,
                "the approved existing-profile endpoint is not loopback-only",
            ));
        };
        if let Some(endpoint) = active_port_endpoint(pid)? {
            if endpoint.ws_url != expected_ws_url {
                return Err(BrowserRefusal::new(
                    BrowserRefusalCode::BrowserEndpointOwnerMismatch,
                    "the browser's exact DevTools endpoint changed after approval",
                ));
            }
            return Ok(Some(endpoint));
        }
        let ports = tokio::task::spawn_blocking(move || loopback_ports_for_pid(pid))
            .await
            .map_err(|error| {
                BrowserRefusal::new(
                    BrowserRefusalCode::BrowserRouteUnavailable,
                    format!("listener inspection task failed: {error}"),
                )
            })??;
        if !ports.contains(&port) {
            return Ok(None);
        }
        Ok(Some(OwnedEndpoint {
            ws_url: expected_ws_url.to_owned(),
            http_port: Some(port),
            transport: EndpointTransport::LegacyJsonVersion,
            ownership: EndpointOwnershipProof {
                method: EndpointOwnershipMethod::ListeningSocketPid,
                owner_pid: pid,
                listener_pid: None,
                detail: Some("/proc owner of exact approved endpoint".to_owned()),
            },
        }))
    }

    async fn setup_existing_profile_endpoint(
        &self,
        request: ExistingProfileSetupRequest,
    ) -> Result<ExistingProfileSetupOutcome, BrowserRefusal> {
        let descriptor = existing_profile_setup_descriptor(request.browser).ok_or_else(|| {
            BrowserRefusal::new(
                BrowserRefusalCode::BrowserRouteUnavailable,
                format!(
                    "approved existing-profile setup is not implemented for {:?}",
                    request.browser
                ),
            )
        })?;
        let pid_u32 = u32::try_from(request.pid).map_err(|_| {
            BrowserRefusal::new(
                BrowserRefusalCode::BrowserWrongTargetRefused,
                "the approved browser pid is outside the Linux process-id range",
            )
        })?;
        // Window cardinality is deliberately NOT a precondition here. Setup acts
        // inside one named window, and `browser_setup_ui` proves that window's
        // identity directly by resolving the native window to exactly one
        // accessibility top-level before it matches or actuates any control. A
        // process owning several windows is the ordinary case for a browser and
        // says nothing about whether the driver can act precisely; refusing on
        // it made the whole existing-profile route unreachable for most real
        // sessions. Where identity genuinely cannot be established — a generic
        // Wayland session with no compositor window list — that same proof fails
        // and setup refuses with a reason that names the cause.
        let window_id = request.window_id;
        let listeners_before =
            tokio::task::spawn_blocking(move || loopback_ports_for_pid(request.pid))
                .await
                .map_err(|error| {
                    BrowserRefusal::new(
                        BrowserRefusalCode::BrowserRouteUnavailable,
                        format!("listener inspection task failed: {error}"),
                    )
                })??;
        let handle = tokio::task::spawn_blocking(move || {
            crate::browser_setup_ui::enable(pid_u32, window_id, descriptor)
        })
        .await
        .map_err(|error| {
            BrowserRefusal::new(
                BrowserRefusalCode::BrowserRouteUnavailable,
                format!(
                    "could not inspect {}'s remote-debugging setup UI: {error}",
                    descriptor.product_name
                ),
            )
        })??;
        let opened_setup_page = handle.opened_setup_page;
        let enabled_remote_debugging = handle.enabled_remote_debugging;
        let focused_setup_address_field = handle.focused_setup_address_field;
        let foregrounded_window = handle.foregrounded_window;
        let injected_global_input = handle.injected_global_input;

        let deadline = std::time::Instant::now() + Duration::from_secs(6);
        let endpoint_result = loop {
            match active_port_endpoint(request.pid) {
                Ok(Some(endpoint)) => break Ok(endpoint),
                Ok(None) => {}
                Err(error) => break Err(error),
            }
            let ports = match tokio::task::spawn_blocking(move || {
                loopback_ports_for_pid(request.pid)
            })
            .await
            {
                Ok(Ok(ports)) => ports,
                Ok(Err(error)) => break Err(error),
                Err(error) => {
                    break Err(BrowserRefusal::new(
                        BrowserRefusalCode::BrowserRouteUnavailable,
                        format!("listener inspection task failed: {error}"),
                    ))
                }
            };
            let mut endpoints = Vec::new();
            for port in &ports {
                if let Some(ws_url) = browser_websocket_url(*port).await {
                    endpoints.push((*port, ws_url, "/proc owner plus /json/version"));
                }
            }
            if endpoints.is_empty() {
                let correlated = ports
                    .iter()
                    .copied()
                    .filter(|port| !listeners_before.contains(port))
                    .collect::<Vec<_>>();
                if let [port] = correlated.as_slice() {
                    // Chromium's consent-gated server intentionally disables
                    // `/json/*` discovery and accepts the stable browser route
                    // without a UUID. The exact setup action plus the newly
                    // PID-owned listener proves which approval server this is.
                    endpoints.push((
                        *port,
                        format!("ws://127.0.0.1:{port}/devtools/browser"),
                        "new PID-owned approval listener correlated with exact setup",
                    ));
                } else if correlated.len() > 1 {
                    break Err(BrowserRefusal::new(
                        BrowserRefusalCode::BrowserBindingAmbiguous,
                        format!(
                            "{} exposed multiple newly correlated PID-owned listeners",
                            descriptor.product_name
                        ),
                    ));
                }
            }
            match endpoints.as_slice() {
                [(port, ws_url, detail)] => {
                    break Ok(OwnedEndpoint {
                        ws_url: ws_url.clone(),
                        http_port: Some(*port),
                        transport: EndpointTransport::LegacyJsonVersion,
                        ownership: EndpointOwnershipProof {
                            method: EndpointOwnershipMethod::ListeningSocketPid,
                            owner_pid: request.pid,
                            listener_pid: None,
                            detail: Some((*detail).to_owned()),
                        },
                    })
                }
                [] if std::time::Instant::now() < deadline => {
                    tokio::time::sleep(Duration::from_millis(100)).await;
                }
                [] => {
                    break Err(BrowserRefusal::new(
                        BrowserRefusalCode::BrowserRequiresSetup,
                        format!(
                            "{} did not expose a uniquely PID-owned loopback endpoint after the exact setup action",
                            descriptor.product_name
                        ),
                    ))
                }
                _ => {
                    break Err(BrowserRefusal::new(
                        BrowserRefusalCode::BrowserBindingAmbiguous,
                        format!(
                            "{} exposed multiple PID-owned endpoint candidates after the exact setup action",
                            descriptor.product_name
                        ),
                    ))
                }
            }
        };
        let endpoint = match endpoint_result {
            Ok(endpoint) => endpoint,
            // The toggle took, but no endpoint appeared. That is Chromium's
            // documented-by-behaviour semantics rather than a failure: "Allow
            // remote debugging for this browser instance" persists a preference
            // that the browser acts on at its NEXT launch — verified on Chrome
            // 151 by enabling it and observing no listener for 25s, then a
            // listener on 127.0.0.1 plus a DevToolsActivePort file immediately
            // after a restart with no --remote-debugging-port flag.
            //
            // Rolling back here erased the setting moments before the restart
            // that would activate it, so this path could never succeed. Keep the
            // preference, close the temporary tab, and tell the caller the one
            // thing it needs to do. The profile is armed, not broken.
            Err(error)
                if enabled_remote_debugging
                    && error.code == BrowserRefusalCode::BrowserRequiresSetup =>
            {
                let closed = tokio::task::spawn_blocking(move || handle.close_for_success())
                    .await
                    .map_err(|join_error| {
                        BrowserRefusal::new(
                            BrowserRefusalCode::BrowserRouteUnavailable,
                            format!("could not finish browser setup cleanup: {join_error}"),
                        )
                    })??;
                return Err(BrowserRefusal::new(
                    BrowserRefusalCode::BrowserRequiresSetup,
                    format!(
                        "remote debugging is now enabled for this {} profile, but {} only opens \
                         its debugging endpoint at startup. Restart the browser, then call \
                         browser_prepare again — the setting persists and does not need to be \
                         applied twice.",
                        descriptor.product_name, descriptor.product_name
                    ),
                )
                .with_detail(serde_json::json!({
                    "restart_required": true,
                    "remote_debugging_enabled": true,
                    "setup_side_effects": {
                        "opened_setup_page": opened_setup_page,
                        "closed_setup_page": closed.unwrap_or(false),
                        "enabled_remote_debugging": true,
                        "restored_remote_debugging": false,
                        "focused_setup_address_field": focused_setup_address_field,
                        "foregrounded_window": foregrounded_window,
                        "injected_global_input": injected_global_input,
                    },
                })));
            }
            Err(error) => {
                let error = tokio::task::spawn_blocking(move || handle.abort(error))
                    .await
                    .map_err(|join_error| {
                        BrowserRefusal::new(
                            BrowserRefusalCode::BrowserRouteUnavailable,
                            format!("could not roll back browser setup: {join_error}"),
                        )
                    })?;
                return Err(error);
            }
        };
        crate::browser_setup_ui::retain_pending(pid_u32, window_id, handle)?;

        Ok(ExistingProfileSetupOutcome {
            opened_setup_page,
            closed_setup_page: false,
            enabled_remote_debugging,
            used_bounded_pixel_fallback: false,
            focused_setup_address_field,
            foregrounded_window,
            injected_global_input,
            endpoint: Some(endpoint),
        })
    }

    async fn commit_existing_profile_setup(
        &self,
        request: ExistingProfileSetupRequest,
    ) -> Result<bool, BrowserRefusal> {
        let pid = u32::try_from(request.pid).map_err(|_| {
            BrowserRefusal::new(
                BrowserRefusalCode::BrowserWrongTargetRefused,
                "the approved browser pid is outside the Linux process-id range",
            )
        })?;
        tokio::task::spawn_blocking(move || {
            crate::browser_setup_ui::commit_pending(pid, request.window_id)
        })
        .await
        .map_err(|error| {
            BrowserRefusal::new(
                BrowserRefusalCode::BrowserRouteUnavailable,
                format!("could not commit exact browser setup cleanup: {error}"),
            )
        })?
    }

    fn cleanup_existing_profile_setup(
        &self,
        request: ExistingProfileSetupRequest,
    ) -> Result<bool, BrowserRefusal> {
        let descriptor = existing_profile_setup_descriptor(request.browser).ok_or_else(|| {
            BrowserRefusal::new(
                BrowserRefusalCode::BrowserRouteUnavailable,
                format!(
                    "existing-profile cleanup is not implemented for {:?}",
                    request.browser
                ),
            )
        })?;
        let pid = u32::try_from(request.pid).map_err(|_| {
            BrowserRefusal::new(
                BrowserRefusalCode::BrowserWrongTargetRefused,
                "the approved browser pid is outside the Linux process-id range",
            )
        })?;
        let window_id = request.window_id;
        run_existing_profile_cleanup(move || {
            let dismissed_before = crate::browser_consent_ui::dismiss(pid, window_id)?;
            let closed_setup_page = crate::browser_setup_ui::disable(pid, window_id, descriptor)?;
            let dismissed_after = crate::browser_consent_ui::dismiss(pid, window_id)?;
            Ok(dismissed_before || closed_setup_page || dismissed_after)
        })?
    }

    async fn abort_existing_profile_setup(
        &self,
        request: ExistingProfileSetupRequest,
        error: BrowserRefusal,
    ) -> BrowserRefusal {
        let Ok(pid) = u32::try_from(request.pid) else {
            return error;
        };
        tokio::task::spawn_blocking(move || {
            crate::browser_setup_ui::abort_pending(pid, request.window_id, error)
        })
        .await
        .unwrap_or_else(|join_error| {
            BrowserRefusal::new(
                BrowserRefusalCode::BrowserRouteUnavailable,
                format!("could not roll back exact browser setup: {join_error}"),
            )
        })
    }

    async fn handle_existing_profile_consent(
        &self,
        request: BrowserConsentRequest,
    ) -> Result<BrowserConsentOutcome, BrowserRefusal> {
        crate::browser_consent_ui::handle(request).await
    }

    async fn process_fingerprint(&self, pid: i64) -> Result<ProcessFingerprint, BrowserRefusal> {
        let (start_time, executable) = tokio::task::spawn_blocking(move || process_identity(pid))
            .await
            .map_err(|error| {
                BrowserRefusal::new(
                    BrowserRefusalCode::BrowserRouteUnavailable,
                    format!("process fingerprint task failed: {error}"),
                )
            })??;
        Ok(ProcessFingerprint {
            pid,
            start_time: Some(start_time),
            executable,
        })
    }

    async fn prepare_endpoint(
        &self,
        request: PrepareRequest,
    ) -> Result<PrepareOutcome, BrowserRefusal> {
        let Some(pid) = request.pid else {
            return Err(BrowserRefusal::new(
                BrowserRefusalCode::BrowserRequiresSetup,
                "pid-free isolated launch is handled by shared core",
            ));
        };
        if let Some(endpoint) = self.discover_owned_endpoint(pid).await? {
            return Ok(PrepareOutcome {
                action: PrepareAction::AlreadyPrepared,
                prepared_pid: Some(endpoint.ownership.owner_pid),
                endpoint: Some(endpoint),
                message: "An owned loopback DevTools endpoint is already available.".to_owned(),
                side_effects: Default::default(),
                attachment: None,
            });
        }
        Err(BrowserRefusal::new(
            BrowserRefusalCode::BrowserRequiresSetup,
            "No owned endpoint is available. Acting setup is handled by shared core only for a verified driver-owned isolated profile.",
        ))
    }
}

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

    #[test]
    fn x11_identity_and_cardinality_precede_compositor_selection() {
        let window = |xid| crate::x11::WindowInfo {
            xid,
            pid: Some(42),
            app_name: String::new(),
            title: "browser".into(),
            is_on_screen: true,
            z_index: None,
            x: 1,
            y: 2,
            width: 3,
            height: 4,
        };
        let (native, only) = select_x11_window(42, 7, vec![window(7)]).unwrap();
        assert!(native.geometry_exact && only);
        assert_eq!(native.window_id, 7);
        assert!(
            !select_x11_window(42, 7, vec![window(7), window(8)])
                .unwrap()
                .1
        );
        for id in [8, u64::from(u32::MAX) + 1] {
            let mut compositor_id = None;
            let result = select_x11_window(42, id, vec![window(7)]).or_else(|| {
                compositor_id = Some(id);
                None
            });
            assert!(result.is_none());
            assert_eq!(compositor_id, Some(id));
        }
        assert!(select_x11_window(43, 7, vec![window(7)]).is_none());
    }

    #[test]
    fn hyprland_browser_identity_requires_exact_pid_and_full_native_address() {
        let address = 0x1234_0000_0042;
        assert!(hyprland_identity_matches(42, address, 42, address));
        assert!(!hyprland_identity_matches(43, address, 42, address));
        assert!(!hyprland_identity_matches(42, 0x42, 42, address));
        assert!(!hyprland_identity_matches(42, address + 1, 42, address));
        assert!(!hyprland_identity_matches(0, address, 0, address));
        assert!(!hyprland_identity_matches(42, 0, 42, 0));
    }

    #[test]
    fn hyprland_browser_cardinality_requires_one_exact_owned_surface() {
        let address = 0x1234_0000_0042;
        assert!(hyprland_is_only_owned_window(42, address, [(42, address)]));
        assert!(hyprland_is_only_owned_window(
            42,
            address,
            [(7, address + 1), (42, address)],
        ));
        for identities in [
            vec![],
            vec![(7, address)],
            vec![(42, 0x42)],
            vec![(42, address + 1)],
            vec![(42, address), (42, address + 1)],
            vec![(42, address), (42, address)],
        ] {
            assert!(!hyprland_is_only_owned_window(42, address, identities));
        }
        assert!(!hyprland_is_only_owned_window(0, address, [(0, address)]));
        assert!(!hyprland_is_only_owned_window(42, 0, [(42, 0)]));
    }

    #[tokio::test(flavor = "multi_thread")]
    async fn existing_profile_cleanup_can_drive_atspi_runtime_from_async_session_teardown() {
        let cleaned = run_existing_profile_cleanup(|| {
            tokio::runtime::Builder::new_current_thread()
                .enable_all()
                .build()
                .expect("AT-SPI-style cleanup runtime")
                .block_on(async { true })
        })
        .expect("cleanup worker");

        assert!(cleaned);
    }

    #[tokio::test]
    async fn browser_visual_feedback_updates_the_declared_session_cursor() {
        let registry = Arc::new(cursor_overlay::CursorRegistry::new());
        let platform = LinuxBrowserPlatform::new(registry.clone());
        platform
            .visualize_browser_action(BrowserVisualAction {
                session: "browser-cursor-test".to_owned(),
                window_id: 77,
                cdp_target_id: "tab-A".to_owned(),
                tab_is_active: true,
                screen_x: Some(321.0),
                screen_y: Some(456.0),
                kind: BrowserVisualActionKind::Click,
            })
            .await;

        let state = registry
            .get("browser-cursor-test")
            .expect("browser action should materialize its session cursor");
        assert_eq!((state.x, state.y), (Some(321.0), Some(456.0)));
    }

    #[tokio::test]
    async fn inactive_tab_feedback_materializes_but_does_not_move_its_cursor() {
        let registry = Arc::new(cursor_overlay::CursorRegistry::new());
        let platform = LinuxBrowserPlatform::new(registry.clone());
        platform
            .visualize_browser_action(BrowserVisualAction {
                session: "browser-cursor-hidden".to_owned(),
                window_id: 77,
                cdp_target_id: "tab-hidden".to_owned(),
                tab_is_active: false,
                screen_x: Some(321.0),
                screen_y: Some(456.0),
                kind: BrowserVisualActionKind::Click,
            })
            .await;

        let state = registry
            .get("browser-cursor-hidden")
            .expect("browser action should establish its session-to-tab binding");
        assert!(
            state.x.is_none() && state.y.is_none(),
            "an inactive tab must not animate or move its visible cursor"
        );
    }

    #[test]
    fn isolated_browser_candidates_use_only_root_managed_payloads() {
        let candidates = isolated_browser_candidates();
        assert!(candidates.iter().all(|candidate| candidate.is_absolute()));
        assert_eq!(
            candidates,
            [
                "/opt/google/chrome/google-chrome",
                "/usr/lib/chromium/chromium",
                "/usr/lib/chromium-browser/chromium-browser",
                "/opt/microsoft/msedge/msedge",
            ]
            .map(PathBuf::from)
        );
    }

    #[test]
    fn user_owned_writable_candidate_is_not_a_trusted_installation() {
        let root = tempfile::tempdir().expect("temporary untrusted installation");
        let executable = root.path().join("google-chrome");
        std::fs::write(&executable, b"not a browser").expect("untrusted executable fixture");
        assert!(!trusted_root_owned_installation(&executable));
    }

    #[test]
    fn proc_net_parser_returns_only_loopback_listeners() {
        let input = "  sl  local_address rem_address   st tx_queue rx_queue tr tm->when retrnsmt   uid  timeout inode\n\
   0: 0100007F:2406 00000000:0000 0A 00000000:00000000 00:00000000 00000000  1000 0 12345\n\
   1: 00000000:2475 00000000:0000 0A 00000000:00000000 00:00000000 00000000  1000 0 67890\n";
        assert_eq!(
            parse_proc_net_loopback_listeners(input),
            vec![(9222, 12345)]
        );
    }

    #[test]
    fn process_family_contains_only_transitive_descendants() {
        assert_eq!(
            descendant_pids(10, [(11, 10), (12, 11), (20, 1), (21, 20)]),
            HashSet::from([10, 11, 12])
        );
    }

    #[test]
    fn classifier_covers_embedded_and_standalone_chromium() {
        assert!(is_chromium("CuaTestHarness.Electron"));
        assert!(is_chromium("chromium-browser"));
        assert!(is_chromium("msedge --remote-debugging-port=9222"));
        assert!(is_chromium("/opt/microsoft/msedge/msedge"));
        assert!(!is_chromium("firefox"));
        assert!(!is_chromium("search-worker"));
        assert!(!is_chromium("ledger-service"));
    }

    #[test]
    fn product_classification_uses_executable_identity_not_page_arguments() {
        assert_eq!(
            browser_product("/usr/lib/firefox/firefox"),
            BrowserProduct::Firefox
        );
        assert_eq!(
            browser_product("/snap/chromium/current/usr/lib/chromium-browser/chrome"),
            BrowserProduct::Chromium
        );
        assert_eq!(
            browser_product("/opt/google/chrome/chrome"),
            BrowserProduct::GoogleChrome
        );
    }
}