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.

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

//! "This machine" as a host, and the first-run onboarding choice.
//!
//! The commands are thin: [`HostCommands`] holds a [`HostBackend`] (the
//! `cua-host` library in the app, a fake in tests) plus the onboarding store.
//! Host setup installs cua-spacesd as a per-OS service that joins the cua.ai
//! relay (default) or listens on a direct `ip:port`; the account token comes
//! from the app's own sign-in session.
//!
//! Installer mode: `--mode host|client` on the app's command line (the
//! installers pass it on first launch) or the MDM file
//! `<cua home>/spaces-install-mode` preselects the onboarding choice. The user
//! still confirms in the app; nothing is installed without that.

use std::path::{Path, PathBuf};
use std::sync::Arc;

use async_trait::async_trait;
use serde::{Deserialize, Serialize};

/// MDM / installer file preselecting the onboarding choice (`host`|`client`).
pub const INSTALL_MODE_FILE: &str = "spaces-install-mode";

/// What the webview sends to `host_setup`, and its validation: the app
/// core's, shared with the SwiftUI app.
pub use cua_spaces_app_core::host::{validate_setup, HostSetupRequest};

/// `ServiceState` of the contract.
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", default)]
pub struct ServiceStateView {
    pub installed: bool,
    pub running: bool,
    pub kind: String,
    pub detail: String,
}

/// A client connected to this machine through the relay (presence).
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", default)]
pub struct ConnectedClientView {
    pub id: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub email: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    pub streams: u32,
    pub since: u64,
}

/// An OS permission the user must grant (macOS TCC panes).
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", default)]
pub struct PermissionHintView {
    pub id: String,
    /// `title` in cua-host.
    #[serde(alias = "title")]
    pub label: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub instructions: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub settings_url: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub granted: Option<bool>,
}

/// One access to this machine (the driver's access log).
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", default)]
pub struct AccessRecordView {
    pub at_ms: u64,
    pub via: String,
    pub who: String,
    pub what: String,
}

/// A Space this machine provides to one of your devices.
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", default)]
pub struct ProvidedSpaceView {
    pub relay_machine: String,
    pub local_space: String,
    pub name: String,
    pub image: String,
    pub os: String,
    pub kind: String,
    pub created_by: String,
    pub created_at_ms: u64,
}

/// One line of this machine's Spaces audit.
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", default)]
pub struct SpacesAuditView {
    pub at_ms: u64,
    pub action: String,
    pub who: String,
    pub space: String,
    pub detail: String,
}

/// A change to this machine's two settings (`None` keeps a value): the app
/// core's `host.settingChange` for a toggle.
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", default)]
pub struct HostSettingChange {
    pub share_desktop: Option<bool>,
    pub provide_spaces: Option<bool>,
}

/// `HostStatus` of the contract, as the webview sees it.
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", default)]
pub struct HostStatusView {
    pub configured: bool,
    pub mode: Option<String>,
    pub relay_url: Option<String>,
    pub direct_url: Option<String>,
    pub machine_id: Option<String>,
    pub name: Option<String>,
    pub sharing: bool,
    pub service: ServiceStateView,
    pub online: Option<bool>,
    pub clients: Vec<ConnectedClientView>,
    pub permissions: Vec<PermissionHintView>,
    pub error: Option<String>,
    pub recent_access: Vec<AccessRecordView>,
    pub access_log_error: Option<String>,
    pub share_desktop: bool,
    pub provide_spaces: bool,
    pub max_spaces: u32,
    pub max_macos_vms: u32,
    pub provided_spaces: Vec<ProvidedSpaceView>,
    pub spaces_audit: Vec<SpacesAuditView>,
    pub spaces_audit_error: Option<String>,
}

impl HostStatusView {
    /// Not configured, with an optional reason.
    pub fn unconfigured(error: Option<String>) -> Self {
        Self {
            error,
            ..Self::default()
        }
    }

    /// Converts any serializable status with the contract's camelCase shape
    /// (the `cua-host` library's `HostStatus`).
    pub fn from_serializable(status: &impl Serialize) -> Result<Self, String> {
        serde_json::to_value(status)
            .and_then(serde_json::from_value)
            .map_err(|e| format!("host status: {e}"))
    }
}

