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.

test(cua-driver): seed macOS Lume TCC grants

johnny2fd8bfc6dd5d
diff --git a/docs/content/docs/how-to-guides/driver/run-tests-in-macos-lume-vm.mdx b/docs/content/docs/how-to-guides/driver/run-tests-in-macos-lume-vm.mdx
index 8f9e6498b6..1871dd7d75 100644
--- a/docs/content/docs/how-to-guides/driver/run-tests-in-macos-lume-vm.mdx
+++ b/docs/content/docs/how-to-guides/driver/run-tests-in-macos-lume-vm.mdx
@@ -175,7 +175,7 @@ bash libs/cua-driver/scripts/install-local.sh --release --autostart
```
Require the message `signed staged app with a stable local identity`. Do not
-grant TCC permissions to an ad-hoc build.
+approve macOS consent for an ad-hoc build.
### Grant the seed's consent paths
@@ -207,8 +207,10 @@ Choose **Allow** for:
- Terminal controlling System Events;
- CuaDriver direct screen capture without the system picker.
-These are normal macOS consent flows. Do not edit `TCC.db`. Rerun all three
-probes and require them to finish without another prompt.
+These are normal macOS consent flows. Do not hand-edit `TCC.db` while building a
+reusable seed. The checked-in SIP-off seed helper is only for disposable workers
+that are not cloned from a granted seed. Rerun all three probes and require them
+to finish without another prompt.
Verify the app-owned grants, signature, capture result, and SIP state:
diff --git a/libs/cua-driver/docs/macos-background-input-v1-plan.md b/libs/cua-driver/docs/macos-background-input-v1-plan.md
index 30ac341015..d02119e60a 100644
--- a/libs/cua-driver/docs/macos-background-input-v1-plan.md
+++ b/libs/cua-driver/docs/macos-background-input-v1-plan.md
@@ -720,7 +720,9 @@ requirements:
- use a disposable worker cloned from the stopped private seed;
- install with `install-local.sh --release --autostart
--require-stable-signing`;
-- never edit `TCC.db`;
+- do not hand-edit `TCC.db`; a SIP-off Lume worker that is not cloned from a
+ granted seed may only use the checked-in `seed-tcc.sh` helper from the
+ canonical runner docs, before the GUI suite starts;
- execute the GUI suite from the guest's logged-in Terminal, not SSH;
- retain exact SHA, environment, code-signing requirement, permission status,
structured results, fixture journals, screenshots/recording where allowed,
@@ -801,7 +803,8 @@ plugin because it can change independently of this plan.
[`scripts/README.md`](../scripts/README.md), use an ephemeral
certificate-backed local signing identity, and install with
`--require-stable-signing`. Never copy a maintainer private key or signing
- keychain to Namespace. Never edit `TCC.db` or bypass TCC.
+ keychain to Namespace. Never edit `TCC.db` or bypass macOS consent in
+ Namespace; the SIP-off Lume helper is not a Namespace substitute.
9. Grant Accessibility and Screen Recording only through normal macOS UI if the
disposable Namespace environment and explicit test approval support it.
Record `permissions status --json` and the `codesign -d -r-` designated
diff --git a/libs/cua-driver/docs/test-matrix.md b/libs/cua-driver/docs/test-matrix.md
index f406ef8666..2cd79ec423 100644
--- a/libs/cua-driver/docs/test-matrix.md
+++ b/libs/cua-driver/docs/test-matrix.md
@@ -189,7 +189,7 @@ allowed, and the desktop-side-effect oracles pass.
| Linux Sway Harness E2E | Controlled wlroots session | `scripts/ci/linux/run-rust-e2e-wayland.sh` |
| Linux nested-compositor E2E | Controlled experimental session | `scripts/ci/linux/run-rust-e2e-inject.sh` |
| Linux representative desktop E2E | Existing GNOME, KDE, or Xorg login | `scripts/ci/linux/run-rust-e2e-desktop.sh <desktop>` |
-| macOS Harness E2E | Maintainer Lume SIP-off worker with a logged-in session and inherited grants | `libs/cua-driver/tests/runners/macos-lume/run-all.sh` |
+| macOS Harness E2E | Maintainer Lume SIP-off worker with a logged-in session and inherited grants, or a disposable worker prepared with the checked-in macOS consent seed helper | `libs/cua-driver/tests/runners/macos-lume/run-all.sh` |
Workflows select private execution lanes. Rust source owns scenario definitions,
fixture oracles, and result records. OS runners only build the driver, stage the
diff --git a/libs/cua-driver/rust/crates/cua-driver/tests/README.md b/libs/cua-driver/rust/crates/cua-driver/tests/README.md
index 195a3c06d2..eb2184b325 100644
--- a/libs/cua-driver/rust/crates/cua-driver/tests/README.md
+++ b/libs/cua-driver/rust/crates/cua-driver/tests/README.md
@@ -81,9 +81,10 @@ external-app suites remain separate.
The canonical macOS E2E entrypoint is
`libs/cua-driver/tests/runners/macos-lume/run-all.sh`. It runs in a disposable
-clone of the private maintainer seed, requires a logged-in user session, and
-verifies the installed driver's Accessibility and Screen Recording grants
-before delegating to `scripts/ci/macos/run-rust-e2e.sh`.
+clone of the private maintainer seed, or in a SIP-off worker prepared with the
+checked-in macOS consent seed helper. It requires a logged-in user session and
+verifies the installed driver's Accessibility and Screen Recording grants before
+delegating to `scripts/ci/macos/run-rust-e2e.sh`.
For focused macOS runs on a workstation shared with other driver clients,
start a TCC-authorized daemon on a dedicated socket and set
diff --git a/libs/cua-driver/scripts/tests/test_macos_lume_runner.py b/libs/cua-driver/scripts/tests/test_macos_lume_runner.py
index 25e192f6a1..267dd9d275 100644
--- a/libs/cua-driver/scripts/tests/test_macos_lume_runner.py
+++ b/libs/cua-driver/scripts/tests/test_macos_lume_runner.py
@@ -12,6 +12,7 @@ import json
import os
import re
import shutil
+import sqlite3
import subprocess
from pathlib import Path
@@ -19,6 +20,8 @@ import pytest
REPO_ROOT = Path(__file__).resolve().parents[4]
RUN_ALL = REPO_ROOT / "libs/cua-driver/tests/runners/macos-lume/run-all.sh"
+SEED_TCC = REPO_ROOT / "libs/cua-driver/tests/runners/macos-lume/seed-tcc.sh"
+SEED_TCC_GUEST = REPO_ROOT / "libs/cua-driver/tests/runners/macos-lume/seed-tcc-guest.sh"
RUN_RUST_E2E = REPO_ROOT / "scripts/ci/macos/run-rust-e2e.sh"
ELECTRON_BUILD = REPO_ROOT / "libs/cua-driver/tests/fixtures/apps/cross-platform/electron/build.sh"
ELECTRON_LOCK = (
@@ -76,7 +79,7 @@ def _fields(output: str) -> dict[str, str]:
@pytest.mark.parametrize(
"script",
- [RUN_ALL, RUN_RUST_E2E, ELECTRON_BUILD, TAURI_BUILD],
+ [RUN_ALL, RUN_RUST_E2E, SEED_TCC, SEED_TCC_GUEST, ELECTRON_BUILD, TAURI_BUILD],
ids=lambda path: f"{path.parent.name}/{path.name}",
)
def test_runner_scripts_have_valid_bash_syntax(script: Path) -> None:
@@ -180,6 +183,213 @@ def test_no_permission_mode_check_pipes_into_grep(script: Path) -> None:
assert re.search(r"\|\s*grep\s+[^\n]*-q", text) is None
+# --------------------------------------------------------------------------
+# SIP-off TCC seed helper
+# --------------------------------------------------------------------------
+
+
+def test_tcc_guest_seed_is_vm_and_sip_gated() -> None:
+ text = SEED_TCC_GUEST.read_text(encoding="utf-8")
+ assert re.search(r'\[\[ "\$\{MODEL\}" == VirtualMac\* \]\] \|\| fail', text)
+ assert "csrutil status" in text
+ assert 'fail "system TCC.db is SIP-protected' in text
+
+
+def test_tcc_guest_seed_refuses_non_virtualmac_before_tcc_access() -> None:
+ completed = subprocess.run(
+ ["bash", str(SEED_TCC_GUEST)],
+ capture_output=True,
+ text=True,
+ check=False,
+ )
+ assert completed.returncode == 2
+ assert "seed-tcc:" in completed.stderr
+ assert "sqlite3" not in completed.stderr
+
+
+def _guest_seed_assignment(name: str) -> str:
+ text = SEED_TCC_GUEST.read_text(encoding="utf-8")
+ match = re.search(rf'^{name}="(?P<body>.*?)"', text, re.DOTALL | re.MULTILINE)
+ assert match is not None
+ return match.group("body")
+
+
+def test_tcc_guest_seed_grants_both_driver_permissions() -> None:
+ text = SEED_TCC_GUEST.read_text(encoding="utf-8")
+ sql_body = _guest_seed_assignment("SQL")
+ assert re.search(
+ r"\('kTCCServiceAccessibility','\$\{CLIENT_SQL\}',\$\{CLIENT_TYPE\},2,2,1,",
+ sql_body,
+ )
+ assert re.search(
+ r"\('kTCCServiceScreenCapture','\$\{CLIENT_SQL\}',\$\{CLIENT_TYPE\},2,2,1,",
+ sql_body,
+ )
+ assert "auth_value" in sql_body
+ assert "csreq" in sql_body
+ assert "allowed" not in sql_body
+ assert "auth_value=2" in text
+ assert "com.trycua.driver.local" in text
+
+
+def test_tcc_guest_seed_sql_executes_against_modern_tcc_schema(tmp_path: Path) -> None:
+ sql_body = _guest_seed_assignment("SQL")
+ verify_sql = _guest_seed_assignment("VERIFY_SQL")
+ client = "com.trycua.driver.local"
+ client_type = "0"
+ csreq_hex = "01020304"
+ substitutions = {
+ "${CLIENT_SQL}": client,
+ "${CLIENT_TYPE}": client_type,
+ "${CSREQ_HEX}": csreq_hex,
+ }
+ for old, new in substitutions.items():
+ sql_body = sql_body.replace(old, new)
+ verify_sql = verify_sql.replace(old, new)
+
+ db = tmp_path / "TCC.db"
+ with sqlite3.connect(db) as conn:
+ conn.executescript(
+ """
+ CREATE TABLE access(
+ service TEXT NOT NULL,
+ client TEXT NOT NULL,
+ client_type INTEGER NOT NULL,
+ auth_value INTEGER,
+ auth_reason INTEGER,
+ auth_version INTEGER,
+ csreq BLOB,
+ flags INTEGER,
+ indirect_object_identifier_type INTEGER,
+ indirect_object_identifier TEXT DEFAULT 'UNUSED',
+ indirect_object_code_identity BLOB,
+ last_modified INTEGER DEFAULT 0
+ );
+ """
+ )
+ conn.executescript(sql_body)
+ row_count = conn.execute(verify_sql).fetchone()[0]
+ rows = conn.execute(
+ """
+ SELECT service, client, client_type, auth_value, auth_reason,
+ auth_version, hex(csreq), indirect_object_identifier
+ FROM access
+ ORDER BY service
+ """
+ ).fetchall()
+
+ assert row_count == 2
+ assert rows == [
+ (
+ "kTCCServiceAccessibility",
+ client,
+ 0,
+ 2,
+ 2,
+ 1,
+ csreq_hex.upper(),
+ "UNUSED",
+ ),
+ (
+ "kTCCServiceScreenCapture",
+ client,
+ 0,
+ 2,
+ 2,
+ 1,
+ csreq_hex.upper(),
+ "UNUSED",
+ ),
+ ]
+
+
+def test_tcc_guest_seed_requires_certificate_backed_requirement_by_default() -> None:
+ text = SEED_TCC_GUEST.read_text(encoding="utf-8")
+ assert '[[ "${ALLOW_ADHOC}" != 1 && "${REQUIREMENT}" != *"certificate leaf"* ]]' in text
+ assert "is not signed with a certificate-backed identity" in text
+
+
+def test_tcc_host_seed_accepts_multiple_vms() -> None:
+ text = SEED_TCC.read_text(encoding="utf-8")
+ assert 'VMS+=("$1")' in text
+ assert 'for vm in "${VMS[@]}"; do' in text
+ assert "seed-tcc-guest.sh" in text
+ assert "CUA_TCC_READ_SUDO_PASSWORD=1" in text
+
+
+def test_tcc_host_seed_runs_the_guest_helper_once_per_vm(tmp_path: Path) -> None:
+ fake_bin = tmp_path / "bin"
+ fake_lume = fake_bin / "lume"
+ fake_scp = fake_bin / "scp"
+ fake_ssh = fake_bin / "ssh"
+ log = tmp_path / "transport.log"
+ _write_executable(
+ fake_lume,
+ """printf 'lume %s\n' "$*" >> "$CUA_TEST_TRANSPORT_LOG"
+if [ "$1" = "get" ]; then
+ case "$2" in
+ worker-a) ip="192.0.2.10" ;;
+ worker-b) ip="192.0.2.11" ;;
+ *) exit 2 ;;
+ esac
+ printf '[{"name":"%s","status":"running","sshAvailable":true,"ipAddress":"%s"}]\n' "$2" "$ip"
+fi
+""",
+ )
+ _write_executable(
+ fake_scp,
+ """printf 'scp askpass=%s pass=%s %s\n' "${SSH_ASKPASS_REQUIRE:-}" "${CUA_TCC_SSH_PASSWORD:-}" "$*" >> "$CUA_TEST_TRANSPORT_LOG"
+""",
+ )
+ _write_executable(
+ fake_ssh,
+ """stdin="$(cat || true)"
+printf 'ssh askpass=%s pass=%s stdin=%s %s\n' "${SSH_ASKPASS_REQUIRE:-}" "${CUA_TCC_SSH_PASSWORD:-}" "$stdin" "$*" >> "$CUA_TEST_TRANSPORT_LOG"
+""",
+ )
+
+ completed = subprocess.run(
+ [
+ "bash",
+ str(SEED_TCC),
+ "--timeout",
+ "5",
+ "worker-a",
+ "worker-b",
+ ],
+ capture_output=True,
+ stdin=subprocess.DEVNULL,
+ text=True,
+ env={
+ **os.environ,
+ "PATH": f"{fake_bin}:/usr/bin:/bin",
+ "CUA_TEST_TRANSPORT_LOG": str(log),
+ "CUA_TCC_SUDO_PASSWORD": "fixture-password",
+ "LUME_SSH_USER": "lume",
+ "LUME_STORAGE": "",
+ },
+ check=False,
+ )
+
+ assert completed.returncode == 0, completed.stderr
+ calls = log.read_text(encoding="utf-8").splitlines()
+ assert len(calls) == 10
+ assert calls[0] == "lume get worker-a --format json"
+ assert calls[1].startswith("scp askpass=force pass=lume -o StrictHostKeyChecking=no ")
+ assert "seed-tcc-guest.sh" in calls[1]
+ assert calls[1].endswith(" [email protected]:/tmp/cua-driver-seed-tcc-guest.sh")
+ assert calls[2].endswith(" [email protected] chmod 700 /tmp/cua-driver-seed-tcc-guest.sh")
+ assert "stdin=fixture-password" in calls[3]
+ assert "CUA_TCC_READ_SUDO_PASSWORD=1 /tmp/cua-driver-seed-tcc-guest.sh" in calls[3]
+ assert calls[4].endswith(" [email protected] /bin/rm -f /tmp/cua-driver-seed-tcc-guest.sh")
+ assert calls[5] == "lume get worker-b --format json"
+ assert calls[6].endswith(" [email protected]:/tmp/cua-driver-seed-tcc-guest.sh")
+ assert calls[7].endswith(" [email protected] chmod 700 /tmp/cua-driver-seed-tcc-guest.sh")
+ assert "stdin=fixture-password" in calls[8]
+ assert "CUA_TCC_READ_SUDO_PASSWORD=1 /tmp/cua-driver-seed-tcc-guest.sh" in calls[8]
+ assert calls[9].endswith(" [email protected] /bin/rm -f /tmp/cua-driver-seed-tcc-guest.sh")
+
+
# --------------------------------------------------------------------------
# Build namespace selection
# --------------------------------------------------------------------------
diff --git a/libs/cua-driver/tests/runners/macos-lume/README.md b/libs/cua-driver/tests/runners/macos-lume/README.md
index afb3c44b29..d35d13d9c1 100644
--- a/libs/cua-driver/tests/runners/macos-lume/README.md
+++ b/libs/cua-driver/tests/runners/macos-lume/README.md
@@ -30,15 +30,20 @@ that exact commit.
- Keep the named golden VM stopped and never run tests in it directly.
- Put no repository credentials, signing secrets, or maintainer private SSH
keys in the guest. A host public key is sufficient for source sync.
-- Grant TCC permissions through `CuaDriverLocal.app`. Do not edit `TCC.db`.
+- For reusable private seeds, request the app-owned Accessibility and Screen
+ Recording grants through `CuaDriverLocal.app`. For disposable SIP-off workers
+ that are not cloned from a granted seed, use the checked-in `seed-tcc.sh`
+ helper below. Do not hand-edit `TCC.db`.
- Require a certificate-backed local signature. An ad-hoc signature invalidates
the inherited grants on the next build.
- Clone one worker per run, retrieve its evidence, then delete the worker.
-SIP-off does not grant or bypass TCC. It makes the disposable behavior lane
-repeatable while the private seed carries grants obtained through the normal
-`CuaDriverLocal.app` prompt flow. The SIP-on check below owns the separate claim that
-the supported permission flow still works with normal platform protection.
+SIP-off alone does not grant Accessibility, Screen Recording, Automation, or
+direct-capture consent. The reusable private seed still carries grants approved
+through the normal `CuaDriverLocal.app` prompt flow. The helper below is only for
+disposable SIP-off workers that need the same app-owned Accessibility and Screen
+Recording grants without preserving a granted seed. The SIP-on check below proves
+the normal user-facing permission flow still works with platform protection.
## Reuse a prepared private seed
@@ -227,7 +232,8 @@ direct-capture prompt. CuaDriverLocal app enumeration must not ask for System
Events. Target-specific Automation prompts may still appear later when a user
explicitly requests an Apple Events-backed browser or app operation; do not
pre-grant those in the seed. These are normal macOS consent flows; do not edit
-`TCC.db`. Rerun the commands and require them to finish without another prompt.
+`TCC.db` by hand while building a reusable seed. Rerun the commands and require
+them to finish without another prompt.
Notification banners can cover Tahoe's consent controls; swipe the banners away
before acting instead of clicking through them. After enabling Screen Recording,
restart the app-owned daemon once before checking status so the live process
@@ -261,6 +267,55 @@ csrutil status
```
All five commands must succeed, and `csrutil status` must report disabled.
+
+### Seed app-owned grants in disposable SIP-off workers
+
+The public [Run Cua Driver in a macOS Lume VM](https://cua.ai/docs/how-to-guides/driver/run-in-macos-lume-vm)
+guide grants macOS consent through the VM display. Keep using that prompt flow
+for reusable private seeds. For automated disposable workers that are not cloned
+from a granted seed, run the host helper after `CuaDriverLocal.app` is installed
+in each running worker with a certificate-backed identity:
+
+```bash
+WORKER_A=cua-driver-macos-e2e-a
+WORKER_B=cua-driver-macos-e2e-b
+libs/cua-driver/tests/runners/macos-lume/seed-tcc.sh "$WORKER_A" "$WORKER_B"
+```
+
+Add `--storage <name-or-path>` when the workers live outside the default Lume
+storage.
+
+The wrapper resolves each VM's IP with `lume get`, copies
+`seed-tcc-guest.sh` with `scp`, then runs it with `ssh` and guest `sudo`.
+Use the default `lume` SSH password, set `LUME_SSH_PASSWORD`, or pass
+`--ssh-password`. Password mode uses OpenSSH's askpass path; leave the password
+empty when the VM accepts host SSH keys.
+The guest helper refuses to write unless `sysctl -n hw.model` reports a
+`VirtualMac*` VM and `csrutil status` reports disabled SIP. It derives the
+permission identity from `/Applications/CuaDriverLocal.app`, writes only the
+Accessibility and Screen Recording entries for that app, restarts `tccd`, and
+verifies both entries.
+
+After seeding, restart `CuaDriverLocal.app` before checking permission status if
+`install-local --autostart` or an earlier probe may have started the daemon:
+
+```bash
+~/.local/bin/cua-driver-local stop
+open -a CuaDriverLocal
+```
+
+If the VM sudo password is not the default `lume`, pass it without putting it
+on the command line:
+
+```bash
+printf '%s\n' "$VM_SUDO_PASSWORD" \
+ | libs/cua-driver/tests/runners/macos-lume/seed-tcc.sh \
+ --sudo-password-stdin "$WORKER_A" "$WORKER_B"
+```
+
+This helper is for SIP-off disposable VMs only. Keep the SIP-on permission-flow
+check below as the proof that the normal user-facing consent path still works.
+
Stop the builder and clone it to a date/version-named private seed plus two
stopped backups:
diff --git a/libs/cua-driver/tests/runners/macos-lume/seed-tcc-guest.sh b/libs/cua-driver/tests/runners/macos-lume/seed-tcc-guest.sh
new file mode 100755
index 0000000000..b58633a755
--- /dev/null
+++ b/libs/cua-driver/tests/runners/macos-lume/seed-tcc-guest.sh
@@ -0,0 +1,229 @@
+#!/usr/bin/env bash
+# Guest-side helper: derive CuaDriver's signed requirement and seed system TCC.
+set -euo pipefail
+
+TCC_DB="/Library/Application Support/com.apple.TCC/TCC.db"
+APP_PATH="${CUA_TCC_APP_PATH:-/Applications/CuaDriverLocal.app}"
+BINARY_PATH="${CUA_TCC_BINARY_PATH:-}"
+EXPECTED_CLIENT="${CUA_TCC_EXPECTED_CLIENT:-com.trycua.driver.local}"
+ALLOW_ADHOC="${CUA_TCC_ALLOW_ADHOC:-0}"
+READ_SUDO_PASSWORD="${CUA_TCC_READ_SUDO_PASSWORD:-0}"
+
+usage() {
+ cat <<'USAGE'
+Usage: seed-tcc-guest.sh [--app PATH] [--binary PATH]
+ [--expected-client ID] [--allow-adhoc]
+
+Run inside a SIP-disabled Lume macOS VM. Seeds kTCCServiceAccessibility and
+kTCCServiceScreenCapture into the system TCC database for the signed CuaDriver
+app identity. The script refuses to run outside VirtualMac or with SIP enabled.
+
+Pass --app /path/to/binary without --binary for a path-type test grant; also
+pass --expected-client with that binary's canonical path. When --app points to
+an app bundle, --binary may only name that bundle's executable.
+USAGE
+}
+
+while (($#)); do
+ case "$1" in
+ --app)
+ if (($# < 2)); then echo "--app requires a value" >&2; exit 2; fi
+ APP_PATH="$2"; shift
+ ;;
+ --app=*) APP_PATH="${1#*=}" ;;
+ --binary)
+ if (($# < 2)); then echo "--binary requires a value" >&2; exit 2; fi
+ BINARY_PATH="$2"; shift
+ ;;
+ --binary=*) BINARY_PATH="${1#*=}" ;;
+ --expected-client)
+ if (($# < 2)); then echo "--expected-client requires a value" >&2; exit 2; fi
+ EXPECTED_CLIENT="$2"; shift
+ ;;
+ --expected-client=*) EXPECTED_CLIENT="${1#*=}" ;;
+ --allow-adhoc) ALLOW_ADHOC=1 ;;
+ -h|--help) usage; exit 0 ;;
+ *) echo "unknown argument: $1" >&2; usage >&2; exit 2 ;;
+ esac
+ shift
+done
+
+fail() {
+ echo "seed-tcc: $*" >&2
+ exit 2
+}
+
+canonical_path() {
+ local path="$1"
+ local dir
+ local base
+ dir="$(/usr/bin/dirname "${path}")"
+ base="$(/usr/bin/basename "${path}")"
+ (cd "${dir}" && printf '%s/%s\n' "$(/bin/pwd -P)" "${base}")
+}
+
+bundle_executable_path() {
+ local app="$1"
+ local info_plist="${app}/Contents/Info.plist"
+ local executable_name
+ [[ -d "${app}" ]] || fail "app bundle is missing: ${app}"
+ [[ -f "${info_plist}" ]] || fail "missing Info.plist at ${info_plist}"
+ executable_name="$(/usr/libexec/PlistBuddy -c 'Print :CFBundleExecutable' "${info_plist}" 2>/dev/null || true)"
+ [[ -n "${executable_name}" ]] || fail "CFBundleExecutable is missing from ${info_plist}"
+ printf '%s/Contents/MacOS/%s\n' "${app}" "${executable_name}"
+}
+
+sql_escape() {
+ /usr/bin/sed "s/'/''/g" <<< "$1"
+}
+
+run_sudo() {
+ if [[ "$(/usr/bin/id -u)" -eq 0 ]]; then
+ "$@"
+ elif [[ -n "${SUDO_PASSWORD_CACHE:-}" ]]; then
+ printf '%s\n' "${SUDO_PASSWORD_CACHE}" | /usr/bin/sudo -S -p '' "$@"
+ else
+ /usr/bin/sudo -n "$@"
+ fi
+}
+
+MODEL="$(/usr/sbin/sysctl -n hw.model 2>/dev/null || true)"
+[[ "${MODEL}" == VirtualMac* ]] || fail "refusing to edit TCC outside a Lume/VirtualMac guest (hw.model=${MODEL:-unknown})"
+
+SIP_STATUS="$(/usr/bin/csrutil status 2>&1 || true)"
+[[ "${SIP_STATUS}" == *"System Integrity Protection status: disabled."* ]] \
+ || [[ "${SIP_STATUS}" == *"status: disabled"* ]] \
+ || fail "system TCC.db is SIP-protected; expected SIP disabled, got: ${SIP_STATUS}"
+
+[[ -n "${EXPECTED_CLIENT}" ]] || fail "--expected-client must not be empty"
+
+CLIENT_TYPE=1
+CLIENT=""
+BUNDLE_ID=""
+SIGN_TARGET=""
+if [[ -n "${APP_PATH}" && -d "${APP_PATH}" ]]; then
+ INFO_PLIST="${APP_PATH}/Contents/Info.plist"
+ APP_EXECUTABLE_PATH="$(bundle_executable_path "${APP_PATH}")"
+ if [[ -n "${BINARY_PATH}" ]]; then
+ [[ -x "${BINARY_PATH}" ]] || fail "CuaDriver executable is missing or not executable: ${BINARY_PATH}"
+ RESOLVED_BINARY_PATH="$(canonical_path "${BINARY_PATH}")"
+ RESOLVED_APP_EXECUTABLE_PATH="$(canonical_path "${APP_EXECUTABLE_PATH}")"
+ [[ "${RESOLVED_BINARY_PATH}" == "${RESOLVED_APP_EXECUTABLE_PATH}" ]] \
+ || fail "--binary must match ${APP_PATH}'s CFBundleExecutable (${APP_EXECUTABLE_PATH}); got ${BINARY_PATH}"
+ else
+ BINARY_PATH="${APP_EXECUTABLE_PATH}"
+ [[ -x "${BINARY_PATH}" ]] || fail "CuaDriver executable is missing or not executable: ${BINARY_PATH}"
+ fi
+ BUNDLE_ID="$(/usr/libexec/PlistBuddy -c 'Print :CFBundleIdentifier' "${INFO_PLIST}" 2>/dev/null || true)"
+ [[ -n "${BUNDLE_ID}" ]] || fail "CFBundleIdentifier is missing from ${INFO_PLIST}"
+ CLIENT_TYPE=0
+ CLIENT="${BUNDLE_ID}"
+ SIGN_TARGET="${APP_PATH}"
+else
+ [[ "${APP_PATH}" != *.app ]] || fail "app bundle is missing: ${APP_PATH}"
+ [[ -z "${BINARY_PATH}" ]] \
+ || fail "--binary requires --app to point at an app bundle; omit --binary and pass the executable path as --app for a path-type grant"
+ BINARY_PATH="${APP_PATH}"
+ [[ -x "${BINARY_PATH}" ]] || fail "CuaDriver executable is missing or not executable: ${BINARY_PATH}"
+ CLIENT="$(canonical_path "${BINARY_PATH}")"
+ SIGN_TARGET="${CLIENT}"
+fi
+
+VERIFY_INFO=""
+if ! VERIFY_INFO="$(/usr/bin/codesign --verify --deep --strict "${SIGN_TARGET}" 2>&1)"; then
+ fail "codesign verification failed for ${SIGN_TARGET}: ${VERIFY_INFO}"
+fi
+
+CODESIGN_INFO=""
+if ! CODESIGN_INFO="$(/usr/bin/codesign -dvvv "${SIGN_TARGET}" 2>&1)"; then
+ fail "could not read codesign metadata from ${SIGN_TARGET}: ${CODESIGN_INFO}"
+fi
+SIGNING_IDENTIFIER="$(/usr/bin/awk -F= '/^Identifier=/ { print $2; exit }' <<< "${CODESIGN_INFO}")"
+[[ -n "${SIGNING_IDENTIFIER}" ]] || fail "could not read signing identifier from ${SIGN_TARGET}"
+
+[[ "${CLIENT}" == "${EXPECTED_CLIENT}" ]] \
+ || fail "TCC client mismatch: expected ${EXPECTED_CLIENT}, resolved ${CLIENT}"
+if [[ "${CLIENT_TYPE}" == 0 ]]; then
+ [[ "${SIGNING_IDENTIFIER}" == "${EXPECTED_CLIENT}" ]] \
+ || fail "codesign identifier mismatch: expected ${EXPECTED_CLIENT}, got ${SIGNING_IDENTIFIER}"
+fi
+
+REQUIREMENT_INFO=""
+if ! REQUIREMENT_INFO="$(/usr/bin/codesign -d -r- "${SIGN_TARGET}" 2>&1)"; then
+ fail "could not read designated requirement from ${SIGN_TARGET}: ${REQUIREMENT_INFO}"
+fi
+REQUIREMENT="$(/usr/bin/awk -F 'designated => ' '/^(# )?designated =>/ { print $2; exit }' <<< "${REQUIREMENT_INFO}")"
+[[ -n "${REQUIREMENT}" ]] || fail "could not read designated requirement from ${SIGN_TARGET}"
+if [[ "${ALLOW_ADHOC}" != 1 && "${REQUIREMENT}" != *"certificate leaf"* ]]; then
+ fail "${SIGN_TARGET} is not signed with a certificate-backed identity; rerun install-local with --require-stable-signing or pass --allow-adhoc for a one-build-only grant"
+fi
+
+CSREQ_TMPDIR="$(/usr/bin/mktemp -d /tmp/cua-driver-tcc-csreq.XXXXXX)"
+cleanup() { /bin/rm -rf "${CSREQ_TMPDIR}"; }
+trap cleanup EXIT
+printf '%s\n' "${REQUIREMENT}" > "${CSREQ_TMPDIR}/requirement.txt"
+if ! /usr/bin/csreq -r "${CSREQ_TMPDIR}/requirement.txt" -b "${CSREQ_TMPDIR}/csreq.bin" >/dev/null; then
+ fail "csreq failed for ${SIGN_TARGET}'s designated requirement"
+fi
+CSREQ_HEX="$(/usr/bin/od -An -tx1 -v "${CSREQ_TMPDIR}/csreq.bin" | /usr/bin/tr -d ' \n')"
+[[ -n "${CSREQ_HEX}" ]] || fail "csreq produced an empty blob"
+
+if [[ "$(/usr/bin/id -u)" -ne 0 ]]; then
+ if /usr/bin/sudo -n -v 2>/dev/null; then
+ true
+ elif [[ "${READ_SUDO_PASSWORD}" == 1 ]]; then
+ if IFS= read -r SUDO_PASSWORD_CACHE || [[ -n "${SUDO_PASSWORD_CACHE:-}" ]]; then
+ true
+ else
+ fail "sudo password was not provided on stdin"
+ fi
+ printf '%s\n' "${SUDO_PASSWORD_CACHE}" | /usr/bin/sudo -S -p '' -v >/dev/null
+ else
+ fail "sudo is required to write ${TCC_DB}; pass the password through the host wrapper or run as root"
+ fi
+fi
+
+[[ -f "${TCC_DB}" ]] || fail "system TCC.db does not exist at ${TCC_DB}"
+ACCESS_COLUMNS="$(run_sudo /usr/bin/sqlite3 "${TCC_DB}" 'PRAGMA table_info(access);')"
+CLIENT_SQL="$(sql_escape "${CLIENT}")"
+
+if ! /usr/bin/grep -q '|auth_value|' <<< "${ACCESS_COLUMNS}"; then
+ fail "unsupported TCC access schema; expected modern auth_value column"
+fi
+
+# Keep this row shape in sync with trycua/uvisor's TCCGrant.swift system grant
+# path. Both helpers seed the same modern macOS TCC schema from a signed csreq.
+SQL="
+BEGIN;
+INSERT OR REPLACE INTO access(
+ service,client,client_type,auth_value,auth_reason,auth_version,
+ csreq,flags,indirect_object_identifier_type,
+ indirect_object_identifier,indirect_object_code_identity,last_modified
+) VALUES
+ ('kTCCServiceAccessibility','${CLIENT_SQL}',${CLIENT_TYPE},2,2,1,
+ X'${CSREQ_HEX}',0,0,'UNUSED',NULL,strftime('%s','now')),
+ ('kTCCServiceScreenCapture','${CLIENT_SQL}',${CLIENT_TYPE},2,2,1,
+ X'${CSREQ_HEX}',0,0,'UNUSED',NULL,strftime('%s','now'));
+COMMIT;
+"
+VERIFY_SQL="SELECT count(*) FROM access WHERE client='${CLIENT_SQL}' AND client_type=${CLIENT_TYPE} AND auth_value=2 AND service IN ('kTCCServiceAccessibility','kTCCServiceScreenCapture');"
+
+run_sudo /usr/bin/sqlite3 "${TCC_DB}" "${SQL}"
+ROW_COUNT="$(run_sudo /usr/bin/sqlite3 "${TCC_DB}" "${VERIFY_SQL}")"
+[[ "${ROW_COUNT}" == 2 ]] || fail "expected two granted rows for ${CLIENT}, found ${ROW_COUNT}"
+
+if run_sudo /usr/bin/pgrep -x tccd >/dev/null 2>&1; then
+ run_sudo /usr/bin/killall tccd >/dev/null \
+ || fail "seeded rows for ${CLIENT}, but failed to restart tccd; restart the VM or tccd before trusting permission status"
+ TCCD_RESTARTED=1
+else
+ TCCD_RESTARTED=0
+ echo "seed-tcc: warning: tccd was not running; no TCC cache process was restarted" >&2
+fi
+
+echo "seeded kTCCServiceAccessibility and kTCCServiceScreenCapture for ${CLIENT} (client_type=${CLIENT_TYPE})"
+echo "restart CuaDriverLocal.app before checking permissions if it was already running"
+echo "model: ${MODEL}"
+echo "sip: ${SIP_STATUS}"
+echo "csreq_bytes: $(( ${#CSREQ_HEX} / 2 ))"
+echo "tccd_restarted: ${TCCD_RESTARTED}"
diff --git a/libs/cua-driver/tests/runners/macos-lume/seed-tcc.sh b/libs/cua-driver/tests/runners/macos-lume/seed-tcc.sh
new file mode 100755
index 0000000000..1ca2031563
--- /dev/null
+++ b/libs/cua-driver/tests/runners/macos-lume/seed-tcc.sh
@@ -0,0 +1,296 @@
+#!/usr/bin/env bash
+# Host-side helper: seed CuaDriverLocal.app Accessibility + Screen Recording
+# in one or more running, SIP-disabled Lume macOS VMs.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+GUEST_HELPER="${SCRIPT_DIR}/seed-tcc-guest.sh"
+REMOTE_HELPER="/tmp/cua-driver-seed-tcc-guest.sh"
+APP_PATH="/Applications/CuaDriverLocal.app"
+BINARY_PATH=""
+EXPECTED_CLIENT="com.trycua.driver.local"
+SSH_USER="${LUME_SSH_USER:-lume}"
+SSH_PASSWORD="${LUME_SSH_PASSWORD-${VM_PASSWORD:-lume}}"
+SSH_TIMEOUT="${CUA_TCC_LUME_SSH_TIMEOUT:-120}"
+SSH_KNOWN_HOSTS="${CUA_TCC_SSH_KNOWN_HOSTS:-/dev/null}"
+STORAGE="${LUME_STORAGE:-}"
+SUDO_PASSWORD="${CUA_TCC_SUDO_PASSWORD:-${VM_PASSWORD:-lume}}"
+READ_SUDO_PASSWORD_STDIN=0
+ALLOW_ADHOC=0
+VMS=()
+ASKPASS_DIR=""
+ASKPASS_HELPER=""
+
+cleanup_local() {
+ if [[ -n "${ASKPASS_DIR}" && -d "${ASKPASS_DIR}" ]]; then
+ /bin/rm -rf "${ASKPASS_DIR}"
+ fi
+}
+trap cleanup_local EXIT
+
+usage() {
+ cat <<'USAGE'
+Usage: seed-tcc.sh [options] <vm-name> [<vm-name> ...]
+
+Seed macOS Accessibility and Screen Recording TCC rows for CuaDriverLocal.app
+inside running, SSH-reachable, SIP-disabled Lume macOS VMs. This uses the
+same SIP-off system-TCC seed model as the later uvisor `gui grant --gui`
+path; it does not install the app. Run install-local first, then run this
+from the host.
+
+Options:
+ --app PATH App bundle to grant inside the guest
+ (default: /Applications/CuaDriverLocal.app)
+ --binary PATH Executable to derive the code requirement from.
+ Defaults to CFBundleExecutable inside --app.
+ Only valid when --app names an app bundle.
+ --expected-client ID Expected TCC client identifier
+ (default: com.trycua.driver.local)
+ --allow-adhoc Allow cdhash-only ad-hoc signatures. The default
+ requires a certificate-backed local/release identity.
+ --ssh-user USER Lume SSH user (default: lume)
+ --ssh-password PASSWORD SSH password for direct ssh/scp after resolving
+ the Lume IP (default: LUME_SSH_PASSWORD,
+ VM_PASSWORD, or lume). Leave empty to use keys.
+ --timeout SECONDS Per-VM connect/copy/command timeout (default: 120)
+ --storage STORAGE Lume storage name/path to pass to lume get
+ --sudo-password-stdin Read the guest sudo password from stdin instead of
+ using CUA_TCC_SUDO_PASSWORD, VM_PASSWORD, or lume.
+ -h, --help Show this help.
+
+Example for two workers:
+ libs/cua-driver/tests/runners/macos-lume/seed-tcc.sh \
+ cua-driver-worker-a cua-driver-worker-b
+USAGE
+}
+
+shell_quote() {
+ printf '%q' "$1"
+}
+
+while (($#)); do
+ case "$1" in
+ --app)
+ if (($# < 2)); then echo "--app requires a value" >&2; exit 2; fi
+ APP_PATH="$2"; shift
+ ;;
+ --app=*) APP_PATH="${1#*=}" ;;
+ --binary)
+ if (($# < 2)); then echo "--binary requires a value" >&2; exit 2; fi
+ BINARY_PATH="$2"; shift
+ ;;
+ --binary=*) BINARY_PATH="${1#*=}" ;;
+ --expected-client)
+ if (($# < 2)); then echo "--expected-client requires a value" >&2; exit 2; fi
+ EXPECTED_CLIENT="$2"; shift
+ ;;
+ --expected-client=*) EXPECTED_CLIENT="${1#*=}" ;;
+ --allow-adhoc) ALLOW_ADHOC=1 ;;
+ --ssh-user)
+ if (($# < 2)); then echo "--ssh-user requires a value" >&2; exit 2; fi
+ SSH_USER="$2"; shift
+ ;;
+ --ssh-user=*) SSH_USER="${1#*=}" ;;
+ --ssh-password)
+ if (($# < 2)); then echo "--ssh-password requires a value" >&2; exit 2; fi
+ SSH_PASSWORD="$2"; shift
+ ;;
+ --ssh-password=*) SSH_PASSWORD="${1#*=}" ;;
+ --timeout)
+ if (($# < 2)); then echo "--timeout requires a value" >&2; exit 2; fi
+ SSH_TIMEOUT="$2"; shift
+ ;;
+ --timeout=*) SSH_TIMEOUT="${1#*=}" ;;
+ --storage)
+ if (($# < 2)); then echo "--storage requires a value" >&2; exit 2; fi
+ STORAGE="$2"; shift
+ ;;
+ --storage=*) STORAGE="${1#*=}" ;;
+ --sudo-password-stdin) READ_SUDO_PASSWORD_STDIN=1 ;;
+ -h|--help) usage; exit 0 ;;
+ --) shift; break ;;
+ -*) echo "unknown option: $1" >&2; usage >&2; exit 2 ;;
+ *) VMS+=("$1") ;;
+ esac
+ shift
+done
+
+if (($#)); then
+ VMS+=("$@")
+fi
+
+if ((${#VMS[@]} == 0)); then
+ echo "at least one VM name is required" >&2
+ usage >&2
+ exit 2
+fi
+
+if [[ ! "${SSH_TIMEOUT}" =~ ^[0-9]+$ ]]; then
+ echo "--timeout must be a non-negative integer" >&2
+ exit 2
+fi
+
+command -v lume >/dev/null 2>&1 || {
+ echo "lume is not on PATH" >&2
+ exit 2
+}
+command -v ssh >/dev/null 2>&1 || {
+ echo "ssh is not on PATH" >&2
+ exit 2
+}
+command -v scp >/dev/null 2>&1 || {
+ echo "scp is not on PATH" >&2
+ exit 2
+}
+command -v python3 >/dev/null 2>&1 || {
+ echo "python3 is not on PATH" >&2
+ exit 2
+}
+if [[ "${SSH_TIMEOUT}" != 0 && ! -x /usr/bin/perl ]]; then
+ echo "/usr/bin/perl is required to enforce --timeout; pass --timeout 0 to disable the command timeout" >&2
+ exit 2
+fi
+
+if [[ ! -f "${GUEST_HELPER}" ]]; then
+ echo "missing guest helper: ${GUEST_HELPER}" >&2
+ exit 2
+fi
+
+if ((READ_SUDO_PASSWORD_STDIN)); then
+ if IFS= read -r SUDO_PASSWORD || [[ -n "${SUDO_PASSWORD}" ]]; then
+ true
+ else
+ echo "--sudo-password-stdin was set but stdin was empty" >&2
+ exit 2
+ fi
+fi
+
+resolve_lume_ip() {
+ local vm="$1"
+ local args=(get "${vm}" --format json)
+ local info
+ if [[ -n "${STORAGE}" ]]; then
+ args+=(--storage "${STORAGE}")
+ fi
+ info="$(lume "${args[@]}")"
+ python3 -c '
+import json
+import sys
+
+name = sys.argv[1]
+payload = json.load(sys.stdin)
+vm = payload[0] if isinstance(payload, list) and payload else payload
+status = vm.get("status")
+ip = vm.get("ipAddress")
+ssh_available = vm.get("sshAvailable")
+if status != "running" or not ip:
+ print(f"{name}: expected running VM with an IP, got status={status!r} ip={ip!r}", file=sys.stderr)
+ sys.exit(1)
+if ssh_available is False:
+ print(f"{name}: SSH is not available yet", file=sys.stderr)
+ sys.exit(1)
+print(ip)
+' "${vm}" <<< "${info}"
+}
+
+ssh_base_opts() {
+ printf '%s\0' \
+ -o StrictHostKeyChecking=no \
+ -o "UserKnownHostsFile=${SSH_KNOWN_HOSTS}" \
+ -o LogLevel=ERROR \
+ -o "ConnectTimeout=${SSH_TIMEOUT}"
+}
+
+ensure_askpass_helper() {
+ if [[ -n "${ASKPASS_HELPER}" ]]; then
+ return
+ fi
+ ASKPASS_DIR="$(/usr/bin/mktemp -d /tmp/cua-driver-tcc-askpass.XXXXXX)"
+ ASKPASS_HELPER="${ASKPASS_DIR}/askpass.sh"
+ cat > "${ASKPASS_HELPER}" <<'ASKPASS'
+#!/bin/sh
+printf '%s\n' "$CUA_TCC_SSH_PASSWORD"
+ASKPASS
+ chmod 700 "${ASKPASS_HELPER}"
+}
+
+run_with_timeout() {
+ if [[ "${SSH_TIMEOUT}" == 0 ]]; then
+ "$@"
+ else
+ /usr/bin/perl -e 'alarm shift; exec @ARGV' "${SSH_TIMEOUT}" "$@"
+ fi
+}
+
+run_ssh() {
+ local ip="$1"
+ local command="$2"
+ local target="${SSH_USER}@${ip}"
+ local opts=()
+ local opt
+ while IFS= read -r -d '' opt; do
+ opts+=("${opt}")
+ done < <(ssh_base_opts)
+ if [[ -n "${SSH_PASSWORD}" ]]; then
+ opts+=(-o PreferredAuthentications=password -o PubkeyAuthentication=no -o NumberOfPasswordPrompts=1)
+ ensure_askpass_helper
+ DISPLAY="${DISPLAY:-:0}" \
+ SSH_ASKPASS="${ASKPASS_HELPER}" \
+ SSH_ASKPASS_REQUIRE=force \
+ CUA_TCC_SSH_PASSWORD="${SSH_PASSWORD}" \
+ run_with_timeout ssh "${opts[@]}" "${target}" "${command}"
+ else
+ opts+=(-o BatchMode=yes)
+ run_with_timeout ssh "${opts[@]}" "${target}" "${command}"
+ fi
+}
+
+copy_to_guest() {
+ local ip="$1"
+ local source="$2"
+ local dest="$3"
+ local target="${SSH_USER}@${ip}:${dest}"
+ local opts=()
+ local opt
+ while IFS= read -r -d '' opt; do
+ opts+=("${opt}")
+ done < <(ssh_base_opts)
+ if [[ -n "${SSH_PASSWORD}" ]]; then
+ opts+=(-o PreferredAuthentications=password -o PubkeyAuthentication=no -o NumberOfPasswordPrompts=1)
+ ensure_askpass_helper
+ DISPLAY="${DISPLAY:-:0}" \
+ SSH_ASKPASS="${ASKPASS_HELPER}" \
+ SSH_ASKPASS_REQUIRE=force \
+ CUA_TCC_SSH_PASSWORD="${SSH_PASSWORD}" \
+ run_with_timeout scp "${opts[@]}" "${source}" "${target}"
+ else
+ opts+=(-o BatchMode=yes)
+ run_with_timeout scp "${opts[@]}" "${source}" "${target}"
+ fi
+}
+
+for vm in "${VMS[@]}"; do
+ ip="$(resolve_lume_ip "${vm}")"
+ echo "[${vm}] installing guest TCC seeder"
+ copy_to_guest "${ip}" "${GUEST_HELPER}" "${REMOTE_HELPER}"
+ run_ssh "${ip}" "chmod 700 $(shell_quote "${REMOTE_HELPER}")"
+
+ remote_cmd="CUA_TCC_APP_PATH=$(shell_quote "${APP_PATH}")"
+ remote_cmd+=" CUA_TCC_BINARY_PATH=$(shell_quote "${BINARY_PATH}")"
+ remote_cmd+=" CUA_TCC_EXPECTED_CLIENT=$(shell_quote "${EXPECTED_CLIENT}")"
+ remote_cmd+=" CUA_TCC_ALLOW_ADHOC=${ALLOW_ADHOC}"
+ remote_cmd+=" CUA_TCC_READ_SUDO_PASSWORD=1"
+ remote_cmd+=" $(shell_quote "${REMOTE_HELPER}")"
+
+ echo "[${vm}] seeding Accessibility + Screen Recording for ${EXPECTED_CLIENT}"
+ set +e +o pipefail
+ printf '%s\n' "${SUDO_PASSWORD}" | run_ssh "${ip}" "${remote_cmd}"
+ pipe_status=("${PIPESTATUS[@]}")
+ set -e -o pipefail
+ ssh_status="${pipe_status[1]}"
+ run_ssh "${ip}" "/bin/rm -f $(shell_quote "${REMOTE_HELPER}")" >/dev/null 2>&1 || true
+ if [[ "${ssh_status}" -ne 0 ]]; then
+ exit "${ssh_status}"
+ fi
+ echo "[${vm}] done"
+done