Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
fix(cua-driver): enforce authorization in embedded SDK (#2542)
Francesco Bonacci06bda89f078e
diff --git a/docs/content/docs/concepts/sdk-mcp-and-hosting.mdx b/docs/content/docs/concepts/sdk-mcp-and-hosting.mdxindex 501b19b348..a2ba88ba36 100644--- a/docs/content/docs/concepts/sdk-mcp-and-hosting.mdx+++ b/docs/content/docs/concepts/sdk-mcp-and-hosting.mdx@@ -47,6 +47,12 @@ MCP remains valuable because it standardizes discovery, calls, results, tasks,and transport for agent runtimes; the generated language SDKs are forapplications embedding the native runtime.+Authorization is part of the native runtime, below this topology choice. A+same-process `CuaDriver.create()` call and a daemon-backed call both pass the+same registry authorization boundary before platform dispatch. MCP, HTTP, CLI,+and daemon adapters may reject a call earlier for defense in depth, but they do+not replace or weaken that native check.+## Why the daemon still existsExternal agents and CLI calls are short-lived or run outside the desktop appdiff --git a/docs/content/docs/reference/cua-driver/permission-modes.mdx b/docs/content/docs/reference/cua-driver/permission-modes.mdxindex 350250ba20..e761803d95 100644--- a/docs/content/docs/reference/cua-driver/permission-modes.mdx+++ b/docs/content/docs/reference/cua-driver/permission-modes.mdx@@ -5,9 +5,10 @@ description: Standard, bounded, and unrestricted startup modes, protected consenimport { Callout } from 'fumadocs-ui/components/callout';-Cua Driver resolves one permission mode when the daemon starts. A tool call-cannot change the mode. The mode controls when work stops for protected human-approval; permission policies still decide which calls are allowed.+Cua Driver resolves one process permission mode when a same-process runtime or+daemon starts. A tool call cannot change the mode. The mode controls when work+stops for protected human approval; permission policies still decide which+calls are allowed.## Modes@@ -32,8 +33,8 @@ Passing `--permission-mode unrestricted` without that flag still fails closed.## The authorization stack-Every daemon transport reaches the same authorization coordinator. A call-must pass each active layer:+Every same-process SDK call and daemon transport reaches the native registry's+authorization coordinator. A call must pass each active layer:1. The reviewed built-in tool and risk map.2. The administrator policy from `CUA_DRIVER_MANAGED_POLICY_FILE`, when set.@@ -45,9 +46,26 @@ Each layer can narrow access. Approval and unrestricted mode cannot widen apolicy layer. An unknown tool has no reviewed risk class and is denied.Tool-list and description responses include risk metadata with `class`,-`enforcement`, `operation_sensitive`, and `version`. The first active adapter-is `browser_prepare` with `strategy.kind=existing_profile`. Other listed risks-are `metadata_only` until their resource, output, and revocation adapters ship.+`enforcement`, `operation_sensitive`, and `version`. The top-level+`enforcement_adapters` array gives the stable adapter ID, exact operation+selectors, resource scope keys, grant TTL, indicator requirement, revocation+triggers, refusal code, and provider requirement.++The current inventory is intentionally narrow:++| Adapter | State | Meaning |+| --- | --- | --- |+| `browser_prepare.existing_profile` | `active` | Existing-profile attachment applies the mode-specific protected-consent or unrestricted path. |+| `private_observation` | `metadata_only` | User-window/display observation is classified but not protected by a shipped grant adapter. |+| `desktop_input` | `metadata_only` | Generic desktop input is classified but not protected by a shipped grant adapter. |+| `file_transfer_and_output` | `metadata_only` | Uploads, downloads, and screenshot-to-file egress are classified but not protected by a shipped grant adapter. |+| `browser_consequential_action` | `metadata_only` | Mutating dialogs and generic page actions are classified but not protected by a shipped grant adapter. |+| `devices`, `shell_and_network` | `not_exposed` | Cua Driver does not expose these open-ended capabilities. |++`metadata_only` is classification, not runtime consent enforcement. These+groups remain metadata-only until an exact resource adapter, certified+protected host, persistent Stop indicator, revocation path, and representative+platform tests all ship.## Protected consent@@ -157,6 +175,12 @@ Setting only the mode or only the acknowledgement fails before the daemonbinds. Treat these as trusted-launch configuration, not tool arguments anagent can choose at runtime.+One process still has one mode and, in bounded mode, one immutable manifest.+Shared-daemon per-session mode selection is not yet a supported security+boundary. Run one daemon per mode unless the host can supply an authenticated+session/action connection; caller-chosen session IDs are lifecycle labels, not+credentials.+## Managed controlsSet `CUA_DRIVER_MANAGED_POLICY_FILE` to apply an administrator-owned YAML or@@ -169,9 +193,10 @@ then rejects unrestricted startup even when the danger flag is present.## Status and revocation-`cua-driver status` reports the effective mode, policy hashes, session-manifest-hash and expiry, active risk adapters, and protected-provider availability. It-does not print policy contents or browser data.+`cua-driver status` reports the process mode, policy hashes, session-manifest+hash and expiry, active/metadata-only/not-exposed adapter IDs, the complete+content-free adapter inventory, and protected-provider availability. It does+not print policy contents or browser data.End one session and every grant it owns:diff --git a/docs/content/docs/reference/cua-driver/permission-policies.mdx b/docs/content/docs/reference/cua-driver/permission-policies.mdxindex a6d4291f26..6e2c29a407 100644--- a/docs/content/docs/reference/cua-driver/permission-policies.mdx+++ b/docs/content/docs/reference/cua-driver/permission-policies.mdx@@ -5,7 +5,7 @@ description: YAML and Rego permission policy schema, environment variable, evaluimport { Callout } from 'fumadocs-ui/components/callout';-Cua Driver evaluates every daemon tool call against the configured policy stack. The daemon loads policies once at process startup; the MCP proxy may repeat the user-policy check as defense in depth. CLI, MCP, and raw-socket calls share the daemon enforcement point. This page describes the user and managed policy formats. [Permission modes](/reference/cua-driver/permission-modes) control when a permitted call also needs protected approval.+Cua Driver evaluates every same-process SDK and daemon tool call against the configured policy stack at the native registry boundary. The runtime loads policies once at process startup; transport adapters may repeat an early policy check as defense in depth. SDK, CLI, MCP, and raw-socket calls cannot bypass the native enforcement point. This page describes the user and managed policy formats. [Permission modes](/reference/cua-driver/permission-modes) control when a permitted call also needs protected approval.---diff --git a/docs/content/docs/reference/cua-driver/sdk-reference.mdx b/docs/content/docs/reference/cua-driver/sdk-reference.mdxindex ece24ba288..d2dc3720cf 100644--- a/docs/content/docs/reference/cua-driver/sdk-reference.mdx+++ b/docs/content/docs/reference/cua-driver/sdk-reference.mdx@@ -24,6 +24,13 @@ asynchronous. Python uses `snake_case`; TypeScript uses `camelCase`.`claude_code_compatibility` / `claudeCodeCompatibility`, which defaults to`false`.+`create()` validates the immutable permission-mode, managed-policy,+user-policy, and bounded-manifest startup configuration before constructing+the native runtime. Every subsequent same-process call passes the same native+authorization coordinator used by daemon-backed calls. An invalid+configuration returns `DriverError.Configuration`; a denied generic call+returns a tool error with stable code `permission_denied`.+`execution_mode()` / `executionMode()` reports the generated`DriverExecutionMode` value. The current enum variants are `Embedded` for thesame-process runtime and `Daemon` for a socket-backed connection.@@ -73,8 +80,9 @@ explicit escalation before desktop tools are enabled.| `hotkey` | `hotkey` | `HotkeyInput` |Use `list_tools_json()` / `listToolsJson()` and `call_tool()` / `callTool()` for-the generic, platform-extensible tool surface. Prefer typed methods when one is-available.+the generic, platform-extensible tool surface. Its top-level+`enforcement_adapters` array distinguishes active, metadata-only, and+not-exposed permission adapters. Prefer typed methods when one is available.## `ToolResult`diff --git a/libs/cua-driver/docs/permission-adapters-and-session-modes-plan.md b/libs/cua-driver/docs/permission-adapters-and-session-modes-plan.mdnew file mode 100644index 0000000000..7fa55b6793--- /dev/null+++ b/libs/cua-driver/docs/permission-adapters-and-session-modes-plan.md@@ -0,0 +1,434 @@+# Active Permission Adapters and Trusted Per-Session Modes++**Status:** Reviewed; implementation sequencing accepted++**Issues:** #2385 and #2437++**Base:** `origin/main` at `544bff3ac739e51185dbaf465160779817dca230`++**Date:** 2026-07-24++## Goal++Finish the permission-mode model in two dimensions:++1. A trusted embedding host can run concurrent `standard`, `bounded`, and+ `unrestricted` sessions on one daemon without allowing an agent to choose or+ widen its own mode.+2. The daemon can promote reviewed capability groups from risk metadata to+ real protected-consent enforcement without duplicating policy logic or+ prompting for every action.++The public `session` argument remains a user-visible lifecycle label. It is+never authority by itself.++## Current state++- `PermissionMode` is a process-global `OnceLock` selected at daemon startup.+- `authorize_tool_call` evaluates hard invariants, managed/user policy, risk+ classification, and the process-global bounded manifest.+- Since RFC 2447, the public SDK can own a same-process native runtime and MCP,+ HTTP, CLI, and daemon transports are downstream adapters. The same-process+ `CuaDriver::create` path currently invokes the tool registry directly and+ does not pass through `authorize_tool_call`; authorization therefore has to+ move into the SDK/native-runtime dispatch boundary rather than remain a+ daemon-only concern.+- `session` is caller-declared. The daemon mirrors it into reserved arguments,+ while the MCP proxy supplies a separate transport session ID.+- The only active consent adapter is+ `browser_prepare(strategy.kind = existing_profile)`.+- `ProtectedConsentProvider` and `ApprovalBroker` are owned by `BrowserEngine`,+ so the canonical dispatch coordinator cannot use them for desktop or file+ capabilities.+- Production registries currently construct `BrowserEngine` without a+ protected provider. Standard/bounded existing-profile attachment therefore+ correctly refuses unless a certified host adapter is installed.+- The compatibility `EmbeddedCuaDriverHost` owns daemon lifecycle and a private+ parent-liveness stdin pipe, but its action transport still uses a+ path-addressed socket. The preferred `CuaDriver::create` topology is+ same-process and needs no shared-daemon session delegation at all.++## Non-negotiable security decisions++### Daemon ceiling and effective session mode are separate++The daemon starts with an immutable `SessionModeCeiling`:++- allowed session modes;+- whether unrestricted sessions were explicitly acknowledged;+- managed/user policy hashes;+- maximum session TTL and idle TTL;+- whether trusted session delegation is enabled.++Every call resolves an immutable `EffectiveAuthorizationContext` containing:++- daemon instance and generation;+- public session;+- transport session;+- effective permission mode;+- optional bounded manifest hash;+- trusted-host execution lease ID;+- policy hashes and expiry.++No context means the call inherits the daemon's legacy process mode. This keeps+standalone CLI/MCP/raw-socket behavior compatible.++### Session IDs are labels, not credentials++For the certified embedded route, delegated authority is bound to an+already-connected session channel rather than represented by a serializable+bearer token. The daemon binds the channel to the full authorization context+when the trusted host creates it. Authority never enters tool arguments,+policy input, logs, telemetry, or responses.++The following can never select a mode:++- public tool arguments or reserved-argument lookalikes;+- MCP metadata or elicitation;+- a caller-selected public or transport session ID;+- ordinary daemon control methods;+- model-visible environment variables or files.++### Only a trusted host can mint delegated sessions++The first supported minting route is the Rust-owned embedded host. It uses a+dedicated host-control channel inherited at spawn and unavailable to the+model-facing MCP stream. The channel is versioned and bound to the daemon+generation. EOF revokes every delegated session and shuts the embedded daemon+down.++The ordinary daemon listener never exposes create/upgrade mode operations.+Future native hosts may implement the same closed control protocol. Hosts that+cannot protect this channel must use one daemon per mode.++### Bind authority to an authenticated accepted connection++The pre-review recommendation is to avoid serializable bearer tokens entirely+for the certified embedded route. The trusted host creates an already-connected+session channel and supplies one endpoint to the daemon and the other to the+SDK or MCP proxy through an explicit inherited-handle allowlist. Every request+arriving on the channel inherits its immutable authorization context; no+request field can select it.++The control channel can mint a delegated session, but minting is not binding.+Binding action calls without a serializable bearer value requires either+#2410's inherited connected action transport or multiplexing action calls onto+another authenticated accepted channel. #2410 is therefore one valid+implementation, not a blanket prerequisite for the context, ceiling, control,+or inventory foundations. A path-addressed same-user socket plus a+caller-declared session ID cannot carry delegated authority.++```text+trusted host daemon model-facing proxy+ | inherited control pair | |+ |-------------------------->| |+ | create connected pair | |+ | create_session(mode, manifest, host endpoint) |+ |-------------------------->| bind context to connection |+ | inherit peer endpoint ---------------------------------->| MCP only+ | |<==== context-bound calls =====|+ | revoke / host EOF ------->| close, revoke, teardown |+```++On Unix the control plane can pass additional descriptors with `SCM_RIGHTS` or+create all required channels before spawn. On Windows the host uses an explicit+handle-inheritance/duplication allowlist in the interactive user session. The+implementation must never fall back to a discoverable named endpoint for a+session advertised as protected.++### Unrestricted remains suppress-only++An unrestricted session skips Cua runtime consent prompts, but it never widens+managed/user policy, hard invariants, identity proofs, cleanup, revocation, or+resource scoping. The daemon may host unrestricted sessions only if trusted+startup explicitly enabled and acknowledged that ceiling.++## Architecture++### 1. Session authorization registry++Add a process-owned `SessionAuthorizationRegistry` in core:++- create a delegated session from a trusted control message and bind it to the+ supplied connected endpoint;+- resolve the connection plus exact public/transport session into an immutable+ context;+- reject connection substitution, session mismatch, expiry, ended sessions,+ daemon generation mismatch, and modes outside the daemon ceiling;+- revoke one context or every context owned by a dead host lease;+- register a session-end hook so grants, indicators, browser bindings, and+ mode authority share one teardown signal.++The first foundation slice stores the context and ceiling while calls continue+to inherit the legacy process mode. Certified per-session selection remains+disabled until action calls arrive on an authenticated connection.++Per-session `bounded` also requires replacing the process-global+`SessionManifest` `OnceLock` with an immutable per-session manifest store. A+manifest hash in the context is not sufficient. Until that store exists, no+mixed-mode status or documentation may claim concurrent bounded manifests.++The registry exposes no handle or resource contents through health. Status may+report counts by mode, allowed modes, provider readiness, and ceiling+provenance.++### 2. Trusted embedded control protocol++Replace the liveness-only stdin reader with a bounded framed control reader.+The host writes versioned messages for:++- `hello` with daemon generation and protocol version;+- `create_session` with public session, requested mode, expiry, and optional+ bounded manifest;+- `revoke_session`;+- provider decision/indicator lifecycle messages in the later provider slice;+- `shutdown` or EOF.++The daemon sends acknowledgements and provider requests over a separate+inherited response handle. Neither handle is inherited by an MCP proxy or+returned in `EmbeddedDriverConnection`.++The SDK returns a host-side `EmbeddedAuthorizedSession` object owning the peer+endpoint. Its MCP launch method explicitly inherits an authenticated action+endpoint into a host-owned proxy process, or multiplexes calls over the+authenticated channel; the model sees ordinary MCP schemas only. Direct SDK+calls use the same accepted connection. A plain command/args/environment+record is insufficient for the protected path because it cannot prove handle+ownership or cleanup.++### 3. Canonical runtime authorization coordinator++Place the coordinator at the native `ToolRegistry::invoke` chokepoint (or the+immediately enclosing `DriverRuntime::invoke`) so the typed SDK, daemon, MCP,+HTTP, CLI, and raw-socket routes cannot bypass it. This corrects an+authorization omission in the RFC 2447 implementation: the canonical+same-process SDK path currently reaches the registry without calling+`authorize_tool_call`.++Replace the process-global lookup inside `authorize_tool_call` with:++1. sanitize reserved arguments;+2. resolve connection-bound authority into `EffectiveAuthorizationContext`;+3. enforce hard invariants;+4. intersect managed, user, and optional session policy;+5. classify the exact operation;+6. route active classifications through the typed enforcement adapter;+7. invoke the tool only after the adapter returns an active grant or confirms+ unrestricted coverage.++The daemon transport supplies authenticated connection context to that runtime+coordinator. In-process SDK runtimes use a trusted constructor-owned context+and do not pretend to be shared daemons. Transport adapters may reject early+but can never mint or satisfy authority.++### 4. Generic protected grant broker++Move provider ownership out of `BrowserEngine` into a daemon-owned+`AuthorizationCoordinator`. Generalize the current broker request with a typed+`ProtectedResource` enum and a canonical resource digest.++The current `ConsentRequest`, digest binding, `IndicatorLease`, and revocation+primitives are retained. The missing work is coordinator ownership and a+certified production host adapter, not reinvention of those primitives.++Initial resources:++- `ExistingBrowserProfile { pid, window_id, fingerprint, endpoint_owner }`;+- `UserWindowObservation { pid, window_id }`;+- `DesktopObservation { display_generation }`;+- `UserWindowInput { pid, window_id, delivery_ceiling }`;+- `DesktopInput { display_generation, delivery_ceiling }`;+- `BrowserFileTransfer { binding, tab, paths_or_destination_digest }`;+- `BrowserConsequentialAction { binding, tab, action_kind }`.++Grants are bound to daemon generation, effective session, transport session,+mode, policy hashes, exact resource digest, expiry, indicator lease, and+revocation generation. They contain no raw typed text, page content, file+contents, or screenshot data.++### 5. Stable enforcement adapter inventory++Replace the hard-coded status string with a machine-readable inventory. Each+entry declares:++- operation selector and risk class;+- state: `active`, `metadata_only`, or `not_exposed`;+- resource kind and scope keys;+- grant type and TTL;+- indicator requirement;+- revocation triggers;+- stable refusal code;+- supported modes and required provider capability.++`tools/list`, authorization status, and generated docs derive from the same+inventory. Unknown tools and unrecognized operation variants remain denied.++## Adapter rollout for the currently exposed surface++### Group A: private observation++Prepare scoped adapters for user-owned `get_window_state`,+`get_accessibility_tree`, and `get_desktop_state`. Keep their public state+`metadata_only` until #2411 and representative platform certification pass.++- Driver-owned/disposable resources remain prompt-free.+- Standard obtains one window/display grant and reuses it inside scope.+- Bounded requires a manifest entry and activates the indicator without a+ second prompt.+- Unrestricted skips the prompt but retains session/resource binding.+- Screenshot-to-file arguments are file egress and are covered by Group C,+ never by an observation-only grant.++### Group B: desktop input++Prepare click, typing, key, pointer, scroll, drag, focus, and set-value routes.+Keep user-owned enforcement `metadata_only` until #2411 and platform+certification pass.++- Window-targeted AX/PX/background/foreground variants map to one exact+ window-input resource with a delivery ceiling.+- Desktop coordinate input maps to a display resource.+- Foreground delivery is a scope expansion unless already approved.+- Cua consent/indicator UI and known OS security prompts remain hard-denied.+- Coordinate input is semantically opaque; the adapter does not claim to+ detect purchases, sends, deletes, or account changes.++### Group C: browser file and consequential routes++Prepare `browser_set_input_files`, `browser_download`, screenshot-to-file,+mutating `browser_dialog`, and mutating `page` operations. Keep them+`metadata_only` until #2411 and platform certification pass.++- Bind file grants to canonical paths and the exact browser binding/tab.+- Prevent aliases, generic page operations, and raw routes from bypassing the+ typed adapter.+- Operations whose consequence cannot be bounded are refused in standard and+ bounded rather than silently treated as ordinary input.++### Not currently exposed++Microphone, camera, generic shell, and generic network tools are not part of+the current registry. The inventory records them as `not_exposed`; no dormant+adapter or unsupported public claim is added.++## Intervention behavior++- Standard: one approval per exact user-owned window/display/browser-file+ scope; no prompt for repeated ordinary actions within that grant. Foreground+ escalation, a new app/window/display, file destination, or consequential+ action may require a new approval.+- Bounded: one trusted session creation/manifest approval; no runtime prompts+ inside the manifest, but persistent indication remains mandatory.+- Unrestricted: one trusted host launch/session selection acknowledgement; no+ Cua runtime prompts.++## Delivery sequence++1. **Canonical SDK/runtime authorization boundary:** eliminate the direct-SDK+ bypass introduced by the new native-core topology while preserving typed+ SDK behavior.+2. **Generic coordinator and inventory (#2385 P0):** context-aware canonical+ dispatch, generic broker ownership, generated active/metadata inventory,+ and stable refusal vocabulary.+3. **Provider ownership refactor:** hoist the existing `ApprovalBroker` out of+ `BrowserEngine` without adding a new active group.+4. **Trusted session authority foundation (#2437):** context model, daemon+ ceiling, immutable per-session manifest store, status, teardown, and+ adversarial tests while mode still inherits legacy configuration.+5. **Authenticated session minting and action binding:** private embedded+ control channel plus either #2410 or actions on that authenticated channel.+6. **Embedded protected provider dependency (#2411):** exact request/response,+ persistent indicator leases, Stop, channel-death revocation, and packaged+ host contract.+7. **Observation and input adapters (#2385 P1):** exact resource extraction,+ grant reuse, foreground expansion, self-target refusal, and platform tests.+8. **File/consequential adapters (#2385 P2/P4):** browser upload/download,+ dialog/page mutations, path constraints, and bypass tests.+9. **Docs and support claims:** expected intervention counts, embedding guide,+ status reference, migration, and unsupported-host fallback.++Keep the slices in dependency order and reviewable. Do not activate a group+until its provider, indicator, revocation, bypass, and platform matrix pass.++## Verification++### Deterministic tests++- mode-ceiling lattice and policy intersection;+- delegated session creation only through the trusted control seam;+- tool/MCP/reserved-argument mode injection denied;+- wrong connection/session/transport/generation, replay, expiry,+ reconnect, and cross-session substitution denied;+- concurrent standard/bounded/unrestricted calls preserve isolation;+- standard grant reuse stays within exact scope;+- bounded manifests cannot self-amend or auto-accept `ask`;+- unrestricted cannot widen a denial;+- active inventory matches every registered tool/alias and generated docs;+- indicator failure and host-control EOF revoke before further side effects.++### Integration and representative environments++- public MCP, CLI, raw socket, same-process SDK, and compatibility-daemon SDK+ calls all reach the same coordinator;+- embedded host creates mixed-mode sessions while the model-facing schemas+ contain no mode/token fields;+- standard without a certified provider returns a stable refusal and produces+ no side effect;+- macOS logged-in VM validates TCC attribution, protected host UI, Stop, and+ window/display observation/input scopes;+- Windows runs in a verified interactive RDP session, never Session 0;+- Linux validates X11 and Wayland separately and reports missing protected UI+ as environment-unavailable before behavior assertions;+- before/after application state, focus, z-order, cursor, and input-isolation+ oracles prove each background-input row.++## Completion bar++- Mixed-mode shared-daemon sessions are supported only through a certified+ trusted host and cannot be selected from the model/tool channel.+- Every currently exposed sensitive capability is either actively enforced+ with complete adapter evidence or explicitly listed as metadata-only with a+ precise reason and no broader security claim.+- The first activated observation/input and file/consequential groups pass+ exact-head unit, integration, adversarial, and representative-platform tests.+- Documentation and machine-readable status agree on the active inventory and+ realistic human-intervention count.+- Delivery is split into dependency-ordered release-scoped pull requests; a+ local plan or unit-only result is not completion.++## Independent review outcome++Claude Code Opus reviewed the plan against+`544bff3ac739e51185dbaf465160779817dca230`. The accepted must-fix findings are:++1. close the shipping same-process SDK authorization bypass first;+2. keep user-owned capability groups `metadata_only` until #2411 and+ representative platform certification exist;+3. bind delegated authority to an authenticated accepted connection, never a+ public session string;+4. hoist provider ownership before generalizing adapters;+5. treat #2410 as one action-binding implementation, not a blanket dependency;+6. classify screenshot-to-file as egress; and+7. make concurrent bounded sessions depend on a real per-session manifest+ store.++The accepted delivery shape is a dependency-ordered PR series. Neither #2437+as a whole nor any user-owned capability group's switch to `active` can be+honestly completed in one PR.++## Prior baseline evidence++On `849e0db2118e17f80433d7a518bae8815e5ca5f6` (Cua Driver `0.11.0`), before+implementation:++- `cargo test -p cua-driver-core authorization::tests`: 10 passed;+- `cargo test -p cua-driver-core consent::tests`: 6 passed;+- `cargo test -p cua-driver-core session_manifest::tests`: 6 passed;+- `cargo test -p cua-driver-sdk embedded::tests::authorization_modes_require_explicit_acknowledgements`:+ 1 passed.++These are baseline contract checks, not evidence for the new behavior.++The plan must be re-baselined on `544bff3ac739e51185dbaf465160779817dca230`+(Cua Driver `0.12.4`) after independent review because RFC 2447 changed the+canonical runtime boundary.diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/authorization.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/authorization.rsindex 3e9c9a5036..f15d4e10f4 100644--- a/libs/cua-driver/rust/crates/cua-driver-core/src/authorization.rs+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/authorization.rs@@ -52,6 +52,7 @@ impl RiskClass {pub enum RiskEnforcement {Active,MetadataOnly,+ NotExposed,}impl RiskEnforcement {@@ -59,10 +60,244 @@ impl RiskEnforcement {match self {Self::Active => "active",Self::MetadataOnly => "metadata_only",+ Self::NotExposed => "not_exposed",}}}+/// Stable, content-free description of one permission-mode enforcement+/// adapter. This inventory is the source for status and tool discovery; it+/// deliberately distinguishes shipped enforcement from reviewed metadata and+/// capabilities that are not exposed at all.+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]+pub struct EnforcementAdapterDescriptor {+ pub id: &'static str,+ pub operations: &'static [&'static str],+ pub state: RiskEnforcement,+ pub risk_class: RiskClass,+ pub resource_kind: &'static str,+ pub scope_keys: &'static [&'static str],+ pub grant_type: Option<&'static str>,+ pub idle_ttl_seconds: Option<u64>,+ pub absolute_ttl_seconds: Option<u64>,+ pub indicator_requirement: &'static str,+ pub revocation_triggers: &'static [&'static str],+ pub refusal_code: Option<&'static str>,+ pub provider_requirement: &'static str,+}++const EXISTING_PROFILE_OPERATIONS: &[&str] = &["browser_prepare[strategy.kind=existing_profile]"];+const EXISTING_PROFILE_SCOPE_KEYS: &[&str] = &[+ "daemon_generation",+ "public_session",+ "transport_session",+ "pid",+ "window_id",+ "process_fingerprint",+ "browser_product",+ "endpoint_owner",+ "permission_mode",+ "managed_policy_sha256",+ "user_policy_sha256",+];+const EXISTING_PROFILE_REVOCATION: &[&str] = &[+ "indicator_stop",+ "session_end",+ "idle_expiry",+ "absolute_expiry",+ "policy_change",+ "process_identity_change",+ "endpoint_identity_change",+ "daemon_restart",+ "reconnect_budget_exhaustion",+];++const PRIVATE_OBSERVATION_OPERATIONS: &[&str] = &[+ "get_desktop_state[without_file_output]",+ "get_accessibility_tree",+ "get_window_state[without_file_output]",+ "page[action=get_text|query_dom]",+];+const PRIVATE_OBSERVATION_SCOPE_KEYS: &[&str] =+ &["public_session", "pid", "window_id", "display_generation"];++const DESKTOP_INPUT_OPERATIONS: &[&str] = &[+ "click",+ "double_click",+ "right_click",+ "drag",+ "scroll",+ "move_cursor",+ "mouse_button_down",+ "mouse_button_up",+ "mouse_drag",+ "parallel_mouse_drag",+ "type_text",+ "type_text_chars",+ "press_key",+ "hotkey",+ "set_value",+ "bring_to_front",+];+const DESKTOP_INPUT_SCOPE_KEYS: &[&str] = &[+ "public_session",+ "pid",+ "window_id",+ "display_generation",+ "delivery_mode_ceiling",+];++const FILE_TRANSFER_OPERATIONS: &[&str] = &[+ "browser_set_input_files",+ "browser_download",+ "get_desktop_state[with_file_output]",+ "get_window_state[with_file_output]",+];+const FILE_TRANSFER_SCOPE_KEYS: &[&str] = &[+ "public_session",+ "browser_binding",+ "tab",+ "canonical_path",+ "destination_class",+];++const CONSEQUENTIAL_OPERATIONS: &[&str] = &[+ "browser_dialog[action=accept|dismiss]",+ "page[action!=get_text|query_dom]",+];+const CONSEQUENTIAL_SCOPE_KEYS: &[&str] =+ &["public_session", "browser_binding", "tab", "action_kind"];++const SESSION_REVOCATION: &[&str] = &[+ "indicator_stop",+ "session_end",+ "expiry",+ "policy_change",+ "resource_identity_change",+ "daemon_restart",+];++pub const ENFORCEMENT_ADAPTERS: &[EnforcementAdapterDescriptor] = &[+ EnforcementAdapterDescriptor {+ id: "browser_prepare.existing_profile",+ operations: EXISTING_PROFILE_OPERATIONS,+ state: RiskEnforcement::Active,+ risk_class: RiskClass::R2,+ resource_kind: "existing_browser_profile",+ scope_keys: EXISTING_PROFILE_SCOPE_KEYS,+ grant_type: Some("existing_profile_session_grant"),+ idle_ttl_seconds: Some(30 * 60),+ absolute_ttl_seconds: Some(8 * 60 * 60),+ indicator_requirement: "required_in_standard_and_bounded",+ revocation_triggers: EXISTING_PROFILE_REVOCATION,+ refusal_code: Some("browser_consent_required"),+ provider_requirement:+ "protected_consent_in_standard; protected_indicator_in_bounded; none_in_unrestricted",+ },+ EnforcementAdapterDescriptor {+ id: "private_observation",+ operations: PRIVATE_OBSERVATION_OPERATIONS,+ state: RiskEnforcement::MetadataOnly,+ risk_class: RiskClass::R2,+ resource_kind: "user_window_or_display_observation",+ scope_keys: PRIVATE_OBSERVATION_SCOPE_KEYS,+ grant_type: None,+ idle_ttl_seconds: None,+ absolute_ttl_seconds: None,+ indicator_requirement: "not_implemented",+ revocation_triggers: SESSION_REVOCATION,+ refusal_code: None,+ provider_requirement: "certified_protected_host_not_implemented",+ },+ EnforcementAdapterDescriptor {+ id: "desktop_input",+ operations: DESKTOP_INPUT_OPERATIONS,+ state: RiskEnforcement::MetadataOnly,+ risk_class: RiskClass::R1,+ resource_kind: "user_window_or_display_input",+ scope_keys: DESKTOP_INPUT_SCOPE_KEYS,+ grant_type: None,+ idle_ttl_seconds: None,+ absolute_ttl_seconds: None,+ indicator_requirement: "not_implemented",+ revocation_triggers: SESSION_REVOCATION,+ refusal_code: None,+ provider_requirement: "certified_protected_host_not_implemented",+ },+ EnforcementAdapterDescriptor {+ id: "file_transfer_and_output",+ operations: FILE_TRANSFER_OPERATIONS,+ state: RiskEnforcement::MetadataOnly,+ risk_class: RiskClass::R3,+ resource_kind: "canonical_file_path_and_destination",+ scope_keys: FILE_TRANSFER_SCOPE_KEYS,+ grant_type: None,+ idle_ttl_seconds: None,+ absolute_ttl_seconds: None,+ indicator_requirement: "not_implemented",+ revocation_triggers: SESSION_REVOCATION,+ refusal_code: None,+ provider_requirement: "certified_protected_host_not_implemented",+ },+ EnforcementAdapterDescriptor {+ id: "browser_consequential_action",+ operations: CONSEQUENTIAL_OPERATIONS,+ state: RiskEnforcement::MetadataOnly,+ risk_class: RiskClass::R3,+ resource_kind: "typed_browser_consequential_action",+ scope_keys: CONSEQUENTIAL_SCOPE_KEYS,+ grant_type: None,+ idle_ttl_seconds: None,+ absolute_ttl_seconds: None,+ indicator_requirement: "not_implemented",+ revocation_triggers: SESSION_REVOCATION,+ refusal_code: None,+ provider_requirement: "certified_protected_host_not_implemented",+ },+ EnforcementAdapterDescriptor {+ id: "devices",+ operations: &["microphone", "camera"],+ state: RiskEnforcement::NotExposed,+ risk_class: RiskClass::Unclassified,+ resource_kind: "device_capture",+ scope_keys: &[],+ grant_type: None,+ idle_ttl_seconds: None,+ absolute_ttl_seconds: None,+ indicator_requirement: "required_before_exposure",+ revocation_triggers: &[],+ refusal_code: None,+ provider_requirement: "capability_not_exposed",+ },+ EnforcementAdapterDescriptor {+ id: "shell_and_network",+ operations: &["generic_shell", "generic_network"],+ state: RiskEnforcement::NotExposed,+ risk_class: RiskClass::Unclassified,+ resource_kind: "open_ended_external_capability",+ scope_keys: &[],+ grant_type: None,+ idle_ttl_seconds: None,+ absolute_ttl_seconds: None,+ indicator_requirement: "required_before_exposure",+ revocation_triggers: &[],+ refusal_code: None,+ provider_requirement: "capability_not_exposed",+ },+];++pub fn enforcement_adapter_inventory_json() -> Value {+ serde_json::to_value(ENFORCEMENT_ADAPTERS).expect("static adapter inventory serializes")+}++pub fn adapter_ids_with_state(state: RiskEnforcement) -> Vec<&'static str> {+ ENFORCEMENT_ADAPTERS+ .iter()+ .filter(|adapter| adapter.state == state)+ .map(|adapter| adapter.id)+ .collect()+}+#[derive(Debug, Clone, Copy, PartialEq, Eq)]pub struct RiskAssessment {pub class: RiskClass,@@ -119,9 +354,7 @@ pub fn advertised_risk_for(tool: &str) -> RiskAssessment {// Surfaces that can reveal or control sensitive local/authenticated// state. Most remain metadata-only until their resource adapters ship."zoom"- | "get_desktop_state"| "get_accessibility_tree"- | "get_window_state"| "set_config"| "escalate_session"| "start_recording"@@ -133,7 +366,9 @@ pub fn advertised_risk_for(tool: &str) -> RiskAssessment {| "browser_pointer" => RiskClass::R2,// External/file side effects or generic compound action surfaces.- "install_ffmpeg"+ "get_desktop_state"+ | "get_window_state"+ | "install_ffmpeg"| "page"| "browser_dialog"| "browser_set_input_files"@@ -144,7 +379,14 @@ pub fn advertised_risk_for(tool: &str) -> RiskAssessment {RiskAssessment {class,enforcement: RiskEnforcement::MetadataOnly,- operation_sensitive: matches!(tool, "browser_prepare" | "browser_dialog" | "page"),+ operation_sensitive: matches!(+ tool,+ "browser_prepare"+ | "browser_dialog"+ | "page"+ | "get_desktop_state"+ | "get_window_state"+ ),}}@@ -193,6 +435,19 @@ pub fn classify_tool_call(tool: &str, args: &Value) -> RiskAssessment {operation_sensitive: true,}}+ "get_desktop_state" | "get_window_state" => RiskAssessment {+ class: if args+ .get("screenshot_out_file")+ .and_then(Value::as_str)+ .is_some_and(|path| !path.is_empty())+ {+ RiskClass::R3+ } else {+ RiskClass::R2+ },+ enforcement: RiskEnforcement::MetadataOnly,+ operation_sensitive: true,+ },_ => advertised_risk_for(tool),}}@@ -488,7 +743,10 @@ pub fn status_json() -> serde_json::Value {"built_in_ceiling": "reviewed_tool_and_risk_map_v1","legacy_existing_profile_approval": legacy_existing_profile_approval_enabled(),"risk_metadata_version": RISK_METADATA_VERSION,- "active_risk_enforcement": ["browser_prepare.existing_profile"],+ "active_risk_enforcement": adapter_ids_with_state(RiskEnforcement::Active),+ "metadata_only_risk_enforcement": adapter_ids_with_state(RiskEnforcement::MetadataOnly),+ "not_exposed_risk_enforcement": adapter_ids_with_state(RiskEnforcement::NotExposed),+ "enforcement_adapters": enforcement_adapter_inventory_json(),"protected_consent_collector": crate::consent::configured_provider_id(),"session_policy_configured": std::env::var_os(crate::session_manifest::SESSION_POLICY_FILE_ENV).is_some(),"session_policy_approved_at_startup": env_flag(crate::session_manifest::SESSION_POLICY_APPROVED_ENV),@@ -595,6 +853,24 @@ mod tests {assert!(!risk.operation_sensitive);}+ #[test]+ fn screenshot_file_output_is_classified_as_egress() {+ for tool in ["get_desktop_state", "get_window_state"] {+ let observation = classify_tool_call(tool, &serde_json::json!({}));+ assert_eq!(observation.class, RiskClass::R2);+ assert_eq!(observation.enforcement, RiskEnforcement::MetadataOnly);++ let egress = classify_tool_call(+ tool,+ &serde_json::json!({"screenshot_out_file": "/tmp/capture.png"}),+ );+ assert_eq!(egress.class, RiskClass::R3);+ assert_eq!(egress.enforcement, RiskEnforcement::MetadataOnly);+ assert!(egress.operation_sensitive);+ assert_eq!(advertised_risk_for(tool).class, RiskClass::R3);+ }+ }+#[test]fn process_targeted_tools_cannot_target_the_authorization_daemon() {let error = authorize_tool_call(@@ -604,4 +880,69 @@ mod tests {.unwrap_err();assert!(error.to_string().contains("authorization process"));}++ #[test]+ fn enforcement_inventory_is_unique_and_truthful() {+ let mut ids = std::collections::BTreeSet::new();+ for adapter in ENFORCEMENT_ADAPTERS {+ assert!(+ ids.insert(adapter.id),+ "duplicate adapter id {}",+ adapter.id+ );+ assert!(+ !adapter.operations.is_empty(),+ "adapter {} needs at least one operation selector",+ adapter.id+ );+ }++ assert_eq!(+ adapter_ids_with_state(RiskEnforcement::Active),+ vec!["browser_prepare.existing_profile"]+ );+ assert_eq!(+ adapter_ids_with_state(RiskEnforcement::MetadataOnly),+ vec![+ "private_observation",+ "desktop_input",+ "file_transfer_and_output",+ "browser_consequential_action",+ ]+ );+ assert_eq!(+ adapter_ids_with_state(RiskEnforcement::NotExposed),+ vec!["devices", "shell_and_network"]+ );++ let existing = ENFORCEMENT_ADAPTERS+ .iter()+ .find(|adapter| adapter.id == "browser_prepare.existing_profile")+ .unwrap();+ assert_eq!(existing.idle_ttl_seconds, Some(30 * 60));+ assert_eq!(existing.absolute_ttl_seconds, Some(8 * 60 * 60));+ assert_eq!(existing.refusal_code, Some("browser_consent_required"));+ }++ #[test]+ fn status_derives_adapter_summaries_from_the_inventory() {+ let status = status_json();+ assert_eq!(+ status["active_risk_enforcement"],+ serde_json::json!(["browser_prepare.existing_profile"])+ );+ assert_eq!(+ status["metadata_only_risk_enforcement"],+ serde_json::json!([+ "private_observation",+ "desktop_input",+ "file_transfer_and_output",+ "browser_consequential_action"+ ])+ );+ assert_eq!(+ status["enforcement_adapters"],+ enforcement_adapter_inventory_json()+ );+ }}diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/tool.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/tool.rsindex e5834b3a94..c9450fc6de 100644--- a/libs/cua-driver/rust/crates/cua-driver-core/src/tool.rs+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/tool.rs@@ -378,6 +378,7 @@ impl ToolRegistry {"tools": list,"capability_version": CAPABILITY_VERSION,"schema_version": TOOLS_LIST_SCHEMA_VERSION,+ "enforcement_adapters": crate::authorization::enforcement_adapter_inventory_json(),})}@@ -416,6 +417,27 @@ impl ToolRegistry {let Some(tool) = self.tools.get(resolved_name) else {return ToolResult::error(format!("Unknown tool: {name}"));};++ // This registry is the canonical native dispatch boundary shared by+ // the same-process SDK and every transport adapter. Authorization must+ // live here: transport-only checks leave CuaDriver::create() able to+ // invoke platform tools without policy, permission-mode, hard-+ // invariant, or reviewed-risk enforcement.+ //+ // Transports may still reject earlier for defense in depth, but those+ // checks must remain side-effect free. Active consent/grant adapters+ // run only downstream of this boundary so a call cannot prompt twice.+ if let Err(error) = crate::authorization::authorize_tool_call(resolved_name, &args) {+ let message = error.to_string();+ return ToolResult::error(message.clone()).with_structured(serde_json::json!({+ "status": "refused",+ "refusal": {+ "code": "permission_denied",+ "message": message,+ }+ }));+ }+// Reject modality violations before reserving a recording turn. A// rejected action has no before/after evidence and must not leave a// pending recorder entry behind.@@ -1143,5 +1165,16 @@ mod capability_tests {assert_eq!(v["schema_version"], "1");assert!(v["tools"].is_array(), "tools array must still be present");assert_eq!(v["tools"].as_array().unwrap().len(), 0);+ assert!(+ v["enforcement_adapters"].is_array(),+ "permission enforcement inventory must be available before tools register"+ );+ assert!(v["enforcement_adapters"]+ .as_array()+ .unwrap()+ .iter()+ .any(|adapter| {+ adapter["id"] == "browser_prepare.existing_profile" && adapter["state"] == "active"+ }));}}diff --git a/libs/cua-driver/rust/crates/cua-driver-sdk/src/lib.rs b/libs/cua-driver/rust/crates/cua-driver-sdk/src/lib.rsindex c2d2d5deb4..83961868a8 100644--- a/libs/cua-driver/rust/crates/cua-driver-sdk/src/lib.rs+++ b/libs/cua-driver/rust/crates/cua-driver-sdk/src/lib.rs@@ -302,6 +302,11 @@ impl CuaDriver {/// `cua-driver` and never opens daemon IPC.#[uniffi::constructor]pub fn create(options: Option<DriverOptions>) -> Result<Arc<Self>, DriverError> {+ cua_driver_core::authorization::validate_startup_authorization().map_err(|error| {+ DriverError::Configuration {+ reason: format!("authorization configuration is invalid: {error}"),+ }+ })?;let options = options.unwrap_or_default();Ok(Arc::new(Self {backend: DriverBackend::Embedded(Arc::new(NativeAbiDriver::create(@@ -768,6 +773,33 @@ mod tests {));}+ #[tokio::test]+ async fn embedded_runtime_enforces_authorization_before_platform_dispatch() {+ let driver = CuaDriver::create(None).unwrap();+ let result = driver+ .call_tool(+ "click".into(),+ serde_json::json!({+ "pid": std::process::id(),+ "x": 1,+ "y": 1+ })+ .to_string(),+ )+ .await+ .unwrap();++ assert!(result.is_error);+ assert_eq!(result.error_code.as_deref(), Some("permission_denied"));+ assert!(result.text.contains("authorization process"));+ let structured: Value =+ serde_json::from_str(result.structured_json.as_deref().unwrap()).unwrap();+ assert_eq!(+ structured.pointer("/refusal/code"),+ Some(&Value::String("permission_denied".into()))+ );+ }+#[tokio::test]async fn typed_desktop_call_serializes_contract_and_normalizes_result() {let response = serde_json::json!({diff --git a/libs/cua-driver/rust/crates/cua-driver/src/sdk_adapter.rs b/libs/cua-driver/rust/crates/cua-driver/src/sdk_adapter.rsindex 78615b8bc3..3dee6d2c67 100644--- a/libs/cua-driver/rust/crates/cua-driver/src/sdk_adapter.rs+++ b/libs/cua-driver/rust/crates/cua-driver/src/sdk_adapter.rs@@ -123,6 +123,7 @@ fn daemon_tools_list_from(tools_list: &Value) -> Value {"tools": tools,"capability_version": tools_list.get("capability_version").cloned().unwrap_or(Value::Null),"schema_version": tools_list.get("schema_version").cloned().unwrap_or(Value::Null),+ "enforcement_adapters": tools_list.get("enforcement_adapters").cloned().unwrap_or_else(|| json!([])),"tool_observation_owner": "daemon",})}@@ -159,11 +160,19 @@ mod tests {"risk": {"level": "low"}}],"capability_version": "1",- "schema_version": "1"+ "schema_version": "1",+ "enforcement_adapters": [{+ "id": "browser_prepare.existing_profile",+ "state": "active"+ }]});let daemon = daemon_tools_list_from(&tools_list);assert_eq!(daemon["tools"][0]["input_schema"]["type"], "object");assert_eq!(daemon["tools"][0]["read_only"], true);+ assert_eq!(+ daemon["enforcement_adapters"][0]["id"],+ "browser_prepare.existing_profile"+ );assert_eq!(daemon["tool_observation_owner"], "daemon");}}