/// Host operations behind the commands.
#[async_trait]
pub trait HostBackend: Send + Sync {
    async fn status(&self) -> Result<HostStatusView, String>;
    async fn setup(&self, request: HostSetupRequest) -> Result<HostStatusView, String>;
    async fn stop_sharing(&self) -> Result<HostStatusView, String>;
    async fn start_sharing(&self) -> Result<HostStatusView, String>;
    async fn remove(&self) -> Result<(), String>;
    /// Changes what this machine shares: its desktop, and Spaces for your
    /// other devices.
    async fn configure(&self, change: HostSettingChange) -> Result<HostStatusView, String>;
}

/// First-run choice.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum OnboardingMode {
    Client,
    Host,
}

impl OnboardingMode {
    pub fn parse(value: &str) -> Option<Self> {
        match value.trim().to_ascii_lowercase().as_str() {
            "client" | "access" => Some(Self::Client),
            "host" | "unattended" => Some(Self::Host),
            _ => None,
        }
    }
}

/// What `onboarding_state` returns.
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct OnboardingState {
    pub completed: bool,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub mode: Option<OnboardingMode>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub installer_mode: Option<OnboardingMode>,
}

#[derive(Default, Serialize, Deserialize)]
struct StoredOnboarding {
    completed: bool,
    #[serde(default)]
    mode: Option<OnboardingMode>,
}

/// Onboarding state persisted in the app's config directory.
#[derive(Clone, Debug)]
pub struct OnboardingStore {
    path: PathBuf,
}

impl OnboardingStore {
    pub fn new(path: impl Into<PathBuf>) -> Self {
        Self { path: path.into() }
    }

    /// `<config dir>/onboarding.json`.
    pub fn in_dir(dir: &Path) -> Self {
        Self::new(dir.join("onboarding.json"))
    }

    pub fn path(&self) -> &Path {
        &self.path
    }

    /// The first run finished.
    pub fn completed(&self) -> bool {
        self.load().completed
    }

    fn load(&self) -> StoredOnboarding {
        std::fs::read(&self.path)
            .ok()
            .and_then(|b| serde_json::from_slice(&b).ok())
            .unwrap_or_default()
    }

    /// Settings, About, "Reset & Show": the saved first run is forgotten, so it
    /// is due from its first step. The file is removed, as the app core's reset
    /// plan says (`onboarding_reset.rs`: `onboarding.json`). Safe to run twice.
    pub fn reset(&self) -> Result<(), String> {
        match std::fs::remove_file(&self.path) {
            Ok(()) => Ok(()),
            Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(()),
            Err(e) => Err(format!("{}: {e}", self.path.display())),
        }
    }

    pub fn complete(&self, mode: OnboardingMode) -> Result<(), String> {
        if let Some(dir) = self.path.parent() {
            std::fs::create_dir_all(dir).map_err(|e| format!("{}: {e}", dir.display()))?;
        }
        let body = serde_json::to_vec_pretty(&StoredOnboarding {
            completed: true,
            mode: Some(mode),
        })
        .map_err(|e| e.to_string())?;
        std::fs::write(&self.path, body).map_err(|e| format!("{}: {e}", self.path.display()))
    }
}

/// `--mode host|client` / `--mode=host` in the process arguments.
pub fn installer_mode_from_args<I, S>(args: I) -> Option<OnboardingMode>
where
    I: IntoIterator<Item = S>,
    S: AsRef<str>,
{
    let mut args = args.into_iter();
    while let Some(arg) = args.next() {
        let arg = arg.as_ref();
        if let Some(value) = arg.strip_prefix("--mode=") {
            return OnboardingMode::parse(value);
        }
        if arg == "--mode" {
            return args.next().and_then(|v| OnboardingMode::parse(v.as_ref()));
        }
    }
    None
}

/// Machine-wide install-mode files an MDM / system installer may write
/// (the per-user `<cua home>/spaces-install-mode` wins over these).
pub fn system_install_mode_paths() -> Vec<PathBuf> {
    #[cfg(target_os = "macos")]
    return vec![PathBuf::from("/Library/Application Support/Cua").join(INSTALL_MODE_FILE)];
    #[cfg(target_os = "windows")]
    return vec![std::env::var_os("ProgramData")
        .map(PathBuf::from)
        .unwrap_or_else(|| PathBuf::from(r"C:\ProgramData"))
        .join("Cua")
        .join(INSTALL_MODE_FILE)];
    #[cfg(not(any(target_os = "macos", target_os = "windows")))]
    return vec![PathBuf::from("/etc/cua").join(INSTALL_MODE_FILE)];
}

