Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
// 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
);
}
}