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.

feat(platform-macos): port PermissionsGate CLI flow for first-launch UX (#1527) (#1529)

Francesco Bonacci0df35d72a2b7
diff --git a/docs/content/docs/cua-driver/guide/getting-started/installation.mdx b/docs/content/docs/cua-driver/guide/getting-started/installation.mdx
index 9d7069c83d..d97b62cc00 100644
--- a/docs/content/docs/cua-driver/guide/getting-started/installation.mdx
+++ b/docs/content/docs/cua-driver/guide/getting-started/installation.mdx
@@ -75,6 +75,29 @@ cua-driver check_permissions
If a grant still reads `NOT granted` after granting in the dialog, open **System Settings → Privacy & Security**, find `CuaDriver.app` under Accessibility and Screen Recording, and flip the toggle.
+<Callout type="info">
+ **First-launch permissions gate (`cua-driver serve`).** On the Rust port,
+ `cua-driver serve` runs an interactive permissions gate at startup. If
+ Accessibility or Screen Recording is missing it prints a banner, auto-opens
+ the matching System Settings pane, and polls until you grant the missing
+ items. When both grants are already active the gate is a transparent no-op.
+
+ **CI / headless runners** should skip the gate so the daemon does not block
+ waiting for a TTY-attached human:
+
+ ```bash
+ # As a flag …
+ cua-driver serve --no-permissions-gate
+
+ # … or as an env-var.
+ CUA_DRIVER_RS_PERMISSIONS_GATE=0 cua-driver serve
+ ```
+
+ Accepted "off" values for the env-var (case-insensitive): `0`, `false`,
+ `no`, `off` — so `FALSE`, `Off`, `NO` etc. all work. Any other value
+ (including unset) leaves the gate active.
+</Callout>
+
## Requirements
- macOS 14 (Sonoma) or later
diff --git a/docs/content/docs/cua-driver/reference/cli-reference.mdx b/docs/content/docs/cua-driver/reference/cli-reference.mdx
index 9bba78d283..3fbb866803 100644
--- a/docs/content/docs/cua-driver/reference/cli-reference.mdx
+++ b/docs/content/docs/cua-driver/reference/cli-reference.mdx
@@ -142,6 +142,13 @@ Subsequent `cua-driver call/list-tools/describe` invocations auto-detect
the socket and forward their requests, so the AppStateEngine's per-pid
element_index cache survives across CLI calls.
+On macOS, `serve` runs a **first-launch permissions gate** before binding
+the socket. When TCC grants for Accessibility or Screen Recording are
+missing, it prints a banner listing exactly what is missing, auto-opens
+the matching `System Settings → Privacy & Security` pane(s), and polls
+every second until the user grants both. When grants are already active
+the gate is a transparent no-op.
+
**Options:**
| Name | Type | Default | Description |
@@ -153,6 +160,7 @@ element_index cache survives across CLI calls.
| Name | Description |
| ---- | ----------- |
| `--no-relaunch` | Stay in the current process instead of re-execing via `open -n -g -a CuaDriver`. |
+| `--no-permissions-gate` | Skip the macOS TCC permissions gate at startup. Use for CI / headless runners where blocking on user input would deadlock the process. Also toggleable by setting `CUA_DRIVER_RS_PERMISSIONS_GATE` to any of `0`, `false`, `no`, or `off` (case-insensitive — e.g. `CUA_DRIVER_RS_PERMISSIONS_GATE=FALSE` works too). |
### cua-driver stop
diff --git a/libs/cua-driver-rs/PARITY.md b/libs/cua-driver-rs/PARITY.md
index 0bf07cf3e1..29a952f2f3 100644
--- a/libs/cua-driver-rs/PARITY.md
+++ b/libs/cua-driver-rs/PARITY.md
@@ -242,6 +242,66 @@ status).
---
+## Startup flow: permissions gate (`serve`)
+- Swift: `libs/cua-driver/Sources/CuaDriverCore/Permissions/PermissionsGate.swift`
+ (SwiftUI panel + AppKit window + 1 Hz polling)
+- Rust:
+ - macos=`crates/platform-macos/src/permissions/gate.rs`
+ (CLI banner + auto-open System Settings + 1 Hz polling)
+ - windows / linux: N/A — TCC is a macOS concept; the `--no-permissions-gate`
+ flag is accepted and silently ignored on those platforms for CLI uniformity.
+- Status:
+ - macos: PORTED with intentional UX divergence (CLI, not SwiftUI)
+ - windows / linux: N/A
+
+### Intentional UX divergence
+
+Swift surfaces a branded SwiftUI window on first launch. The Rust port
+ships a terminal-driven banner instead. Rationale:
+
+1. cua-driver-rs already drives an AppKit run loop on the main thread
+ for the cursor overlay; bolting on a second window invites
+ main-thread deadlocks.
+2. The Rust binary's primary deployment shape is the daemon under
+ `cua-driver serve` from a shell (Claude Code, Cursor, Codex), which
+ already has a terminal attached.
+3. Headless / CI use cases need an opt-out; a CLI flow with
+ `--no-permissions-gate` + `CUA_DRIVER_RS_PERMISSIONS_GATE=0` is the
+ straight-line approach. Replicating Swift's window only to suppress
+ it under headless would be more code with no UX upside.
+
+The CLI gate still preserves the substantive Swift behaviours:
+
+- Lists exactly which TCC grants are missing (Accessibility / Screen
+ Recording), with the same rationale strings the SwiftUI panel uses.
+- Opens both `x-apple.systempreferences:` URLs at once so the user can
+ grant both in a single Settings visit. (Swift's "chain to next pane
+ when one flips green" trick is unnecessary when both panes are
+ pre-opened.)
+- Polls at 1 Hz, identical cadence to the Swift `Timer`.
+- Auto-continues startup the moment all required grants are green.
+
+### Opt-out signals
+
+| Signal | Effect |
+| --------------------------------------- | ----------- |
+| `--no-permissions-gate` flag | gate skipped |
+| `CUA_DRIVER_RS_PERMISSIONS_GATE=0` | gate skipped |
+| `CUA_DRIVER_RS_PERMISSIONS_GATE=false` | gate skipped |
+| `CUA_DRIVER_RS_PERMISSIONS_GATE=no` | gate skipped |
+| `CUA_DRIVER_RS_PERMISSIONS_GATE=off` | gate skipped |
+| any other env value | gate active |
+
+Default deadline is 10 minutes; on timeout the gate logs an error and
+`serve` continues to start, mirroring the Swift "user closed the
+panel" path (individual tool calls then fail with the underlying TCC
+error).
+
+A native `NSAlert` via objc2 is tracked as a follow-up if the
+terminal-only flow proves insufficient; the CLI is the MVP.
+
+---
+
## MCP tool: `list_apps`
- Swift: `libs/cua-driver/Sources/CuaDriverServer/Tools/ListAppsTool.swift:6-71`
+ `libs/cua-driver/Sources/CuaDriverCore/Apps/AppInfo.swift`
diff --git a/libs/cua-driver-rs/crates/cua-driver/src/cli.rs b/libs/cua-driver-rs/crates/cua-driver/src/cli.rs
index 4215bdfff3..c22e324a03 100644
--- a/libs/cua-driver-rs/crates/cua-driver/src/cli.rs
+++ b/libs/cua-driver-rs/crates/cua-driver/src/cli.rs
@@ -22,7 +22,14 @@ pub enum Command {
Describe(String),
Call { tool: String, json_args: Option<serde_json::Value>, screenshot_out_file: Option<String> },
McpConfig { client: Option<String> },
- Serve { socket: Option<String> },
+ Serve {
+ socket: Option<String>,
+ /// True when `--no-permissions-gate` is on argv. The env-var
+ /// `CUA_DRIVER_RS_PERMISSIONS_GATE=0` short-circuits the gate too
+ /// (checked inside the gate itself), so the flag is only one of
+ /// two opt-out signals.
+ no_permissions_gate: bool,
+ },
Stop { socket: Option<String> },
Status { socket: Option<String> },
Recording { subcommand: String, args: Vec<String>, socket: Option<String> },
@@ -93,7 +100,11 @@ pub fn parse_command() -> Command {
None | Some("mcp") => Command::Mcp,
Some("list-tools") => Command::ListTools,
Some("mcp-config") => Command::McpConfig { client: mcp_client },
- Some("serve") => Command::Serve { socket },
+ Some("serve") => Command::Serve {
+ socket,
+ // Bare flag — present anywhere on argv counts as "skip the gate".
+ no_permissions_gate: args.iter().any(|a| a == "--no-permissions-gate"),
+ },
Some("stop") => Command::Stop { socket },
Some("status") => Command::Status { socket },
Some("recording") => {
diff --git a/libs/cua-driver-rs/crates/cua-driver/src/main.rs b/libs/cua-driver-rs/crates/cua-driver/src/main.rs
index c8f8504187..a6c629ea01 100644
--- a/libs/cua-driver-rs/crates/cua-driver/src/main.rs
+++ b/libs/cua-driver-rs/crates/cua-driver/src/main.rs
@@ -84,7 +84,25 @@ fn main() {
cli::run_call(reg, &tool, json_args, screenshot_out_file);
return;
}
- cli::Command::Serve { socket } => {
+ cli::Command::Serve { socket, no_permissions_gate } => {
+ // First-launch permissions gate (Swift PermissionsGate parity).
+ // Runs on every `serve` start; no-op when both grants are
+ // already active. Honors --no-permissions-gate and
+ // CUA_DRIVER_RS_PERMISSIONS_GATE=0 for CI / headless.
+ //
+ // Failures (e.g. deadline elapsed without grants) are logged
+ // and the daemon continues to start — individual tool calls
+ // will then fail with the underlying TCC error, mirroring
+ // Swift's "user closed the panel" fallback.
+ let gate_opts = platform_macos::permissions::GateOpts::from_env_and_flag(
+ no_permissions_gate,
+ );
+ if let Err(e) = platform_macos::permissions::run_if_needed(gate_opts) {
+ eprintln!("[cua-driver] permissions gate: {e}");
+ eprintln!("[cua-driver] continuing serve startup anyway — \
+ expect tool calls touching AX or Screen Recording \
+ to fail until you grant the missing TCC permissions.");
+ }
mcp_server::recording::set_screenshot_fn(|window_id, pid| {
if let Some(wid) = window_id {
platform_macos::capture::screenshot_window_bytes(wid as u32).ok()
@@ -251,7 +269,11 @@ fn main() -> anyhow::Result<()> {
}).join().ok();
return Ok(());
}
- cli::Command::Serve { socket } => {
+ cli::Command::Serve { socket, no_permissions_gate } => {
+ // The Rust permissions gate is macOS-only (TCC concept).
+ // On Windows / Linux the flag is silently accepted for
+ // CLI uniformity and ignored.
+ let _ = no_permissions_gate;
// Serve mode needs the cursor overlay just like MCP mode.
let cursor_cfg = cursor_overlay::CursorConfig::from_args();
let reg = Arc::new(build_registry(cursor_cfg));
diff --git a/libs/cua-driver-rs/crates/platform-macos/src/lib.rs b/libs/cua-driver-rs/crates/platform-macos/src/lib.rs
index c3e469faa9..cf8d92bef1 100644
--- a/libs/cua-driver-rs/crates/platform-macos/src/lib.rs
+++ b/libs/cua-driver-rs/crates/platform-macos/src/lib.rs
@@ -23,6 +23,8 @@ pub mod browser;
#[cfg(target_os = "macos")]
pub mod focus_steal;
#[cfg(target_os = "macos")]
+pub mod permissions;
+#[cfg(target_os = "macos")]
pub mod tools;
use mcp_server::tool::ToolRegistry;
diff --git a/libs/cua-driver-rs/crates/platform-macos/src/permissions/gate.rs b/libs/cua-driver-rs/crates/platform-macos/src/permissions/gate.rs
new file mode 100644
index 0000000000..2e0fdf02da
--- /dev/null
+++ b/libs/cua-driver-rs/crates/platform-macos/src/permissions/gate.rs
@@ -0,0 +1,503 @@
+//! First-launch permissions gate — CLI flow.
+//!
+//! Rust port of Swift's `PermissionsGate` (SwiftUI panel + polling). The
+//! Rust port intentionally drops the SwiftUI window and reimplements the
+//! flow as a terminal-only experience:
+//!
+//! 1. Inspect TCC state on `serve` startup.
+//! 2. If any required grant is missing, print a clear explanation
+//! (which grant, why cua-driver needs it, what to do next).
+//! 3. Open the relevant `System Settings` pane(s) via the
+//! `x-apple.systempreferences:` URL scheme.
+//! 4. Poll TCC state every second. Emit a "still waiting" line every
+//! 5 seconds so the user knows the daemon is still alive and what
+//! it is waiting for.
+//! 5. As soon as everything flips green, print a confirmation and
+//! return — `serve` proceeds normally.
+//!
+//! Opt-out: `--no-permissions-gate` flag or
+//! `CUA_DRIVER_RS_PERMISSIONS_GATE` set to `0` / `false` / `no` / `off`
+//! (case-insensitive) skips the entire flow. Intended for CI / headless
+//! automation where blocking on user input would deadlock the runner.
+//!
+//! Why no GUI window: the Swift gate uses AppKit + SwiftUI which would
+//! require a full overlay + NSApplication run loop just to display a
+//! dialog. cua-driver-rs already has a separate AppKit thread for the
+//! cursor overlay, and grafting another window onto it is a recipe for
+//! main-thread deadlocks. A terminal-driven flow is uglier but reliable
+//! and works headless (with the opt-out flag), which is exactly the
+//! audience for the Rust port.
+//!
+//! A future enhancement could open a native `NSAlert` via objc2 for a
+//! more polished look — left as a follow-up; CLI is the MVP.
+
+use std::io::Write;
+use std::time::{Duration, Instant};
+
+use anyhow::Result;
+
+use crate::permissions::status::{
+ current_status, request_accessibility, request_screen_recording, PermissionsStatus,
+};
+
+/// Which TCC grant is missing. Each variant maps 1:1 to a System Settings
+/// pane URL via [`MissingPermission::settings_url`].
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum MissingPermission {
+ Accessibility,
+ ScreenRecording,
+}
+
+impl MissingPermission {
+ /// Short human-readable label used in CLI output.
+ pub fn label(self) -> &'static str {
+ match self {
+ Self::Accessibility => "Accessibility",
+ Self::ScreenRecording => "Screen Recording",
+ }
+ }
+
+ /// One-line rationale shown in the missing-permission listing. Text
+ /// adapted from the Swift gate's SwiftUI subtitle copy.
+ pub fn rationale(self) -> &'static str {
+ match self {
+ Self::Accessibility =>
+ "lets cua-driver read the accessibility tree of running apps and \
+ send clicks / keystrokes via AX RPC.",
+ Self::ScreenRecording =>
+ "lets cua-driver capture per-window screenshots so agents can see \
+ the current UI state alongside the tree.",
+ }
+ }
+
+ /// `x-apple.systempreferences:` URL that deep-links into the matching
+ /// Privacy pane. Same strings the Swift gate uses.
+ pub fn settings_url(self) -> &'static str {
+ match self {
+ Self::Accessibility =>
+ "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility",
+ Self::ScreenRecording =>
+ "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture",
+ }
+ }
+}
+
+/// All missing required permissions, derived from a [`PermissionsStatus`]
+/// snapshot. Returns an empty vec when everything is granted.
+pub fn missing_from_status(status: PermissionsStatus) -> Vec<MissingPermission> {
+ let mut out = Vec::new();
+ if !status.accessibility {
+ out.push(MissingPermission::Accessibility);
+ }
+ if !status.screen_recording {
+ out.push(MissingPermission::ScreenRecording);
+ }
+ out
+}
+
+/// Inspect live TCC state and return whatever is missing. Convenience
+/// wrapper around `missing_from_status(current_status())`.
+pub fn check_required_permissions() -> Vec<MissingPermission> {
+ missing_from_status(current_status())
+}
+
+/// Open the System Settings pane for a single permission via `open(1)`.
+///
+/// macOS routes `x-apple.systempreferences:` URLs through `System Settings`
+/// automatically — same mechanism the Swift gate uses via `NSWorkspace.open`.
+pub fn open_system_settings_for(permission: MissingPermission) -> Result<()> {
+ let status = std::process::Command::new("open")
+ .arg(permission.settings_url())
+ .status()?;
+ if !status.success() {
+ anyhow::bail!(
+ "`open {}` exited with status {:?}",
+ permission.settings_url(),
+ status.code()
+ );
+ }
+ Ok(())
+}
+
+/// Knobs for [`run_if_needed`]. Defaults are tuned for an interactive
+/// `serve` startup; CI callers should set `opt_out = true` (either via
+/// the `--no-permissions-gate` flag or the env-var honored by
+/// [`GateOpts::from_env_and_flag`]).
+#[derive(Debug, Clone)]
+pub struct GateOpts {
+ /// When `true` the gate is a no-op even if permissions are missing.
+ pub opt_out: bool,
+ /// Cap the polling phase so a forgotten daemon does not hang
+ /// forever. `None` means "wait indefinitely" — matches Swift's
+ /// SwiftUI panel which has no built-in timeout. Default: 10 min.
+ pub deadline: Option<Duration>,
+ /// How often to re-check TCC state. Default: 1s — same cadence as
+ /// the Swift gate's `Timer.scheduledTimer(withTimeInterval: 1.0)`.
+ pub poll_interval: Duration,
+ /// How often to print a "still waiting for X" status line. Default:
+ /// 5s — frequent enough to reassure the user the daemon is alive,
+ /// rare enough not to spam the terminal.
+ pub status_interval: Duration,
+ /// When `true` and a required permission is missing, also raise the
+ /// macOS TCC prompts (`AXIsProcessTrustedWithOptions` /
+ /// `CGRequestScreenCaptureAccess`). Helpful on first launch when
+ /// the process has never asked before. Default: true.
+ pub also_raise_prompts: bool,
+ /// When `true` (default), `open` the System Settings pane for the
+ /// missing permission(s). Set false to suppress the auto-open in
+ /// tests or scripted scenarios.
+ pub open_settings: bool,
+}
+
+impl Default for GateOpts {
+ fn default() -> Self {
+ Self {
+ opt_out: false,
+ deadline: Some(Duration::from_secs(10 * 60)),
+ poll_interval: Duration::from_secs(1),
+ status_interval: Duration::from_secs(5),
+ also_raise_prompts: true,
+ open_settings: true,
+ }
+ }
+}
+
+impl GateOpts {
+ /// Construct from the standard env-var
+ /// (`CUA_DRIVER_RS_PERMISSIONS_GATE` set to `0` / `false` / `no` /
+ /// `off`, case-insensitive, disables the gate) and an explicit
+ /// `--no-permissions-gate` flag. Either signal is sufficient to opt
+ /// out.
+ pub fn from_env_and_flag(no_gate_flag: bool) -> Self {
+ // Match the standard list of "off" sentinels case-insensitively so
+ // CI scripts can use any of `0`, `false`, `no`, `off`, `FALSE`,
+ // `Off`, etc. without surprises. Anything not in this set leaves
+ // the gate active — fail-safe default for first-launch UX.
+ let env_disabled = std::env::var("CUA_DRIVER_RS_PERMISSIONS_GATE")
+ .ok()
+ .map(|v| {
+ let lower = v.to_ascii_lowercase();
+ matches!(lower.as_str(), "0" | "false" | "no" | "off")
+ })
+ .unwrap_or(false);
+ Self {
+ opt_out: no_gate_flag || env_disabled,
+ ..Self::default()
+ }
+ }
+}
+
+/// Run the gate if needed. When called and the process already has both
+/// grants, this returns immediately without printing anything — the
+/// `serve` happy path is unaffected.
+///
+/// When grants are missing and `opt_out` is false:
+/// - Prints the missing-permissions banner.
+/// - Optionally raises the system TCC prompts (`also_raise_prompts`).
+/// - Opens the System Settings pane(s) for the user.
+/// - Polls TCC every `poll_interval` and re-emits a status line every
+/// `status_interval` until everything is green or `deadline` elapses.
+///
+/// Returns `Ok(())` on success (all green or opt-out). Returns
+/// `Err` only if the deadline elapsed without all permissions granted —
+/// callers may choose to continue anyway and let individual tools fail
+/// with their existing error messages, mirroring Swift's "user closes
+/// the panel" path.
+pub fn run_if_needed(opts: GateOpts) -> Result<()> {
+ if opts.opt_out {
+ tracing::debug!("permissions gate skipped (opt_out=true)");
+ return Ok(());
+ }
+
+ let initial = current_status();
+ if initial.all_granted() {
+ // Fast path: everything already green. No banner, no polling —
+ // the user sees nothing different from before this gate existed.
+ return Ok(());
+ }
+
+ let missing = missing_from_status(initial);
+ print_banner(&missing, opts.open_settings);
+
+ if opts.also_raise_prompts {
+ // These are no-ops when the grant is already active and are the
+ // documented way to fire the first-launch system dialogs. Match
+ // the behaviour of the `check_permissions` MCP tool's default path.
+ if missing.contains(&MissingPermission::Accessibility) {
+ let _ = request_accessibility();
+ }
+ if missing.contains(&MissingPermission::ScreenRecording) {
+ let _ = request_screen_recording();
+ }
+ }
+
+ if opts.open_settings {
+ // Open *both* missing panes up front. System Settings collapses
+ // duplicate-open requests to a single navigation, so this isn't
+ // disruptive even when only one grant is needed.
+ for m in &missing {
+ if let Err(e) = open_system_settings_for(*m) {
+ eprintln!(" (could not auto-open Settings for {}: {e})", m.label());
+ }
+ }
+ }
+
+ wait_for_grants(&opts)
+}
+
+/// Block until all required permissions are granted or the deadline
+/// elapses. Emits a status line every `opts.status_interval` while
+/// waiting so the user has feedback.
+///
+/// Exposed separately from [`run_if_needed`] for callers that want to
+/// drive the wait phase manually (e.g. tests that pre-skip the banner).
+pub fn wait_for_grants(opts: &GateOpts) -> Result<()> {
+ let start = Instant::now();
+ let mut last_status_print = start;
+ let mut last_missing: Vec<MissingPermission> = check_required_permissions();
+
+ loop {
+ if last_missing.is_empty() {
+ println!("[cua-driver] permissions granted — continuing startup");
+ let _ = std::io::stdout().flush();
+ return Ok(());
+ }
+
+ if let Some(deadline) = opts.deadline {
+ if start.elapsed() >= deadline {
+ anyhow::bail!(
+ "permissions gate timed out after {:?} — still missing: {}",
+ deadline,
+ fmt_missing(&last_missing)
+ );
+ }
+ }
+
+ std::thread::sleep(opts.poll_interval);
+
+ let new_missing = check_required_permissions();
+ if new_missing != last_missing {
+ // State changed (red→green, or order-flipped). Re-emit so the
+ // user sees progress without waiting for the next status tick.
+ if !new_missing.is_empty() {
+ println!(
+ "[cua-driver] progress — still waiting on: {}",
+ fmt_missing(&new_missing)
+ );
+ let _ = std::io::stdout().flush();
+ }
+ last_status_print = Instant::now();
+ last_missing = new_missing;
+ continue;
+ }
+
+ if last_status_print.elapsed() >= opts.status_interval {
+ println!(
+ "[cua-driver] still waiting on: {} \
+ (open System Settings → Privacy & Security to grant)",
+ fmt_missing(&last_missing)
+ );
+ let _ = std::io::stdout().flush();
+ last_status_print = Instant::now();
+ }
+ }
+}
+
+fn print_banner(missing: &[MissingPermission], open_settings: bool) {
+ println!();
+ println!("──────────────────────────────────────────────────────────────");
+ println!(" cua-driver needs your permission before `serve` can start");
+ println!("──────────────────────────────────────────────────────────────");
+ println!();
+ println!(" Missing TCC grant(s) for this process:");
+ for m in missing {
+ println!(" • {}", m.label());
+ println!(" {}", m.rationale());
+ }
+ println!();
+ if open_settings {
+ println!(" Opening System Settings → Privacy & Security now.");
+ } else {
+ // open_settings was suppressed by the caller — print the manual
+ // command(s) instead so the user still knows where to go. Listing
+ // each pane keeps copy-paste working when only one grant is needed.
+ println!(" Open System Settings → Privacy & Security manually, e.g.:");
+ for m in missing {
+ println!(" open \"{}\" # {}", m.settings_url(), m.label());
+ }
+ }
+ println!(" Grant each item, then this prompt will auto-continue.");
+ println!();
+ println!(" Skip this gate (CI / headless): re-run with");
+ println!(" cua-driver serve --no-permissions-gate");
+ println!(" or set CUA_DRIVER_RS_PERMISSIONS_GATE to 0/false/no/off");
+ println!(" (case-insensitive) in the environment.");
+ println!();
+ let _ = std::io::stdout().flush();
+}
+
+fn fmt_missing(missing: &[MissingPermission]) -> String {
+ missing
+ .iter()
+ .map(|m| m.label())
+ .collect::<Vec<_>>()
+ .join(", ")
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use std::sync::{Mutex, OnceLock};
+
+ /// Serializes every test that mutates `CUA_DRIVER_RS_PERMISSIONS_GATE`.
+ /// `cargo test` runs tests in parallel by default and `std::env::set_var`
+ /// / `remove_var` touch a process-global table — without this lock the
+ /// env-var tests race and produce flaky failures.
+ static TEST_ENV_MUTEX: OnceLock<Mutex<()>> = OnceLock::new();
+
+ fn env_lock() -> std::sync::MutexGuard<'static, ()> {
+ // `lock()` can only fail if a previous holder panicked. Recover the
+ // guard and keep going — the env var will be re-set/cleared by this
+ // test anyway, so a poisoned mutex carries no stale invariant.
+ TEST_ENV_MUTEX
+ .get_or_init(|| Mutex::new(()))
+ .lock()
+ .unwrap_or_else(|e| e.into_inner())
+ }
+
+ #[test]
+ fn opt_out_short_circuits_run_if_needed() {
+ // With opt_out=true the gate must return Ok(()) without touching
+ // TCC state, opening Settings, or sleeping. We can't easily assert
+ // "didn't sleep" without a clock, but we can assert that an
+ // unrealistically short deadline still produces Ok — which proves
+ // the wait loop was not entered.
+ let opts = GateOpts {
+ opt_out: true,
+ deadline: Some(Duration::from_nanos(1)),
+ poll_interval: Duration::from_secs(60),
+ status_interval: Duration::from_secs(60),
+ also_raise_prompts: false,
+ open_settings: false,
+ };
+ assert!(run_if_needed(opts).is_ok());
+ }
+
+ #[test]
+ fn env_var_disables_gate() {
+ let _guard = env_lock();
+ std::env::set_var("CUA_DRIVER_RS_PERMISSIONS_GATE", "0");
+ let opts = GateOpts::from_env_and_flag(false);
+ assert!(opts.opt_out, "env=0 must opt out");
+ std::env::remove_var("CUA_DRIVER_RS_PERMISSIONS_GATE");
+ }
+
+ #[test]
+ fn flag_disables_gate() {
+ let _guard = env_lock();
+ std::env::remove_var("CUA_DRIVER_RS_PERMISSIONS_GATE");
+ let opts = GateOpts::from_env_and_flag(true);
+ assert!(opts.opt_out, "--no-permissions-gate must opt out");
+ }
+
+ #[test]
+ fn neither_flag_nor_env_does_not_opt_out() {
+ let _guard = env_lock();
+ std::env::remove_var("CUA_DRIVER_RS_PERMISSIONS_GATE");
+ let opts = GateOpts::from_env_and_flag(false);
+ assert!(!opts.opt_out);
+ }
+
+ #[test]
+ fn env_var_truthy_values_do_not_opt_out() {
+ let _guard = env_lock();
+ // Only the explicit "off" sentinels disable the gate. Anything
+ // else (including empty string or unknown garbage) leaves the gate
+ // active — fail-safe default for first-launch UX.
+ for v in &["1", "true", "yes", "on", "garbage", ""] {
+ std::env::set_var("CUA_DRIVER_RS_PERMISSIONS_GATE", v);
+ let opts = GateOpts::from_env_and_flag(false);
+ assert!(
+ !opts.opt_out,
+ "env={v:?} must not opt out (only 0/false/no/off do)"
+ );
+ }
+ std::env::remove_var("CUA_DRIVER_RS_PERMISSIONS_GATE");
+ }
+
+ #[test]
+ fn env_var_off_sentinels_are_case_insensitive() {
+ let _guard = env_lock();
+ // Every documented off-sentinel must opt out regardless of case so
+ // CI scripts can use whatever convention they prefer.
+ for v in &[
+ "0", "false", "FALSE", "False", "no", "NO", "No", "off", "OFF", "Off", "TrUe",
+ ] {
+ std::env::set_var("CUA_DRIVER_RS_PERMISSIONS_GATE", v);
+ let opts = GateOpts::from_env_and_flag(false);
+ // "TrUe" is in the list intentionally — it must NOT opt out
+ // (it's not in the off-sentinel set), so split the assertion.
+ let expected_opt_out =
+ matches!(v.to_ascii_lowercase().as_str(), "0" | "false" | "no" | "off");
+ assert_eq!(
+ opts.opt_out, expected_opt_out,
+ "env={v:?} opt_out mismatch (expected {expected_opt_out})"
+ );
+ }
+ std::env::remove_var("CUA_DRIVER_RS_PERMISSIONS_GATE");
+ }
+
+ #[test]
+ fn missing_from_status_orders_accessibility_first() {
+ let neither = PermissionsStatus {
+ accessibility: false,
+ screen_recording: false,
+ };
+ assert_eq!(
+ missing_from_status(neither),
+ vec![
+ MissingPermission::Accessibility,
+ MissingPermission::ScreenRecording
+ ]
+ );
+
+ let only_sr = PermissionsStatus {
+ accessibility: false,
+ screen_recording: true,
+ };
+ assert_eq!(
+ missing_from_status(only_sr),
+ vec![MissingPermission::Accessibility]
+ );
+
+ let only_ax = PermissionsStatus {
+ accessibility: true,
+ screen_recording: false,
+ };
+ assert_eq!(
+ missing_from_status(only_ax),
+ vec![MissingPermission::ScreenRecording]
+ );
+
+ let all = PermissionsStatus {
+ accessibility: true,
+ screen_recording: true,
+ };
+ assert!(missing_from_status(all).is_empty());
+ }
+
+ #[test]
+ fn settings_urls_match_swift() {
+ // Verbatim parity with PermissionsGate.swift's SettingsPane enum so
+ // grant-flows opens the exact same panes on both the Swift and
+ // Rust binaries.
+ assert_eq!(
+ MissingPermission::Accessibility.settings_url(),
+ "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility"
+ );
+ assert_eq!(
+ MissingPermission::ScreenRecording.settings_url(),
+ "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"
+ );
+ }
+}
diff --git a/libs/cua-driver-rs/crates/platform-macos/src/permissions/mod.rs b/libs/cua-driver-rs/crates/platform-macos/src/permissions/mod.rs
new file mode 100644
index 0000000000..fbf043a5c1
--- /dev/null
+++ b/libs/cua-driver-rs/crates/platform-macos/src/permissions/mod.rs
@@ -0,0 +1,20 @@
+//! macOS TCC permission checks + first-launch CLI gate.
+//!
+//! Two layers:
+//! - [`status`] — low-level booleans for Accessibility / Screen Recording.
+//! - [`gate`] — startup-time interactive flow that walks the user through
+//! granting the missing permissions before `serve` binds.
+//!
+//! The gate is a Rust port of Swift's `PermissionsGate` (SwiftUI panel),
+//! re-implemented as a terminal-only flow so the Rust port does not pull in
+//! a GUI framework. See `gate.rs` for the rationale + UX shape.
+//!
+//! Mirrors `libs/cua-driver/Sources/CuaDriverCore/Permissions/`:
+//! - `Permissions.swift` → `permissions::status`
+//! - `PermissionsGate.swift` → `permissions::gate` (CLI-only)
+
+pub mod gate;
+pub mod status;
+
+pub use status::{PermissionsStatus, current_status};
+pub use gate::{GateOpts, MissingPermission, run_if_needed};
diff --git a/libs/cua-driver-rs/crates/platform-macos/src/permissions/status.rs b/libs/cua-driver-rs/crates/platform-macos/src/permissions/status.rs
new file mode 100644
index 0000000000..2b6b25c1ab
--- /dev/null
+++ b/libs/cua-driver-rs/crates/platform-macos/src/permissions/status.rs
@@ -0,0 +1,86 @@
+//! Low-level TCC permission status probes.
+//!
+//! Mirrors Swift `Permissions.currentStatus()` / `Permissions.requestAccessibility()`
+//! / `Permissions.requestScreenRecording()` — bare booleans, no UI. Used by
+//! both the `check_permissions` MCP tool and the startup permissions gate
+//! (`super::gate`).
+
+/// Snapshot of which TCC grants are active for the current process.
+///
+/// Field naming matches the JSON shape used by the `check_permissions`
+/// MCP tool: `accessibility` + `screen_recording`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub struct PermissionsStatus {
+ pub accessibility: bool,
+ #[serde(rename = "screen_recording")]
+ pub screen_recording: bool,
+}
+
+impl PermissionsStatus {
+ /// True when **both** required TCC grants are active.
+ pub fn all_granted(self) -> bool {
+ self.accessibility && self.screen_recording
+ }
+}
+
+/// Read the live TCC status for both required grants. Cheap to call
+/// repeatedly — `AXIsProcessTrusted` is a quick C function and the
+/// screen recording probe falls back to the window-enumeration heuristic
+/// when `CGPreflightScreenCaptureAccess` reports false.
+///
+/// Mirrors Swift `Permissions.currentStatus()`. Difference: Swift uses
+/// `SCShareableContent.excludingDesktopWindows` (ScreenCaptureKit) for
+/// the screen recording probe, which is unavailable from Rust without
+/// large bindings — same caveat documented in `check_permissions.rs`.
+pub fn current_status() -> PermissionsStatus {
+ PermissionsStatus {
+ accessibility: accessibility_granted(),
+ screen_recording: screen_recording_granted(),
+ }
+}
+
+/// Live AX trust state — `AXIsProcessTrusted()`.
+pub fn accessibility_granted() -> bool {
+ unsafe { crate::ax::bindings::AXIsProcessTrusted() }
+}
+
+/// Best-effort screen recording probe. Uses `CGPreflightScreenCaptureAccess`
+/// then falls back to the window-enumeration heuristic for parity with
+/// the existing `check_permissions` tool — see that file for rationale.
+pub fn screen_recording_granted() -> bool {
+ #[link(name = "CoreGraphics", kind = "framework")]
+ extern "C" {
+ fn CGPreflightScreenCaptureAccess() -> bool;
+ }
+ if unsafe { CGPreflightScreenCaptureAccess() } {
+ return true;
+ }
+ !crate::windows::all_windows().is_empty()
+}
+
+/// Raise the Accessibility TCC prompt if not yet granted. No-op when
+/// already active. Mirrors Swift `Permissions.requestAccessibility()`.
+pub fn request_accessibility() -> bool {
+ use core_foundation::base::TCFType;
+ use core_foundation::boolean::CFBoolean;
+ use core_foundation::dictionary::CFDictionary;
+ use core_foundation::string::CFString;
+
+ let key = CFString::new("AXTrustedCheckOptionPrompt");
+ let val = CFBoolean::true_value();
+ let options =
+ CFDictionary::from_CFType_pairs(&[(key.as_CFType(), val.as_CFType())]);
+ unsafe {
+ crate::ax::bindings::AXIsProcessTrustedWithOptions(options.as_concrete_TypeRef())
+ }
+}
+
+/// Raise the Screen Recording TCC prompt if not yet granted.
+/// Mirrors Swift `Permissions.requestScreenRecording()`.
+pub fn request_screen_recording() -> bool {
+ #[link(name = "CoreGraphics", kind = "framework")]
+ extern "C" {
+ fn CGRequestScreenCaptureAccess() -> bool;
+ }
+ unsafe { CGRequestScreenCaptureAccess() }
+}
diff --git a/libs/cua-driver-rs/crates/platform-macos/src/tools/check_permissions.rs b/libs/cua-driver-rs/crates/platform-macos/src/tools/check_permissions.rs
index 40e9cde230..7d87269f06 100644
--- a/libs/cua-driver-rs/crates/platform-macos/src/tools/check_permissions.rs
+++ b/libs/cua-driver-rs/crates/platform-macos/src/tools/check_permissions.rs
@@ -2,6 +2,11 @@ use async_trait::async_trait;
use mcp_server::{protocol::ToolResult, tool::{Tool, ToolDef}};
use serde_json::Value;
+use crate::permissions::status::{
+ accessibility_granted, request_accessibility, request_screen_recording,
+ screen_recording_granted,
+};
+
pub struct CheckPermissionsTool;
static DEF: std::sync::OnceLock<ToolDef> = std::sync::OnceLock::new();
@@ -45,8 +50,8 @@ impl Tool for CheckPermissionsTool {
let _ = request_accessibility();
let _ = request_screen_recording();
}
- let accessibility = unsafe { crate::ax::bindings::AXIsProcessTrusted() };
- let screen_recording = probe_screen_recording();
+ let accessibility = accessibility_granted();
+ let screen_recording = screen_recording_granted();
// Text format mirrors Swift 1:1:
// "✅ Accessibility: granted.\n✅ Screen Recording: granted."
@@ -65,45 +70,3 @@ impl Tool for CheckPermissionsTool {
}))
}
}
-
-/// Raise the Accessibility TCC prompt if not yet granted. No-op when active.
-/// Mirrors Swift `Permissions.requestAccessibility()`.
-fn request_accessibility() -> bool {
- use core_foundation::base::TCFType;
- use core_foundation::boolean::CFBoolean;
- use core_foundation::dictionary::CFDictionary;
- use core_foundation::string::CFString;
-
- let key = CFString::new("AXTrustedCheckOptionPrompt");
- let val = CFBoolean::true_value();
- let options = CFDictionary::from_CFType_pairs(&[(key.as_CFType(), val.as_CFType())]);
- unsafe {
- crate::ax::bindings::AXIsProcessTrustedWithOptions(options.as_concrete_TypeRef())
- }
-}
-
-/// Raise the Screen Recording TCC prompt if not yet granted.
-/// Mirrors Swift `Permissions.requestScreenRecording()` (`CGRequestScreenCaptureAccess`).
-fn request_screen_recording() -> bool {
- #[link(name = "CoreGraphics", kind = "framework")]
- extern "C" {
- fn CGRequestScreenCaptureAccess() -> bool;
- }
- unsafe { CGRequestScreenCaptureAccess() }
-}
-
-/// Real probe — Swift uses `SCShareableContent.excludingDesktopWindows`,
-/// which is unavailable from Rust without large ScreenCaptureKit bindings.
-/// `CGPreflightScreenCaptureAccess` returns false negatives for
-/// subprocess-launched apps but is the closest stable C API. When that
-/// returns false, fall back to the existing window-enumeration heuristic
-/// (returns content only when Screen Recording is actually granted).
-fn probe_screen_recording() -> bool {
- #[link(name = "CoreGraphics", kind = "framework")]
- extern "C" {
- fn CGPreflightScreenCaptureAccess() -> bool;
- }
- if unsafe { CGPreflightScreenCaptureAccess() } { return true; }
- let windows = crate::windows::all_windows();
- !windows.is_empty()
-}