/// Parses an install-mode file: a bare `host` / `client`, or the MSI's INI
/// form (`[spaces]` / `mode=host`).
pub fn parse_install_mode(content: &str) -> Option<OnboardingMode> {
    content
        .lines()
        .map(str::trim)
        .filter(|l| {
            !l.is_empty() && !l.starts_with('[') && !l.starts_with('#') && !l.starts_with(';')
        })
        .find_map(|line| {
            let value = match line.split_once('=') {
                Some((key, value)) if key.trim().eq_ignore_ascii_case("mode") => value,
                Some(_) => return None,
                None => line,
            };
            OnboardingMode::parse(value)
        })
}

/// The installer-preselected mode from the per-user file
/// (`<cua home>/spaces-install-mode`), then `system` files.
pub fn installer_mode_from_files(cua_home: &Path, system: &[PathBuf]) -> Option<OnboardingMode> {
    std::iter::once(cua_home.join(INSTALL_MODE_FILE))
        .chain(system.iter().cloned())
        .find_map(|path| {
            std::fs::read_to_string(path)
                .ok()
                .and_then(|s| parse_install_mode(&s))
        })
}

/// [`installer_mode_from_files`] with this OS's system locations.
pub fn installer_mode_from_file(cua_home: &Path) -> Option<OnboardingMode> {
    installer_mode_from_files(cua_home, &system_install_mode_paths())
}

/// Settings panes the webview may ask to open (permission hints, and the
/// Cua Volume file system extension's approval in Login Items &
/// Extensions). Anything else goes through `open_external` (http(s) only).
pub fn allowed_settings_url(url: &str) -> bool {
    const PREFIXES: &[&str] = &[
        "x-apple.systempreferences:com.apple.preference.security?Privacy_",
        "x-apple.systempreferences:com.apple.settings.PrivacySecurity.extension?Privacy_",
        "x-apple.systempreferences:com.apple.LoginItems-Settings.extension",
        "ms-settings:privacy",
    ];
    PREFIXES.iter().any(|p| url.starts_with(p))
        && url
            .bytes()
            // No `&`: Windows opens the pane through `cmd /C start`, and
            // cmd would read it as a command separator.
            .all(|b| b.is_ascii_alphanumeric() || b"._-:?=".contains(&b))
}

/// Everything the host/onboarding commands need.
pub struct HostCommands {
    backend: Arc<dyn HostBackend>,
    onboarding: OnboardingStore,
    installer_mode: Option<OnboardingMode>,
}

impl HostCommands {
    pub fn new(
        backend: Arc<dyn HostBackend>,
        onboarding: OnboardingStore,
        installer_mode: Option<OnboardingMode>,
    ) -> Self {
        Self {
            backend,
            onboarding,
            installer_mode,
        }
    }

    pub fn onboarding_state(&self) -> OnboardingState {
        let stored = self.onboarding.load();
        OnboardingState {
            completed: stored.completed,
            mode: stored.mode,
            installer_mode: self.installer_mode,
        }
    }

    pub fn reset_onboarding(&self) -> Result<(), String> {
        self.onboarding.reset()
    }

    pub fn complete_onboarding(&self, mode: &str) -> Result<(), String> {
        let mode = OnboardingMode::parse(mode)
            .ok_or_else(|| format!("unknown onboarding mode {mode:?} (host or client)"))?;
        self.onboarding.complete(mode)
    }

    /// Never fails: an unreachable backend reads as "not configured" with the
    /// reason, so the roster entry can still offer "Set up for access".
    pub async fn status(&self) -> HostStatusView {
        match self.backend.status().await {
            Ok(status) => status,
            Err(error) => HostStatusView::unconfigured(Some(error)),
        }
    }

    pub async fn setup(&self, request: HostSetupRequest) -> Result<HostStatusView, String> {
        let request = validate_setup(request)?;
        self.backend.setup(request).await
    }

    pub async fn stop_sharing(&self) -> Result<HostStatusView, String> {
        self.backend.stop_sharing().await
    }

    pub async fn start_sharing(&self) -> Result<HostStatusView, String> {
        self.backend.start_sharing().await
    }

    pub async fn remove(&self) -> Result<(), String> {
        self.backend.remove().await
    }

    pub async fn configure(&self, change: HostSettingChange) -> Result<HostStatusView, String> {
        if change.share_desktop.is_none() && change.provide_spaces.is_none() {
            return Err("nothing to change".into());
        }
        self.backend.configure(change).await
    }
}

/// Backend used when this build has no host support wired in.
pub struct UnavailableHost(pub String);

#[async_trait]
impl HostBackend for UnavailableHost {
    async fn status(&self) -> Result<HostStatusView, String> {
        Ok(HostStatusView::unconfigured(None))
    }
    async fn setup(&self, _: HostSetupRequest) -> Result<HostStatusView, String> {
        Err(self.0.clone())
    }
    async fn stop_sharing(&self) -> Result<HostStatusView, String> {
        Err(self.0.clone())
    }
    async fn start_sharing(&self) -> Result<HostStatusView, String> {
        Err(self.0.clone())
    }
    async fn remove(&self) -> Result<(), String> {
        Err(self.0.clone())
    }
    async fn configure(&self, _: HostSettingChange) -> Result<HostStatusView, String> {
        Err(self.0.clone())
    }
}

/// Opens an allow-listed OS settings pane (only ever on a user click).
pub fn open_settings_url(url: &str) -> Result<(), String> {
    if !allowed_settings_url(url) {
        return Err("not a permission settings pane".into());
    }
    #[cfg(target_os = "macos")]
    let mut command = {
        let mut c = std::process::Command::new("open");
        c.arg(url);
        c
    };
    #[cfg(target_os = "windows")]
    let mut command = {
        let mut c = std::process::Command::new("cmd");
        c.args(["/C", "start", "", url]);
        c
    };
    #[cfg(not(any(target_os = "macos", target_os = "windows")))]
    let mut command = {
        let mut c = std::process::Command::new("xdg-open");
        c.arg(url);
        c
    };
    command
        .spawn()
        .map(|_| ())
        .map_err(|e| format!("failed to open {url}: {e}"))
}

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

    #[test]
    fn installer_mode_parsing() {
        assert_eq!(
            installer_mode_from_args(["app", "--mode", "host"]),
            Some(OnboardingMode::Host)
        );
        assert_eq!(
            installer_mode_from_args(["app", "--mode=client"]),
            Some(OnboardingMode::Client)
        );
        assert_eq!(installer_mode_from_args(["app", "--mode", "bogus"]), None);
        assert_eq!(installer_mode_from_args(["app"]), None);
        let dir = tempfile::tempdir().unwrap();
        let system = dir.path().join("system-mode");
        let sys = [system.clone()];
        assert_eq!(installer_mode_from_files(dir.path(), &sys), None);
        // MSI INI form in the machine-wide file.
        std::fs::write(&system, "[spaces]\r\nmode=client\r\n").unwrap();
        assert_eq!(
            installer_mode_from_files(dir.path(), &sys),
            Some(OnboardingMode::Client)
        );
        // The per-user file (NSIS / MDM) wins.
        std::fs::write(dir.path().join(INSTALL_MODE_FILE), "HOST\n").unwrap();
        assert_eq!(
            installer_mode_from_files(dir.path(), &sys),
            Some(OnboardingMode::Host)
        );
        assert_eq!(parse_install_mode("other=host"), None);
        assert_eq!(
            parse_install_mode("# comment\nclient"),
            Some(OnboardingMode::Client)
        );
    }

    #[test]
    fn settings_urls_are_allowlisted() {
        assert!(allowed_settings_url(
            "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"
        ));
        assert!(allowed_settings_url(
            "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility"
        ));
        assert!(!allowed_settings_url("file:///etc/passwd"));
        assert!(!allowed_settings_url(
            "x-apple.systempreferences:com.apple.preference.security?Privacy_A; rm"
        ));
        assert!(!allowed_settings_url("https://example.com"));
        assert!(allowed_settings_url("ms-settings:privacy-webcam"));
        // Cua Volume's FSKit extension (volume_mount_status.settings_url).
        assert!(allowed_settings_url(
            "x-apple.systempreferences:com.apple.LoginItems-Settings.extension"
        ));
        assert!(allowed_settings_url(
            "x-apple.systempreferences:com.apple.LoginItems-Settings.extension?ExtensionItems"
        ));
        assert!(!allowed_settings_url(
            "x-apple.systempreferences:com.apple.LoginItems-Settings.extension; open -a Terminal"
        ));
        assert!(!allowed_settings_url(
            "x-apple.systempreferences:com.apple.LoginItems-Settings.extensio"
        ));
        for shell in [
            "ms-settings:privacy&calc",
            "ms-settings:privacy|x",
            "ms-settings:privacy^&x",
        ] {
            assert!(!allowed_settings_url(shell), "{shell}");
        }
    }
}