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(cua-driver): support approved existing browser profiles (#2261)

Francesco Bonacci8582630ca8f4
diff --git a/docs/content/docs/concepts/browser-targeting-and-background-delivery.mdx b/docs/content/docs/concepts/browser-targeting-and-background-delivery.mdx
index 94428a3b9c..85cc2e02e0 100644
--- a/docs/content/docs/concepts/browser-targeting-and-background-delivery.mdx
+++ b/docs/content/docs/concepts/browser-targeting-and-background-delivery.mdx
@@ -76,15 +76,42 @@ now belongs to another document.
Browser inspection never enables remote debugging or restarts a browser as a
side effect. `browser_prepare` is a separate destructive approval boundary. It
may launch another browser with a driver-owned `isolated_new` or
-`isolated_named` profile, but it never copies, modifies, restarts, or terminates
-the selected user profile. Remote-debugging arguments passed through
+`isolated_named` profile. For an existing supported Chromium profile, a
+stronger operation-bound approval may instead authorize one exact-window AX,
+UIA, or AT-SPI setup of the browser's per-instance remote-debugging switch. The
+route is proven for Chrome and Edge on macOS and Windows and for Chrome in the
+validated Linux X11 and Sway lanes. It never copies profile data, edits profile
+files, restarts, or terminates the selected process, and it reports its
+temporary-tab and setting effects. Remote-debugging arguments passed through
`launch_app` are refused.
+The setup transition and protocol attachment are separate proofs. A listener
+must be loopback-only, attributed to the approved pid, and either discoverable
+as DevTools or correlated with the exact approved checkbox transition. The
+driver then requires a successful DevTools WebSocket claim before reporting an
+attachment; a bare browser-owned loopback listener is not sufficient.
+
An MCP host supplies approval through its destructive-tool approval path.
Direct CLI and raw-socket callers use a short-lived, single-use token minted by
the interactive `browser-approve` command. A Boolean supplied by the model is
not treated as user consent.
+An existing authenticated profile has a stronger boundary than a
+driver-created isolated profile. Attaching exposes the profile's live pages,
+cookies, and storage to the browser protocol, so ordinary MCP transport
+approval is not enough. The initial existing-profile route requires a separate
+interactive artifact bound to one process, native window, and named driver
+session.
+
+Chrome can ask for consent whenever a genuinely new browser-level socket is
+opened. Cua Driver therefore keeps one socket for each approved connection
+generation and multiplexes tabs over it. If the socket drops, one reconnect
+leader re-proves process, endpoint, and native-window identity before it may
+press the exact browser-owned consent action. A successful reconnect changes
+the generation and makes every old target, tab, snapshot, and ref stale. This
+is deliberate: silently remapping an old capability could act on a different
+tab after a browser lifecycle change.
+
## Platform meaning
Page-aware routes are cross-platform, but exact native correlation and input
diff --git a/docs/content/docs/how-to-guides/driver/drive-a-web-page.mdx b/docs/content/docs/how-to-guides/driver/drive-a-web-page.mdx
index 4df3b4ae0b..e758c38145 100644
--- a/docs/content/docs/how-to-guides/driver/drive-a-web-page.mdx
+++ b/docs/content/docs/how-to-guides/driver/drive-a-web-page.mdx
@@ -66,6 +66,79 @@ cua-driver browser-approve --pid 844 --profile-mode isolated_new
Pass the returned token as `approval_token` in the otherwise identical
`browser_prepare` call. `get_browser_state` never performs this setup itself.
+## Attach to an existing Chrome or Edge profile
+
+Use this route only when the agent must work in a supported Chromium profile
+that is already running and authenticated. Cua Driver does not restart the
+browser, copy the profile, or modify profile files. The route supports Chrome
+and Edge on macOS and Windows, plus Chrome in the validated Linux X11 and Sway
+configurations. Chromium and Edge have descriptor-backed Linux routes but are
+not yet product-validated there. Start a named driver session and mint an approval
+artifact for the exact process, native window, and session:
+
+```bash
+cua-driver browser-approve \
+ --strategy existing_profile \
+ --pid 844 \
+ --window-id 10725 \
+ --session research-1
+```
+
+The command requires an interactive terminal and asks you to type `APPROVE`.
+Pass its five-minute, single-use token to `browser_prepare`:
+
+```jsonc
+browser_prepare({
+ "pid": 844,
+ "window_id": 10725,
+ "session": "research-1",
+ "strategy": {"kind": "existing_profile"},
+ "approval_token": "<token>"
+})
+```
+
+The browser may display its own remote-debugging consent prompt. Cua Driver will
+press only the exact browser-owned semantic allow action for this approved
+process and window. An absent, ambiguous, dismissed, or unrecognized prompt is
+refused; it is never treated as generic permission to click security dialogs.
+
+If the approved process has no DevTools endpoint, Cua Driver opens a temporary
+tab in the approved window and navigates to the product's fixed remote-debugging
+page (`chrome://inspect/#remote-debugging` or
+`edge://inspect/#remote-debugging`). It matches exactly one **Allow remote
+debugging for this browser instance** checkbox, verifies that it is off, and
+presses it once. It then proves that the new listener is loopback-only and
+owned by the approved process before closing the temporary tab. The result's
+`side_effects` reports whether the page was opened and closed, whether the
+address field was focused, whether the setting was enabled, and whether Chrome
+displayed a connection-consent prompt. If setup fails after a visible action,
+the structured refusal reports `detail.setup_side_effects`; a checkbox changed
+by that failed attempt is restored when its exact state can still be proven.
+Any ambiguous control or changed process/window identity is refused.
+
+On Linux, launch the browser with `--force-renderer-accessibility` unless a
+screen reader already enables its complete AT-SPI tree. Native Wayland also
+requires a validated compositor route that can prove the exact process,
+window, geometry, and temporary focus restoration. A missing prerequisite is
+reported as a refusal; Cua Driver does not fall back to an unscoped desktop
+click.
+
+After `attached_existing_profile`, list windows again if needed and call
+`get_browser_state({pid, window_id, session})`. Attachment invalidates older
+browser capabilities, so do not reuse a previous `target_id`, `tab_id`, or
+page ref.
+
+The grant lives only in daemon memory. It expires after inactivity, has an
+absolute lifetime, and is revoked when its owning session ends or the daemon
+restarts. A dropped browser socket may reconnect up to three times under the
+same live grant; a successful reconnect invalidates capabilities again and
+requires another bind. Browser restart requires a new approval in this first
+release.
+
+Existing-profile consent turns record redacted action metadata and results but
+omit screenshots and accessibility snapshots, so authenticated page content is
+not persisted as consent evidence.
+
## Bind the native window
Browser capabilities are scoped to a driver session. Start one and pass the
@@ -194,5 +267,6 @@ ownership, capability lifetime, and refusal reasons remain explicit.
- [Browser targeting and background delivery](/concepts/browser-targeting-and-background-delivery)
- [Browser tool reference](/reference/cua-driver/mcp-tools#get_browser_state)
+- [Existing-profile attachment reference](/reference/cua-driver/browser-profile-attachment)
- [Known limits](/reference/cua-driver/limits)
- [Capture and delivery modalities](/concepts/capture-and-delivery-modalities)
diff --git a/docs/content/docs/reference/cua-driver/browser-profile-attachment.mdx b/docs/content/docs/reference/cua-driver/browser-profile-attachment.mdx
new file mode 100644
index 0000000000..281ce54dd7
--- /dev/null
+++ b/docs/content/docs/reference/cua-driver/browser-profile-attachment.mdx
@@ -0,0 +1,125 @@
+---
+title: Browser Profile Attachment
+description: Contract, lifetimes, refusals, and platform scope for attaching Cua Driver to an existing Chromium profile.
+---
+
+# Browser Profile Attachment
+
+Existing-profile attachment is an additive `browser_prepare` strategy. It does
+not change the lifecycle of driver-owned `isolated_new` and `isolated_named`
+profiles.
+
+## Request
+
+```jsonc
+{
+ "pid": 844,
+ "window_id": 10725,
+ "session": "research-1",
+ "strategy": {"kind": "existing_profile"},
+ "approval_token": "<interactive one-use token>"
+}
+```
+
+`pid`, `window_id`, and `session` are required. `strategy` cannot be combined
+with legacy `allow_launch` or `profile` fields. The approval token must be
+minted by `cua-driver browser-approve` for the exact same values. It expires
+after five minutes, is consumed once, and is consumed by a mismatched attempt.
+
+The internal approval marker supplied by an MCP transport does not authorize
+this strategy.
+
+## Success result
+
+A successful call returns `action: "attached_existing_profile"` and an
+`attachment` object with:
+
+| Field | Value |
+| --- | --- |
+| `kind` | `existing_profile` |
+| `browser` | `chromium` |
+| `capabilities_invalidated` | `true` |
+| `next_action` | `get_browser_state` |
+
+`side_effects` reports the bounded setup and consent effects:
+
+| Field | Meaning |
+| --- | --- |
+| `opened_setup_page` | A temporary tab was opened in the approved native window. |
+| `closed_setup_page` | That temporary setup tab was closed successfully. |
+| `focused_setup_address_field` | The temporary tab's address field received in-app focus for exact navigation. |
+| `enabled_remote_debugging` | The exact per-instance Chrome checkbox was toggled from off to on. |
+| `changed_preferences` | Mirrors `enabled_remote_debugging` for the generic prepare contract. |
+| `displayed_consent_prompt` | Chrome displayed its browser-owned connection-consent prompt. |
+
+All fields are `false` when the endpoint was already available. The driver does
+not return the profile identity, endpoint address, port, connection generation,
+grant identifier, or approval artifact.
+
+A refusal after setup begins may include `detail.setup_side_effects`. This uses
+the same setup fields and adds `restored_remote_debugging` when the driver had
+to reverse its own checkbox change. It never claims cleanup succeeded unless
+the exact checkbox returned to the off state.
+
+## Grant lifetime
+
+The grant is scoped to the daemon instance, public session, transport session,
+browser process fingerprint, approved native window, and proven loopback
+endpoint. It expires after 30 minutes of inactivity or eight hours absolutely,
+whichever comes first. Session end, consent dismissal, identity mismatch,
+reconnect exhaustion, and daemon restart revoke it.
+
+One browser-level connection is owned per generation. At most three reconnect
+attempts are made after a socket loss. A successful reconnect increments the
+generation and invalidates every target, tab, snapshot, frame, and ref minted
+by the previous generation.
+
+## Refusals
+
+| Code | Meaning |
+| --- | --- |
+| `browser_consent_required` | No live exact approval exists, or it expired. |
+| `browser_consent_revoked` | The person dismissed or denied the browser prompt. |
+| `browser_requires_setup` | No unique approved browser endpoint is available. |
+| `browser_endpoint_owner_mismatch` | Endpoint ownership or identity changed. |
+| `browser_wrong_target_refused` | The native window, prompt, or browser target is not exact. |
+| `browser_binding_stale` | A connection generation changed; bind again. |
+| `browser_reconnect_exhausted` | The bounded reconnect policy could not establish a proven socket. |
+| `browser_input_incomplete` | Keystroke typing delivered only a reported prefix. |
+
+## Recording and telemetry
+
+Consent turns persist redacted request metadata and the structured outcome.
+They suppress browser screenshots and accessibility snapshots. Public results,
+recordings, and telemetry must not contain profile paths or hashes, endpoint
+URLs or ports, approval tokens, page content, tab URLs, cookies, or storage.
+
+## Platform scope
+
+The prompt-assisted route is available for Google Chrome and Microsoft Edge on
+macOS and Windows. Chrome has product-specific acceptance evidence on Linux
+X11 and on the validated native-Wayland Sway lane. Chromium and Edge use the
+same descriptor-backed Linux route, but still need product-specific acceptance
+evidence before they are listed as validated. Every route requires an
+exact approved PID and native window, one uniquely matched setup control, a
+loopback endpoint owned by that process, one exact browser-owned consent
+action, and a fresh native/CDP rebind.
+
+Linux additionally requires the browser's complete AT-SPI renderer tree. Start
+the Chromium-family process with `--force-renderer-accessibility`, or run a
+screen reader that enables full renderer accessibility. On Sway, Cua Driver
+briefly focuses the exact compositor-attested container for fixed internal-page
+navigation and restores the previous container before continuing. It refuses
+generic Wayland sessions that cannot prove exact process, window, and geometry
+identity.
+
+The setup adapters currently recognize the products' English accessibility
+labels. Other UI locales fail closed without toggling an unrecognized control.
+Safari, Firefox, Brave, Vivaldi, Opera, Arc, and Electron do not have an
+existing-profile setup descriptor and return a structured refusal. An already
+available endpoint may still use the ordinary exact browser binding route when
+the platform independently proves it.
+
+See [Drive a web page](/how-to-guides/driver/drive-a-web-page) for the task
+workflow and [Browser targeting and background delivery](/concepts/browser-targeting-and-background-delivery)
+for the security and generation model.
diff --git a/docs/content/docs/reference/cua-driver/limits.mdx b/docs/content/docs/reference/cua-driver/limits.mdx
index 870bae024e..e334c121a3 100644
--- a/docs/content/docs/reference/cua-driver/limits.mdx
+++ b/docs/content/docs/reference/cua-driver/limits.mdx
@@ -42,10 +42,14 @@ otherwise the omitted frame is reported as a limitation instead of being
flattened into the main document. A newer snapshot or navigation invalidates
previous refs.
-Chrome remote debugging is prepared only in a separate driver-owned isolated
-profile. `browser_prepare` never enables it on, copies, or restarts the selected
-user profile. Endpoint ownership must resolve to the requested browser pid;
-wrapper processes or ambiguous process trees are refused.
+`browser_prepare` can either create a separate driver-owned isolated profile or
+attach to an approved existing Chrome, Edge, or Chromium profile on a proven
+platform. Existing-profile setup may enable that browser instance's own
+remote-debugging switch through one exact accessibility action, but it never
+copies profile data, edits profile files, restarts, or terminates the selected
+process. Endpoint ownership must resolve to the approved browser PID; wrapper
+processes, ambiguous process trees, unsupported products, unrecognized UI
+locales, and generic Wayland identities are refused.
On generic GNOME or KDE Wayland sessions, browser state may be discoverable
without enough compositor evidence to correlate native and DevTools geometry
diff --git a/docs/content/docs/reference/cua-driver/mcp-tools.mdx b/docs/content/docs/reference/cua-driver/mcp-tools.mdx
index 6dc8312d75..8f636b60ec 100644
--- a/docs/content/docs/reference/cua-driver/mcp-tools.mdx
+++ b/docs/content/docs/reference/cua-driver/mcp-tools.mdx
@@ -758,7 +758,7 @@ Read-only browser inspection. Mode 1 (bind): pass pid + window_id of a native br
### `browser_prepare`
-Explicitly prepare an owned DevTools endpoint for a browser pid. Existing endpoints are detected without side effects. Acting setup requires MCP-host approval or a short-lived token from the interactive browser-approve command, allow_launch=true, and a driver-owned isolated profile. It launches a separate browser and never copies, modifies, or terminates the requested user profile.
+Explicitly prepare an owned DevTools endpoint for a browser pid. Existing endpoints are detected without side effects. Acting setup requires MCP-host approval or a short-lived token from the interactive browser-approve command, allow_launch=true, and a driver-owned isolated profile. It launches a separate browser and never copies, modifies, or terminates the requested user profile. Existing-profile attachment is explicit, requires an exact interactive approval artifact, and never treats ordinary MCP transport approval as profile consent. On proven platforms, that approval also permits one bounded exact-window setup: open the recognized browser product's fixed remote-debugging page, toggle its uniquely matched per-instance checkbox, prove the PID-owned loopback endpoint, and close the temporary tab. Every visible effect is reported; ambiguity is refused.
**Arguments:**
@@ -767,6 +767,8 @@ Explicitly prepare an owned DevTools endpoint for a browser pid. Existing endpoi
- `pid` (integer, required): Browser process id to prepare.
- `profile` (object, optional)
- `session` (string, optional): Stable caller-declared session id. Browser targets, tabs, and refs are scoped to this session.
+- `strategy` (object, optional)
+- `window_id` (integer, optional): Exact native window approval anchor; required for strategy.kind=existing_profile.
```json
{"pid":844}
diff --git a/docs/content/docs/reference/cua-driver/meta.json b/docs/content/docs/reference/cua-driver/meta.json
index bb831d4a6a..7571af6a89 100644
--- a/docs/content/docs/reference/cua-driver/meta.json
+++ b/docs/content/docs/reference/cua-driver/meta.json
@@ -7,6 +7,7 @@
"embedding",
"mcp-tools",
"mcp-tool-notes",
+ "browser-profile-attachment",
"action-selection-policy",
"permission-policies",
"contracts",
diff --git a/docs/content/docs/reference/cua-driver/platform-support.mdx b/docs/content/docs/reference/cua-driver/platform-support.mdx
index f5513021d1..c1e347f22d 100644
--- a/docs/content/docs/reference/cua-driver/platform-support.mdx
+++ b/docs/content/docs/reference/cua-driver/platform-support.mdx
@@ -48,7 +48,17 @@ harnesses; an unlisted trust class or host shape is not implied.
`browser_prepare` may launch a separate driver-owned Chromium profile after an
approved destructive call. `isolated_new` processes and their complete child
trees are reaped and the marked profile is removed when the owning session
-ends. The selected user's existing browser process and profile are not changed.
+ends.
+
+Existing-profile attachment is proven for Chrome and Edge on macOS and Windows,
+for Chrome on Linux X11, and for Chrome in the native Sway lane. The same exact
+descriptor route covers Chromium and Edge on Linux, subject to a complete
+AT-SPI renderer tree and product-specific acceptance evidence. The harness
+proves exact interactive approval, setup-control identity, browser-owned
+consent, PID-owned loopback endpoint discovery, temporary-tab cleanup, focus
+restoration, and an exact native/CDP rebind without restarting, copying, or
+editing the profile. Unsupported products and unproven Wayland compositors
+return a structured refusal.
## Linux window systems
diff --git a/libs/cua-driver/docs/browser-existing-profile-attachment-plan.md b/libs/cua-driver/docs/browser-existing-profile-attachment-plan.md
new file mode 100644
index 0000000000..95f884dd0f
--- /dev/null
+++ b/libs/cua-driver/docs/browser-existing-profile-attachment-plan.md
@@ -0,0 +1,652 @@
+# Existing-Profile Browser Attachment and Reconnect Plan
+
+## Status
+
+- **State:** Implemented and accepted from exact source SHA `7fa6c80f` across macOS, Windows, Linux X11, and Linux Wayland on Sway
+- **Plan date:** 2026-07-16
+- **Base:** `main` at `0835daa6` (`feat(cua-driver): add capability-aware browser tools`)
+- **Primary tracker:** [#2192](https://github.com/trycua/cua/issues/2192)
+- **Scope:** First-class, user-approved attachment to an existing Chromium profile, followed by bounded autonomous reconnection
+- **Delivery:** Draft PR [#2261](https://github.com/trycua/cua/pull/2261) on `codex/browser-existing-profile-reconnect-plan`; canonical replay is complete and the PR remains draft for review
+
+## Implementation outcome
+
+- Chrome and Edge use exact AX setup and consent adapters on macOS and exact
+ UIA adapters on Windows. Chrome, Chromium, and Edge have exact product
+ descriptors on Linux, with AT-SPI adapters for X11 and the validated native
+ Sway route.
+- Setup is bounded and visible: it opens one fixed internal page in the
+ approved window, toggles one exact per-instance control, proves a PID-owned
+ loopback endpoint, handles one exact browser-owned consent action, closes the
+ temporary tab, and reports or rolls back its own effects.
+- Exact-SHA acceptance passed Chrome and Edge on macOS Lume and a live Windows
+ RDP user session, Chrome on Linux X11, and Chromium on native Sway. The 60
+ declared rows produced 50 deliveries, 10 expected structured refusals, no
+ failures or skips, and 60 playable videos.
+- Safari, Firefox, products without an exact setup descriptor, unrecognized UI
+ locales, and Wayland sessions without exact compositor identity remain
+ structured refusals.
+
+This plan is based on a read-only audit of the merged browser tools, platform
+adapters, approval path, CDP transport, legacy macOS page implementation,
+recording system, and Rust E2E harnesses. A separate Fable review challenged the
+public contract, consent boundary, reconnect ordering, concurrency model, issue
+grouping, and pull request sequence.
+
+## Definition of Done
+
+The project is done when an agent can attach to an existing authenticated
+Chromium profile after one genuine host/user approval, continue through bounded
+socket reconnects without asking the model to approve security UI, and either
+act on the exact intended tab or return an exact structured refusal. Completion
+requires:
+
+1. A real user approval path that cannot be forged by a model or inferred from
+ ordinary MCP transport.
+2. One browser-level CDP connection per approved connection generation.
+3. Exact prompt ownership and semantics before any automated consent click.
+4. Endpoint, process, profile, native window, and CDP target identity re-proven
+ after reconnect.
+5. Old target, tab, and page-ref capabilities invalidated across generations.
+6. Browser mutations serialized at the canonical CDP target boundary, with
+ honest partial-delivery results.
+7. Deterministic unit, adversarial, and real-browser E2E evidence on every
+ advertised platform.
+8. Recording, telemetry, docs, and bundled skills that do not leak profile or
+ authenticated-page data and do not overstate support.
+
+## Problem
+
+The merged browser tools support exact Chromium binding and driver-owned
+`isolated_new` or `isolated_named` profiles. They deliberately do not prepare a
+person's already-running authenticated profile.
+
+The legacy macOS page route proves that an existing Chrome profile can expose a
+browser-level CDP endpoint through `chrome://inspect/#remote-debugging`. That
+route has three limitations:
+
+- it is outside the first-class browser capability and ownership model;
+- Chrome may show an `Allow remote debugging?` prompt for every genuinely new
+ WebSocket connection;
+- a dropped socket causes a fresh connection and therefore another prompt.
+
+The current core `CdpPool` replaces a closed socket and retries once, but it
+does not have a consent state machine, connection generations, cancellation,
+or a mutation coordinator. The current MCP server also injects an internal
+approval marker for every `browser_prepare` call. That marker is protected from
+client forgery, but it proves transport provenance, not an interactive user
+decision. It is insufficient for attaching to a personal browser profile.
+
+## Goals
+
+1. Add a typed existing-profile strategy to `browser_prepare` without changing
+ the meaning of driver-owned isolated profiles.
+2. Require one operation-bound user approval before enabling or attaching to an
+ existing profile.
+3. Let the driver handle the browser's exact consent prompt while that grant is
+ live, including bounded reconnects.
+4. Keep `get_browser_state` strictly read-only.
+5. Preserve exact-or-refused native window to CDP target binding.
+6. Make socket loss and browser restart explicit state transitions rather than
+ transparent retries with stale capabilities.
+7. Apply the same concurrency and completion guarantees to all browser
+ mutations so reconnect does not introduce partial or cross-target actions.
+8. Roll out only where real platform evidence supports the contract.
+
+## Non-Goals
+
+- Generic approval of system or application dialogs.
+- Matching consent UI by screenshot, fuzzy title, or button text alone.
+- Treating a model-provided Boolean, public token, or ordinary MCP call as user
+ approval.
+- Persisting grants across daemon restart in the first release.
+- Restarting a user's browser with remote-debugging flags.
+- Copying, modifying, or disclosing an existing profile directory.
+- Safari, Firefox, or WebDriver BiDi support in this project.
+- Mutation on a Wayland compositor where exact native identity cannot be
+ proven.
+- Fixing native-route issues [#2201](https://github.com/trycua/cua/issues/2201)
+ or [#2202](https://github.com/trycua/cua/issues/2202) through browser-specific
+ workarounds.
+- Migrating the complete legacy `page` surface in the same pull request stack.
+
+## Locked Design Decisions
+
+### Existing profile is an attachment strategy, not a profile lifecycle mode
+
+`PrepareProfileMode` continues to mean driver-owned profile lifecycle and keeps
+only `isolated_new` and `isolated_named`. Existing profiles are not owned by the
+driver and must not inherit isolated-profile creation or cleanup behavior.
+
+Add an optional tagged `strategy` object. Calls that omit it retain today's
+behavior. Current `allow_launch` and `profile` fields remain accepted as a
+compatibility form and are normalized internally.
+
+```json
+{
+ "pid": 4242,
+ "window_id": 991,
+ "session": "agent-session",
+ "strategy": {
+ "kind": "existing_profile"
+ }
+}
+```
+
+`window_id` is required for `existing_profile`. The endpoint grant is
+process/profile-wide, but the selected native window provides the user-visible
+approval anchor and an exact initial ownership proof. Browser product is
+derived from the process and is never trusted from a caller claim.
+
+Supplying `strategy` together with legacy `allow_launch` or `profile` fields is
+an invalid request. A later cleanup may expose tagged isolated strategies, but
+that is not required for this feature.
+
+### Approval is out of band and operation bound
+
+The public request never contains `approved: true` or a reusable grant ID.
+
+When no valid grant exists, `browser_prepare` returns the existing structured
+`browser_consent_required` refusal with a short-lived approval request ID in
+`detail`. The request ID correlates a host UI action; possession does not grant
+permission.
+
+Approval providers are:
+
+- an interactive `browser-approve` CLI artifact extended to bind the exact
+ existing-profile request digest; and
+- a host approval broker that injects an internal, operation-bound approval
+ certificate only after a real user action.
+
+The current automatically injected MCP host marker remains sufficient only for
+the existing isolated-launch contract. It must never authorize
+`existing_profile`.
+
+An approved request mints an in-memory `ExistingProfileGrant` scoped to:
+
+- daemon instance;
+- public and transport session;
+- browser product and platform identity proof;
+- opaque profile identity when the platform can prove it;
+- current process fingerprint;
+- approved side effects and reconnect budget;
+- idle and absolute expiry.
+
+The internal profile identity may be a daemon-salted hash of a canonical path,
+but the path or hash is never returned, logged, or recorded. If a platform
+cannot prove profile identity independently, the initial release binds the
+grant to the current process fingerprint and requires approval after a browser
+restart.
+
+Daemon restart always discards the grant. Durable grants backed by Keychain,
+DPAPI, or Secret Service require a separate security design and are deferred.
+
+### One browser-level socket per connection generation
+
+Chrome may prompt once per genuinely new WebSocket, not once per operation.
+The coordinator therefore owns exactly one browser-level
+`/devtools/browser` socket for an attachment generation and multiplexes tabs
+through flattened `Target.attachToTarget` sessions.
+
+Core must not open independent per-target sockets for an approved existing
+profile. If a browser product cannot support the browser-level route, that
+product is unsupported until its prompt count and connection semantics are
+modeled explicitly.
+
+The new route becomes the sole socket owner for a grant-owned endpoint. The
+legacy page cache must refuse access to such an endpoint and direct callers to
+the first-class browser tools. This prevents duplicate prompts and split-brain
+connection ownership.
+
+### Prompt handling occurs while connection is pending
+
+The browser prompt is caused by opening the WebSocket, so the driver cannot
+click it before starting the connection. The state machine must initiate a
+bounded connect, observe the exact resulting prompt, press its exact semantic
+action, and then confirm that the same pending connection completed.
+
+```text
+approval_required
+ -> grant_active
+ -> endpoint_preflight
+ -> connecting_pending_consent
+ -> socket_ready
+ -> consent_prompt_observed -> consent_pressed -> socket_ready
+ -> consent_dismissed -> grant_revoked
+ -> timeout_or_ambiguity -> refused
+ -> endpoint_reproved
+ -> capabilities_invalidated
+ -> ready_for_rebind
+```
+
+On socket loss:
+
+```text
+ready
+ -> reconnect_singleflight
+ -> mutation_gates_closed
+ -> process_profile_endpoint_revalidated
+ -> connecting_pending_consent
+ -> endpoint_generation_incremented
+ -> old_capabilities_invalidated
+ -> mutation_gates_reopened
+ -> ready_for_rebind
+```
+
+The first implementation uses a fixed policy rather than caller-tunable
+security limits:
+
+- one reconnect leader per approved browser identity;
+- at most three connection attempts per loss;
+- one exact consent action per attempt;
+- one total deadline for the transition;
+- immediate revocation when a person dismisses or denies the prompt;
+- cancellation when the owning session ends.
+
+### Internal desktop primitives, never recursive MCP calls
+
+Prompt handling reuses the same native perception and semantic action
+primitives that support `get_window_state` and AX/UIA/AT-SPI clicks, but it does
+not invoke public MCP tools from inside `browser_prepare` or CDP reconnect.
+Recursive public calls would create policy, recording, and lifecycle deadlocks.
+
+Each platform provides a narrow internal `BrowserConsentUi` adapter that can:
+
+1. derive or verify a browser/profile identity;
+2. observe browser-owned consent candidates within a bounded scope;
+3. return proof-rich role, subrole, identifier, action, process, window, modal
+ relationship, and bounds metadata;
+4. press one exact semantic action;
+5. report whether the prompt was accepted, dismissed, ambiguous, or stale.
+
+A candidate is actionable only when all available independent evidence agrees:
+
+- the prompt belongs to the approved browser process or a platform-proven
+ browser-owned helper;
+- the binary identity matches the approved browser;
+- the prompt has the expected native role, modal relationship, semantic
+ identifier, and advertised action;
+- the action belongs to the exact prompt snapshot;
+- the endpoint being opened belongs to the same approved browser identity.
+
+Localized text may corroborate identity but cannot be the sole proof. If a
+browser/version does not expose stable semantics, the adapter refuses it.
+
+### Reconnect invalidates capabilities
+
+Every connection has an internal monotonically increasing endpoint generation.
+`TargetRecord`, `TabRecord`, and page refs record the generation that minted
+them. A successful reconnect increments the generation and invalidates every
+older target, tab, snapshot, frame, and ref capability.
+
+The caller receives `capabilities_invalidated: true` and must call
+`get_browser_state` again with the new native `(pid, window_id)` before any
+mutation. The driver never silently remaps an old capability to a new CDP
+target.
+
+### Mutation serialization is part of reconnect safety
+
+Add a mutation gate keyed by canonical browser identity plus CDP target ID, not
+by public session ID. This serializes mutations from multiple sessions that
+resolve to the same real tab while allowing proven independent tabs to proceed
+in parallel.
+
+`browser_navigate`, `browser_click`, `browser_type`, and future file upload
+hold the gate across revalidation, dispatch, and outcome verification. A
+reconnect closes all gates for that browser identity. In-flight actions either
+complete on the old generation or return a stale-generation refusal; they
+never continue on the new socket.
+
+`browser_type` additionally reports requested and delivered character counts.
+Keystroke mode updates the delivered count only after the full key-down/key-up
+pair succeeds. A partial write returns a structured `browser_input_incomplete`
+refusal with retryability metadata instead of `status: ok`.
+
+This prevents the first-class browser surface from repeating the partial and
+interleaved delivery classes tracked in
+[#2255](https://github.com/trycua/cua/issues/2255) and
+[#2256](https://github.com/trycua/cua/issues/2256). Those issues' native
+`type_text` paths remain separate fixes.
+
+### Consent evidence is privacy bounded
+
+Ordinary before/after screenshots of a live authenticated browser can expose
+URLs, page text, or authentication state. Consent turns therefore record:
+
+- the structured approval request digest and grant scope, with identifiers
+ hashed or redacted;
+- prompt ownership, role, action, and bounds proof;
+- one prompt-bounds crop only when it excludes surrounding browser content;
+- otherwise no screenshot for the consent phase;
+- endpoint ownership method, never port or WebSocket URL;
+- transition outcome, attempt count, and elapsed time.
+
+Recording and telemetry must never contain profile paths, profile hashes,
+ports, WebSocket URLs or tokens, cookies, storage, page content, tab URLs,
+JavaScript, or approval artifacts.
+
+## Public Result Contract
+
+Existing successful isolated results remain unchanged. Existing-profile
+success is additive:
+
+```json
+{
+ "status": "ok",
+ "prepared": true,
+ "action": "attached_existing_profile",
+ "prepared_pid": 4242,
+ "attachment": {
+ "kind": "existing_profile",
+ "browser": "chromium",
+ "capabilities_invalidated": true,
+ "next_action": "get_browser_state"
+ },
+ "endpoint_ownership": {
+ "method": "listening_socket_pid",
+ "owner_pid": 4242
+ },
+ "side_effects": {
+ "launched_browser": false,
+ "restarted_browser": false,
+ "created_profile": false,
+ "reused_driver_profile": false,
+ "copied_profile_data": false,
+ "changed_preferences": false,
+ "displayed_consent_prompt": true
+ }
+}
+```
+
+Do not return a grant ID, profile identity, endpoint generation, port, or
+WebSocket URL. Those are internal security and lifecycle facts, not caller
+capabilities.
+
+Use existing refusals where their meaning is exact:
+
+- `browser_consent_required` for no valid user grant;
+- `browser_endpoint_owner_mismatch` for endpoint identity failure;
+- `browser_binding_stale` after generation change;
+- `browser_wrong_target_refused` for prompt/window/target mismatch;
+- `browser_route_unavailable` for unsupported browser/platform setup.
+
+Add only the codes callers need to branch on distinctly:
+
+- `browser_consent_revoked` when the person dismisses or denies the prompt;
+- `browser_reconnect_exhausted` after the bounded reconnect policy fails;
+- `browser_input_incomplete` with requested and delivered counts.
+
+All refusal additions must also update the testkit's closed `RefusalCode`
+mirror and serialization tests.
+
+## Browser Restart and Endpoint Setup
+
+Three events have different authorization semantics:
+
+| Event | Default behavior |
+| --- | --- |
+| Socket drop, same process/profile | Reconnect under the live grant after full revalidation |
+| Browser restart | Reuse the grant only if exact browser and opaque profile identity can be re-proven; otherwise require approval |
+| Driver daemon restart | Always require approval in v1 |
+
+If no remote-debugging endpoint exists, v1 must not restart the browser with
+flags. The first macOS implementation may automate Chrome's own internal
+remote-debugging setup UI only after the same user grant and only when every
+navigation, toggle, prompt, and cleanup step is exact and recorded as a
+declared side effect. Until that path has real evidence, return
+`browser_requires_setup` with a human action and leave the profile untouched.
+
+## Platform Rollout
+
+| Platform | Initial scope | Required proof before support | Unsupported/refusal behavior |
+| --- | --- | --- | --- |
+| macOS | Chrome first; Edge only after separate evidence | Bundle/team identity, process fingerprint, CGWindow ownership, exact AX prompt semantics, PID-owned loopback endpoint, exact native/CDP rebind | Refuse unrecognized prompt or browser build |
+| Windows | Chrome and Edge after a UIA feasibility spike | Authenticode/process identity, HWND ownership, UIA modal/action semantics, exact PID listener, interactive desktop E2E | Refuse when prompt behavior or interactive session is unproven |
+| Linux X11 | Chromium/Chrome after AT-SPI spike | Executable/process identity, `_NET_WM_PID`, exact geometry, AT-SPI modal/action semantics, `/proc` socket inode owner | Refuse unrecognized desktop/browser combinations |
+| Linux Wayland | Exact compositors only, beginning with validated Sway/GNOME paths | Exact compositor pid/window identity plus AT-SPI prompt proof | Generic Wayland remains read-only or returns `browser_route_unavailable` |
+
+Support is per browser version range and desktop environment, not inferred from
+the existence of AX/UIA/AT-SPI alone.
+
+## Internal File Map
+
+### Shared core
+
+| Path | Planned responsibility |
+| --- | --- |
+| `crates/cua-driver-core/src/browser/platform.rs` | Tagged prepare strategy, approval scope, platform consent/identity contracts |
+| `crates/cua-driver-core/src/browser/approval.rs` | Existing-profile request digest and single-use approval artifact validation |
+| `crates/cua-driver-core/src/browser/grant.rs` (new) | In-memory grant store, expiry, scope, revocation, session cleanup |
+| `crates/cua-driver-core/src/browser/reconnect.rs` (new) | Bounded state machine, singleflight, cancellation, endpoint generations |
+| `crates/cua-driver-core/src/browser/mutation.rs` (new) | Canonical-target mutation gates and reconnect exclusion |
+| `crates/cua-driver-core/src/browser/cdp_ws.rs` | One browser-level socket per generation, flattened target sessions, generation-aware pool eviction |
+| `crates/cua-driver-core/src/browser/store.rs` | Generation on target/tab/ref records and browser-wide invalidation |
+| `crates/cua-driver-core/src/browser/engine.rs` | Coordinator integration, rebind and mutation gate lifecycle |
+| `crates/cua-driver-core/src/browser/tools.rs` | Additive schema/result fields and honest type completion metadata |
+| `crates/cua-driver-core/src/browser/refusal.rs` | Additive reconnect, revocation, and incomplete-input refusals |
+| `crates/cua-driver-core/src/server.rs` and `crates/cua-driver/src/serve.rs` | Operation-bound host approval broker; no automatic existing-profile approval |
+| `crates/cua-driver/src/cli.rs` | Interactive existing-profile approval request and exact scope display |
+
+### Platform adapters
+
+Each `*BrowserPlatform` becomes stateful enough to own a narrow consent adapter
+constructed from the platform's existing internal desktop primitives. Do not
+give core access to the full platform `ToolState`.
+
+| Platform | Planned paths |
+| --- | --- |
+| macOS | `platform-macos/src/browser/platform.rs`, new `browser/consent_ui.rs`, registration in `tools/mod.rs`, reuse `ax` and `input/ax_actions.rs` |
+| Windows | `platform-windows/src/browser_platform.rs`, new `browser_consent_ui.rs`, registration in `tools/impl_.rs`, reuse UIA semantic actions |
+| Linux | `platform-linux/src/browser_platform.rs`, new `browser_consent_ui.rs`, registration in `tools/impl_.rs`, reuse AT-SPI and compositor identity paths |
+
+### Tests and documentation
+
+| Path | Planned responsibility |
+| --- | --- |
+| `cua-driver-core/src/browser/v2_tests.rs` | Fake grant, prompt, endpoint, generation, and concurrent mutation tests |
+| `cua-driver-testkit/src/e2e.rs` | New refusal codes, browser attachment case declarations, evidence contract |
+| `cua-driver/tests/standalone_browser_behavior_test.rs` | Disposable existing-like Chromium profile E2E and adversarial endpoint rows |
+| `.github/workflows/e2e-rust-standalone-browsers.yml` | Maintainer-dispatched Windows/Linux compatibility evidence |
+| `tests/runners/macos-lume/` | TCC-stable macOS real-browser evidence |
+| `docs/content/docs/` | Diataxis tutorial, how-to, reference, and explanation updates |
+| `rust/Skills/cua-driver/WEB_APPS.md` and platform skill docs | Agent flow, refusal handling, and platform limits |
+
+## Validation Strategy
+
+### Unit and model tests
+
+1. Grant cannot be minted by a public Boolean, forged reserved argument, or
+ ordinary MCP call.
+2. CLI approval artifact is request-bound, single-use, expiring, and consumed
+ on mismatch.
+3. Grant cannot cross public session, transport session, daemon instance,
+ browser identity, profile identity, or process fingerprint.
+4. The state machine has no unbounded transition, retry, or wait.
+5. Concurrent reconnect requests produce one leader, one socket, and at most
+ one semantic prompt action per attempt.
+6. Human dismissal revokes the grant and prevents an automatic retry.
+7. Generation bump evicts the old socket and invalidates every old browser
+ capability.
+8. A mutation racing reconnect cannot continue on the new generation.
+9. Same-target mutations serialize across sessions; distinct proven tabs may
+ proceed concurrently.
+10. Partial keystroke delivery reports exact requested and delivered counts.
+
+### Adversarial tests
+
+1. An unrelated process displays a pixel-identical consent prompt.
+2. Another Chrome process or profile displays the real prompt.
+3. A conventional debugging port belongs to an unrelated browser.
+4. PID or port reuse occurs between approval, prompt observation, and socket
+ completion.
+5. The prompt becomes stale between snapshot and semantic press.
+6. Two matching prompt candidates exist.
+7. A localized browser exposes no stable semantic identifier.
+8. Socket loss happens during click, navigation, typing, and file upload.
+9. Browser restart preserves the product but changes profile identity.
+10. Daemon restart reuses a stale approval request, artifact, target, tab, or
+ ref.
+11. Legacy page attempts to connect to a grant-owned endpoint.
+12. Recording artifacts are scanned for profile paths, URLs, ports, endpoint
+ tokens, page text, and approval artifacts.
+
+### Real-browser E2E
+
+Tests use a disposable repository-created profile that behaves like an
+existing profile but contains no personal data. The driver does not own or
+delete it during the test. Independent fixture journals verify page effects;
+native sentinels verify focus, z-order, cursor, and leaked input where the
+operation claims background behavior.
+
+Required rows per supported platform/browser:
+
+- first approved attach;
+- repeated operations on one socket without another prompt;
+- tab switch through flattened sessions without another socket;
+- socket drop and successful prompt-assisted reconnect;
+- browser restart with profile identity re-proof or exact reapproval refusal;
+- user dismissal and grant revocation;
+- decoy prompt and unrelated endpoint refusal;
+- multi-window ambiguity refusal;
+- stale target/tab/ref refusal after generation change;
+- long and concurrent `browser_type` completion guarantees;
+- artifact/video privacy validation.
+
+## Issue Grouping
+
+| Issue | Relationship | Landing decision |
+| --- | --- | --- |
+| [#2192](https://github.com/trycua/cua/issues/2192) | Direct existing authenticated-profile tracker | Closed by this implementation stack |
+| [#2255](https://github.com/trycua/cua/issues/2255), [#2256](https://github.com/trycua/cua/issues/2256) | Partial and concurrent native text delivery; same bug class applies to browser mutations | Browser regression guarantees in this stack; native fixes remain separate |
+| [#2176](https://github.com/trycua/cua/issues/2176) | Web fallback should prefer a background browser route over foreground native input | Update recommendation/escalation to typed browser tools in this stack; close only when live behavior matches |
+| [#2240](https://github.com/trycua/cua/issues/2240) | CDP file upload action | Separate stacked PR after mutation gates land |
+| [#2084](https://github.com/trycua/cua/issues/2084) | Legacy page typing parity | Mark superseded by shared browser tools where applicable; legacy delegation remains separate |
+| [#2245](https://github.com/trycua/cua/issues/2245) | Legacy macOS page fallback provenance | Separate legacy migration/cleanup PR |
+| [#2201](https://github.com/trycua/cua/issues/2201), [#2202](https://github.com/trycua/cua/issues/2202) | Native Chrome click/drag behavior | Linked compatibility issues, not closed by browser attachment |
+| [#1616](https://github.com/trycua/cua/issues/1616) | Electron/Chromium native accessibility exposure | Separate native/embedded surface issue |
+
+These issues should be addressed in the same initiative where they share core
+primitives, but not placed in one code review. A single large pull request would
+mix approval security, transport lifecycle, mutation correctness, three native
+accessibility stacks, and legacy migration.
+
+## Proposed Pull Request Sequence
+
+| PR | Scope | User-visible change | Exit gate |
+| --- | --- | --- | --- |
+| 1 | Approval and schema contract | `existing_profile` request returns a real approval requirement; no attachment yet | Security review; forged/replayed/cross-session approval tests pass; isolated behavior unchanged |
+| 2 | Reconnect coordinator and connection generations | No advertised platform support yet | Fake-CDP state machine, singleflight, cancellation, prompt-dismissal, generation invalidation, and pool ownership tests pass |
+| 3 | Mutation gates and honest typing | Browser mutations serialize by canonical target; partial type is explicit | Concurrent same-tab/cross-session tests, cross-tab parallel test, mid-write failure counts, reconnect race tests pass |
+| 4 | macOS Chrome existing-profile adapter | Experimental user-approved attach and reconnect on macOS | Lume real-Chrome first attach, repeat, socket loss, restart/refusal, decoy, dismissal, privacy, and regression rows pass |
+| 5 | Windows Chrome/Edge adapter | Experimental support for products proven by the UIA spike | Interactive Windows E2E matches PR 4 evidence; unsupported product builds refuse |
+| 6 | Linux X11 and exact Wayland adapters | Experimental support only for validated browser/desktop combinations | X11 and each advertised compositor pass real-browser rows; generic Wayland refusal is tested |
+| 7 | Docs, skills, diagnostics, and issue reconciliation | Public setup/reconnect guidance and accurate support matrix | Diataxis docs, bundled skills, schemas, diagnostics, and issue states agree with evidence |
+| 8 | Stacked file upload from #2240 | Typed browser file-input action through the mutation gate | CDP fixture verifies files, count, input/change events, path validation, and reconnect race behavior |
+
+No incomplete platform is advertised between PRs. Experimental registration or
+capability reporting remains disabled until that platform's E2E exit gate is
+accepted.
+
+## Documentation Deliverables
+
+Use the Diataxis structure already established for CUA Driver:
+
+### Tutorial
+
+- Attach to a disposable existing Chromium profile, approve once, bind a tab,
+ and survive a reconnect.
+
+### How-to guides
+
+- Attach to an authenticated existing profile safely.
+- Handle `browser_consent_required`, revocation, and reconnect exhaustion.
+- Rebind after capability invalidation.
+- Validate existing-profile behavior with the Rust harnesses.
+
+### Reference
+
+- `browser_prepare` strategy schema and result fields.
+- Grant, connection generation, target, tab, and ref lifetimes.
+- Structured refusal vocabulary.
+- Browser/product/platform support matrix and exact evidence links.
+- Recording and telemetry redaction contract.
+
+### Explanation
+
+- Why an existing profile is not a driver-owned profile mode.
+- Why one approval does not imply a permanent ambient permission.
+- Why reconnect invalidates browser capabilities.
+- Why the driver may press one exact browser consent action but may not approve
+ arbitrary dialogs.
+- Why generic Wayland and unproven browser versions refuse mutation.
+
+## Review Questions
+
+Reviewers should explicitly decide these points before PR 1 implementation:
+
+1. Is the host approval provider a daemon-native prompt, an MCP host callback,
+ an MCP elicitation flow, or an initial CLI-only contract? Every supported
+ path must prove a real user action.
+2. Should v1 automate Chrome's internal remote-debugging toggle after approval,
+ or require the endpoint to be enabled manually and automate only connection
+ prompts?
+3. Which exact browser/profile identity can each platform prove without
+ disclosing a path?
+4. Is browser restart under the same grant required for v1, or enabled only on
+ platforms that prove the same opaque profile identity?
+5. Should `browser_input_incomplete` include a caller-retry hint when repeating
+ the remaining suffix may be unsafe for stateful editors?
+6. Should [#2240](https://github.com/trycua/cua/issues/2240) land immediately
+ after the mutation gate or wait until macOS existing-profile evidence is
+ accepted?
+
+## Implementation Evidence (2026-07-17)
+
+The canonical standalone-browser matrix was replayed from exact source SHA
+`7fa6c80f5c433a7d4dadef75e4873af89de0cd3f` after the final testkit posture
+correction. That correction waits for the foreground sentinel to become ready,
+then explicitly activates and proves the exact sentinel instead of assuming an
+application will take focus during launch. It changes setup reliability only;
+no action oracle or expected product outcome was relaxed.
+
+| Platform | Representative products | Rows | Delivered | Expected refusals | Failed | Skipped | Videos |
+| --- | --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| Windows/Win32 | Chrome, Edge | 20 | 18 | 2 | 0 | 0 | 20 |
+| macOS/Quartz | Chrome, Edge | 20 | 16 | 4 | 0 | 0 | 20 |
+| Linux/X11 | Chrome | 10 | 8 | 2 | 0 | 0 | 10 |
+| Linux/Wayland | Chromium on Sway | 10 | 8 | 2 | 0 | 0 | 10 |
+| **Total** | | **60** | **50** | **10** | **0** | **0** | **60** |
+
+Every expected refusal was exact and fail-closed. All platforms refused a
+native-window/CDP bind when two browser windows had indistinguishable bounds
+and titles. macOS and Linux also refused Chromium's trusted CDP Input click
+because that route activated the standalone browser; callers can use the
+ref-targeted `dom_event` route when a synthetic full-background click is
+acceptable. Windows delivered the trusted route without changing the sentinel
+posture.
+
+The final reports prove existing-profile setup, attach, exact multi-tab and
+frame binding, isolated launch, background type and mutation, stale-ref
+invalidation, trusted-input policy, ambiguity refusal, focus and z-order
+preservation, no leaked input, cursor preservation where available, and video
+capture. Local testkit validation also passed all 46 library tests. CI at the
+same branch head passed Windows and Linux unit/compile, Nix package and policy,
+documentation, link, distribution-compatibility, and publication checks.
+
+No approval token, profile path, endpoint token, host address, machine name, or
+credential is recorded in committed documentation or the pull request.
+
+## Recommendation
+
+The implementation is ready for security and maintainer review in draft PR
+[#2261](https://github.com/trycua/cua/pull/2261). Keep the advertised support
+matrix limited to the representative products and desktops proven above:
+Chrome and Edge on macOS and Windows, Chrome on X11, and Chromium on Sway.
+Linux product descriptors for Chrome, Chromium, and Edge remain available, but
+an untested product/desktop pair must not be described as release-accepted.
+
+Keep Safari, Firefox, unknown browser builds or locales, and generic Wayland
+compositors as structured refusals until they have an exact native setup
+adapter and representative real-browser evidence. Treat
+[#2240](https://github.com/trycua/cua/issues/2240) as the first consumer of the
+mutation gate in a separate follow-up; legacy page migration remains separate.
diff --git a/libs/cua-driver/docs/browser-tool-implementation-journal.md b/libs/cua-driver/docs/browser-tool-implementation-journal.md
index bb48c2d093..3c77980dff 100644
--- a/libs/cua-driver/docs/browser-tool-implementation-journal.md
+++ b/libs/cua-driver/docs/browser-tool-implementation-journal.md
@@ -534,3 +534,151 @@ page pass on the physical host, so this result is an environment limitation in
that VM image rather than a browser-tool or fixture regression. The matrix
keeps its readiness assertion; it does not convert the blank surface into a
pass or an expected product refusal.
+
+## 2026-07-16: existing-profile attachment and bounded reconnect
+
+Implemented the reviewed existing-profile strategy without changing the
+driver-owned isolated profile contract:
+
+- `browser_prepare` accepts the tagged
+ `strategy:{kind:"existing_profile"}` request only with an exact pid,
+ native window, named session, and five-minute single-use artifact minted by
+ the interactive `browser-approve` CLI. The ordinary MCP host marker cannot
+ authorize this route.
+- Grants live only in daemon memory and are scoped to public and transport
+ session, process fingerprint, native window, browser product, endpoint, and
+ connection generation. Idle/absolute expiry, consent dismissal, identity
+ change, reconnect exhaustion, session end, and daemon restart revoke the
+ grant and release its claimed socket.
+- One browser-level CDP connection is owned per generation. Reconnect is
+ single-flight per approved browser, has three attempts under one bounded
+ deadline, re-proves endpoint/process identity, and invalidates every older
+ target, tab, snapshot, frame, and ref capability.
+- Browser mutations serialize by process fingerprint plus real CDP target, so
+ two sessions cannot interleave actions in the same tab while independent
+ tabs remain parallel. Keystroke typing reports exact requested and delivered
+ character counts and returns `browser_input_incomplete` for a partial prefix.
+- Consent-bearing recording turns persist redacted metadata and result only.
+ Browser screenshots, AX snapshots, approval tokens, endpoint addresses,
+ ports, profile data, and authenticated page content are suppressed.
+
+The macOS Chrome adapter discovers a unique PID-owned loopback listener and
+uses a bounded native AX adapter. It acts only on one browser-owned modal sheet
+with remote-debugging corroboration and one semantic Allow button advertising
+AXPress. During physical-host validation, Chrome exposed the same top-level
+window through both AXChildren and AXWindows with different proxy pointers;
+top-level deduplication now uses Core Foundation object equality so a single
+sheet cannot become a false ambiguous match.
+
+A fresh disposable Chrome profile provided the real acceptance evidence. The
+user-facing remote-debugging toggle exposed one PID-owned listener; the exact
+CLI artifact authorized one call; Cua Driver pressed Chrome's consent action;
+`browser_prepare` returned `attached_existing_profile`; and the following
+`get_browser_state(pid, window_id, session)` produced an exact
+`native_cdp_window` binding without launching, restarting, copying, or changing
+the profile. A separate disposable-profile standalone harness proves the same
+public contract and a DOM mutation against an independent fixture oracle.
+
+Final local verification passed 236 core tests, 134 macOS platform tests, 102
+CLI tests, the protocol and session integration suites, and the ignored
+source-built `standalone_browser_existing_profile` real-browser row. The shared
+Windows/Linux/testkit packages compile with the additive contract. The exact
+branch build was installed locally as Cua Driver 0.8.3; its stable app identity
+retained both Accessibility and Screen Recording grants.
+
+Windows and Linux compile the same contract, grant, generation, mutation, and
+refusal model. Their native consent adapters remain strict refusals until an
+interactive UIA or AT-SPI harness proves stable browser-owned prompt semantics;
+no unsupported prompt route is advertised as working.
+
+The committed source snapshot was also replayed natively on isolated remote VM
+staging paths. The interactive Windows VM passed all 236 shared-core tests and
+96 Windows platform tests, with the two pre-existing cache UAF repro cases
+remaining ignored. The Wayland VM passed all 237 Linux shared-core tests and
+all 100 Linux platform tests. These are native contract and platform-crate
+results, not evidence of UIA or AT-SPI consent-dialog automation. An additional
+X11 VM attempt reached dependency compilation but its root filesystem had only
+4 MB free and returned `No space left on device`; it produced no behavioral
+verdict and was not counted as product evidence.
+
+## 2026-07-16: cross-platform existing-profile setup parity
+
+The existing-profile route now has product-specific setup descriptors for
+Chrome, Chromium, and Edge and native exact-control adapters on all advertised
+desktop platforms:
+
+- macOS uses exact AX page, checkbox, tab-cleanup, and browser-owned consent
+ semantics. A disposable Lume guest passed Chrome and Edge setup with video.
+- Windows uses exact HWND ownership plus UIA page, checkbox, cleanup, and
+ consent semantics. Chrome and Edge passed in a live Azure RDP user session,
+ not Session 0, with video.
+- Linux X11 uses exact X11 foreground restoration for the fixed setup
+ navigation and AT-SPI for the checkbox and consent action. Chrome passed with
+ video.
+- Linux native Wayland requires an exact Sway container and the browser's full
+ renderer accessibility tree. The setup path keeps URL text plus Enter in one
+ virtual-keyboard lifetime, then invokes the unique AT-SPI Remote debugging
+ navigation control. Chrome passed with another Chrome process open, proving
+ that changing tab titles and a shared app id do not redirect the action.
+
+Linux Chromium-family processes used by this harness include
+`--force-renderer-accessibility`; production calls without a complete AT-SPI
+tree refuse with the missing prerequisite. Sway focus is restored through the
+exact compositor container guard. Generic Wayland sessions without exact PID,
+window, and geometry identity are not promoted into a mutation route.
+
+All setup paths still require an operation-bound one-use approval artifact,
+prove a loopback listener owned by the approved PID, attach one browser-level
+socket, invalidate old capabilities, report every visible side effect, and
+attempt exact rollback after a failed setup. Safari, Firefox, unrecognized
+products/locales, and ambiguous setup or consent controls remain refusals.
+
+The evidence in this entry was produced from a dirty diagnostic source marker
+while the implementation was converging. It establishes behavior but is not
+release acceptance; the final commit must be synced and replayed with its exact
+SHA on every retained platform lane.
+
+## 2026-07-17: exact-SHA cross-platform existing-profile acceptance
+
+The final acceptance replay used exact source SHA
+`7fa6c80f5c433a7d4dadef75e4873af89de0cd3f`. A preceding Windows replay was
+discarded because host input and another runner contaminated the interactive
+desktop. A macOS replay then exposed a testkit posture defect: the foreground
+sentinel waited for Electron to focus itself before the harness explicitly
+activated it. The final testkit change waits for readiness, activates the exact
+sentinel, and proves native focus plus the fixture focus journal. It does not
+change any browser action or oracle.
+
+| Platform | Representative products | Rows | Delivered | Expected refusals | Failed | Skipped | Playable videos |
+| --- | --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| Windows/Win32 | Chrome, Edge | 20 | 18 | 2 | 0 | 0 | 20 |
+| macOS/Quartz | Chrome, Edge | 20 | 16 | 4 | 0 | 0 | 20 |
+| Linux/X11 | Chrome | 10 | 8 | 2 | 0 | 0 | 10 |
+| Linux/Wayland | Chromium on Sway | 10 | 8 | 2 | 0 | 0 | 10 |
+| **Total** | | **60** | **50** | **10** | **0** | **0** | **60** |
+
+All 60 declarations ran. Every result had `test_status=pass`; every MP4 was
+downloaded and independently checked for positive duration. The Windows lane
+ran in a live RDP user desktop rather than Session 0. The Linux lanes used
+Openbox/X11 and native Sway/Wayland respectively, while macOS ran in a
+TCC-authorized disposable Lume guest.
+
+The expected refusals are product signal, not environment skips. Every platform
+refused `browser_binding_ambiguous` when two native browser windows had the same
+bounds and no unique title tie-break. macOS and Linux additionally refused
+`browser_input_trust_unavailable` for Chromium's trusted CDP Input click because
+that route activated the standalone target; the ref-targeted `dom_event` route
+remains the synthetic full-background alternative. Windows delivered trusted
+clicks for both Chrome and Edge without changing the sentinel posture.
+
+The Sway wrapper replaced itself with `nix develop`, so its redundant shell EXIT
+trap could not write an exit-marker file. The canonical runner nevertheless
+finished, produced its summary, exited from the process table, recorded all 10
+passing rows, and generated 10 valid videos. The acceptance verdict is based on
+those canonical artifacts rather than the disposable wrapper marker.
+
+Focused local validation at the same source SHA passed all 46 testkit library
+tests. Branch CI passed Windows and Linux unit/compile, Nix package and policy,
+documentation, link, distribution-compatibility, and publication checks. The
+later documentation-only commit records this evidence and does not alter the
+accepted executable or harness source.
diff --git a/libs/cua-driver/rust/Skills/cua-driver/WEB_APPS.md b/libs/cua-driver/rust/Skills/cua-driver/WEB_APPS.md
index f1f68c079e..efd2838d9d 100644
--- a/libs/cua-driver/rust/Skills/cua-driver/WEB_APPS.md
+++ b/libs/cua-driver/rust/Skills/cua-driver/WEB_APPS.md
@@ -26,6 +26,34 @@ normal profile accidentally. MCP hosts approve the destructive prepare call;
direct/raw clients first mint a single-use token with the interactive
`cua-driver browser-approve` command.
+### Existing authenticated Chrome profiles (experimental macOS route)
+
+Do not treat ordinary MCP approval as permission to attach to a person's live
+profile. Mint an exact one-use artifact interactively before allowing any
+existing-profile setup:
+
+```bash
+cua-driver browser-approve --strategy existing_profile \
+ --pid <pid> --window-id <window_id> --session <session>
+```
+
+Pass the token to `browser_prepare` with
+`strategy:{kind:"existing_profile"}` and the same pid, window, and session.
+On macOS Chrome, if no endpoint exists, this approved operation opens a
+temporary tab in that exact window, navigates to Chrome's internal
+remote-debugging page, toggles the uniquely labelled per-instance checkbox,
+proves the loopback listener belongs to the approved pid, and closes the tab.
+Every visible effect, including temporary in-app address-field focus, is
+returned in `side_effects`; a refusal after setup starts reports partial effects
+in `detail.setup_side_effects`. Any missing or ambiguous control is refused.
+The exact AX setup currently recognizes English Chrome labels and fails closed
+on other locales. `get_browser_state` never performs this setup.
+After `attached_existing_profile`, bind again with `get_browser_state`; every
+older target, tab, and ref is stale. Rebind again after any successful bounded
+reconnect. Never retry a consent dismissal, invent an approval token, click a
+similar-looking dialog yourself, or pass the profile's path. End the named
+session when finished to revoke the in-memory grant.
+
This is the page-aware Chromium rung. Navigation, default ref-bound text
insertion, and an explicit DOM click can run against an exactly bound page
without raising its native window. `browser_click` defaults to trusted
diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/approval.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/approval.rs
index 6c6102f197..87669abf59 100644
--- a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/approval.rs
+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/approval.rs
@@ -20,7 +20,7 @@ pub const MCP_HOST_APPROVAL_ARG: &str = "_cua_browser_prepare_mcp_host_approved"
pub const MAX_APPROVAL_TTL: Duration = Duration::from_secs(5 * 60);
#[derive(Debug, Serialize, Deserialize)]
-struct ApprovalArtifact {
+struct IsolatedApprovalArtifact {
schema: String,
token: String,
pid: i64,
@@ -28,6 +28,24 @@ struct ApprovalArtifact {
expires_unix_ms: u128,
}
+/// Exact public operation authorized by an interactive existing-profile
+/// approval. Transport identity is intentionally absent: the daemon binds it
+/// when consuming the artifact and minting its in-memory grant.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ExistingProfileApprovalScope {
+ pub pid: i64,
+ pub window_id: u64,
+ pub session: String,
+}
+
+#[derive(Debug, Serialize, Deserialize)]
+struct ExistingProfileApprovalArtifact {
+ schema: String,
+ token: String,
+ scope: ExistingProfileApprovalScope,
+ expires_unix_ms: u128,
+}
+
fn refusal(message: impl Into<String>) -> BrowserRefusal {
BrowserRefusal::new(BrowserRefusalCode::BrowserConsentRequired, message)
}
@@ -90,7 +108,7 @@ pub fn mint_prepare_approval(pid: i64, profile: PrepareProfile) -> Result<String
.map_err(|error| refusal(format!("could not restrict approval directory: {error}")))?;
}
- let artifact = ApprovalArtifact {
+ let artifact = IsolatedApprovalArtifact {
schema: "cua-browser-prepare-approval-v1".to_owned(),
token: token.clone(),
pid,
@@ -116,6 +134,55 @@ pub fn mint_prepare_approval(pid: i64, profile: PrepareProfile) -> Result<String
Ok(token)
}
+fn persist_artifact<T: Serialize>(token: &str, artifact: &T) -> Result<(), BrowserRefusal> {
+ let root = approval_root();
+ fs::create_dir_all(&root)
+ .map_err(|error| refusal(format!("could not create approval directory: {error}")))?;
+ #[cfg(unix)]
+ {
+ use std::os::unix::fs::PermissionsExt;
+ fs::set_permissions(&root, fs::Permissions::from_mode(0o700))
+ .map_err(|error| refusal(format!("could not restrict approval directory: {error}")))?;
+ }
+ let path = artifact_path(token)?;
+ let mut options = OpenOptions::new();
+ options.write(true).create_new(true);
+ #[cfg(unix)]
+ {
+ use std::os::unix::fs::OpenOptionsExt;
+ options.mode(0o600);
+ }
+ let mut file = options
+ .open(path)
+ .map_err(|error| refusal(format!("could not create approval artifact: {error}")))?;
+ let bytes = serde_json::to_vec(artifact)
+ .map_err(|error| refusal(format!("could not encode approval artifact: {error}")))?;
+ file.write_all(&bytes)
+ .and_then(|_| file.sync_all())
+ .map_err(|error| refusal(format!("could not persist approval artifact: {error}")))
+}
+
+/// Mint a single-use artifact for the exact existing-profile request shown to
+/// the person at the interactive approval boundary.
+pub fn mint_existing_profile_approval(
+ scope: ExistingProfileApprovalScope,
+) -> Result<String, BrowserRefusal> {
+ if scope.pid <= 0 || scope.window_id == 0 || scope.session.trim().is_empty() {
+ return Err(refusal(
+ "existing-profile approval requires a positive pid/window_id and explicit session",
+ ));
+ }
+ let token = Uuid::new_v4().to_string();
+ let artifact = ExistingProfileApprovalArtifact {
+ schema: "cua-browser-existing-profile-approval-v1".to_owned(),
+ token: token.clone(),
+ scope,
+ expires_unix_ms: now_unix_ms()? + MAX_APPROVAL_TTL.as_millis(),
+ };
+ persist_artifact(&token, &artifact)?;
+ Ok(token)
+}
+
/// Consume approval evidence. The artifact is removed before any semantic
/// validation so malformed, mismatched, and expired attempts are single-use.
pub fn consume_prepare_approval(
@@ -129,7 +196,7 @@ pub fn consume_prepare_approval(
.map_err(|_| refusal("browser preparation approval token is missing or expired"))?;
fs::remove_file(&path)
.map_err(|error| refusal(format!("could not consume approval artifact: {error}")))?;
- let artifact: ApprovalArtifact = serde_json::from_slice(&bytes)
+ let artifact: IsolatedApprovalArtifact = serde_json::from_slice(&bytes)
.map_err(|_| refusal("browser preparation approval artifact is invalid"))?;
if artifact.schema != "cua-browser-prepare-approval-v1"
|| artifact.token != token
@@ -144,6 +211,31 @@ pub fn consume_prepare_approval(
Ok(())
}
+/// Consume an existing-profile artifact before validating it. A mismatch is
+/// deliberately destructive so an artifact can never become a probing oracle.
+pub fn consume_existing_profile_approval(
+ token: &str,
+ scope: &ExistingProfileApprovalScope,
+) -> Result<(), BrowserRefusal> {
+ let path = artifact_path(token)?;
+ let bytes = fs::read(&path)
+ .map_err(|_| refusal("browser preparation approval token is missing or expired"))?;
+ fs::remove_file(&path)
+ .map_err(|error| refusal(format!("could not consume approval artifact: {error}")))?;
+ let artifact: ExistingProfileApprovalArtifact = serde_json::from_slice(&bytes)
+ .map_err(|_| refusal("browser preparation approval artifact is invalid"))?;
+ if artifact.schema != "cua-browser-existing-profile-approval-v1"
+ || artifact.token != token
+ || artifact.scope != *scope
+ || artifact.expires_unix_ms < now_unix_ms()?
+ {
+ return Err(refusal(
+ "browser preparation approval does not match this pid/window/session request or has expired",
+ ));
+ }
+ Ok(())
+}
+
#[cfg(test)]
mod tests {
use super::*;
@@ -178,4 +270,30 @@ mod tests {
}
validate_profile(&named("research_2026-07")).unwrap();
}
+
+ #[test]
+ fn existing_profile_approval_is_exact_and_single_use() {
+ let scope = ExistingProfileApprovalScope {
+ pid: 42,
+ window_id: 7,
+ session: "approval-existing".to_owned(),
+ };
+ let token = mint_existing_profile_approval(scope.clone()).unwrap();
+ consume_existing_profile_approval(&token, &scope).unwrap();
+ assert!(consume_existing_profile_approval(&token, &scope).is_err());
+ }
+
+ #[test]
+ fn existing_profile_mismatch_consumes_artifact() {
+ let scope = ExistingProfileApprovalScope {
+ pid: 42,
+ window_id: 7,
+ session: "approval-existing-mismatch".to_owned(),
+ };
+ let token = mint_existing_profile_approval(scope.clone()).unwrap();
+ let mut wrong = scope.clone();
+ wrong.window_id = 8;
+ assert!(consume_existing_profile_approval(&token, &wrong).is_err());
+ assert!(consume_existing_profile_approval(&token, &scope).is_err());
+ }
}
diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/cdp_ws.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/cdp_ws.rs
index 53abcf1180..122438242c 100644
--- a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/cdp_ws.rs
+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/cdp_ws.rs
@@ -12,9 +12,9 @@
//! Only loopback `ws://` URLs are accepted: the endpoint is a local
//! browser the platform adapter proved we own, never a remote service.
-use std::collections::HashMap;
+use std::collections::{HashMap, HashSet};
use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
-use std::sync::{Arc, Mutex as StdMutex};
+use std::sync::{Arc, Mutex as StdMutex, OnceLock};
use std::time::Duration;
use futures_util::stream::{SplitSink, SplitStream};
@@ -246,9 +246,36 @@ impl CdpConnection {
}
}
-/// One pooled connection per endpoint URL.
+#[derive(Clone)]
+struct PoolEntry {
+ conn: Arc<CdpConnection>,
+ generation: Option<u64>,
+}
+
+fn claimed_ports() -> &'static StdMutex<HashSet<u16>> {
+ static CLAIMED: OnceLock<StdMutex<HashSet<u16>>> = OnceLock::new();
+ CLAIMED.get_or_init(|| StdMutex::new(HashSet::new()))
+}
+
+fn loopback_port(url: &str) -> Option<u16> {
+ let rest = url.strip_prefix("ws://")?;
+ let authority = rest.split('/').next()?;
+ if let Some(bracketed) = authority.strip_prefix('[') {
+ return bracketed.split_once("]:")?.1.parse().ok();
+ }
+ authority.rsplit_once(':')?.1.parse().ok()
+}
+
+/// Whether an existing-profile grant owns the DevTools listener used by this
+/// URL. The legacy page route consults this before opening its own page socket.
+pub fn endpoint_port_is_grant_owned(url: &str) -> bool {
+ loopback_port(url).is_some_and(|port| claimed_ports().lock().unwrap().contains(&port))
+}
+
+/// One pooled browser-level connection per endpoint URL. Existing-profile
+/// entries are additionally owned by one explicit connection generation.
pub struct CdpPool {
- conns: Mutex<HashMap<String, Arc<CdpConnection>>>,
+ conns: Mutex<HashMap<String, PoolEntry>>,
}
impl CdpPool {
@@ -261,15 +288,124 @@ impl CdpPool {
/// Get the pooled connection for `ws_url`, dialing if needed.
/// A connection whose socket closed is replaced transparently.
pub async fn get(&self, ws_url: &str) -> anyhow::Result<Arc<CdpConnection>> {
+ if endpoint_port_is_grant_owned(ws_url) {
+ anyhow::bail!(
+ "this DevTools endpoint is owned by a first-class existing-profile attachment"
+ );
+ }
let mut conns = self.conns.lock().await;
if let Some(existing) = conns.get(ws_url) {
- if !existing.is_closed() {
- return Ok(existing.clone());
+ if existing.generation.is_some() {
+ anyhow::bail!("this DevTools endpoint is owned by an attachment generation");
+ }
+ if !existing.conn.is_closed() {
+ return Ok(existing.conn.clone());
}
conns.remove(ws_url);
}
let conn = Arc::new(CdpConnection::connect(ws_url).await?);
- conns.insert(ws_url.to_owned(), conn.clone());
+ conns.insert(
+ ws_url.to_owned(),
+ PoolEntry {
+ conn: conn.clone(),
+ generation: None,
+ },
+ );
+ Ok(conn)
+ }
+
+ /// Convert the one live browser-level socket into grant-owned state. This
+ /// does not redial and therefore cannot create a second consent prompt.
+ pub async fn claim_existing(
+ &self,
+ ws_url: &str,
+ generation: u64,
+ ) -> anyhow::Result<Arc<CdpConnection>> {
+ let port = loopback_port(ws_url)
+ .ok_or_else(|| anyhow::anyhow!("existing-profile endpoint has no loopback port"))?;
+ let mut conns = self.conns.lock().await;
+ let conn = match conns.get(ws_url) {
+ Some(entry) if !entry.conn.is_closed() => entry.conn.clone(),
+ Some(_) => anyhow::bail!("the approved browser socket closed before it was claimed"),
+ None => Arc::new(CdpConnection::connect(ws_url).await?),
+ };
+ conns.insert(
+ ws_url.to_owned(),
+ PoolEntry {
+ conn: conn.clone(),
+ generation: Some(generation),
+ },
+ );
+ claimed_ports().lock().unwrap().insert(port);
+ Ok(conn)
+ }
+
+ /// Reuse only the socket belonging to the exact live grant generation.
+ /// Closed sockets are not replaced here; reconnect is an explicit state
+ /// transition owned by the browser engine.
+ pub async fn get_existing(
+ &self,
+ ws_url: &str,
+ generation: u64,
+ ) -> anyhow::Result<Arc<CdpConnection>> {
+ let conns = self.conns.lock().await;
+ let entry = conns
+ .get(ws_url)
+ .ok_or_else(|| anyhow::anyhow!("the grant-owned browser socket is missing"))?;
+ if entry.generation != Some(generation) {
+ anyhow::bail!("the browser socket belongs to a different connection generation");
+ }
+ if entry.conn.is_closed() {
+ anyhow::bail!("the grant-owned browser socket is closed");
+ }
+ Ok(entry.conn.clone())
+ }
+
+ /// Replace one dead grant-owned socket with exactly one new generation.
+ pub async fn reconnect_existing(
+ &self,
+ ws_url: &str,
+ old_generation: u64,
+ new_generation: u64,
+ ) -> anyhow::Result<Arc<CdpConnection>> {
+ {
+ let conns = self.conns.lock().await;
+ if let Some(entry) = conns.get(ws_url) {
+ if entry
+ .generation
+ .is_some_and(|generation| generation > old_generation)
+ {
+ anyhow::bail!("the reconnect source generation is no longer current");
+ }
+ if entry.generation == Some(old_generation) && !entry.conn.is_closed() {
+ return Ok(entry.conn.clone());
+ }
+ }
+ }
+
+ // A WebSocket handshake can wait for browser-owned consent UI. Never
+ // hold the pool mutex across that wait: grant revocation must remain
+ // able to remove the old generation when consent is refused.
+ let conn = Arc::new(CdpConnection::connect(ws_url).await?);
+ let mut conns = self.conns.lock().await;
+ if let Some(entry) = conns.get(ws_url) {
+ if entry
+ .generation
+ .is_some_and(|generation| generation > old_generation)
+ {
+ if entry.generation == Some(new_generation) && !entry.conn.is_closed() {
+ return Ok(entry.conn.clone());
+ }
+ anyhow::bail!("the reconnect source generation is no longer current");
+ }
+ }
+ conns.insert(
+ ws_url.to_owned(),
+ PoolEntry {
+ conn: conn.clone(),
+ generation: Some(new_generation),
+ },
+ );
Ok(conn)
}
@@ -277,6 +413,24 @@ impl CdpPool {
pub async fn evict(&self, ws_url: &str) {
self.conns.lock().await.remove(ws_url);
}
+
+ pub fn release_claim_marker(&self, ws_url: &str) {
+ if let Some(port) = loopback_port(ws_url) {
+ claimed_ports().lock().unwrap().remove(&port);
+ }
+ }
+
+ pub async fn release_existing(&self, ws_url: &str, generation: u64) {
+ let mut conns = self.conns.lock().await;
+ if conns
+ .get(ws_url)
+ .is_some_and(|entry| entry.generation == Some(generation))
+ {
+ conns.remove(ws_url);
+ }
+ drop(conns);
+ self.release_claim_marker(ws_url);
+ }
}
impl Default for CdpPool {
@@ -334,6 +488,55 @@ mod tests {
assert_eq!(result["echoed"]["x"], 7);
}
+ #[tokio::test]
+ async fn claimed_existing_profile_socket_is_generation_owned() {
+ let server = MockCdpServer::start(StdArc::new(|_| MockReply::ok(json!({})))).await;
+ let url = server.ws_url();
+ let pool = CdpPool::new();
+ let initial = pool.get(&url).await.unwrap();
+ let claimed = pool.claim_existing(&url, 1).await.unwrap();
+ assert!(Arc::ptr_eq(&initial, &claimed), "claim must not redial");
+ assert!(pool.get(&url).await.is_err(), "legacy access must refuse");
+ assert!(pool.get_existing(&url, 2).await.is_err());
+ let reused = pool.get_existing(&url, 1).await.unwrap();
+ assert!(Arc::ptr_eq(&claimed, &reused));
+ pool.release_existing(&url, 1).await;
+ assert!(
+ pool.get(&url).await.is_ok(),
+ "session cleanup releases ownership"
+ );
+ }
+
+ #[tokio::test]
+ async fn stalled_reconnect_does_not_block_generation_release() {
+ let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+ let port = listener.local_addr().unwrap().port();
+ let server = tokio::spawn(async move {
+ let (first, _) = listener.accept().await.unwrap();
+ let _first_ws = tokio_tungstenite::accept_async(first).await.unwrap();
+ let (_stalled_reconnect, _) = listener.accept().await.unwrap();
+ tokio::time::sleep(std::time::Duration::from_secs(10)).await;
+ });
+ let url = format!("ws://127.0.0.1:{port}/devtools/browser/reconnect");
+ let pool = CdpPool::new();
+ let claimed = pool.claim_existing(&url, 1).await.unwrap();
+ claimed.demux.close();
+
+ let mut reconnect = Box::pin(pool.reconnect_existing(&url, 1, 2));
+ tokio::select! {
+ _ = &mut reconnect => panic!("reconnect unexpectedly completed"),
+ _ = tokio::time::sleep(std::time::Duration::from_millis(100)) => {}
+ }
+ tokio::time::timeout(
+ std::time::Duration::from_millis(500),
+ pool.release_existing(&url, 1),
+ )
+ .await
+ .expect("grant release must not wait for the reconnect handshake");
+ drop(reconnect);
+ server.abort();
+ }
+
#[tokio::test]
async fn cdp_error_codes_are_preserved_in_the_message() {
let server = MockCdpServer::start(StdArc::new(|_| {
diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/engine.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/engine.rs
index 7c671f3a34..18d2a23bc4 100644
--- a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/engine.rs
+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/engine.rs
@@ -32,8 +32,11 @@ use crate::session::register_session_end_hook;
use super::binding::{cardinality_exact_candidate, correlate, BindingOutcome, CdpWindowCandidate};
use super::cdp_ws::{CdpConnection, CdpPool};
-use super::platform::BrowserPlatform;
+use super::grant::{ExistingProfileGrant, ExistingProfileGrants, GrantLookup};
+use super::mutation::{MutationGates, MutationKey};
+use super::platform::{BrowserConsentOutcome, BrowserConsentRequest, BrowserPlatform};
use super::prepare::ManagedBrowsers;
+use super::reconnect::ReconnectGates;
use super::refusal::{BrowserRefusal, BrowserRefusalCode};
use super::store::{
format_ref, BrowserStore, FrameIdentity, FrameKind, FrameRef, RefEntry, SnapshotRecord,
@@ -54,6 +57,9 @@ pub struct BrowserEngine {
pub(crate) store: BrowserStore,
pub(crate) pool: CdpPool,
pub(crate) managed_browsers: ManagedBrowsers,
+ pub(crate) existing_profile_grants: ExistingProfileGrants,
+ mutation_gates: MutationGates,
+ reconnect_gates: ReconnectGates,
}
fn refuse(code: BrowserRefusalCode, msg: impl Into<String>) -> BrowserRefusal {
@@ -209,12 +215,26 @@ impl BrowserEngine {
store: BrowserStore::new(),
pool: CdpPool::new(),
managed_browsers: Default::default(),
+ existing_profile_grants: ExistingProfileGrants::new(),
+ mutation_gates: MutationGates::new(),
+ reconnect_gates: ReconnectGates::new(),
});
let weak: Weak<Self> = Arc::downgrade(&engine);
register_session_end_hook(move |session_id| {
if let Some(engine) = weak.upgrade() {
engine.store.remove_session(session_id);
engine.cleanup_prepared_session(session_id);
+ for (endpoint, generation) in
+ engine.existing_profile_grants.remove_session(session_id)
+ {
+ engine.pool.release_claim_marker(&endpoint);
+ if let Ok(runtime) = tokio::runtime::Handle::try_current() {
+ let engine = engine.clone();
+ runtime.spawn(async move {
+ engine.pool.release_existing(&endpoint, generation).await;
+ });
+ }
+ }
}
});
engine
@@ -222,7 +242,49 @@ impl BrowserEngine {
// ── Endpoint / CDP plumbing ─────────────────────────────────────────
- async fn connect(&self, ws_url: &str) -> Result<Arc<CdpConnection>, BrowserRefusal> {
+ pub(crate) async fn existing_profile_grant(
+ &self,
+ session: &str,
+ transport_session: Option<&str>,
+ pid: i64,
+ ) -> Result<Option<ExistingProfileGrant>, BrowserRefusal> {
+ match self
+ .existing_profile_grants
+ .lookup(session, transport_session, pid)
+ {
+ GrantLookup::Missing => Ok(None),
+ GrantLookup::Live(grant) => Ok(Some(grant)),
+ GrantLookup::Expired(grant) => {
+ self.pool.release_claim_marker(&grant.endpoint_ws_url);
+ self.pool
+ .release_existing(&grant.endpoint_ws_url, grant.generation)
+ .await;
+ Err(refuse(
+ BrowserRefusalCode::BrowserConsentRequired,
+ "the existing-profile grant expired; approve this attachment again",
+ ))
+ }
+ }
+ }
+
+ pub(crate) async fn revoke_existing_profile_grant(
+ &self,
+ session: &str,
+ transport_session: Option<&str>,
+ pid: i64,
+ ) {
+ if let Some(grant) = self
+ .existing_profile_grants
+ .revoke(session, transport_session, pid)
+ {
+ self.pool.release_claim_marker(&grant.endpoint_ws_url);
+ self.pool
+ .release_existing(&grant.endpoint_ws_url, grant.generation)
+ .await;
+ }
+ }
+
+ pub(crate) async fn connect(&self, ws_url: &str) -> Result<Arc<CdpConnection>, BrowserRefusal> {
match self.pool.get(ws_url).await {
Ok(conn) => Ok(conn),
Err(first_err) => {
@@ -237,8 +299,204 @@ impl BrowserEngine {
}
}
+ async fn connect_existing_profile(
+ &self,
+ session: &str,
+ transport_session: Option<&str>,
+ pid: i64,
+ ) -> Result<(Arc<CdpConnection>, ExistingProfileGrant), BrowserRefusal> {
+ let grant = self
+ .existing_profile_grant(session, transport_session, pid)
+ .await?
+ .ok_or_else(|| {
+ refuse(
+ BrowserRefusalCode::BrowserConsentRequired,
+ "no live existing-profile grant remains for this browser session",
+ )
+ })?;
+ if let Ok(conn) = self
+ .pool
+ .get_existing(&grant.endpoint_ws_url, grant.generation)
+ .await
+ {
+ return Ok((conn, grant));
+ }
+
+ // One leader owns endpoint reproof and bounded redial. Followers
+ // re-check the generation after acquiring this gate and reuse its
+ // socket rather than opening another browser-level connection.
+ let _leader = self
+ .reconnect_gates
+ .lock(&grant.fingerprint, &grant.endpoint_ws_url)
+ .await;
+ let mut grant = self
+ .existing_profile_grant(session, transport_session, pid)
+ .await?
+ .ok_or_else(|| {
+ refuse(
+ BrowserRefusalCode::BrowserConsentRequired,
+ "the existing-profile grant ended while reconnecting",
+ )
+ })?;
+ if let Ok(conn) = self
+ .pool
+ .get_existing(&grant.endpoint_ws_url, grant.generation)
+ .await
+ {
+ return Ok((conn, grant));
+ }
+
+ let deadline = tokio::time::Instant::now() + std::time::Duration::from_secs(32);
+ let mut last_error = None;
+ while tokio::time::Instant::now() < deadline && grant.reconnect_attempts_remaining > 0 {
+ if grant.pid != pid || grant.browser != "chromium" {
+ self.revoke_existing_profile_grant(session, transport_session, pid)
+ .await;
+ return Err(refuse(
+ BrowserRefusalCode::BrowserConsentRequired,
+ "the reconnect request no longer matches the approved browser identity",
+ ));
+ }
+ let classification = self.platform.classify_browser(pid).await?;
+ if !classification.supports_cdp
+ || classification.engine != super::types::BrowserEngineFamily::Chromium
+ {
+ self.revoke_existing_profile_grant(session, transport_session, pid)
+ .await;
+ return Err(refuse(
+ BrowserRefusalCode::BrowserConsentRequired,
+ "the approved process is no longer a supported Chromium browser",
+ ));
+ }
+ let fingerprint = self.platform.process_fingerprint(pid).await?;
+ if !grant.fingerprint.matches(&fingerprint) {
+ self.revoke_existing_profile_grant(session, transport_session, pid)
+ .await;
+ return Err(refuse(
+ BrowserRefusalCode::BrowserConsentRequired,
+ "the browser process changed; existing-profile attachment needs fresh approval",
+ ));
+ }
+ let endpoint = self
+ .platform
+ .reprove_existing_profile_endpoint(pid, &grant.endpoint_ws_url)
+ .await?
+ .ok_or_else(|| {
+ refuse(
+ BrowserRefusalCode::BrowserRequiresSetup,
+ "the approved browser endpoint disappeared during reconnect",
+ )
+ })?;
+ if endpoint.ownership.owner_pid != pid {
+ return Err(refuse(
+ BrowserRefusalCode::BrowserEndpointOwnerMismatch,
+ "the reconnect endpoint is not owned by the approved browser process",
+ ));
+ }
+ if endpoint.ws_url != grant.endpoint_ws_url {
+ self.revoke_existing_profile_grant(session, transport_session, pid)
+ .await;
+ return Err(refuse(
+ BrowserRefusalCode::BrowserEndpointOwnerMismatch,
+ "the browser DevTools endpoint changed during reconnect",
+ ));
+ }
+
+ let old_generation = grant.generation;
+ let new_generation =
+ self.existing_profile_grants
+ .bump_generation(session, transport_session, pid)?;
+ self.store
+ .invalidate_endpoint_generation(pid, old_generation);
+ let attempt = super::grant::MAX_RECONNECT_ATTEMPTS
+ .saturating_sub(grant.reconnect_attempts_remaining)
+ .saturating_add(1);
+ let mut reconnect = Box::pin(self.pool.reconnect_existing(
+ &endpoint.ws_url,
+ old_generation,
+ new_generation,
+ ));
+ let reconnected = tokio::select! {
+ result = &mut reconnect => result,
+ _ = tokio::time::sleep(std::time::Duration::from_millis(500)) => {
+ match self.platform.handle_existing_profile_consent(BrowserConsentRequest {
+ pid,
+ window_id: grant.window_id,
+ attempt,
+ }).await {
+ Ok(BrowserConsentOutcome::Accepted | BrowserConsentOutcome::NotPresent) => {
+ reconnect.await
+ }
+ Err(error) => {
+ // The reconnect future may be waiting on browser
+ // consent. Cancel it before grant revocation so no
+ // socket-pool resource can outlive this refusal.
+ drop(reconnect);
+ if error.code == BrowserRefusalCode::BrowserConsentRevoked {
+ self.revoke_existing_profile_grant(session, transport_session, pid)
+ .await;
+ }
+ return Err(error);
+ }
+ }
+ }
+ };
+ match reconnected {
+ Ok(conn) => {
+ grant = self
+ .existing_profile_grant(session, transport_session, pid)
+ .await?
+ .expect("grant exists after successful generation bump");
+ return Ok((conn, grant));
+ }
+ Err(error) => {
+ last_error = Some(error.to_string());
+ grant = self
+ .existing_profile_grant(session, transport_session, pid)
+ .await?
+ .expect("grant exists while reconnect budget remains");
+ }
+ }
+ }
+ self.revoke_existing_profile_grant(session, transport_session, pid)
+ .await;
+ Err(refuse(
+ BrowserRefusalCode::BrowserReconnectExhausted,
+ "the bounded existing-profile reconnect attempts did not establish a proven browser socket",
+ )
+ .with_detail(json!({
+ "attempt_limit": super::grant::MAX_RECONNECT_ATTEMPTS,
+ "last_error": last_error.map(|_| "connection_failed"),
+ "retryable": false,
+ })))
+ }
+
+ async fn connection_for_record(
+ &self,
+ session: &str,
+ record: &TargetRecord,
+ ) -> Result<Arc<CdpConnection>, BrowserRefusal> {
+ if record.generation == 0 {
+ return self.connect(&record.ws_url).await;
+ }
+ let (conn, grant) = self
+ .connect_existing_profile(
+ session,
+ record.grant_transport_session.as_deref(),
+ record.pid,
+ )
+ .await?;
+ if grant.generation != record.generation {
+ return Err(refuse(
+ BrowserRefusalCode::BrowserBindingStale,
+ "the browser reconnected and invalidated this target; re-run get_browser_state",
+ ));
+ }
+ Ok(conn)
+ }
+
/// Discover + ownership-check the endpoint for `pid`.
- async fn owned_endpoint(&self, pid: i64) -> Result<OwnedEndpoint, BrowserRefusal> {
+ pub(crate) async fn owned_endpoint(&self, pid: i64) -> Result<OwnedEndpoint, BrowserRefusal> {
let endpoint = self
.platform
.discover_owned_endpoint(pid)
@@ -265,6 +523,35 @@ impl BrowserEngine {
Ok(endpoint)
}
+ /// Re-prove the endpoint exposed by an explicitly approved existing
+ /// profile. This route is intentionally separate from driver-managed
+ /// endpoint discovery: Chrome's per-instance remote-debugging toggle can
+ /// expose only a PID-owned listener, with no DevToolsActivePort file or
+ /// discoverable driver-owned profile.
+ async fn existing_profile_endpoint(
+ &self,
+ pid: i64,
+ expected_ws_url: &str,
+ ) -> Result<OwnedEndpoint, BrowserRefusal> {
+ let endpoint = self
+ .platform
+ .reprove_existing_profile_endpoint(pid, expected_ws_url)
+ .await?
+ .ok_or_else(|| {
+ refuse(
+ BrowserRefusalCode::BrowserRequiresSetup,
+ "the approved existing-profile DevTools endpoint is no longer available",
+ )
+ })?;
+ if endpoint.ownership.owner_pid != pid {
+ return Err(refuse(
+ BrowserRefusalCode::BrowserEndpointOwnerMismatch,
+ "the existing-profile endpoint is not owned by the approved browser process",
+ ));
+ }
+ Ok(endpoint)
+ }
+
/// List page-type CDP targets with their window geometry.
async fn window_candidates(
&self,
@@ -428,6 +715,7 @@ impl BrowserEngine {
pub(crate) async fn bind_native(
&self,
session: &str,
+ transport_session: Option<&str>,
pid: i64,
window_id: u64,
) -> Result<(String, TargetRecord), BrowserRefusal> {
@@ -449,9 +737,36 @@ impl BrowserEngine {
}
let native = self.native_window_checked(pid, window_id).await?;
- let endpoint = self.owned_endpoint(pid).await?;
let fingerprint = self.platform.process_fingerprint(pid).await?;
- let conn = self.connect(&endpoint.ws_url).await?;
+ let mut grant = self
+ .existing_profile_grant(session, transport_session, pid)
+ .await?;
+ let endpoint = if let Some(live_grant) = &grant {
+ self.existing_profile_endpoint(pid, &live_grant.endpoint_ws_url)
+ .await?
+ } else {
+ self.owned_endpoint(pid).await?
+ };
+ if let Some(grant) = &grant {
+ if !grant.fingerprint.matches(&fingerprint)
+ || grant.endpoint_ws_url != endpoint.ws_url
+ || grant.window_id != window_id
+ {
+ return Err(refuse(
+ BrowserRefusalCode::BrowserBindingStale,
+ "the approved browser process, endpoint, or native window changed; approve the existing profile again",
+ ));
+ }
+ }
+ let conn = if grant.is_some() {
+ let (conn, live_grant) = self
+ .connect_existing_profile(session, transport_session, pid)
+ .await?;
+ grant = Some(live_grant);
+ conn
+ } else {
+ self.connect(&endpoint.ws_url).await?
+ };
let candidates = self.window_candidates(&conn).await?;
let correlation = correlate(&native, &candidates, BOUNDS_TOLERANCE_PX);
@@ -513,6 +828,7 @@ impl BrowserEngine {
TabRecord {
tab_id,
cdp_target_id: c.cdp_target_id.clone(),
+ generation: grant.as_ref().map_or(0, |grant| grant.generation),
snapshots: HashMap::new(),
},
);
@@ -524,6 +840,8 @@ impl BrowserEngine {
window_id,
ws_url: endpoint.ws_url.clone(),
endpoint_owner_pid: endpoint.ownership.owner_pid,
+ generation: grant.as_ref().map_or(0, |grant| grant.generation),
+ grant_transport_session: grant.as_ref().map(|grant| grant.transport_session.clone()),
fingerprint,
native_title: native.title.clone(),
native_bounds: native.bounds,
@@ -537,7 +855,7 @@ impl BrowserEngine {
Ok((target_id, record))
}
- async fn native_window_checked(
+ pub(crate) async fn native_window_checked(
&self,
pid: i64,
window_id: u64,
@@ -590,6 +908,34 @@ impl BrowserEngine {
)
})?;
+ if record.generation != tab.generation {
+ return Err(refuse(
+ BrowserRefusalCode::BrowserBindingStale,
+ "the tab capability belongs to an older browser connection generation",
+ ));
+ }
+ if record.generation > 0 {
+ let grant = self
+ .existing_profile_grant(
+ session,
+ record.grant_transport_session.as_deref(),
+ record.pid,
+ )
+ .await?
+ .ok_or_else(|| {
+ refuse(
+ BrowserRefusalCode::BrowserConsentRequired,
+ "the existing-profile grant ended; approve and bind the browser again",
+ )
+ })?;
+ if grant.generation != record.generation {
+ return Err(refuse(
+ BrowserRefusalCode::BrowserBindingStale,
+ "the browser connection generation changed; re-run get_browser_state",
+ ));
+ }
+ }
+
// 1. Process fingerprint — pid reuse / restart detection.
let fp_now = self.platform.process_fingerprint(record.pid).await?;
if !record.fingerprint.matches(&fp_now) {
@@ -609,7 +955,12 @@ impl BrowserEngine {
.await?;
// 3. Endpoint still owned and unchanged.
- let endpoint = self.owned_endpoint(record.pid).await?;
+ let endpoint = if record.generation > 0 {
+ self.existing_profile_endpoint(record.pid, &record.ws_url)
+ .await?
+ } else {
+ self.owned_endpoint(record.pid).await?
+ };
if endpoint.ws_url != record.ws_url {
return Err(refuse(
BrowserRefusalCode::BrowserBindingStale,
@@ -620,7 +971,7 @@ impl BrowserEngine {
// 4. CDP target still a page in the bound CDP window, with either
// matching geometry or the same singleton cardinality proof.
- let conn = self.connect(&record.ws_url).await?;
+ let conn = self.connection_for_record(session, &record).await?;
let candidates = self.window_candidates(&conn).await?;
let live = candidates
.iter()
@@ -681,6 +1032,27 @@ impl BrowserEngine {
})
}
+ /// Serialize the full revalidate-dispatch-verify interval by the real CDP
+ /// target rather than by a caller-controlled session id.
+ pub(crate) async fn lock_mutation(
+ &self,
+ session: &str,
+ target_id: &str,
+ tab_id: &str,
+ ) -> Result<tokio::sync::OwnedMutexGuard<()>, BrowserRefusal> {
+ let record = self.store.get_target(session, target_id)?;
+ let tab = record.tabs.get(tab_id).ok_or_else(|| {
+ refuse(
+ BrowserRefusalCode::BrowserTabNotFound,
+ format!("tab {tab_id} is not known for target {target_id}"),
+ )
+ })?;
+ Ok(self
+ .mutation_gates
+ .lock(MutationKey::new(&record.fingerprint, &tab.cdp_target_id))
+ .await)
+ }
+
// ── Frame identity / OOPIF plumbing ─────────────────────────────────
/// Fetch and parse one session's local frame tree.
@@ -875,7 +1247,7 @@ impl BrowserEngine {
format!("tab {tab_id} is not known for target {target_id}"),
)
})?;
- let conn = self.connect(&record.ws_url).await?;
+ let conn = self.connection_for_record(session, &record).await?;
let cdp_session = self.attach(&conn, &tab.cdp_target_id).await?;
let doc = conn
@@ -1057,6 +1429,7 @@ impl BrowserEngine {
snapshot_id,
SnapshotRecord {
id: snapshot_id,
+ generation: record.generation,
url: url.clone(),
refs,
},
diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/grant.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/grant.rs
new file mode 100644
index 0000000000..60f9d71d7e
--- /dev/null
+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/grant.rs
@@ -0,0 +1,268 @@
+//! Daemon-memory grants for user-owned browser profile attachment.
+//!
+//! Grant identifiers never cross the public tool boundary. The store itself is
+//! the daemon-instance boundary: dropping/restarting the engine drops every
+//! grant, connection generation, and reconnect budget.
+
+use std::collections::HashMap;
+use std::sync::Mutex;
+use std::time::{Duration, Instant};
+
+use super::refusal::{BrowserRefusal, BrowserRefusalCode};
+use super::types::ProcessFingerprint;
+
+const GRANT_IDLE_TTL: Duration = Duration::from_secs(30 * 60);
+const GRANT_ABSOLUTE_TTL: Duration = Duration::from_secs(8 * 60 * 60);
+pub const MAX_RECONNECT_ATTEMPTS: u8 = 3;
+
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+struct GrantKey {
+ public_session: String,
+ transport_session: String,
+ pid: i64,
+}
+
+#[derive(Debug, Clone)]
+pub(crate) struct ExistingProfileGrant {
+ pub public_session: String,
+ pub transport_session: String,
+ pub pid: i64,
+ pub window_id: u64,
+ pub fingerprint: ProcessFingerprint,
+ pub browser: String,
+ pub endpoint_ws_url: String,
+ pub generation: u64,
+ pub reconnect_attempts_remaining: u8,
+ created_at: Instant,
+ last_used_at: Instant,
+}
+
+pub(crate) enum GrantLookup {
+ Missing,
+ Live(ExistingProfileGrant),
+ Expired(ExistingProfileGrant),
+}
+
+impl ExistingProfileGrant {
+ fn expired(&self, now: Instant) -> bool {
+ now.duration_since(self.last_used_at) > GRANT_IDLE_TTL
+ || now.duration_since(self.created_at) > GRANT_ABSOLUTE_TTL
+ }
+}
+
+#[derive(Default)]
+pub(crate) struct ExistingProfileGrants {
+ inner: Mutex<HashMap<GrantKey, ExistingProfileGrant>>,
+}
+
+impl ExistingProfileGrants {
+ pub fn new() -> Self {
+ Self::default()
+ }
+
+ fn key(public_session: &str, transport_session: Option<&str>, pid: i64) -> GrantKey {
+ GrantKey {
+ public_session: public_session.to_owned(),
+ transport_session: transport_session.unwrap_or(public_session).to_owned(),
+ pid,
+ }
+ }
+
+ pub fn mint(
+ &self,
+ public_session: &str,
+ transport_session: Option<&str>,
+ pid: i64,
+ window_id: u64,
+ fingerprint: ProcessFingerprint,
+ browser: String,
+ endpoint_ws_url: String,
+ ) -> ExistingProfileGrant {
+ let now = Instant::now();
+ let key = Self::key(public_session, transport_session, pid);
+ let generation = self
+ .inner
+ .lock()
+ .unwrap()
+ .get(&key)
+ .map_or(1, |grant| grant.generation.saturating_add(1));
+ let grant = ExistingProfileGrant {
+ public_session: public_session.to_owned(),
+ transport_session: transport_session.unwrap_or(public_session).to_owned(),
+ pid,
+ window_id,
+ fingerprint,
+ browser,
+ endpoint_ws_url,
+ generation,
+ reconnect_attempts_remaining: MAX_RECONNECT_ATTEMPTS,
+ created_at: now,
+ last_used_at: now,
+ };
+ self.inner.lock().unwrap().insert(key, grant.clone());
+ grant
+ }
+
+ pub fn lookup(
+ &self,
+ public_session: &str,
+ transport_session: Option<&str>,
+ pid: i64,
+ ) -> GrantLookup {
+ let key = Self::key(public_session, transport_session, pid);
+ let now = Instant::now();
+ let mut grants = self.inner.lock().unwrap();
+ let Some(grant) = grants.get_mut(&key) else {
+ return GrantLookup::Missing;
+ };
+ if grant.expired(now) {
+ return GrantLookup::Expired(grants.remove(&key).expect("expired grant exists"));
+ }
+ grant.last_used_at = now;
+ GrantLookup::Live(grant.clone())
+ }
+
+ pub fn revoke(
+ &self,
+ public_session: &str,
+ transport_session: Option<&str>,
+ pid: i64,
+ ) -> Option<ExistingProfileGrant> {
+ self.inner
+ .lock()
+ .unwrap()
+ .remove(&Self::key(public_session, transport_session, pid))
+ }
+
+ pub fn remove_session(&self, session: &str) -> Vec<(String, u64)> {
+ let mut removed = Vec::new();
+ self.inner.lock().unwrap().retain(|_, grant| {
+ let keep = grant.public_session != session && grant.transport_session != session;
+ if !keep {
+ removed.push((grant.endpoint_ws_url.clone(), grant.generation));
+ }
+ keep
+ });
+ removed
+ }
+
+ pub fn bump_generation(
+ &self,
+ public_session: &str,
+ transport_session: Option<&str>,
+ pid: i64,
+ ) -> Result<u64, BrowserRefusal> {
+ let key = Self::key(public_session, transport_session, pid);
+ let mut grants = self.inner.lock().unwrap();
+ let grant = grants.get_mut(&key).ok_or_else(|| {
+ BrowserRefusal::new(
+ BrowserRefusalCode::BrowserConsentRequired,
+ "no live existing-profile grant remains for reconnect",
+ )
+ })?;
+ if grant.reconnect_attempts_remaining == 0 {
+ return Err(BrowserRefusal::new(
+ BrowserRefusalCode::BrowserReconnectExhausted,
+ "the bounded existing-profile reconnect budget is exhausted",
+ ));
+ }
+ grant.reconnect_attempts_remaining -= 1;
+ grant.generation = grant.generation.saturating_add(1);
+ grant.last_used_at = Instant::now();
+ Ok(grant.generation)
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn fingerprint(pid: i64) -> ProcessFingerprint {
+ ProcessFingerprint {
+ pid,
+ start_time: Some(7),
+ executable: Some("chrome".to_owned()),
+ }
+ }
+
+ #[test]
+ fn grants_are_scoped_to_public_and_transport_session() {
+ let grants = ExistingProfileGrants::new();
+ grants.mint(
+ "public-a",
+ Some("transport-a"),
+ 42,
+ 9,
+ fingerprint(42),
+ "chromium".to_owned(),
+ "ws://127.0.0.1:1/devtools/browser/x".to_owned(),
+ );
+ assert!(matches!(
+ grants.lookup("public-a", Some("transport-a"), 42),
+ GrantLookup::Live(_)
+ ));
+ assert!(matches!(
+ grants.lookup("public-b", Some("transport-a"), 42),
+ GrantLookup::Missing
+ ));
+ assert!(matches!(
+ grants.lookup("public-a", Some("transport-b"), 42),
+ GrantLookup::Missing
+ ));
+ }
+
+ #[test]
+ fn session_cleanup_revokes_both_owners() {
+ let grants = ExistingProfileGrants::new();
+ grants.mint(
+ "public-a",
+ Some("transport-a"),
+ 42,
+ 9,
+ fingerprint(42),
+ "chromium".to_owned(),
+ "ws://127.0.0.1:1/devtools/browser/x".to_owned(),
+ );
+ assert_eq!(grants.remove_session("transport-a").len(), 1);
+ assert!(matches!(
+ grants.lookup("public-a", Some("transport-a"), 42),
+ GrantLookup::Missing
+ ));
+ }
+
+ #[test]
+ fn expired_lookup_returns_the_connection_owner_for_cleanup() {
+ let grants = ExistingProfileGrants::new();
+ grants.mint(
+ "public-a",
+ Some("transport-a"),
+ 42,
+ 9,
+ fingerprint(42),
+ "chromium".to_owned(),
+ "ws://127.0.0.1:1/devtools/browser/x".to_owned(),
+ );
+ let key = ExistingProfileGrants::key("public-a", Some("transport-a"), 42);
+ grants
+ .inner
+ .lock()
+ .unwrap()
+ .get_mut(&key)
+ .unwrap()
+ .last_used_at = Instant::now() - GRANT_IDLE_TTL - Duration::from_secs(1);
+
+ let GrantLookup::Expired(expired) = grants.lookup("public-a", Some("transport-a"), 42)
+ else {
+ panic!("expired grant must be returned for socket cleanup");
+ };
+ assert_eq!(expired.generation, 1);
+ assert_eq!(
+ expired.endpoint_ws_url,
+ "ws://127.0.0.1:1/devtools/browser/x"
+ );
+ assert!(matches!(
+ grants.lookup("public-a", Some("transport-a"), 42),
+ GrantLookup::Missing
+ ));
+ }
+}
diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/mod.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/mod.rs
index 398d13f2eb..2d521943e8 100644
--- a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/mod.rs
+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/mod.rs
@@ -40,11 +40,15 @@ pub mod approval;
pub mod binding;
pub mod cdp_ws;
pub mod engine;
+mod grant;
#[cfg(test)]
pub(crate) mod mock_cdp;
+mod mutation;
pub mod platform;
mod prepare;
+mod reconnect;
pub mod refusal;
+mod setup_descriptor;
pub mod store;
pub mod tools;
pub mod types;
@@ -53,13 +57,18 @@ mod v2_tests;
pub use engine::BrowserEngine;
pub use platform::{
- BrowserPlatform, PrepareAction, PrepareAuthorization, PrepareOutcome, PrepareProfile,
- PrepareProfileMode, PrepareRequest, PrepareSideEffects,
+ BrowserConsentOutcome, BrowserConsentRequest, BrowserPlatform, ExistingProfileSetupOutcome,
+ ExistingProfileSetupRequest, PrepareAction, PrepareAttachment, PrepareAttachmentKind,
+ PrepareAuthorization, PrepareOutcome, PrepareProfile, PrepareProfileMode, PrepareRequest,
+ PrepareSideEffects, PrepareStrategy,
};
pub use refusal::{BrowserRefusal, BrowserRefusalCode};
+pub use setup_descriptor::{
+ existing_profile_setup_descriptor, BrowserSetupDescriptor, EXISTING_PROFILE_SETUP_READY_TIMEOUT,
+};
pub use tools::register_browser_tools;
pub use types::{
- BindingQuality, BrowserClassification, BrowserEngineFamily, EndpointOwnershipMethod,
- EndpointOwnershipProof, NativeOwnershipMethod, NativeOwnershipProof, NativeWindowInfo,
- OwnedEndpoint, ProcessFingerprint, Rect,
+ BindingQuality, BrowserClassification, BrowserEngineFamily, BrowserProduct,
+ EndpointOwnershipMethod, EndpointOwnershipProof, NativeOwnershipMethod, NativeOwnershipProof,
+ NativeWindowInfo, OwnedEndpoint, ProcessFingerprint, Rect,
};
diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/mutation.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/mutation.rs
new file mode 100644
index 0000000000..dfe5425665
--- /dev/null
+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/mutation.rs
@@ -0,0 +1,98 @@
+//! Canonical browser-target mutation gates.
+//!
+//! Public session ids are capability namespaces, not browser identity. Gates
+//! therefore key on process identity plus the real CDP target so two sessions
+//! addressing one tab serialize while independently proven tabs can proceed.
+
+use std::collections::HashMap;
+use std::sync::{Arc, Mutex};
+
+use tokio::sync::{Mutex as AsyncMutex, OwnedMutexGuard};
+
+use super::types::ProcessFingerprint;
+
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub(crate) struct MutationKey {
+ pid: i64,
+ start_time: Option<u64>,
+ executable: Option<String>,
+ cdp_target_id: String,
+}
+
+impl MutationKey {
+ pub fn new(fingerprint: &ProcessFingerprint, cdp_target_id: &str) -> Self {
+ Self {
+ pid: fingerprint.pid,
+ start_time: fingerprint.start_time,
+ executable: fingerprint.executable.clone(),
+ cdp_target_id: cdp_target_id.to_owned(),
+ }
+ }
+}
+
+#[derive(Default)]
+pub(crate) struct MutationGates {
+ gates: Mutex<HashMap<MutationKey, Arc<AsyncMutex<()>>>>,
+}
+
+impl MutationGates {
+ pub fn new() -> Self {
+ Self::default()
+ }
+
+ pub async fn lock(&self, key: MutationKey) -> OwnedMutexGuard<()> {
+ let gate = self
+ .gates
+ .lock()
+ .unwrap()
+ .entry(key)
+ .or_insert_with(|| Arc::new(AsyncMutex::new(())))
+ .clone();
+ gate.lock_owned().await
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn fingerprint() -> ProcessFingerprint {
+ ProcessFingerprint {
+ pid: 42,
+ start_time: Some(1),
+ executable: Some("chrome".to_owned()),
+ }
+ }
+
+ #[tokio::test]
+ async fn same_real_tab_serializes_across_callers() {
+ let gates = MutationGates::new();
+ let key = MutationKey::new(&fingerprint(), "target-a");
+ let first = gates.lock(key.clone()).await;
+ let second = tokio::time::timeout(
+ std::time::Duration::from_millis(20),
+ gates.lock(key.clone()),
+ )
+ .await;
+ assert!(
+ second.is_err(),
+ "same target must wait for the live mutation"
+ );
+ drop(first);
+ let _next = gates.lock(key).await;
+ }
+
+ #[tokio::test]
+ async fn independent_tabs_do_not_block_each_other() {
+ let gates = MutationGates::new();
+ let _first = gates
+ .lock(MutationKey::new(&fingerprint(), "target-a"))
+ .await;
+ tokio::time::timeout(
+ std::time::Duration::from_millis(20),
+ gates.lock(MutationKey::new(&fingerprint(), "target-b")),
+ )
+ .await
+ .expect("independent target should not block");
+ }
+}
diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/platform.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/platform.rs
index f1cedbd07a..db4e98215f 100644
--- a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/platform.rs
+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/platform.rs
@@ -12,7 +12,9 @@ use async_trait::async_trait;
use serde::{Deserialize, Serialize};
use super::refusal::BrowserRefusal;
-use super::types::{BrowserClassification, NativeWindowInfo, OwnedEndpoint, ProcessFingerprint};
+use super::types::{
+ BrowserClassification, BrowserProduct, NativeWindowInfo, OwnedEndpoint, ProcessFingerprint,
+};
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
@@ -28,6 +30,14 @@ pub struct PrepareProfile {
pub name: Option<String>,
}
+/// Acting strategy for browser preparation that is not a driver-owned profile
+/// lifecycle operation. Existing profiles remain owned by the user/browser.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+pub enum PrepareStrategy {
+ ExistingProfile,
+}
+
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum PrepareAuthorization {
McpHost,
@@ -39,12 +49,17 @@ pub enum PrepareAuthorization {
#[derive(Debug, Clone)]
pub struct PrepareRequest {
pub pid: i64,
+ /// Exact native window used as the visible approval and ownership anchor
+ /// for existing-profile attachment.
+ pub window_id: Option<u64>,
pub session: String,
/// Private transport lifecycle owner. A daemon-backed MCP proxy supplies
/// this independently from the public capability session so either proxy
/// disconnect or explicit `end_session` can reap a spawned browser.
pub transport_session: Option<String>,
pub authorization: Option<PrepareAuthorization>,
+ /// Omitted for the legacy isolated-profile compatibility form.
+ pub strategy: Option<PrepareStrategy>,
pub profile: Option<PrepareProfile>,
/// Allows launching a separate driver-owned isolated browser process.
/// It never authorizes terminating or modifying the requested process.
@@ -63,6 +78,8 @@ pub enum PrepareAction {
RelaunchedBrowser,
/// The driver launched a separate isolated browser process.
LaunchedIsolatedBrowser,
+ /// Attached to a user-owned, already-running profile under a live grant.
+ AttachedExistingProfile,
/// Nothing was done — see `message` on the outcome.
NoOp,
}
@@ -78,6 +95,64 @@ pub struct PrepareOutcome {
pub prepared_pid: Option<i64>,
#[serde(default)]
pub side_effects: PrepareSideEffects,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub attachment: Option<PrepareAttachment>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PrepareAttachment {
+ pub kind: PrepareAttachmentKind,
+ pub browser: String,
+ pub capabilities_invalidated: bool,
+ pub next_action: String,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum PrepareAttachmentKind {
+ ExistingProfile,
+}
+
+#[derive(Debug, Clone)]
+pub struct BrowserConsentRequest {
+ pub pid: i64,
+ pub window_id: u64,
+ pub attempt: u8,
+}
+
+/// Exact, already-approved browser/window scope for enabling an existing
+/// Chromium profile's own DevTools endpoint. Core consumes the approval and
+/// validates this native window before invoking the platform adapter.
+#[derive(Debug, Clone)]
+pub struct ExistingProfileSetupRequest {
+ pub pid: i64,
+ pub window_id: u64,
+ /// Product identity attested immediately before approval-bound setup.
+ pub browser: BrowserProduct,
+}
+
+/// Declared user-visible effects of one bounded existing-profile setup.
+#[derive(Debug, Clone, Default, Serialize)]
+pub struct ExistingProfileSetupOutcome {
+ pub opened_setup_page: bool,
+ pub closed_setup_page: bool,
+ pub enabled_remote_debugging: bool,
+ pub focused_setup_address_field: bool,
+ pub foregrounded_window: bool,
+ pub injected_global_input: bool,
+ /// Endpoint proven as part of an exact setup transition. This is needed
+ /// for Chrome's in-browser toggle, whose listener does not expose the
+ /// classic `/json/version` discovery surface.
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub endpoint: Option<OwnedEndpoint>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum BrowserConsentOutcome {
+ /// One exact browser-owned consent action was semantically pressed.
+ Accepted,
+ /// The adapter proved no consent prompt was present in the approved scope.
+ NotPresent,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
@@ -89,6 +164,12 @@ pub struct PrepareSideEffects {
pub copied_profile_data: bool,
pub changed_preferences: bool,
pub displayed_consent_prompt: bool,
+ pub opened_setup_page: bool,
+ pub closed_setup_page: bool,
+ pub enabled_remote_debugging: bool,
+ pub focused_setup_address_field: bool,
+ pub foregrounded_window: bool,
+ pub injected_global_input: bool,
}
/// OS-identity services a platform crate provides to the browser-tool
@@ -142,6 +223,78 @@ pub trait BrowserPlatform: Send + Sync {
pid: i64,
) -> Result<Option<OwnedEndpoint>, BrowserRefusal>;
+ /// Discover an endpoint while handling an explicitly approved
+ /// existing-profile request. The default is the ordinary side-effect-free
+ /// discovery path. Platforms may additionally return a uniquely proven
+ /// browser-level route that does not expose HTTP discovery, but must not
+ /// open its WebSocket or interact with consent UI here.
+ async fn discover_existing_profile_endpoint(
+ &self,
+ pid: i64,
+ ) -> Result<Option<OwnedEndpoint>, BrowserRefusal> {
+ self.discover_owned_endpoint(pid).await
+ }
+
+ /// Re-prove an endpoint that was already claimed under an existing-profile
+ /// grant. Unlike discovery, this receives the exact WebSocket URL captured
+ /// during the approved setup and may therefore prove that specific route
+ /// without treating an arbitrary PID-owned listener as DevTools.
+ async fn reprove_existing_profile_endpoint(
+ &self,
+ pid: i64,
+ _expected_ws_url: &str,
+ ) -> Result<Option<OwnedEndpoint>, BrowserRefusal> {
+ self.discover_existing_profile_endpoint(pid).await
+ }
+
+ /// Enable an existing Chromium profile's browser-owned DevTools endpoint
+ /// after core has consumed exact interactive approval. Implementations may
+ /// act only within `pid` and `window_id`, must fail on ambiguous UI, and
+ /// must not restart the browser or modify profile files.
+ async fn setup_existing_profile_endpoint(
+ &self,
+ _request: ExistingProfileSetupRequest,
+ ) -> Result<ExistingProfileSetupOutcome, BrowserRefusal> {
+ Err(BrowserRefusal::new(
+ super::refusal::BrowserRefusalCode::BrowserRequiresSetup,
+ "automatic existing-profile endpoint setup is not proven on this platform",
+ ))
+ }
+
+ /// Commit a setup transition after core has protocol-proven and claimed
+ /// the correlated browser endpoint. Implementations use this boundary to
+ /// close only the exact temporary setup tab they opened.
+ async fn commit_existing_profile_setup(
+ &self,
+ _request: ExistingProfileSetupRequest,
+ ) -> Result<bool, BrowserRefusal> {
+ Ok(false)
+ }
+
+ /// Roll back a setup transition that core could not safely claim. The
+ /// adapter must preserve `error`, adding exact cleanup evidence where
+ /// useful, and must never act on an unproven current tab or control.
+ async fn abort_existing_profile_setup(
+ &self,
+ _request: ExistingProfileSetupRequest,
+ error: BrowserRefusal,
+ ) -> BrowserRefusal {
+ error
+ }
+
+ /// Handle one pending browser-owned connection prompt. Implementations
+ /// must use exact native semantics and may perform at most one declared
+ /// consent action for this request. Generic dialog automation is forbidden.
+ async fn handle_existing_profile_consent(
+ &self,
+ _request: BrowserConsentRequest,
+ ) -> Result<BrowserConsentOutcome, BrowserRefusal> {
+ Err(BrowserRefusal::new(
+ super::refusal::BrowserRefusalCode::BrowserRouteUnavailable,
+ "prompt-assisted existing-profile attachment is not proven on this platform",
+ ))
+ }
+
/// Current identity fingerprint for `pid`. Used to detect pid reuse
/// between binding and mutation.
async fn process_fingerprint(&self, pid: i64) -> Result<ProcessFingerprint, BrowserRefusal>;
diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/prepare.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/prepare.rs
index 57fb619bc2..26050ffe32 100644
--- a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/prepare.rs
+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/prepare.rs
@@ -4,15 +4,20 @@ use std::fs::{self, OpenOptions};
use std::io::Write;
use std::path::{Path, PathBuf};
use std::process::{Child, Command, Stdio};
-use std::sync::Mutex;
+use std::sync::{Arc, Mutex};
use std::time::{Duration, Instant};
use serde::{Deserialize, Serialize};
-use super::approval::{consume_prepare_approval, validate_profile};
+use super::approval::{
+ consume_existing_profile_approval, consume_prepare_approval, validate_profile,
+ ExistingProfileApprovalScope,
+};
use super::platform::{
- PrepareAction, PrepareAuthorization, PrepareOutcome, PrepareProfile, PrepareProfileMode,
- PrepareRequest, PrepareSideEffects,
+ BrowserConsentOutcome, BrowserConsentRequest, ExistingProfileSetupOutcome,
+ ExistingProfileSetupRequest, PrepareAction, PrepareAttachment, PrepareAttachmentKind,
+ PrepareAuthorization, PrepareOutcome, PrepareProfile, PrepareProfileMode, PrepareRequest,
+ PrepareSideEffects, PrepareStrategy,
};
use super::refusal::{BrowserRefusal, BrowserRefusalCode};
use super::types::{
@@ -23,6 +28,121 @@ use super::BrowserEngine;
const PROFILE_MARKER: &str = ".cua-driver-owned-profile.json";
const PROFILE_SCHEMA: &str = "cua-driver-browser-profile-v1";
+fn with_setup_side_effects(
+ mut error: BrowserRefusal,
+ setup: &ExistingProfileSetupOutcome,
+) -> BrowserRefusal {
+ if !setup.opened_setup_page
+ && !setup.closed_setup_page
+ && !setup.enabled_remote_debugging
+ && !setup.focused_setup_address_field
+ && !setup.foregrounded_window
+ && !setup.injected_global_input
+ {
+ return error;
+ }
+ let cause = error.detail.take();
+ error.detail = Some(serde_json::json!({
+ "setup_side_effects": {
+ "opened_setup_page": setup.opened_setup_page,
+ "closed_setup_page": setup.closed_setup_page,
+ "focused_setup_address_field": setup.focused_setup_address_field,
+ "enabled_remote_debugging": setup.enabled_remote_debugging,
+ "foregrounded_window": setup.foregrounded_window,
+ "injected_global_input": setup.injected_global_input,
+ },
+ "cause": cause,
+ }));
+ error
+}
+
+fn with_prepare_side_effects(
+ mut error: BrowserRefusal,
+ setup: &ExistingProfileSetupOutcome,
+ displayed_consent_prompt: bool,
+) -> BrowserRefusal {
+ error = with_setup_side_effects(error, setup);
+ if !displayed_consent_prompt {
+ return error;
+ }
+ let mut detail = match error.detail.take() {
+ Some(serde_json::Value::Object(detail)) => detail,
+ Some(cause) => {
+ let mut detail = serde_json::Map::new();
+ detail.insert("cause".to_owned(), cause);
+ detail
+ }
+ None => serde_json::Map::new(),
+ };
+ detail.insert(
+ "displayed_consent_prompt".to_owned(),
+ serde_json::Value::Bool(true),
+ );
+ error.detail = Some(serde_json::Value::Object(detail));
+ error
+}
+
+struct PendingExistingProfileSetup {
+ platform: Arc<dyn super::platform::BrowserPlatform>,
+ request: Option<ExistingProfileSetupRequest>,
+}
+
+impl PendingExistingProfileSetup {
+ fn new(
+ platform: Arc<dyn super::platform::BrowserPlatform>,
+ request: ExistingProfileSetupRequest,
+ ) -> Self {
+ Self {
+ platform,
+ request: Some(request),
+ }
+ }
+
+ async fn abort(&mut self, error: BrowserRefusal) -> BrowserRefusal {
+ let Some(request) = self.request.clone() else {
+ return error;
+ };
+ let result = self
+ .platform
+ .abort_existing_profile_setup(request, error)
+ .await;
+ self.request = None;
+ result
+ }
+
+ async fn commit(&mut self) -> Result<bool, BrowserRefusal> {
+ let request = self.request.clone().ok_or_else(|| {
+ refusal(
+ BrowserRefusalCode::BrowserBindingStale,
+ "the pending browser setup was already finalized",
+ )
+ })?;
+ let result = self.platform.commit_existing_profile_setup(request).await;
+ if result.is_ok() {
+ self.request = None;
+ }
+ result
+ }
+}
+
+impl Drop for PendingExistingProfileSetup {
+ fn drop(&mut self) {
+ let Some(request) = self.request.take() else {
+ return;
+ };
+ let platform = self.platform.clone();
+ let error = refusal(
+ BrowserRefusalCode::BrowserBindingStale,
+ "the existing-profile setup request ended before commit; rolling back its exact pending setup",
+ );
+ if let Ok(runtime) = tokio::runtime::Handle::try_current() {
+ runtime.spawn(async move {
+ let _ = platform.abort_existing_profile_setup(request, error).await;
+ });
+ }
+ }
+}
+
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
struct ProfileMarker {
schema: String,
@@ -407,6 +527,16 @@ impl BrowserEngine {
&self,
request: PrepareRequest,
) -> Result<PrepareOutcome, BrowserRefusal> {
+ if request.strategy == Some(PrepareStrategy::ExistingProfile) {
+ return self.attach_existing_profile(request).await;
+ }
+ if request.strategy.is_some() {
+ return Err(refusal(
+ BrowserRefusalCode::BrowserRouteUnavailable,
+ "the requested browser preparation strategy is unsupported",
+ ));
+ }
+
match self.platform.prepare_endpoint(request.clone()).await {
Ok(mut outcome) => {
if outcome.prepared_pid.is_none() {
@@ -516,6 +646,325 @@ impl BrowserEngine {
reused_driver_profile: !prepared_profile.created,
..PrepareSideEffects::default()
},
+ attachment: None,
+ })
+ }
+
+ async fn attach_existing_profile(
+ &self,
+ request: PrepareRequest,
+ ) -> Result<PrepareOutcome, BrowserRefusal> {
+ let window_id = request.window_id.ok_or_else(|| {
+ refusal(
+ BrowserRefusalCode::BrowserConsentRequired,
+ "strategy=existing_profile requires an exact window_id approval anchor",
+ )
+ })?;
+ let scope = ExistingProfileApprovalScope {
+ pid: request.pid,
+ window_id,
+ session: request.session.clone(),
+ };
+ match request.authorization.as_ref() {
+ Some(PrepareAuthorization::ApprovalArtifact(token)) => {
+ consume_existing_profile_approval(token, &scope)?;
+ }
+ // The ordinary MCP destructive-tool marker proves transport
+ // provenance, not a person's approval of their authenticated
+ // profile. It is deliberately insufficient here.
+ Some(PrepareAuthorization::McpHost) | None => {
+ return Err(refusal(
+ BrowserRefusalCode::BrowserConsentRequired,
+ "existing-profile attachment requires a fresh operation-bound browser-approve artifact",
+ )
+ .with_detail(serde_json::json!({
+ "approval_request_id": uuid::Uuid::new_v4().to_string(),
+ "approval_command": "cua-driver browser-approve --strategy existing_profile --pid <pid> --window-id <window_id> --session <session>",
+ })));
+ }
+ }
+ if request.profile.is_some() || request.allow_launch {
+ return Err(refusal(
+ BrowserRefusalCode::BrowserConsentRequired,
+ "strategy=existing_profile cannot be combined with profile or allow_launch",
+ ));
+ }
+
+ let classification = self.platform.classify_browser(request.pid).await?;
+ if !classification.supports_cdp || classification.engine != BrowserEngineFamily::Chromium {
+ return Err(refusal(
+ BrowserRefusalCode::BrowserRouteUnavailable,
+ "existing-profile attachment is currently limited to Chromium browsers",
+ ));
+ }
+ self.native_window_checked(request.pid, window_id).await?;
+ let fingerprint = self.platform.process_fingerprint(request.pid).await?;
+ let mut setup = ExistingProfileSetupOutcome::default();
+ let setup_request = ExistingProfileSetupRequest {
+ pid: request.pid,
+ window_id,
+ browser: classification.product_kind,
+ };
+ let mut setup_pending = false;
+ let mut setup_guard = None;
+ let mut endpoint = self
+ .platform
+ .discover_existing_profile_endpoint(request.pid)
+ .await?;
+ if endpoint.is_none() {
+ setup = self
+ .platform
+ .setup_existing_profile_endpoint(setup_request.clone())
+ .await?;
+ setup_pending = true;
+ setup_guard = Some(PendingExistingProfileSetup::new(
+ self.platform.clone(),
+ setup_request.clone(),
+ ));
+
+ // Setup is allowed to interact only with the already-approved
+ // process/window generation. Re-prove both before accepting the
+ // newly exposed listener.
+ if let Err(error) = self.native_window_checked(request.pid, window_id).await {
+ return Err(setup_guard
+ .as_mut()
+ .expect("setup guard exists while setup is pending")
+ .abort(with_setup_side_effects(error, &setup))
+ .await);
+ }
+ let current_fingerprint = match self.platform.process_fingerprint(request.pid).await {
+ Ok(fingerprint) => fingerprint,
+ Err(error) => {
+ return Err(setup_guard
+ .as_mut()
+ .expect("setup guard exists while setup is pending")
+ .abort(with_setup_side_effects(error, &setup))
+ .await)
+ }
+ };
+ if current_fingerprint != fingerprint {
+ let error = with_setup_side_effects(
+ refusal(
+ BrowserRefusalCode::BrowserBindingStale,
+ "the approved browser process changed while remote debugging was being enabled",
+ ),
+ &setup,
+ );
+ return Err(setup_guard
+ .as_mut()
+ .expect("setup guard exists while setup is pending")
+ .abort(error)
+ .await);
+ }
+ endpoint = setup.endpoint.clone();
+ if endpoint.is_none() {
+ endpoint = match self
+ .platform
+ .discover_existing_profile_endpoint(request.pid)
+ .await
+ {
+ Ok(endpoint) => endpoint,
+ Err(error) => {
+ return Err(setup_guard
+ .as_mut()
+ .expect("setup guard exists while setup is pending")
+ .abort(with_setup_side_effects(error, &setup))
+ .await)
+ }
+ };
+ }
+ }
+ let endpoint = match endpoint {
+ Some(endpoint) => endpoint,
+ None => {
+ let error = with_setup_side_effects(refusal(
+ BrowserRefusalCode::BrowserRequiresSetup,
+ "the approved browser still has no uniquely proven DevTools endpoint after bounded setup",
+ ), &setup);
+ if setup_pending {
+ return Err(setup_guard
+ .as_mut()
+ .expect("setup guard exists while setup is pending")
+ .abort(error)
+ .await);
+ }
+ return Err(error);
+ }
+ };
+ if endpoint.ownership.owner_pid != request.pid {
+ let error = with_setup_side_effects(
+ refusal(
+ BrowserRefusalCode::BrowserEndpointOwnerMismatch,
+ "the existing-profile endpoint is not owned by the approved browser process",
+ ),
+ &setup,
+ );
+ if setup_pending {
+ return Err(setup_guard
+ .as_mut()
+ .expect("setup guard exists while setup is pending")
+ .abort(error)
+ .await);
+ }
+ return Err(error);
+ }
+
+ let previous_grant = self
+ .existing_profile_grant(
+ &request.session,
+ request.transport_session.as_deref(),
+ request.pid,
+ )
+ .await;
+ let previous_grant = match previous_grant {
+ Ok(grant) => grant,
+ Err(error) => {
+ let error = with_setup_side_effects(error, &setup);
+ if setup_pending {
+ return Err(setup_guard
+ .as_mut()
+ .expect("setup guard exists while setup is pending")
+ .abort(error)
+ .await);
+ }
+ return Err(error);
+ }
+ };
+ let previous_generation = previous_grant.as_ref().map_or(0, |grant| grant.generation);
+ let grant = self.existing_profile_grants.mint(
+ &request.session,
+ request.transport_session.as_deref(),
+ request.pid,
+ window_id,
+ fingerprint,
+ "chromium".to_owned(),
+ endpoint.ws_url.clone(),
+ );
+ if let Some(previous) = previous_grant {
+ self.pool
+ .release_existing(&previous.endpoint_ws_url, previous.generation)
+ .await;
+ if previous.endpoint_ws_url != endpoint.ws_url {
+ self.pool.release_claim_marker(&previous.endpoint_ws_url);
+ }
+ }
+ let (claimed, displayed_consent_prompt) = {
+ let ws_url = endpoint.ws_url.clone();
+ let mut claim = Box::pin(self.pool.claim_existing(&ws_url, grant.generation));
+ let initial = tokio::select! {
+ result = &mut claim => Some(result),
+ _ = tokio::time::sleep(Duration::from_millis(500)) => None,
+ };
+ if let Some(result) = initial {
+ (result, false)
+ } else {
+ match self
+ .platform
+ .handle_existing_profile_consent(BrowserConsentRequest {
+ pid: request.pid,
+ window_id,
+ attempt: 1,
+ })
+ .await
+ {
+ Ok(BrowserConsentOutcome::Accepted) => (claim.await, true),
+ Ok(BrowserConsentOutcome::NotPresent) => (claim.await, false),
+ Err(error) => {
+ // The connection future may hold the pool mutex while
+ // awaiting its WebSocket handshake. Cancel it before
+ // revoking the grant, which also needs that mutex.
+ drop(claim);
+ self.revoke_existing_profile_grant(
+ &request.session,
+ request.transport_session.as_deref(),
+ request.pid,
+ )
+ .await;
+ let error = with_setup_side_effects(error, &setup);
+ if setup_pending {
+ return Err(setup_guard
+ .as_mut()
+ .expect("setup guard exists while setup is pending")
+ .abort(error)
+ .await);
+ }
+ return Err(error);
+ }
+ }
+ }
+ };
+ if let Err(_error) = claimed {
+ self.revoke_existing_profile_grant(
+ &request.session,
+ request.transport_session.as_deref(),
+ request.pid,
+ )
+ .await;
+ let error = with_prepare_side_effects(
+ refusal(
+ BrowserRefusalCode::BrowserReconnectExhausted,
+ "the approved browser socket could not be claimed",
+ ),
+ &setup,
+ displayed_consent_prompt,
+ );
+ if setup_pending {
+ return Err(setup_guard
+ .as_mut()
+ .expect("setup guard exists while setup is pending")
+ .abort(error)
+ .await);
+ }
+ return Err(error);
+ }
+ if setup_pending {
+ match setup_guard
+ .as_mut()
+ .expect("setup guard exists while setup is pending")
+ .commit()
+ .await
+ {
+ Ok(closed) => setup.closed_setup_page = closed,
+ Err(error) => {
+ self.revoke_existing_profile_grant(
+ &request.session,
+ request.transport_session.as_deref(),
+ request.pid,
+ )
+ .await;
+ return Err(with_prepare_side_effects(
+ error,
+ &setup,
+ displayed_consent_prompt,
+ ));
+ }
+ }
+ }
+ self.store
+ .invalidate_endpoint_generation(request.pid, previous_generation);
+
+ Ok(PrepareOutcome {
+ action: PrepareAction::AttachedExistingProfile,
+ endpoint: Some(endpoint),
+ message: "Attached to the approved existing Chromium profile. Bind the native window again before using browser capabilities.".to_owned(),
+ prepared_pid: Some(request.pid),
+ side_effects: PrepareSideEffects {
+ displayed_consent_prompt,
+ changed_preferences: setup.enabled_remote_debugging,
+ opened_setup_page: setup.opened_setup_page,
+ closed_setup_page: setup.closed_setup_page,
+ enabled_remote_debugging: setup.enabled_remote_debugging,
+ focused_setup_address_field: setup.focused_setup_address_field,
+ foregrounded_window: setup.foregrounded_window,
+ injected_global_input: setup.injected_global_input,
+ ..PrepareSideEffects::default()
+ },
+ attachment: Some(PrepareAttachment {
+ kind: PrepareAttachmentKind::ExistingProfile,
+ browser: "chromium".to_owned(),
+ capabilities_invalidated: true,
+ next_action: "get_browser_state".to_owned(),
+ }),
})
}
}
@@ -524,6 +973,33 @@ impl BrowserEngine {
mod tests {
use super::*;
+ #[test]
+ fn setup_side_effects_are_preserved_on_refusal() {
+ let error = with_setup_side_effects(
+ refusal(
+ BrowserRefusalCode::BrowserBindingStale,
+ "fixture binding changed",
+ )
+ .with_detail(serde_json::json!({"original": true})),
+ &ExistingProfileSetupOutcome {
+ opened_setup_page: true,
+ closed_setup_page: true,
+ enabled_remote_debugging: true,
+ focused_setup_address_field: true,
+ foregrounded_window: true,
+ injected_global_input: true,
+ endpoint: None,
+ },
+ );
+ let detail = error.detail.expect("setup detail");
+ assert_eq!(detail["setup_side_effects"]["opened_setup_page"], true);
+ assert_eq!(
+ detail["setup_side_effects"]["enabled_remote_debugging"],
+ true
+ );
+ assert_eq!(detail["cause"]["original"], true);
+ }
+
#[test]
fn profile_marker_must_match_mode_and_name_exactly() {
let path = std::env::temp_dir().join(format!(
diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/reconnect.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/reconnect.rs
new file mode 100644
index 0000000000..a6e328c98d
--- /dev/null
+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/reconnect.rs
@@ -0,0 +1,100 @@
+//! Per-browser reconnect leadership.
+//!
+//! A public session is not browser identity. Reconnect callers therefore
+//! single-flight on the approved process fingerprint and endpoint while
+//! unrelated browsers remain independent.
+
+use std::collections::HashMap;
+use std::sync::{Arc, Mutex};
+
+use tokio::sync::{Mutex as AsyncMutex, OwnedMutexGuard};
+
+use super::types::ProcessFingerprint;
+
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+struct ReconnectKey {
+ pid: i64,
+ start_time: Option<u64>,
+ executable: Option<String>,
+ endpoint_ws_url: String,
+}
+
+impl ReconnectKey {
+ fn new(fingerprint: &ProcessFingerprint, endpoint_ws_url: &str) -> Self {
+ Self {
+ pid: fingerprint.pid,
+ start_time: fingerprint.start_time,
+ executable: fingerprint.executable.clone(),
+ endpoint_ws_url: endpoint_ws_url.to_owned(),
+ }
+ }
+}
+
+#[derive(Default)]
+pub(crate) struct ReconnectGates {
+ gates: Mutex<HashMap<ReconnectKey, Arc<AsyncMutex<()>>>>,
+}
+
+impl ReconnectGates {
+ pub fn new() -> Self {
+ Self::default()
+ }
+
+ pub async fn lock(
+ &self,
+ fingerprint: &ProcessFingerprint,
+ endpoint_ws_url: &str,
+ ) -> OwnedMutexGuard<()> {
+ let gate = self
+ .gates
+ .lock()
+ .unwrap()
+ .entry(ReconnectKey::new(fingerprint, endpoint_ws_url))
+ .or_insert_with(|| Arc::new(AsyncMutex::new(())))
+ .clone();
+ gate.lock_owned().await
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn fingerprint(pid: i64) -> ProcessFingerprint {
+ ProcessFingerprint {
+ pid,
+ start_time: Some(11),
+ executable: Some("chrome".to_owned()),
+ }
+ }
+
+ #[tokio::test]
+ async fn same_browser_has_one_reconnect_leader() {
+ let gates = ReconnectGates::new();
+ let identity = fingerprint(42);
+ let endpoint = "ws://127.0.0.1:1/devtools/browser/a";
+ let first = gates.lock(&identity, endpoint).await;
+ assert!(tokio::time::timeout(
+ std::time::Duration::from_millis(20),
+ gates.lock(&identity, endpoint),
+ )
+ .await
+ .is_err());
+ drop(first);
+ let _next = gates.lock(&identity, endpoint).await;
+ }
+
+ #[tokio::test]
+ async fn unrelated_browsers_reconnect_independently() {
+ let gates = ReconnectGates::new();
+ let _first = gates
+ .lock(&fingerprint(42), "ws://127.0.0.1:1/devtools/browser/a")
+ .await;
+ tokio::time::timeout(
+ std::time::Duration::from_millis(20),
+ gates.lock(&fingerprint(43), "ws://127.0.0.1:2/devtools/browser/b"),
+ )
+ .await
+ .expect("an unrelated browser must not wait on another prompt");
+ }
+}
diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/refusal.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/refusal.rs
index 5ab2a31ec9..5de453de29 100644
--- a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/refusal.rs
+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/refusal.rs
@@ -52,6 +52,12 @@ pub enum BrowserRefusalCode {
/// The platform adapter requires explicit user/caller consent
/// before it will prepare an endpoint.
BrowserConsentRequired,
+ /// A person explicitly dismissed or denied the browser-owned consent UI.
+ BrowserConsentRevoked,
+ /// The fixed reconnect attempt/deadline policy was exhausted.
+ BrowserReconnectExhausted,
+ /// A typing operation delivered only a proven prefix of the request.
+ BrowserInputIncomplete,
}
impl BrowserRefusalCode {
@@ -69,6 +75,9 @@ impl BrowserRefusalCode {
Self::BrowserInputTrustUnavailable => "browser_input_trust_unavailable",
Self::BrowserEndpointOwnerMismatch => "browser_endpoint_owner_mismatch",
Self::BrowserConsentRequired => "browser_consent_required",
+ Self::BrowserConsentRevoked => "browser_consent_revoked",
+ Self::BrowserReconnectExhausted => "browser_reconnect_exhausted",
+ Self::BrowserInputIncomplete => "browser_input_incomplete",
}
}
}
@@ -157,6 +166,18 @@ mod tests {
BrowserRefusalCode::BrowserConsentRequired,
"browser_consent_required",
),
+ (
+ BrowserRefusalCode::BrowserConsentRevoked,
+ "browser_consent_revoked",
+ ),
+ (
+ BrowserRefusalCode::BrowserReconnectExhausted,
+ "browser_reconnect_exhausted",
+ ),
+ (
+ BrowserRefusalCode::BrowserInputIncomplete,
+ "browser_input_incomplete",
+ ),
];
for (code, wire) in all {
assert_eq!(code.as_str(), wire);
diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/setup_descriptor.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/setup_descriptor.rs
new file mode 100644
index 0000000000..dc4bd33bfb
--- /dev/null
+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/setup_descriptor.rs
@@ -0,0 +1,114 @@
+//! Exact, product-specific anchors for approved existing-profile setup.
+
+use std::time::Duration;
+
+use super::types::BrowserProduct;
+
+/// Cold browser profiles can spend several seconds initializing their internal
+/// DevTools page. Keep one bounded timeout across platform adapters so a slow
+/// first render does not become platform-specific behavior.
+pub const EXISTING_PROFILE_SETUP_READY_TIMEOUT: Duration = Duration::from_secs(12);
+
+/// Accessibility-visible anchors for a Chromium product's internal remote
+/// debugging page. Adapters still require an exact native window and exact
+/// control matches; these values only describe the product surface.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct BrowserSetupDescriptor {
+ pub product: BrowserProduct,
+ pub product_name: &'static str,
+ pub setup_url: &'static str,
+ pub page_titles: &'static [&'static str],
+ pub page_heading: &'static str,
+ pub checkbox_label: &'static str,
+ pub tab_close_labels: &'static [&'static str],
+}
+
+const CHROME_TITLES: &[&str] = &["Inspect with Chrome Developer Tools"];
+const CHROMIUM_TITLES: &[&str] = &[
+ "Inspect with Chromium Developer Tools",
+ "Inspect with Chrome Developer Tools",
+];
+const EDGE_TITLES: &[&str] = &[
+ "Inspect with Edge Developer Tools",
+ "Inspect with Microsoft Edge DevTools",
+ "Inspect with Edge DevTools",
+];
+const CHROME_TAB_CLOSE_LABELS: &[&str] = &["Close"];
+const EDGE_TAB_CLOSE_LABELS: &[&str] = &["Close tab"];
+
+const CHROME: BrowserSetupDescriptor = BrowserSetupDescriptor {
+ product: BrowserProduct::GoogleChrome,
+ product_name: "Google Chrome",
+ setup_url: "chrome://inspect/#remote-debugging",
+ page_titles: CHROME_TITLES,
+ page_heading: "Remote debugging",
+ checkbox_label: "Allow remote debugging for this browser instance",
+ tab_close_labels: CHROME_TAB_CLOSE_LABELS,
+};
+
+const CHROMIUM: BrowserSetupDescriptor = BrowserSetupDescriptor {
+ product: BrowserProduct::Chromium,
+ product_name: "Chromium",
+ setup_url: "chrome://inspect/#remote-debugging",
+ page_titles: CHROMIUM_TITLES,
+ page_heading: "Remote debugging",
+ checkbox_label: "Allow remote debugging for this browser instance",
+ tab_close_labels: CHROME_TAB_CLOSE_LABELS,
+};
+
+const EDGE: BrowserSetupDescriptor = BrowserSetupDescriptor {
+ product: BrowserProduct::MicrosoftEdge,
+ product_name: "Microsoft Edge",
+ setup_url: "edge://inspect/#remote-debugging",
+ page_titles: EDGE_TITLES,
+ page_heading: "Remote debugging",
+ checkbox_label: "Allow remote debugging for this browser instance",
+ tab_close_labels: EDGE_TAB_CLOSE_LABELS,
+};
+
+pub fn existing_profile_setup_descriptor(
+ product: BrowserProduct,
+) -> Option<&'static BrowserSetupDescriptor> {
+ match product {
+ BrowserProduct::GoogleChrome => Some(&CHROME),
+ BrowserProduct::Chromium => Some(&CHROMIUM),
+ BrowserProduct::MicrosoftEdge => Some(&EDGE),
+ _ => None,
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn setup_is_limited_to_products_with_exact_descriptors() {
+ assert_eq!(
+ existing_profile_setup_descriptor(BrowserProduct::GoogleChrome)
+ .unwrap()
+ .setup_url,
+ "chrome://inspect/#remote-debugging"
+ );
+ assert_eq!(
+ existing_profile_setup_descriptor(BrowserProduct::MicrosoftEdge)
+ .unwrap()
+ .setup_url,
+ "edge://inspect/#remote-debugging"
+ );
+ assert_eq!(
+ existing_profile_setup_descriptor(BrowserProduct::Chromium)
+ .unwrap()
+ .product,
+ BrowserProduct::Chromium
+ );
+ for product in [
+ BrowserProduct::Brave,
+ BrowserProduct::Firefox,
+ BrowserProduct::Safari,
+ BrowserProduct::Electron,
+ BrowserProduct::Other,
+ ] {
+ assert!(existing_profile_setup_descriptor(product).is_none());
+ }
+ }
+}
diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/store.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/store.rs
index b82eb75d2f..753b372b36 100644
--- a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/store.rs
+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/store.rs
@@ -107,6 +107,7 @@ pub struct RefEntry {
#[derive(Debug, Clone)]
pub struct SnapshotRecord {
pub id: u64,
+ pub generation: u64,
pub url: String,
/// index → entry; the external ref is `p<id>:<index>`.
pub refs: HashMap<u32, RefEntry>,
@@ -116,6 +117,7 @@ pub struct SnapshotRecord {
pub struct TabRecord {
pub tab_id: String,
pub cdp_target_id: String,
+ pub generation: u64,
pub snapshots: HashMap<u64, SnapshotRecord>,
}
@@ -128,6 +130,11 @@ pub struct TargetRecord {
pub window_id: u64,
pub ws_url: String,
pub endpoint_owner_pid: i64,
+ /// CDP connection generation that minted this capability. Zero denotes
+ /// the legacy/non-grant route.
+ pub generation: u64,
+ /// Internal transport owner for a grant-backed existing-profile route.
+ pub grant_transport_session: Option<String>,
pub fingerprint: ProcessFingerprint,
pub native_title: String,
pub native_bounds: Rect,
@@ -273,7 +280,8 @@ impl BrowserStore {
})?;
tab.snapshots
.get(&snap)
- .and_then(|s| s.refs.get(&idx))
+ .filter(|snapshot| snapshot.generation == target.generation)
+ .and_then(|snapshot| snapshot.refs.get(&idx))
.cloned()
.ok_or_else(|| {
BrowserRefusal::new(
@@ -301,6 +309,20 @@ impl BrowserStore {
self.inner.lock().unwrap().remove(session);
}
+ /// Invalidate every capability minted for one browser endpoint before a
+ /// reconnect generation becomes visible.
+ pub fn invalidate_endpoint_generation(&self, pid: i64, generation: u64) -> usize {
+ let mut removed = 0;
+ for session in self.inner.lock().unwrap().values_mut() {
+ let before = session.targets.len();
+ session
+ .targets
+ .retain(|_, target| !(target.pid == pid && target.generation == generation));
+ removed += before - session.targets.len();
+ }
+ removed
+ }
+
/// Number of live targets in a session (diagnostics/tests).
pub fn target_count(&self, session: &str) -> usize {
self.inner
@@ -329,6 +351,8 @@ mod tests {
window_id: 7,
ws_url: "ws://127.0.0.1:9222/devtools/browser/x".into(),
endpoint_owner_pid: 42,
+ generation: 0,
+ grant_transport_session: None,
fingerprint: ProcessFingerprint {
pid: 42,
start_time: Some(1),
@@ -372,10 +396,12 @@ mod tests {
TabRecord {
tab_id: tab_id.clone(),
cdp_target_id: "CDP1".into(),
+ generation: 0,
snapshots: HashMap::from([(
snap_id,
SnapshotRecord {
id: snap_id,
+ generation: 0,
url: "https://example.test".into(),
refs,
},
@@ -473,6 +499,28 @@ mod tests {
assert_eq!(err.code, BrowserRefusalCode::BrowserBindingStale);
}
+ #[test]
+ fn generation_invalidation_is_browser_wide_and_exact() {
+ let store = BrowserStore::new();
+ let mut old = record();
+ old.generation = 1;
+ let mut current = record();
+ current.generation = 2;
+ let mut other_process = record();
+ other_process.pid = 99;
+ other_process.endpoint_owner_pid = 99;
+ other_process.fingerprint.pid = 99;
+ other_process.generation = 1;
+ store.mint_target("session-a", old);
+ store.mint_target("session-b", current);
+ store.mint_target("session-c", other_process);
+
+ assert_eq!(store.invalidate_endpoint_generation(42, 1), 1);
+ assert_eq!(store.target_count("session-a"), 0);
+ assert_eq!(store.target_count("session-b"), 1);
+ assert_eq!(store.target_count("session-c"), 1);
+ }
+
#[test]
fn minted_ids_are_unique_across_sessions() {
let store = BrowserStore::new();
diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/tools.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/tools.rs
index e6140bf878..ef31669caf 100644
--- a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/tools.rs
+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/tools.rs
@@ -17,7 +17,7 @@ use crate::tool_args::ArgsExt;
use super::approval::MCP_HOST_APPROVAL_ARG;
use super::engine::BrowserEngine;
-use super::platform::{PrepareAuthorization, PrepareProfile, PrepareRequest};
+use super::platform::{PrepareAuthorization, PrepareProfile, PrepareRequest, PrepareStrategy};
use super::refusal::{BrowserRefusal, BrowserRefusalCode};
use super::types::BindingQuality;
@@ -207,7 +207,12 @@ impl Tool for GetBrowserStateTool {
Err(e) => return e,
};
- match self.engine.bind_native(&session, pid, window_id).await {
+ let transport_session = args.opt_str("_transport_session_id");
+ match self
+ .engine
+ .bind_native(&session, transport_session.as_deref(), pid, window_id)
+ .await
+ {
Ok((target_id, record)) => {
let tabs: Vec<Value> = record
.tabs
@@ -264,12 +269,20 @@ impl BrowserPrepareTool {
requires MCP-host approval or a short-lived token from the interactive \
browser-approve command, allow_launch=true, and a driver-owned isolated \
profile. It launches a separate browser and never copies, modifies, or \
- terminates the requested user profile."
+ terminates the requested user profile. Existing-profile attachment is \
+ explicit, requires an exact interactive approval artifact, and never \
+ treats ordinary MCP transport approval as profile consent. On proven \
+ platforms, that approval also permits one bounded exact-window setup: \
+ open the recognized browser product's fixed remote-debugging page, toggle \
+ its uniquely matched per-instance checkbox, prove the PID-owned loopback \
+ endpoint, and close the temporary tab. Every visible effect is reported; \
+ ambiguity is refused."
.into(),
input_schema: json!({
"type": "object",
"properties": {
"pid": { "type": "integer", "description": "Browser process id to prepare." },
+ "window_id": { "type": "integer", "description": "Exact native window approval anchor; required for strategy.kind=existing_profile." },
"approval_token": {
"type": "string",
"description": "Single-use token minted by `cua-driver browser-approve` for direct CLI/raw use. Omit for an MCP-host-approved call."
@@ -287,6 +300,14 @@ impl BrowserPrepareTool {
"required": ["mode"],
"additionalProperties": false
},
+ "strategy": {
+ "type": "object",
+ "properties": {
+ "kind": { "type": "string", "enum": ["existing_profile"] }
+ },
+ "required": ["kind"],
+ "additionalProperties": false
+ },
"session": schema_session(),
},
"required": ["pid"],
@@ -325,21 +346,36 @@ impl Tool for BrowserPrepareTool {
}
},
};
- let authorization = if args
+ let strategy = match args.get("strategy") {
+ None | Some(Value::Null) => None,
+ Some(value) => match serde_json::from_value::<PrepareStrategy>(value.clone()) {
+ Ok(strategy) => Some(strategy),
+ Err(error) => {
+ return ToolResult::error(format!(
+ "invalid browser preparation strategy: {error}"
+ ))
+ }
+ },
+ };
+ let approval_token = args.opt_str("approval_token");
+ let authorization = if strategy == Some(PrepareStrategy::ExistingProfile) {
+ approval_token.map(PrepareAuthorization::ApprovalArtifact)
+ } else if args
.get(MCP_HOST_APPROVAL_ARG)
.and_then(Value::as_bool)
.unwrap_or(false)
{
Some(PrepareAuthorization::McpHost)
} else {
- args.opt_str("approval_token")
- .map(PrepareAuthorization::ApprovalArtifact)
+ approval_token.map(PrepareAuthorization::ApprovalArtifact)
};
let request = PrepareRequest {
pid,
+ window_id: args.opt_u64("window_id"),
session,
transport_session: args.opt_str("_transport_session_id"),
authorization,
+ strategy,
profile,
allow_launch: args.opt_bool("allow_launch").unwrap_or(false),
};
@@ -364,6 +400,7 @@ impl Tool for BrowserPrepareTool {
"endpoint_ownership": outcome.endpoint.map(|e| e.ownership),
"prepared_pid": outcome.prepared_pid,
"side_effects": outcome.side_effects,
+ "attachment": outcome.attachment,
}))
}
Err(refusal) => refusal.to_tool_result(),
@@ -435,6 +472,14 @@ impl Tool for BrowserNavigateTool {
));
}
+ let _mutation = match self
+ .engine
+ .lock_mutation(&session, &target_id, &tab_id)
+ .await
+ {
+ Ok(guard) => guard,
+ Err(refusal) => return refusal.to_tool_result(),
+ };
let validated = match self
.engine
.revalidate_for_mutation(&session, &target_id, Some(&tab_id))
@@ -562,6 +607,14 @@ impl Tool for BrowserClickTool {
// Resolve the ref BEFORE revalidation? No — revalidate first so a
// stale binding refuses before we touch the page at all.
+ let _mutation = match self
+ .engine
+ .lock_mutation(&session, &target_id, &tab_id)
+ .await
+ {
+ Ok(guard) => guard,
+ Err(refusal) => return refusal.to_tool_result(),
+ };
let validated = match self
.engine
.revalidate_for_mutation(&session, &target_id, Some(&tab_id))
@@ -869,6 +922,14 @@ impl Tool for BrowserTypeTool {
));
}
+ let _mutation = match self
+ .engine
+ .lock_mutation(&session, &target_id, &tab_id)
+ .await
+ {
+ Ok(guard) => guard,
+ Err(refusal) => return refusal.to_tool_result(),
+ };
let validated = match self
.engine
.revalidate_for_mutation(&session, &target_id, Some(&tab_id))
@@ -967,12 +1028,18 @@ impl Tool for BrowserTypeTool {
.to_tool_result();
}
- let typed = if mode == "insert_text" {
- conn.call(Some(cdp), "Input.insertText", json!({ "text": text }))
+ let requested_chars = text.chars().count();
+ let (typed, delivered_chars) = if mode == "insert_text" {
+ match conn
+ .call(Some(cdp), "Input.insertText", json!({ "text": text }))
.await
- .map(|_| ())
+ {
+ Ok(_) => (Ok(()), requested_chars),
+ Err(error) => (Err(error), 0),
+ }
} else {
let mut result = Ok(());
+ let mut delivered = 0;
for ch in text.chars() {
let (key, key_text) = if ch == '\n' {
("Enter".to_string(), "\r".to_string())
@@ -997,14 +1064,15 @@ impl Tool for BrowserTypeTool {
result = Err(e);
break;
}
+ delivered += 1;
}
- result
+ (result, delivered)
};
match typed {
Ok(()) => ToolResult::text(format!(
"typed {} char(s) into {tab_id}",
- text.chars().count()
+ requested_chars
))
.with_structured(json!({
"status": "ok",
@@ -1013,12 +1081,21 @@ impl Tool for BrowserTypeTool {
"ref": ext_ref,
"frame": entry.frame.kind.as_str(),
"mode": mode,
- "chars": text.chars().count(),
+ "chars": requested_chars,
+ "requested_chars": requested_chars,
+ "delivered_chars": delivered_chars,
})),
Err(e) => BrowserRefusal::new(
- BrowserRefusalCode::BrowserInputTrustUnavailable,
- format!("trusted Input typing route failed: {e}"),
+ BrowserRefusalCode::BrowserInputIncomplete,
+ format!(
+ "trusted Input typing stopped after {delivered_chars} of {requested_chars} character(s): {e}"
+ ),
)
+ .with_detail(json!({
+ "requested_chars": requested_chars,
+ "delivered_chars": delivered_chars,
+ "retryable": false,
+ }))
.to_tool_result(),
}
}
@@ -1029,8 +1106,8 @@ mod tests {
use super::*;
use crate::browser::platform::{BrowserPlatform, PrepareOutcome, PrepareRequest};
use crate::browser::types::{
- BrowserClassification, BrowserEngineFamily, NativeWindowInfo, OwnedEndpoint,
- ProcessFingerprint,
+ BrowserClassification, BrowserEngineFamily, BrowserProduct, NativeWindowInfo,
+ OwnedEndpoint, ProcessFingerprint,
};
/// Minimal adapter: pid 1 is a CDP-capable browser with no endpoint
@@ -1048,6 +1125,7 @@ mod tests {
1 => BrowserClassification {
is_browser: true,
engine: BrowserEngineFamily::Chromium,
+ product_kind: BrowserProduct::GoogleChrome,
product: Some("MockChrome".into()),
channel: Some("stable".into()),
supports_cdp: true,
@@ -1055,6 +1133,7 @@ mod tests {
3 => BrowserClassification {
is_browser: true,
engine: BrowserEngineFamily::Webkit,
+ product_kind: BrowserProduct::Safari,
product: Some("MockSafari".into()),
channel: None,
supports_cdp: false,
@@ -1062,6 +1141,7 @@ mod tests {
_ => BrowserClassification {
is_browser: false,
engine: BrowserEngineFamily::Unknown,
+ product_kind: BrowserProduct::Other,
product: None,
channel: None,
supports_cdp: false,
@@ -1284,6 +1364,52 @@ mod tests {
);
}
+ #[tokio::test]
+ async fn ordinary_mcp_marker_never_approves_an_existing_profile() {
+ let tool = BrowserPrepareTool::new(engine());
+ let result = tool
+ .invoke(json!({
+ "pid": 1,
+ "window_id": 7,
+ "strategy": { "kind": "existing_profile" },
+ "session": "existing-profile-run",
+ MCP_HOST_APPROVAL_ARG: true
+ }))
+ .await;
+ let structured = structured(&result);
+ assert_eq!(structured["refusal"]["code"], "browser_consent_required");
+ assert!(structured["refusal"]["detail"]["approval_request_id"]
+ .as_str()
+ .is_some());
+ }
+
+ #[tokio::test]
+ async fn existing_strategy_conflicts_fail_before_platform_setup() {
+ let tool = BrowserPrepareTool::new(engine());
+ let token = crate::browser::approval::mint_existing_profile_approval(
+ crate::browser::approval::ExistingProfileApprovalScope {
+ pid: 1,
+ window_id: 7,
+ session: "existing-conflict".to_owned(),
+ },
+ )
+ .unwrap();
+ let result = tool
+ .invoke(json!({
+ "pid": 1,
+ "window_id": 7,
+ "strategy": { "kind": "existing_profile" },
+ "profile": { "mode": "isolated_new" },
+ "approval_token": token,
+ "session": "existing-conflict"
+ }))
+ .await;
+ assert_eq!(
+ structured(&result)["refusal"]["code"],
+ "browser_consent_required"
+ );
+ }
+
#[tokio::test]
async fn mutations_on_unknown_targets_refuse_binding_stale() {
let e = engine();
@@ -1349,6 +1475,7 @@ mod tests {
crate::browser::store::TabRecord {
tab_id: tab_id.clone(),
cdp_target_id: "CDPX".into(),
+ generation: 0,
snapshots: HashMap::new(),
},
);
@@ -1360,6 +1487,8 @@ mod tests {
window_id: 7,
ws_url: "ws://127.0.0.1:9222/devtools/browser/x".into(),
endpoint_owner_pid: 1,
+ generation: 0,
+ grant_transport_session: None,
fingerprint: ProcessFingerprint {
pid: 1,
start_time: Some(1),
@@ -1400,6 +1529,7 @@ mod tests {
crate::browser::store::TabRecord {
tab_id: tab_id.clone(),
cdp_target_id: "CDPX".into(),
+ generation: 0,
snapshots: HashMap::new(),
},
);
@@ -1412,6 +1542,8 @@ mod tests {
window_id: 7,
ws_url: "ws://127.0.0.1:9222/devtools/browser/x".into(),
endpoint_owner_pid: 1,
+ generation: 0,
+ grant_transport_session: None,
fingerprint: ProcessFingerprint {
pid: 1,
start_time: Some(999),
@@ -1453,6 +1585,8 @@ mod tests {
window_id: 7,
ws_url: "ws://127.0.0.1:9222/devtools/browser/x".into(),
endpoint_owner_pid: 1,
+ generation: 0,
+ grant_transport_session: None,
fingerprint: ProcessFingerprint {
pid: 1,
start_time: Some(1),
diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/types.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/types.rs
index 0156188657..c7ed410cc7 100644
--- a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/types.rs
+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/types.rs
@@ -51,6 +51,26 @@ pub enum BrowserEngineFamily {
Unknown,
}
+/// Browser product identity attested by the platform adapter. Engine family
+/// alone is insufficient for acting setup because Chromium products expose
+/// different internal URLs and accessibility labels.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
+#[serde(rename_all = "snake_case")]
+pub enum BrowserProduct {
+ GoogleChrome,
+ Chromium,
+ MicrosoftEdge,
+ Brave,
+ Vivaldi,
+ Opera,
+ Arc,
+ Electron,
+ Firefox,
+ Safari,
+ #[default]
+ Other,
+}
+
/// Platform adapter's verdict on whether a pid is a browser and which
/// engine family it belongs to. `supports_cdp` is the gate for the whole
/// browser-tool route in v1 (Chromium-family only).
@@ -58,6 +78,9 @@ pub enum BrowserEngineFamily {
pub struct BrowserClassification {
pub is_browser: bool,
pub engine: BrowserEngineFamily,
+ /// Stable product identity used for product-specific setup policy.
+ #[serde(default)]
+ pub product_kind: BrowserProduct,
/// Human-readable product name, e.g. "Google Chrome", "Microsoft Edge".
pub product: Option<String>,
/// Release channel when known, e.g. "stable", "canary".
diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/v2_tests.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/v2_tests.rs
index 609c4dc828..d44bf68450 100644
--- a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/v2_tests.rs
+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/v2_tests.rs
@@ -4,7 +4,10 @@
//! revalidation, navigation invalidation, and unproven-capability
//! omission/refusal.
-use std::sync::{Arc, Mutex as StdMutex};
+use std::sync::{
+ atomic::{AtomicBool, Ordering},
+ Arc, Mutex as StdMutex,
+};
use async_trait::async_trait;
use serde_json::{json, Value};
@@ -14,13 +17,16 @@ use crate::tool::Tool;
use super::engine::BrowserEngine;
use super::mock_cdp::{MockCdpServer, MockEvent, MockHandler, MockReply};
-use super::platform::{BrowserPlatform, PrepareAction, PrepareOutcome, PrepareRequest};
+use super::platform::{
+ BrowserConsentOutcome, BrowserConsentRequest, BrowserPlatform, ExistingProfileSetupOutcome,
+ ExistingProfileSetupRequest, PrepareAction, PrepareOutcome, PrepareRequest,
+};
use super::refusal::BrowserRefusal;
-use super::tools::{BrowserClickTool, BrowserTypeTool, GetBrowserStateTool};
+use super::tools::{BrowserClickTool, BrowserPrepareTool, BrowserTypeTool, GetBrowserStateTool};
use super::types::{
- BrowserClassification, BrowserEngineFamily, EndpointOwnershipMethod, EndpointOwnershipProof,
- NativeOwnershipMethod, NativeOwnershipProof, NativeWindowInfo, OwnedEndpoint,
- ProcessFingerprint, Rect,
+ BrowserClassification, BrowserEngineFamily, BrowserProduct, EndpointOwnershipMethod,
+ EndpointOwnershipProof, NativeOwnershipMethod, NativeOwnershipProof, NativeWindowInfo,
+ OwnedEndpoint, ProcessFingerprint, Rect,
};
// ── Scripted Chromium fixture ────────────────────────────────────────────────
@@ -38,6 +44,8 @@ struct FixtureState {
oopif_loader: String,
tab_sessions: u64,
oopif_sessions: u64,
+ fail_key_down_after: Option<usize>,
+ completed_key_pairs: usize,
/// Every incoming CDP call: (sessionId, method, params).
calls: Vec<(Option<String>, String, Value)>,
}
@@ -53,6 +61,8 @@ impl Default for FixtureState {
oopif_loader: "L_OOPIF_1".into(),
tab_sessions: 0,
oopif_sessions: 0,
+ fail_key_down_after: None,
+ completed_key_pairs: 0,
calls: Vec::new(),
}
}
@@ -303,10 +313,21 @@ fn fixture_handler(state: SharedState) -> MockHandler {
MockReply::err(-32000, "No node with given id")
}
}
- "DOM.focus"
- | "Input.dispatchMouseEvent"
- | "Input.insertText"
- | "Input.dispatchKeyEvent" => MockReply::ok(json!({})),
+ "Input.dispatchKeyEvent" => {
+ let event_type = call.params["type"].as_str().unwrap_or_default();
+ if event_type == "keyDown" && st.fail_key_down_after == Some(st.completed_key_pairs)
+ {
+ MockReply::err(-32000, "fixture key delivery failure")
+ } else {
+ if event_type == "keyUp" {
+ st.completed_key_pairs += 1;
+ }
+ MockReply::ok(json!({}))
+ }
+ }
+ "DOM.focus" | "Input.dispatchMouseEvent" | "Input.insertText" => {
+ MockReply::ok(json!({}))
+ }
"DOM.resolveNode" => MockReply::ok(json!({
"object": { "objectId": format!("obj-{}", call.params["backendNodeId"]) }
})),
@@ -321,6 +342,11 @@ fn fixture_handler(state: SharedState) -> MockHandler {
struct FixturePlatform {
ws_url: String,
trusted_input_limited: bool,
+ managed_endpoint_visible: bool,
+ existing_endpoint_visible: Arc<AtomicBool>,
+ setup_invoked: Arc<AtomicBool>,
+ setup_aborted: Arc<AtomicBool>,
+ stall_consent: bool,
}
#[async_trait]
@@ -334,6 +360,7 @@ impl BrowserPlatform for FixturePlatform {
Ok(BrowserClassification {
is_browser: true,
engine: BrowserEngineFamily::Chromium,
+ product_kind: BrowserProduct::GoogleChrome,
product: Some("MockChrome".into()),
channel: Some("stable".into()),
supports_cdp: true,
@@ -371,6 +398,19 @@ impl BrowserPlatform for FixturePlatform {
&self,
pid: i64,
) -> Result<Option<OwnedEndpoint>, BrowserRefusal> {
+ if !self.managed_endpoint_visible {
+ return Ok(None);
+ }
+ self.discover_existing_profile_endpoint(pid).await
+ }
+
+ async fn discover_existing_profile_endpoint(
+ &self,
+ pid: i64,
+ ) -> Result<Option<OwnedEndpoint>, BrowserRefusal> {
+ if !self.existing_endpoint_visible.load(Ordering::SeqCst) {
+ return Ok(None);
+ }
Ok(Some(OwnedEndpoint {
ws_url: self.ws_url.clone(),
http_port: None,
@@ -382,6 +422,79 @@ impl BrowserPlatform for FixturePlatform {
}))
}
+ async fn reprove_existing_profile_endpoint(
+ &self,
+ pid: i64,
+ expected_ws_url: &str,
+ ) -> Result<Option<OwnedEndpoint>, BrowserRefusal> {
+ if expected_ws_url != self.ws_url {
+ return Ok(None);
+ }
+ Ok(Some(OwnedEndpoint {
+ ws_url: self.ws_url.clone(),
+ http_port: None,
+ ownership: EndpointOwnershipProof {
+ method: EndpointOwnershipMethod::ListeningSocketPid,
+ owner_pid: pid,
+ detail: Some("fixture exact approved endpoint".to_owned()),
+ },
+ }))
+ }
+
+ async fn setup_existing_profile_endpoint(
+ &self,
+ _request: ExistingProfileSetupRequest,
+ ) -> Result<ExistingProfileSetupOutcome, BrowserRefusal> {
+ self.setup_invoked.store(true, Ordering::SeqCst);
+ Ok(ExistingProfileSetupOutcome {
+ opened_setup_page: true,
+ closed_setup_page: false,
+ enabled_remote_debugging: true,
+ focused_setup_address_field: true,
+ foregrounded_window: false,
+ injected_global_input: false,
+ endpoint: Some(OwnedEndpoint {
+ ws_url: self.ws_url.clone(),
+ http_port: None,
+ ownership: EndpointOwnershipProof {
+ method: EndpointOwnershipMethod::ListeningSocketPid,
+ owner_pid: 1,
+ detail: Some("fixture exact setup transition".to_owned()),
+ },
+ }),
+ })
+ }
+
+ async fn commit_existing_profile_setup(
+ &self,
+ _request: ExistingProfileSetupRequest,
+ ) -> Result<bool, BrowserRefusal> {
+ Ok(true)
+ }
+
+ async fn abort_existing_profile_setup(
+ &self,
+ _request: ExistingProfileSetupRequest,
+ error: BrowserRefusal,
+ ) -> BrowserRefusal {
+ self.setup_aborted.store(true, Ordering::SeqCst);
+ error
+ }
+
+ async fn handle_existing_profile_consent(
+ &self,
+ _request: BrowserConsentRequest,
+ ) -> Result<BrowserConsentOutcome, BrowserRefusal> {
+ if self.stall_consent {
+ tokio::time::sleep(std::time::Duration::from_secs(10)).await;
+ return Ok(BrowserConsentOutcome::NotPresent);
+ }
+ Err(BrowserRefusal::new(
+ super::refusal::BrowserRefusalCode::BrowserRouteUnavailable,
+ "fixture consent prompt is unavailable",
+ ))
+ }
+
async fn process_fingerprint(&self, pid: i64) -> Result<ProcessFingerprint, BrowserRefusal> {
Ok(ProcessFingerprint {
pid,
@@ -400,6 +513,7 @@ impl BrowserPlatform for FixturePlatform {
message: "fixture: nothing to do".into(),
prepared_pid: None,
side_effects: Default::default(),
+ attachment: None,
})
}
}
@@ -411,6 +525,7 @@ struct Fixture {
// Kept alive for the test's duration; dropping it kills the endpoint.
_server: MockCdpServer,
engine: Arc<BrowserEngine>,
+ setup_invoked: Arc<AtomicBool>,
}
async fn fixture_with(configure: impl FnOnce(&mut FixtureState)) -> Fixture {
@@ -425,14 +540,21 @@ async fn fixture_with_platform(
configure(&mut initial);
let state = Arc::new(StdMutex::new(initial));
let server = MockCdpServer::start(fixture_handler(state.clone())).await;
+ let setup_invoked = Arc::new(AtomicBool::new(false));
let engine = BrowserEngine::new(Arc::new(FixturePlatform {
ws_url: server.ws_url(),
trusted_input_limited,
+ managed_endpoint_visible: true,
+ existing_endpoint_visible: Arc::new(AtomicBool::new(true)),
+ setup_invoked: setup_invoked.clone(),
+ setup_aborted: Arc::new(AtomicBool::new(false)),
+ stall_consent: false,
}));
Fixture {
state,
_server: server,
engine,
+ setup_invoked,
}
}
@@ -440,6 +562,51 @@ async fn fixture() -> Fixture {
fixture_with(|_| {}).await
}
+async fn existing_profile_only_fixture() -> Fixture {
+ let state = Arc::new(StdMutex::new(FixtureState::default()));
+ let server = MockCdpServer::start(fixture_handler(state.clone())).await;
+ let setup_invoked = Arc::new(AtomicBool::new(false));
+ let engine = BrowserEngine::new(Arc::new(FixturePlatform {
+ ws_url: server.ws_url(),
+ trusted_input_limited: false,
+ managed_endpoint_visible: false,
+ existing_endpoint_visible: Arc::new(AtomicBool::new(true)),
+ setup_invoked: setup_invoked.clone(),
+ setup_aborted: Arc::new(AtomicBool::new(false)),
+ stall_consent: false,
+ }));
+ Fixture {
+ state,
+ _server: server,
+ engine,
+ setup_invoked,
+ }
+}
+
+async fn existing_profile_setup_fixture() -> (Fixture, Arc<AtomicBool>) {
+ let state = Arc::new(StdMutex::new(FixtureState::default()));
+ let server = MockCdpServer::start(fixture_handler(state.clone())).await;
+ let setup_invoked = Arc::new(AtomicBool::new(false));
+ let engine = BrowserEngine::new(Arc::new(FixturePlatform {
+ ws_url: server.ws_url(),
+ trusted_input_limited: false,
+ managed_endpoint_visible: false,
+ existing_endpoint_visible: Arc::new(AtomicBool::new(false)),
+ setup_invoked: setup_invoked.clone(),
+ setup_aborted: Arc::new(AtomicBool::new(false)),
+ stall_consent: false,
+ }));
+ (
+ Fixture {
+ state,
+ _server: server,
+ engine,
+ setup_invoked: setup_invoked.clone(),
+ },
+ setup_invoked,
+ )
+}
+
fn structured(result: &ToolResult) -> &Value {
result
.structured_content
@@ -462,6 +629,187 @@ async fn bind(f: &Fixture) -> (String, String) {
(target_id, tab_id)
}
+#[tokio::test]
+async fn approved_existing_profile_attach_claims_then_binds_one_generation() {
+ // Match Chrome's per-instance toggle: the endpoint is discoverable only
+ // through the approved existing-profile route, never as driver-managed.
+ let f = existing_profile_only_fixture().await;
+ let token = super::approval::mint_existing_profile_approval(
+ super::approval::ExistingProfileApprovalScope {
+ pid: 1,
+ window_id: 7,
+ session: SESSION.to_owned(),
+ },
+ )
+ .unwrap();
+ let prepare = BrowserPrepareTool::new(f.engine.clone())
+ .invoke(json!({
+ "pid": 1,
+ "window_id": 7,
+ "session": SESSION,
+ "_transport_session_id": "transport-v2-attach",
+ "strategy": { "kind": "existing_profile" },
+ "approval_token": token
+ }))
+ .await;
+ let prepared = structured(&prepare);
+ assert_eq!(prepared["status"], "ok", "{prepared}");
+ assert_eq!(prepared["action"], "attached_existing_profile");
+ assert_eq!(prepared["attachment"]["kind"], "existing_profile");
+ assert_eq!(prepared["attachment"]["capabilities_invalidated"], true);
+ assert_eq!(prepared["side_effects"]["displayed_consent_prompt"], false);
+ assert!(!f.setup_invoked.load(Ordering::SeqCst));
+
+ let state = GetBrowserStateTool::new(f.engine.clone())
+ .invoke(json!({
+ "pid": 1,
+ "window_id": 7,
+ "session": SESSION,
+ "_transport_session_id": "transport-v2-attach"
+ }))
+ .await;
+ assert_eq!(structured(&state)["status"], "ok", "{}", structured(&state));
+ crate::session::fire_session_end("transport-v2-attach");
+}
+
+#[tokio::test]
+async fn approved_existing_profile_setup_reports_exact_side_effects() {
+ let (f, setup_invoked) = existing_profile_setup_fixture().await;
+ let token = super::approval::mint_existing_profile_approval(
+ super::approval::ExistingProfileApprovalScope {
+ pid: 1,
+ window_id: 7,
+ session: SESSION.to_owned(),
+ },
+ )
+ .unwrap();
+ let prepare = BrowserPrepareTool::new(f.engine.clone())
+ .invoke(json!({
+ "pid": 1,
+ "window_id": 7,
+ "session": SESSION,
+ "strategy": { "kind": "existing_profile" },
+ "approval_token": token
+ }))
+ .await;
+ let prepared = structured(&prepare);
+ assert_eq!(prepared["status"], "ok", "{prepared}");
+ assert!(setup_invoked.load(Ordering::SeqCst));
+ assert_eq!(prepared["side_effects"]["opened_setup_page"], true);
+ assert_eq!(prepared["side_effects"]["closed_setup_page"], true);
+ assert_eq!(prepared["side_effects"]["enabled_remote_debugging"], true);
+ assert_eq!(prepared["side_effects"]["changed_preferences"], true);
+ assert_eq!(
+ prepared["side_effects"]["focused_setup_address_field"],
+ true
+ );
+
+ let state = GetBrowserStateTool::new(f.engine.clone())
+ .invoke(json!({
+ "pid": 1,
+ "window_id": 7,
+ "session": SESSION
+ }))
+ .await;
+ assert_eq!(structured(&state)["status"], "ok", "{}", structured(&state));
+}
+
+#[tokio::test]
+async fn refused_consent_cancels_stalled_claim_before_revoking_grant() {
+ let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+ let address = listener.local_addr().unwrap();
+ let stalled_server = tokio::spawn(async move {
+ let (_stream, _) = listener.accept().await.unwrap();
+ tokio::time::sleep(std::time::Duration::from_secs(10)).await;
+ });
+ let engine = BrowserEngine::new(Arc::new(FixturePlatform {
+ ws_url: format!("ws://{address}/devtools/browser"),
+ trusted_input_limited: false,
+ managed_endpoint_visible: false,
+ existing_endpoint_visible: Arc::new(AtomicBool::new(false)),
+ setup_invoked: Arc::new(AtomicBool::new(false)),
+ setup_aborted: Arc::new(AtomicBool::new(false)),
+ stall_consent: false,
+ }));
+ let token = super::approval::mint_existing_profile_approval(
+ super::approval::ExistingProfileApprovalScope {
+ pid: 1,
+ window_id: 7,
+ session: SESSION.to_owned(),
+ },
+ )
+ .unwrap();
+ let prepared = tokio::time::timeout(
+ std::time::Duration::from_secs(3),
+ BrowserPrepareTool::new(engine).invoke(json!({
+ "pid": 1,
+ "window_id": 7,
+ "session": SESSION,
+ "strategy": { "kind": "existing_profile" },
+ "approval_token": token
+ })),
+ )
+ .await
+ .expect("a refused consent route must not deadlock grant revocation");
+ assert_eq!(structured(&prepared)["status"], "refused");
+ assert_eq!(
+ structured(&prepared)["refusal"]["code"],
+ "browser_route_unavailable"
+ );
+ stalled_server.abort();
+}
+
+#[tokio::test]
+async fn cancelled_prepare_aborts_the_exact_pending_setup() {
+ let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+ let address = listener.local_addr().unwrap();
+ let stalled_server = tokio::spawn(async move {
+ let (_stream, _) = listener.accept().await.unwrap();
+ tokio::time::sleep(std::time::Duration::from_secs(10)).await;
+ });
+ let setup_aborted = Arc::new(AtomicBool::new(false));
+ let engine = BrowserEngine::new(Arc::new(FixturePlatform {
+ ws_url: format!("ws://{address}/devtools/browser"),
+ trusted_input_limited: false,
+ managed_endpoint_visible: false,
+ existing_endpoint_visible: Arc::new(AtomicBool::new(false)),
+ setup_invoked: Arc::new(AtomicBool::new(false)),
+ setup_aborted: setup_aborted.clone(),
+ stall_consent: true,
+ }));
+ let token = super::approval::mint_existing_profile_approval(
+ super::approval::ExistingProfileApprovalScope {
+ pid: 1,
+ window_id: 7,
+ session: SESSION.to_owned(),
+ },
+ )
+ .unwrap();
+ let cancelled = tokio::time::timeout(
+ std::time::Duration::from_millis(750),
+ BrowserPrepareTool::new(engine).invoke(json!({
+ "pid": 1,
+ "window_id": 7,
+ "session": SESSION,
+ "strategy": { "kind": "existing_profile" },
+ "approval_token": token
+ })),
+ )
+ .await;
+ assert!(
+ cancelled.is_err(),
+ "fixture must cancel during consent handling"
+ );
+ tokio::time::timeout(std::time::Duration::from_secs(1), async {
+ while !setup_aborted.load(Ordering::SeqCst) {
+ tokio::task::yield_now().await;
+ }
+ })
+ .await
+ .expect("dropping prepare must schedule exact pending-setup rollback");
+ stalled_server.abort();
+}
+
async fn snapshot(f: &Fixture, target_id: &str, tab_id: &str) -> Value {
let tool = GetBrowserStateTool::new(f.engine.clone());
let result = tool
@@ -857,3 +1205,27 @@ async fn typing_into_an_oopif_input_routes_to_the_child_session() {
.iter()
.all(|(sess, _)| sess.as_deref().unwrap().starts_with("oopif-sess-")));
}
+
+#[tokio::test]
+async fn partial_keystrokes_report_exact_delivered_prefix() {
+ let f = fixture_with(|state| state.fail_key_down_after = Some(2)).await;
+ let (target, tab) = bind(&f).await;
+ let snap = snapshot(&f, &target, &tab).await;
+ let shadow_ref = ref_of(&snap, "main", "Shadow Input");
+
+ let result = BrowserTypeTool::new(f.engine.clone())
+ .invoke(json!({
+ "target_id": target,
+ "tab_id": tab,
+ "ref": shadow_ref,
+ "text": "four",
+ "mode": "keystrokes",
+ "session": SESSION
+ }))
+ .await;
+ let refusal = &structured(&result)["refusal"];
+ assert_eq!(refusal["code"], "browser_input_incomplete");
+ assert_eq!(refusal["detail"]["requested_chars"], 4);
+ assert_eq!(refusal["detail"]["delivered_chars"], 2);
+ assert_eq!(refusal["detail"]["retryable"], false);
+}
diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/recording.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/recording.rs
index 459a6dbc14..82b45129a6 100644
--- a/libs/cua-driver/rust/crates/cua-driver-core/src/recording.rs
+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/recording.rs
@@ -47,8 +47,7 @@ impl ScreenshotCapture {
}
}
-type ScreenshotFnBox =
- Box<dyn Fn(Option<u64>, Option<i64>) -> ScreenshotCapture + Send + Sync>;
+type ScreenshotFnBox = Box<dyn Fn(Option<u64>, Option<i64>) -> ScreenshotCapture + Send + Sync>;
static SCREENSHOT_FN: OnceLock<ScreenshotFnBox> = OnceLock::new();
/// Register the platform-specific screenshot callback. Call once at startup
@@ -147,6 +146,7 @@ pub struct PendingTurn {
window_id: Option<u64>,
pid: Option<i64>,
click_point: Option<(f64, f64)>,
+ capture_visual_state: bool,
before: TurnCapture,
}
@@ -477,6 +477,29 @@ impl RecordingSession {
/// Reserve a turn and capture its target immediately before tool dispatch.
/// No-op when recording is disabled.
pub fn begin_turn(&self, tool_name: &str, args: &Value, start_ms: u64) -> Option<PendingTurn> {
+ self.begin_turn_with_capture(tool_name, args, start_ms, true)
+ }
+
+ /// Reserve a turn while deliberately suppressing visual and accessibility
+ /// capture. Used for consent-bearing operations where the target may be an
+ /// authenticated browser profile: action metadata and the structured result
+ /// remain auditable without persisting page or dialog contents.
+ pub fn begin_private_turn(
+ &self,
+ tool_name: &str,
+ args: &Value,
+ start_ms: u64,
+ ) -> Option<PendingTurn> {
+ self.begin_turn_with_capture(tool_name, args, start_ms, false)
+ }
+
+ fn begin_turn_with_capture(
+ &self,
+ tool_name: &str,
+ args: &Value,
+ start_ms: u64,
+ capture_visual_state: bool,
+ ) -> Option<PendingTurn> {
let (turn_dir, session_start_ms, generation) = {
let mut inner = self.inner.lock().unwrap();
if !inner.enabled {
@@ -514,7 +537,15 @@ impl RecordingSession {
}
}
let click_point = resolve_click_point(tool_name, &args, window_id, pid, element_index);
- let before = capture_turn(window_id, pid);
+ let before = if capture_visual_state {
+ capture_turn(window_id, pid)
+ } else {
+ TurnCapture {
+ state: None,
+ screenshot: None,
+ screenshot_classification: Some("privacy_suppressed"),
+ }
+ };
let mut inner = self.inner.lock().unwrap();
if !inner.enabled || inner.generation != generation {
@@ -535,6 +566,7 @@ impl RecordingSession {
window_id,
pid,
click_point,
+ capture_visual_state,
before,
})
}
@@ -624,11 +656,7 @@ fn write_phase_artifacts(
Ok(())
}
-fn capture_status(
- captured: bool,
- expected: bool,
- classification: Option<&'static str>,
-) -> Value {
+fn capture_status(captured: bool, expected: bool, classification: Option<&'static str>) -> Value {
if captured {
serde_json::json!({ "status": "captured" })
} else if expected {
@@ -704,15 +732,21 @@ fn write_turn(pending: PendingTurn, result_text: &str) -> anyhow::Result<()> {
window_id,
pid,
click_point,
+ capture_visual_state,
before,
} = pending;
std::fs::create_dir_all(&turn_dir)?;
let now = now_ms();
- let after = capture_turn(window_id, pid);
- let click_expected = matches!(
- tool_name.as_str(),
- "click" | "double_click" | "right_click"
- );
+ let after = if capture_visual_state {
+ capture_turn(window_id, pid)
+ } else {
+ TurnCapture {
+ state: None,
+ screenshot: None,
+ screenshot_classification: Some("privacy_suppressed"),
+ }
+ };
+ let click_expected = matches!(tool_name.as_str(), "click" | "double_click" | "right_click");
let mut payload = serde_json::json!({
"tool": tool_name,
@@ -754,7 +788,7 @@ fn write_turn(pending: PendingTurn, result_text: &str) -> anyhow::Result<()> {
&turn_dir,
&before,
&after,
- pid.is_some(),
+ pid.is_some() && capture_visual_state,
click_expected,
click_captured,
)?;
@@ -985,6 +1019,62 @@ mod tests {
std::fs::remove_dir(&output_dir).expect("remove recording directory");
}
+ #[test]
+ fn private_turn_records_metadata_without_visual_or_ax_artifacts() {
+ let output_dir = std::env::temp_dir().join(format!(
+ "cua-recording-private-turn-{}-{}",
+ std::process::id(),
+ now_ms()
+ ));
+ let session = RecordingSession::new();
+ {
+ let mut inner = session.inner.lock().expect("recording lock");
+ inner.enabled = true;
+ inner.output_dir = Some(output_dir.clone());
+ inner.session_start_ms = now_ms();
+ }
+ let pending = session
+ .begin_private_turn(
+ "browser_prepare",
+ &serde_json::json!({"pid": 1, "window_id": 2}),
+ now_ms(),
+ )
+ .expect("reserve private consent turn");
+ session.finish_turn(pending, "attached");
+
+ let turn = output_dir.join("turn-00001");
+ assert!(turn.join("action.json").exists());
+ assert!(turn.join("evidence.json").exists());
+ for private_artifact in [
+ "before.png",
+ "after.png",
+ "screenshot.png",
+ "before_state.json",
+ "after_state.json",
+ "app_state.json",
+ ] {
+ assert!(!turn.join(private_artifact).exists(), "{private_artifact}");
+ }
+ let evidence: Value = serde_json::from_slice(
+ &std::fs::read(turn.join("evidence.json")).expect("read private evidence"),
+ )
+ .expect("parse private evidence");
+ assert_eq!(
+ evidence["before"]["screenshot"]["classification"],
+ "privacy_suppressed"
+ );
+ assert_eq!(
+ evidence["after"]["screenshot"]["classification"],
+ "privacy_suppressed"
+ );
+
+ for file in ["action.json", "evidence.json"] {
+ std::fs::remove_file(turn.join(file)).expect("remove private turn artifact");
+ }
+ std::fs::remove_dir(&turn).expect("remove private turn directory");
+ std::fs::remove_dir(&output_dir).expect("remove private recording directory");
+ }
+
#[test]
fn stop_owner_surfaces_video_finalization_failure() {
let output_dir = std::env::temp_dir().join(format!(
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.rs
index 4404091ea0..aa593ca324 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
@@ -407,26 +407,17 @@ impl ToolRegistry {
resolved_name,
"start_recording" | "stop_recording" | "get_recording_state" | "replay_trajectory"
);
- let recording_args = if resolved_name == "browser_prepare" {
- let mut redacted = args.clone();
- if let Some(arguments) = redacted.as_object_mut() {
- if arguments.contains_key("approval_token") {
- arguments.insert(
- "approval_token".to_owned(),
- Value::String("[redacted]".to_owned()),
- );
- }
- arguments.remove("_cua_browser_prepare_mcp_host_approved");
- arguments.remove("_transport_session_id");
- }
- redacted
- } else {
- args.clone()
- };
+ let private_consent_turn = is_existing_profile_prepare(resolved_name, &args);
+ let recording_args = recording_args_for(resolved_name, &args);
let pending_turn = should_record
.then(|| {
- self.recording
- .begin_turn(resolved_name, &recording_args, start_ms)
+ if private_consent_turn {
+ self.recording
+ .begin_private_turn(resolved_name, &recording_args, start_ms)
+ } else {
+ self.recording
+ .begin_turn(resolved_name, &recording_args, start_ms)
+ }
})
.flatten();
@@ -464,7 +455,7 @@ impl ToolRegistry {
// of action tools the recording pipeline cares about (non-read-only,
// not the recording-control meta-tools) so the live view matches
// what the recorder would have captured for the turn.
- if pip_hook::pip_enabled() && should_record {
+ if pip_hook::pip_enabled() && should_record && !private_consent_turn {
let window_id = args.opt_u64("window_id");
let pid = args.opt_i64("pid");
if let Some(png_bytes) = screenshot_for(window_id, pid) {
@@ -481,6 +472,33 @@ impl ToolRegistry {
}
}
+fn is_existing_profile_prepare(tool_name: &str, args: &Value) -> bool {
+ tool_name == "browser_prepare"
+ && args
+ .get("strategy")
+ .and_then(|strategy| strategy.get("kind"))
+ .and_then(Value::as_str)
+ == Some("existing_profile")
+}
+
+fn recording_args_for(tool_name: &str, args: &Value) -> Value {
+ if tool_name != "browser_prepare" {
+ return args.clone();
+ }
+ let mut redacted = args.clone();
+ if let Some(arguments) = redacted.as_object_mut() {
+ if arguments.contains_key("approval_token") {
+ arguments.insert(
+ "approval_token".to_owned(),
+ Value::String("[redacted]".to_owned()),
+ );
+ }
+ arguments.remove("_cua_browser_prepare_mcp_host_approved");
+ arguments.remove("_transport_session_id");
+ }
+ redacted
+}
+
impl Default for ToolRegistry {
fn default() -> Self {
Self::new()
@@ -542,6 +560,46 @@ mod capability_tests {
//! of the registry response — no platform code involved.
use super::*;
+ #[test]
+ fn browser_prepare_recording_redacts_authority_and_transport_secrets() {
+ let recorded = recording_args_for(
+ "browser_prepare",
+ &serde_json::json!({
+ "pid": 42,
+ "window_id": 7,
+ "session": "public-session",
+ "strategy": {"kind": "existing_profile"},
+ "approval_token": "one-use-secret",
+ "_cua_browser_prepare_mcp_host_approved": true,
+ "_transport_session_id": "private-transport",
+ }),
+ );
+ assert_eq!(recorded["approval_token"], "[redacted]");
+ assert!(recorded
+ .get("_cua_browser_prepare_mcp_host_approved")
+ .is_none());
+ assert!(recorded.get("_transport_session_id").is_none());
+ assert_eq!(recorded["pid"], 42);
+ assert_eq!(recorded["window_id"], 7);
+ assert_eq!(recorded["strategy"]["kind"], "existing_profile");
+ }
+
+ #[test]
+ fn existing_profile_prepare_is_a_private_consent_turn() {
+ assert!(is_existing_profile_prepare(
+ "browser_prepare",
+ &serde_json::json!({"strategy": {"kind": "existing_profile"}}),
+ ));
+ assert!(!is_existing_profile_prepare(
+ "browser_prepare",
+ &serde_json::json!({"profile": {"mode": "isolated_new"}}),
+ ));
+ assert!(!is_existing_profile_prepare(
+ "get_browser_state",
+ &serde_json::json!({"strategy": {"kind": "existing_profile"}}),
+ ));
+ }
+
/// Tools whose `default_capabilities_for` mapping must NOT be
/// empty. Mirrors the documented vocabulary above. Lives here
/// rather than in an integration test because adding a new tool
diff --git a/libs/cua-driver/rust/crates/cua-driver-testkit/src/e2e.rs b/libs/cua-driver/rust/crates/cua-driver-testkit/src/e2e.rs
index f5574bddf7..ab8707cd25 100644
--- a/libs/cua-driver/rust/crates/cua-driver-testkit/src/e2e.rs
+++ b/libs/cua-driver/rust/crates/cua-driver-testkit/src/e2e.rs
@@ -309,6 +309,10 @@ pub enum RefusalCode {
BrowserTabNotFound,
BrowserRefStale,
BrowserInputTrustUnavailable,
+ BrowserConsentRequired,
+ BrowserConsentRevoked,
+ BrowserReconnectExhausted,
+ BrowserInputIncomplete,
}
impl RefusalCode {
@@ -325,6 +329,10 @@ impl RefusalCode {
"browser_tab_not_found" => Some(Self::BrowserTabNotFound),
"browser_ref_stale" => Some(Self::BrowserRefStale),
"browser_input_trust_unavailable" => Some(Self::BrowserInputTrustUnavailable),
+ "browser_consent_required" => Some(Self::BrowserConsentRequired),
+ "browser_consent_revoked" => Some(Self::BrowserConsentRevoked),
+ "browser_reconnect_exhausted" => Some(Self::BrowserReconnectExhausted),
+ "browser_input_incomplete" => Some(Self::BrowserInputIncomplete),
_ => None,
}
}
@@ -1473,6 +1481,10 @@ fn validate_one_turn(turn: &Path, cell_id: &str, errors: &mut Vec<String>) {
.and_then(|value| value[phase][kind]["classification"].as_str())
};
let tool = action.as_ref().and_then(|value| value["tool"].as_str());
+ let private_existing_profile_prepare = action.as_ref().is_some_and(|value| {
+ value["tool"].as_str() == Some("browser_prepare")
+ && value["arguments"]["strategy"]["kind"].as_str() == Some("existing_profile")
+ });
let successful_restore = action.as_ref().is_some_and(|value| {
value["result_summary"]
.as_str()
@@ -1482,13 +1494,15 @@ fn validate_one_turn(turn: &Path, cell_id: &str, errors: &mut Vec<String>) {
.as_ref()
.is_some_and(|value| value["after"]["state"]["status"].as_str() == Some("captured"));
let expected_unavailable_screenshot = |phase: &str| {
- tool == Some("bring_to_front")
- && ((phase == "before"
- && classification(phase, "screenshot") == Some("target_minimized"))
- || (phase == "after"
- && successful_restore
- && restored_state_captured
- && classification(phase, "screenshot") == Some("capture_failed")))
+ (private_existing_profile_prepare
+ && classification(phase, "screenshot") == Some("privacy_suppressed"))
+ || (tool == Some("bring_to_front")
+ && ((phase == "before"
+ && classification(phase, "screenshot") == Some("target_minimized"))
+ || (phase == "after"
+ && successful_restore
+ && restored_state_captured
+ && classification(phase, "screenshot") == Some("capture_failed"))))
};
for (phase, kind) in [("before", "screenshot"), ("after", "screenshot")] {
@@ -1521,10 +1535,11 @@ fn validate_one_turn(turn: &Path, cell_id: &str, errors: &mut Vec<String>) {
);
}
- let state_expected = action
- .as_ref()
- .and_then(|value| value["arguments"]["pid"].as_i64())
- .is_some();
+ let state_expected = !private_existing_profile_prepare
+ && action
+ .as_ref()
+ .and_then(|value| value["arguments"]["pid"].as_i64())
+ .is_some();
if state_expected {
for phase in ["before", "after"] {
validate_capture_status(
@@ -2037,6 +2052,60 @@ mod tests {
}));
}
+ #[test]
+ fn validator_accepts_private_existing_profile_prepare_turn() {
+ let (root, case, result, turn) = complete_turn_fixture();
+ std::fs::write(
+ turn.join("action.json"),
+ br#"{
+ "tool":"browser_prepare",
+ "arguments":{
+ "approval_token":"[redacted]",
+ "pid":1,
+ "window_id":2,
+ "strategy":{"kind":"existing_profile"}
+ }
+ }"#,
+ )
+ .expect("write private prepare action");
+ std::fs::write(
+ turn.join("evidence.json"),
+ br#"{
+ "schema":"cua-turn-evidence/v1",
+ "before":{"state":{"status":"not_applicable","classification":"no_target_pid"},"screenshot":{"status":"unavailable","classification":"privacy_suppressed"}},
+ "after":{"state":{"status":"not_applicable","classification":"no_target_pid"},"screenshot":{"status":"unavailable","classification":"privacy_suppressed"}},
+ "click":{"status":"not_applicable","classification":"no_target_pid"}
+ }"#,
+ )
+ .expect("write private prepare evidence");
+ for file in [
+ "before.png",
+ "after.png",
+ "screenshot.png",
+ "before_state.json",
+ "after_state.json",
+ "app_state.json",
+ ] {
+ std::fs::remove_file(turn.join(file)).expect("remove private visual evidence");
+ }
+
+ validate_catalog(&[case.clone()], &[result.clone()], Some(root.path()), true)
+ .expect("private existing-profile consent must not persist visual state");
+
+ let mut action: Value = read_json_value(&turn.join("action.json")).expect("read action");
+ action["arguments"]["strategy"]["kind"] = Value::String("isolated_new".to_owned());
+ std::fs::write(
+ turn.join("action.json"),
+ serde_json::to_vec(&action).expect("serialize action"),
+ )
+ .expect("rewrite non-private action");
+ let errors = validate_catalog(&[case], &[result], Some(root.path()), true)
+ .expect_err("privacy suppression is limited to existing-profile consent turns");
+ assert!(errors
+ .iter()
+ .any(|error| error.contains("classified privacy_suppressed")));
+ }
+
#[test]
fn validator_accepts_minimized_preimage_for_restore_action() {
let (root, case, result, turn) = complete_turn_fixture();
diff --git a/libs/cua-driver/rust/crates/cua-driver-testkit/src/sentinel.rs b/libs/cua-driver/rust/crates/cua-driver-testkit/src/sentinel.rs
index f9ce5491d7..ddb4e5ce62 100644
--- a/libs/cua-driver/rust/crates/cua-driver-testkit/src/sentinel.rs
+++ b/libs/cua-driver/rust/crates/cua-driver-testkit/src/sentinel.rs
@@ -89,19 +89,10 @@ impl ForegroundSentinel {
// The compositor observation is the authoritative Wayland focus gate.
wait_for_native_focus_stable(target);
} else {
- loop {
- let journal = fs::read_to_string(&journal_path).unwrap_or_default();
- if journal.contains(r#""kind":"ready""#) && journal.contains(r#""kind":"focus""#) {
- break;
- }
- assert!(
- Instant::now() < focus_deadline,
- "foreground sentinel did not become ready and focused: {journal}"
- );
- std::thread::sleep(Duration::from_millis(100));
- }
+ wait_for_journal(&journal_path, focus_deadline, r#""kind":"ready""#, "ready");
activate_native_foreground(driver, target);
wait_for_native_focus_stable(target);
+ wait_for_journal(&journal_path, focus_deadline, r#""kind":"focus""#, "focus");
}
fs::write(&journal_path, "").expect("reset focused sentinel journal");
diff --git a/libs/cua-driver/rust/crates/cua-driver/src/cli.rs b/libs/cua-driver/rust/crates/cua-driver/src/cli.rs
index 15de58fed0..16f53b02ad 100644
--- a/libs/cua-driver/rust/crates/cua-driver/src/cli.rs
+++ b/libs/cua-driver/rust/crates/cua-driver/src/cli.rs
@@ -162,7 +162,10 @@ pub enum Command {
/// `browser_prepare` call. This command requires an interactive terminal.
BrowserApprove {
pid: i64,
- profile_mode: String,
+ strategy: Option<String>,
+ window_id: Option<u64>,
+ session: Option<String>,
+ profile_mode: Option<String>,
profile_name: Option<String>,
},
}
@@ -193,6 +196,9 @@ const VALUE_FLAGS: &[&str] = &[
"--type",
"--host-bundle-id",
"--pid",
+ "--strategy",
+ "--window-id",
+ "--session",
"--profile-mode",
"--profile-name",
// Experimental PiP preview — value flag for the optional geometry
@@ -422,6 +428,9 @@ pub fn parse_command() -> Command {
println!(" Interactively mint a five-minute, single-use token for a");
println!(" direct CLI/raw browser_prepare call. MCP hosts use their");
println!(" destructive-tool approval flow instead.");
+ println!(" cua-driver browser-approve --strategy existing_profile --pid <pid>");
+ println!(" --window-id <window_id> --session <session>");
+ println!(" Approve attachment to one exact existing browser request.");
println!();
println!("mcp options (macOS):");
println!(
@@ -515,6 +524,9 @@ pub fn parse_command() -> Command {
let mcp_client = flag_value(&args, "--client");
let socket = flag_value(&args, "--socket");
let approval_pid = flag_value(&args, "--pid");
+ let approval_strategy = flag_value(&args, "--strategy");
+ let approval_window_id = flag_value(&args, "--window-id");
+ let approval_session = flag_value(&args, "--session");
let approval_profile_mode = flag_value(&args, "--profile-mode");
let approval_profile_name = flag_value(&args, "--profile-name");
@@ -750,13 +762,12 @@ pub fn parse_command() -> Command {
eprintln!("browser-approve requires --pid <positive integer>");
process::exit(64);
});
- let profile_mode = approval_profile_mode.unwrap_or_else(|| {
- eprintln!("browser-approve requires --profile-mode isolated_new|isolated_named");
- process::exit(64);
- });
Command::BrowserApprove {
pid,
- profile_mode,
+ strategy: approval_strategy,
+ window_id: approval_window_id.and_then(|value| value.parse::<u64>().ok()),
+ session: approval_session,
+ profile_mode: approval_profile_mode,
profile_name: approval_profile_name,
}
}
@@ -796,13 +807,73 @@ pub fn parse_command() -> Command {
}
}
-pub fn run_browser_approve(pid: i64, profile_mode: &str, profile_name: Option<&str>) {
+pub fn run_browser_approve(
+ pid: i64,
+ strategy: Option<&str>,
+ window_id: Option<u64>,
+ session: Option<&str>,
+ profile_mode: Option<&str>,
+ profile_name: Option<&str>,
+) {
use std::io::{IsTerminal as _, Write as _};
if !std::io::stdin().is_terminal() || !std::io::stderr().is_terminal() {
eprintln!("browser-approve requires an interactive terminal; approval cannot be piped or scripted");
process::exit(1);
}
+ if let Some(strategy) = strategy {
+ if strategy != "existing_profile" {
+ eprintln!("unsupported browser approval strategy {strategy:?}; use existing_profile");
+ process::exit(64);
+ }
+ if profile_mode.is_some() || profile_name.is_some() {
+ eprintln!("--strategy existing_profile cannot be combined with profile flags");
+ process::exit(64);
+ }
+ let Some(window_id) = window_id.filter(|window_id| *window_id > 0) else {
+ eprintln!("existing-profile approval requires --window-id <positive integer>");
+ process::exit(64);
+ };
+ let Some(session) = session.filter(|session| !session.trim().is_empty()) else {
+ eprintln!("existing-profile approval requires --session <explicit session>");
+ process::exit(64);
+ };
+ eprintln!("Approve CUA Driver to attach to this existing Chromium profile?");
+ eprintln!(" browser pid: {pid}");
+ eprintln!(" native window id: {window_id}");
+ eprintln!(" caller session: {session}");
+ eprintln!("This grant stays in daemon memory, expires, and never authorizes arbitrary dialogs.");
+ eprint!("Type APPROVE to continue: ");
+ let _ = std::io::stderr().flush();
+ let mut confirmation = String::new();
+ if std::io::stdin().read_line(&mut confirmation).is_err()
+ || confirmation.trim() != "APPROVE"
+ {
+ eprintln!("browser attachment approval declined; no artifact was created");
+ process::exit(1);
+ }
+ let scope = cua_driver_core::browser::approval::ExistingProfileApprovalScope {
+ pid,
+ window_id,
+ session: session.to_owned(),
+ };
+ match cua_driver_core::browser::approval::mint_existing_profile_approval(scope) {
+ Ok(token) => println!("{token}"),
+ Err(error) => {
+ eprintln!("{}", error.message);
+ process::exit(1);
+ }
+ }
+ return;
+ }
+ if window_id.is_some() || session.is_some() {
+ eprintln!("--window-id/--session require --strategy existing_profile");
+ process::exit(64);
+ }
+ let profile_mode = profile_mode.unwrap_or_else(|| {
+ eprintln!("browser-approve requires --profile-mode isolated_new|isolated_named");
+ process::exit(64);
+ });
let mode = match profile_mode {
"isolated_new" => cua_driver_core::browser::PrepareProfileMode::IsolatedNew,
"isolated_named" => cua_driver_core::browser::PrepareProfileMode::IsolatedNamed,
diff --git a/libs/cua-driver/rust/crates/cua-driver/src/main.rs b/libs/cua-driver/rust/crates/cua-driver/src/main.rs
index fc329440e0..8b5646a8ec 100644
--- a/libs/cua-driver/rust/crates/cua-driver/src/main.rs
+++ b/libs/cua-driver/rust/crates/cua-driver/src/main.rs
@@ -552,10 +552,20 @@ fn main() {
}
cli::Command::BrowserApprove {
pid,
+ strategy,
+ window_id,
+ session,
profile_mode,
profile_name,
} => {
- cli::run_browser_approve(pid, &profile_mode, profile_name.as_deref());
+ cli::run_browser_approve(
+ pid,
+ strategy.as_deref(),
+ window_id,
+ session.as_deref(),
+ profile_mode.as_deref(),
+ profile_name.as_deref(),
+ );
return;
}
cli::Command::Config {
@@ -867,10 +877,20 @@ fn main() -> anyhow::Result<()> {
}
cli::Command::BrowserApprove {
pid,
+ strategy,
+ window_id,
+ session,
profile_mode,
profile_name,
} => {
- cli::run_browser_approve(pid, &profile_mode, profile_name.as_deref());
+ cli::run_browser_approve(
+ pid,
+ strategy.as_deref(),
+ window_id,
+ session.as_deref(),
+ profile_mode.as_deref(),
+ profile_name.as_deref(),
+ );
return Ok(());
}
cli::Command::Config {
diff --git a/libs/cua-driver/rust/crates/cua-driver/tests/standalone_browser_behavior_test.rs b/libs/cua-driver/rust/crates/cua-driver/tests/standalone_browser_behavior_test.rs
index 3c354997b8..6487468d09 100644
--- a/libs/cua-driver/rust/crates/cua-driver/tests/standalone_browser_behavior_test.rs
+++ b/libs/cua-driver/rust/crates/cua-driver/tests/standalone_browser_behavior_test.rs
@@ -24,6 +24,10 @@ use cua_driver_testkit::{spawn_in_job, BrowserFixtureServer, Driver, McpDriver,
use futures_util::{SinkExt, StreamExt};
use tokio_tungstenite::tungstenite::Message;
+use cua_driver_core::browser::approval::{
+ mint_existing_profile_approval, ExistingProfileApprovalScope,
+};
+
const FIXTURE_HTML: &str = include_str!("../../../../tests/fixtures/shared/web/index.html");
static STANDALONE_BROWSER_TEST_LOCK: Mutex<()> = Mutex::new(());
@@ -536,7 +540,13 @@ fn command_for_unprepared_browser(
.arg(format!("--window-size={TEST_BROWSER_WINDOW_SIZE}"));
configure_test_browser_sandbox(&mut command);
#[cfg(target_os = "linux")]
- configure_linux_browser_command(&mut command);
+ {
+ configure_linux_browser_command(&mut command);
+ // Linux existing-profile setup is authorized through the exact
+ // Chromium checkbox in AT-SPI. Chromium otherwise commonly exposes
+ // only its top-level frame when no screen reader is active.
+ command.arg("--force-renderer-accessibility");
+ }
command
.arg(url)
.stdin(Stdio::null())
@@ -709,6 +719,35 @@ fn launch_browser_with_html(spec: &BrowserSpec, label: &str, html: String) -> Br
}
}
+fn launch_unprepared_browser(spec: &BrowserSpec, label: &str) -> BrowserFixture {
+ let mut driver = spawn_driver(label);
+ let server = BrowserFixtureServer::start(&standalone_fixture_html());
+ let profile = tempfile::Builder::new()
+ .prefix("cua-e2e-existing-browser-")
+ .tempdir()
+ .expect("create existing browser profile");
+ let before = window_ids(&mut driver);
+ let mut command = command_for_unprepared_browser(
+ spec,
+ profile.path(),
+ server.page_url(),
+ TEST_BROWSER_INITIAL_POSITION,
+ );
+ let child = spawn_in_job(&mut command).expect("launch unprepared standalone browser");
+ driver.reaper().push(child);
+ let (pid, window_id) = wait_for_fixture_window(&mut driver, &before, &server)
+ .expect("unprepared browser fixture window");
+ driver.reaper().track_pid(pid);
+ BrowserFixture {
+ driver,
+ server,
+ _profile: profile,
+ cdp_port: 0,
+ pid,
+ window_id,
+ }
+}
+
fn launch_additional_window(fixture: &mut BrowserFixture) -> (BrowserFixtureServer, u32, u64) {
let html = standalone_fixture_html();
let server = BrowserFixtureServer::start(&html);
@@ -877,8 +916,26 @@ fn run_with_background_oracles(
pid: fixture.pid,
native_id: fixture.window_id,
};
+
+ // Chromium can occasionally map a fresh Windows profile as iconic even
+ // when no minimized launch flag was requested. Normalize the test-owned
+ // window before the recording boundary, then put the sentinel back in
+ // front. Dispatch still requires the target to be visibly mapped and
+ // fully occluded; this does not retry or weaken the action assertion.
+ let raised = fixture.driver.call(
+ "bring_to_front",
+ serde_json::json!({
+ "pid": target.pid,
+ "window_id": target.native_id,
+ }),
+ );
+ assert!(
+ !raised.is_error(),
+ "normalize standalone browser window posture: {}",
+ raised.raw
+ );
sentinel
- .assert_background_posture(target)
+ .prepare_background_observation(&mut fixture.driver, target)
.expect("establish standalone browser background posture");
fixture.driver.start_behavior_recording();
sentinel
@@ -1202,6 +1259,320 @@ fn run_prepare_isolated_launch(spec: &BrowserSpec) {
);
}
+fn run_existing_profile_attach(spec: &BrowserSpec) {
+ let scenario = format!(
+ "{}-{}-standalone-existing-profile",
+ std::env::consts::OS,
+ spec.name
+ );
+ execute_case(
+ case(&spec.name, "browser_prepare_existing_profile"),
+ |evidence| {
+ let mut fixture = launch_browser(spec, &scenario);
+ *evidence = recording_evidence(fixture.driver.recording_dir());
+ run_with_background_oracles(&mut fixture, |fixture| {
+ let session = format!("standalone-existing-profile-{}", fixture.pid);
+ let started = fixture
+ .driver
+ .call("start_session", serde_json::json!({ "session": session }));
+ assert!(!started.is_error(), "start_session failed: {}", started.raw);
+
+ // A live MCP proxy proves transport provenance, not a person's
+ // approval to attach an authenticated profile.
+ let unapproved = fixture.driver.call(
+ "browser_prepare",
+ serde_json::json!({
+ "pid": fixture.pid as i64,
+ "window_id": fixture.window_id,
+ "session": session,
+ "strategy": {"kind": "existing_profile"},
+ }),
+ );
+ assert_eq!(
+ unapproved.structured()["refusal"]["code"],
+ "browser_consent_required",
+ "{}",
+ unapproved.raw
+ );
+
+ let approval_token = mint_existing_profile_approval(ExistingProfileApprovalScope {
+ pid: fixture.pid as i64,
+ window_id: fixture.window_id,
+ session: session.clone(),
+ })
+ .expect("mint exact existing-profile approval");
+ fixture.driver.start_behavior_recording();
+ let prepared = fixture.driver.call(
+ "browser_prepare",
+ serde_json::json!({
+ "pid": fixture.pid as i64,
+ "window_id": fixture.window_id,
+ "session": session,
+ "strategy": {"kind": "existing_profile"},
+ "approval_token": approval_token,
+ }),
+ );
+ assert_eq!(prepared.structured()["status"], "ok", "{}", prepared.raw);
+ assert_eq!(
+ prepared.structured()["action"],
+ "attached_existing_profile",
+ "{}",
+ prepared.raw
+ );
+ assert_eq!(
+ prepared.structured()["attachment"]["kind"],
+ "existing_profile"
+ );
+ assert_eq!(
+ prepared.structured()["attachment"]["capabilities_invalidated"],
+ true
+ );
+ assert_eq!(
+ prepared.structured()["attachment"]["next_action"],
+ "get_browser_state"
+ );
+ assert_eq!(
+ prepared.structured()["side_effects"]["launched_browser"],
+ false
+ );
+ assert_eq!(
+ prepared.structured()["side_effects"]["created_profile"],
+ false
+ );
+ assert_eq!(
+ prepared.structured()["side_effects"]["copied_profile_data"],
+ false
+ );
+
+ let public_result = prepared.raw.to_string();
+ assert!(!public_result.contains("ws://"), "{}", prepared.raw);
+ assert!(
+ !public_result.contains("webSocketDebuggerUrl"),
+ "{}",
+ prepared.raw
+ );
+ assert!(!public_result.contains(&approval_token), "{}", prepared.raw);
+ assert!(
+ !public_result.contains(&fixture._profile.path().display().to_string()),
+ "{}",
+ prepared.raw
+ );
+
+ let state = fixture.driver.call(
+ "get_browser_state",
+ serde_json::json!({
+ "pid": fixture.pid as i64,
+ "window_id": fixture.window_id,
+ "session": session,
+ }),
+ );
+ assert_eq!(
+ state.structured()["binding_quality"],
+ "exact",
+ "{}",
+ state.raw
+ );
+ let target = state.structured()["target_id"]
+ .as_str()
+ .expect("existing-profile target")
+ .to_owned();
+ let tab = state.structured()["tabs"]
+ .as_array()
+ .and_then(|tabs| tabs.iter().find(|tab| tab["active"] == true))
+ .and_then(|tab| tab["tab_id"].as_str())
+ .expect("existing-profile active tab")
+ .to_owned();
+ let snapshot = fixture.driver.call(
+ "get_browser_state",
+ serde_json::json!({
+ "target_id": target,
+ "tab_id": tab,
+ "session": session,
+ }),
+ );
+ let click_ref = ref_by_label(&snapshot, "id=btn-increment");
+ let clicked = fixture.driver.call(
+ "browser_click",
+ serde_json::json!({
+ "target_id": target,
+ "tab_id": tab,
+ "ref": click_ref,
+ "input_route": "dom_event",
+ "session": session,
+ }),
+ );
+ assert_eq!(clicked.structured()["status"], "ok", "{}", clicked.raw);
+ wait_for_text(&fixture.server, "lbl-counter", "counter=1");
+
+ let ended = fixture
+ .driver
+ .call("end_session", serde_json::json!({ "session": session }));
+ assert!(!ended.is_error(), "end_session failed: {}", ended.raw);
+ let windows = fixture
+ .driver
+ .call("list_windows", serde_json::json!({"pid": fixture.pid}));
+ assert!(
+ windows.structured()["windows"]
+ .as_array()
+ .is_some_and(|windows| windows.iter().any(|window| {
+ window["window_id"].as_u64() == Some(fixture.window_id)
+ })),
+ "ending an attachment grant must not close the user-owned browser: {}",
+ windows.raw
+ );
+
+ Observation::delivered(vec![OracleKind::FixtureState], Evidence::default())
+ })
+ },
+ );
+}
+
+fn run_existing_profile_setup(spec: &BrowserSpec) {
+ let scenario = format!(
+ "{}-{}-standalone-existing-profile-setup",
+ std::env::consts::OS,
+ spec.name
+ );
+ execute_case(
+ case(&spec.name, "browser_prepare_existing_profile_setup"),
+ |evidence| {
+ let mut fixture = launch_unprepared_browser(spec, &scenario);
+ *evidence = recording_evidence(fixture.driver.recording_dir());
+ let session = format!("standalone-existing-profile-setup-{}", fixture.pid);
+ let started = fixture
+ .driver
+ .call("start_session", serde_json::json!({ "session": session }));
+ assert!(!started.is_error(), "start_session failed: {}", started.raw);
+
+ let approval_token = mint_existing_profile_approval(ExistingProfileApprovalScope {
+ pid: fixture.pid as i64,
+ window_id: fixture.window_id,
+ session: session.clone(),
+ })
+ .expect("mint exact existing-profile setup approval");
+ fixture.driver.start_behavior_recording();
+ let prepared = fixture.driver.call(
+ "browser_prepare",
+ serde_json::json!({
+ "pid": fixture.pid as i64,
+ "window_id": fixture.window_id,
+ "session": session,
+ "strategy": {"kind": "existing_profile"},
+ "approval_token": approval_token,
+ }),
+ );
+ assert_eq!(prepared.structured()["status"], "ok", "{}", prepared.raw);
+ assert_eq!(
+ prepared.structured()["action"],
+ "attached_existing_profile",
+ "{}",
+ prepared.raw
+ );
+ assert_eq!(
+ prepared.structured()["side_effects"]["opened_setup_page"],
+ true,
+ "{}",
+ prepared.raw
+ );
+ assert_eq!(
+ prepared.structured()["side_effects"]["closed_setup_page"],
+ true,
+ "{}",
+ prepared.raw
+ );
+ assert_eq!(
+ prepared.structured()["side_effects"]["enabled_remote_debugging"],
+ true,
+ "{}",
+ prepared.raw
+ );
+ assert_eq!(
+ prepared.structured()["side_effects"]["launched_browser"],
+ false
+ );
+ assert_eq!(
+ prepared.structured()["side_effects"]["created_profile"],
+ false
+ );
+
+ let public_result = prepared.raw.to_string();
+ assert!(!public_result.contains("ws://"), "{}", prepared.raw);
+ assert!(!public_result.contains(&approval_token), "{}", prepared.raw);
+ assert!(
+ !public_result.contains(&fixture._profile.path().display().to_string()),
+ "{}",
+ prepared.raw
+ );
+
+ run_with_background_oracles(&mut fixture, |fixture| {
+ let state = fixture.driver.call(
+ "get_browser_state",
+ serde_json::json!({
+ "pid": fixture.pid as i64,
+ "window_id": fixture.window_id,
+ "session": session,
+ }),
+ );
+ assert_eq!(
+ state.structured()["binding_quality"],
+ "exact",
+ "{}",
+ state.raw
+ );
+ let target = state.structured()["target_id"]
+ .as_str()
+ .expect("existing-profile setup target")
+ .to_owned();
+ let tab = state.structured()["tabs"]
+ .as_array()
+ .and_then(|tabs| tabs.iter().find(|tab| tab["active"] == true))
+ .and_then(|tab| tab["tab_id"].as_str())
+ .expect("existing-profile setup active tab")
+ .to_owned();
+ let snapshot = fixture.driver.call(
+ "get_browser_state",
+ serde_json::json!({
+ "target_id": target,
+ "tab_id": tab,
+ "session": session,
+ }),
+ );
+ let click_ref = ref_by_label(&snapshot, "id=btn-increment");
+ let clicked = fixture.driver.call(
+ "browser_click",
+ serde_json::json!({
+ "target_id": target,
+ "tab_id": tab,
+ "ref": click_ref,
+ "input_route": "dom_event",
+ "session": session,
+ }),
+ );
+ assert_eq!(clicked.structured()["status"], "ok", "{}", clicked.raw);
+ wait_for_text(&fixture.server, "lbl-counter", "counter=1");
+
+ let ended = fixture
+ .driver
+ .call("end_session", serde_json::json!({ "session": session }));
+ assert!(!ended.is_error(), "end_session failed: {}", ended.raw);
+ let windows = fixture
+ .driver
+ .call("list_windows", serde_json::json!({"pid": fixture.pid}));
+ assert!(
+ windows.structured()["windows"]
+ .as_array()
+ .is_some_and(|windows| windows.iter().any(|window| {
+ window["window_id"].as_u64() == Some(fixture.window_id)
+ })),
+ "ending the setup grant must not close the user-owned browser: {}",
+ windows.raw
+ );
+ Observation::delivered(vec![OracleKind::FixtureState], Evidence::default())
+ })
+ },
+ );
+}
+
fn run_stale_ref(spec: &BrowserSpec) {
let scenario = format!(
"{}-{}-standalone-stale-ref",
@@ -1498,6 +1869,14 @@ standalone_browser_test!(
standalone_browser_prepare_isolated,
run_prepare_isolated_launch
);
+standalone_browser_test!(
+ standalone_browser_existing_profile,
+ run_existing_profile_attach
+);
+standalone_browser_test!(
+ standalone_browser_existing_profile_setup,
+ run_existing_profile_setup
+);
standalone_browser_test!(standalone_browser_stale_ref, run_stale_ref);
standalone_browser_test!(standalone_browser_frames, run_frame_roundtrip);
standalone_browser_test!(standalone_browser_multi_tab, run_multi_tab);
diff --git a/libs/cua-driver/rust/crates/platform-linux/src/atspi/mod.rs b/libs/cua-driver/rust/crates/platform-linux/src/atspi/mod.rs
index e83970012f..cda1e0927a 100644
--- a/libs/cua-driver/rust/crates/platform-linux/src/atspi/mod.rs
+++ b/libs/cua-driver/rust/crates/platform-linux/src/atspi/mod.rs
@@ -22,6 +22,8 @@ pub struct AtspiNode {
pub role: String,
pub name: Option<String>,
pub value: Option<String>,
+ /// Checked state when the accessibility backend exposes one for a toggle.
+ pub checked: Option<bool>,
pub description: Option<String>,
pub actions: Vec<String>,
/// For AT-SPI: element_key = element_index as u64.
@@ -33,6 +35,9 @@ pub struct AtspiNode {
/// `element_index` of the nearest actionable ancestor, if any.
/// Mirrors what the markdown indent shows.
pub parent_element_index: Option<usize>,
+ /// True when the native AT-SPI walker observed this node below renderer
+ /// web content. Browser-owned consent UI must never match such nodes.
+ pub in_web_content: bool,
}
pub struct AtspiTreeResult {
@@ -225,6 +230,7 @@ fn walk_via_x11_properties(xid: u64, query: Option<&str>) -> AtspiTreeResult {
Some(title.clone())
},
value: None,
+ checked: None,
description: if wm_class.is_empty() {
None
} else {
@@ -234,6 +240,7 @@ fn walk_via_x11_properties(xid: u64, query: Option<&str>) -> AtspiTreeResult {
element_key: xid,
depth: 0,
parent_element_index: None,
+ in_web_content: false,
};
md.push_str(&format!(
"- [0] window \"{}\" [actions=[activate]]\n",
diff --git a/libs/cua-driver/rust/crates/platform-linux/src/atspi/native.rs b/libs/cua-driver/rust/crates/platform-linux/src/atspi/native.rs
index 4a37af54aa..937e09dac3 100644
--- a/libs/cua-driver/rust/crates/platform-linux/src/atspi/native.rs
+++ b/libs/cua-driver/rust/crates/platform-linux/src/atspi/native.rs
@@ -128,6 +128,7 @@ struct Visited<'a> {
/// expose no name — the Text-interface content (where typed text lives).
name: String,
value: Option<String>,
+ checked: Option<bool>,
actions: Vec<String>,
has_editable: bool,
has_value: bool,
@@ -482,7 +483,15 @@ async fn collect_visited_bounded<'a>(
Some(Ok(n)) => n,
_ => String::new(),
};
- let focused = matches!(state_r, Some(Ok(s)) if s.contains(State::Focused));
+ let focused = matches!(state_r.as_ref(), Some(Ok(s)) if s.contains(State::Focused));
+ let checked = if role.to_ascii_lowercase().contains("check") {
+ state_r
+ .as_ref()
+ .and_then(|state| state.as_ref().ok())
+ .map(|state| state.contains(State::Checked))
+ } else {
+ None
+ };
// Collect action names, numeric value, and (crucially) Text-interface
// content. Only touch `proxies` when an interface is actually present,
@@ -558,6 +567,7 @@ async fn collect_visited_bounded<'a>(
role,
name,
value,
+ checked,
actions,
has_editable,
has_value,
@@ -621,11 +631,13 @@ fn render(visited: &[Visited<'_>]) -> (String, Vec<AtspiNode>) {
Some(v.name.clone())
},
value: v.value.clone().filter(|s| !s.is_empty()),
+ checked: v.checked,
description: None,
actions: v.actions.clone(),
element_key: idx as u64,
depth: v.depth,
parent_element_index,
+ in_web_content: v.in_web_doc,
});
// Record this actionable index at its depth, and invalidate any
// deeper entries from a previous subtree.
diff --git a/libs/cua-driver/rust/crates/platform-linux/src/browser_consent_ui.rs b/libs/cua-driver/rust/crates/platform-linux/src/browser_consent_ui.rs
new file mode 100644
index 0000000000..b1aff9e976
--- /dev/null
+++ b/libs/cua-driver/rust/crates/platform-linux/src/browser_consent_ui.rs
@@ -0,0 +1,304 @@
+//! Exact Linux AT-SPI handling for Chromium's browser-owned debugging consent.
+
+use std::time::{Duration, Instant};
+
+use cua_driver_core::browser::{
+ BrowserConsentOutcome, BrowserConsentRequest, BrowserRefusal, BrowserRefusalCode,
+};
+
+use crate::atspi::AtspiNode;
+
+fn refusal(code: BrowserRefusalCode, message: impl Into<String>) -> BrowserRefusal {
+ BrowserRefusal::new(code, message)
+}
+
+fn normalized_text(node: &AtspiNode) -> String {
+ [
+ node.name.as_deref(),
+ node.value.as_deref(),
+ node.description.as_deref(),
+ ]
+ .into_iter()
+ .flatten()
+ .collect::<Vec<_>>()
+ .join(" ")
+ .trim()
+ .to_ascii_lowercase()
+}
+
+fn role_is(node: &AtspiNode, accepted: &[&str]) -> bool {
+ let role = node.role.trim().to_ascii_lowercase();
+ accepted.iter().any(|candidate| role == *candidate)
+}
+
+fn is_in_web_content(nodes: &[AtspiNode], node: &AtspiNode) -> bool {
+ let mut parent = node.parent_element_index;
+ for _ in 0..nodes.len() {
+ let Some(parent_index) = parent else {
+ return false;
+ };
+ let Some(parent_node) = nodes
+ .iter()
+ .find(|candidate| candidate.element_index == Some(parent_index))
+ else {
+ return false;
+ };
+ if role_is(parent_node, &["document web", "document frame", "document"]) {
+ return true;
+ }
+ parent = parent_node.parent_element_index;
+ }
+ true
+}
+
+fn trusted_prompt_nodes(nodes: &[AtspiNode]) -> impl Iterator<Item = &AtspiNode> {
+ nodes.iter().filter(|node| {
+ !node.in_web_content
+ && !role_is(node, &["document web", "document frame", "document"])
+ && !is_in_web_content(nodes, node)
+ })
+}
+
+fn remote_debugging_prompt_present(nodes: &[AtspiNode]) -> bool {
+ let has_title =
+ trusted_prompt_nodes(nodes).any(|node| normalized_text(node) == "allow remote debugging?");
+ let body = trusted_prompt_nodes(nodes)
+ .map(normalized_text)
+ .collect::<Vec<_>>()
+ .join(" ");
+ has_title
+ && body.contains("external app wants full control")
+ && body.contains("saved data, cookies and site data")
+ && body.contains("navigate to any url")
+}
+
+fn exact_allow_button(
+ nodes: &[AtspiNode],
+ bounds: &[(usize, i32, i32, u32, u32)],
+) -> Result<Option<usize>, BrowserRefusal> {
+ if !remote_debugging_prompt_present(nodes) {
+ return Ok(None);
+ }
+ let matches = trusted_prompt_nodes(nodes)
+ .filter(|node| {
+ role_is(node, &["push button", "button"])
+ && normalized_text(node) == "allow"
+ && !node.actions.is_empty()
+ && node.element_index.is_some()
+ })
+ .map(|node| {
+ (
+ node.element_index.expect("filtered actionable index"),
+ node.element_key,
+ node.depth,
+ node.role.clone(),
+ node.actions.clone(),
+ node.parent_element_index,
+ )
+ })
+ .collect::<Vec<_>>();
+ if matches.len() > 1 {
+ let candidate_bounds = |element_index: usize| {
+ bounds
+ .iter()
+ .find(|(index, _, _, width, height)| {
+ *index == element_index && *width > 0 && *height > 0
+ })
+ .map(|(_, x, y, width, height)| (*x, *y, *width, *height))
+ };
+ let first_bounds = candidate_bounds(matches[0].0);
+ let same_physical_control = first_bounds.is_some()
+ && matches.iter().all(|candidate| {
+ candidate.3 == matches[0].3
+ && candidate.4 == matches[0].4
+ && candidate_bounds(candidate.0) == first_bounds
+ });
+ if same_physical_control {
+ return Ok(matches
+ .iter()
+ .max_by_key(|candidate| candidate.2)
+ .map(|candidate| candidate.0));
+ }
+ }
+ match matches.as_slice() {
+ [] => Ok(None),
+ [(index, ..)] => Ok(Some(*index)),
+ _ => Err(refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ "multiple exact Allow actions matched the browser consent prompt",
+ )
+ .with_detail(serde_json::json!({
+ "candidates": matches.iter().map(|(element_index, element_key, depth, role, actions, parent_element_index)| {
+ let parent = parent_element_index.and_then(|parent_index| nodes.iter().find(|node| node.element_index == Some(parent_index)));
+ let bounds = bounds.iter().find(|(index, ..)| index == element_index);
+ serde_json::json!({
+ "element_index": element_index,
+ "element_key": element_key,
+ "depth": depth,
+ "role": role,
+ "actions": actions,
+ "parent_element_index": parent_element_index,
+ "parent_role": parent.map(|node| node.role.as_str()),
+ "parent_name": parent.and_then(|node| node.name.as_deref()),
+ "bounds": bounds.map(|(_, x, y, width, height)| serde_json::json!({"x": x, "y": y, "width": width, "height": height})),
+ })}).collect::<Vec<_>>()
+ }))),
+ }
+}
+
+fn prove_window_owner(pid: u32, window_id: u64) -> Result<(), BrowserRefusal> {
+ let owned = crate::wayland::list_windows_dispatch(Some(pid))
+ .into_iter()
+ .any(|window| window.xid == window_id);
+ if !owned {
+ return Err(refusal(
+ BrowserRefusalCode::BrowserBindingStale,
+ "the approved browser window changed ownership before consent",
+ ));
+ }
+ Ok(())
+}
+
+pub async fn handle(
+ request: BrowserConsentRequest,
+) -> Result<BrowserConsentOutcome, BrowserRefusal> {
+ let pid = u32::try_from(request.pid).map_err(|_| {
+ refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ "the approved browser pid is outside the Linux process-id range",
+ )
+ })?;
+ prove_window_owner(pid, request.window_id)?;
+ let deadline = Instant::now() + Duration::from_secs(4);
+ let mut saw_prompt = false;
+ loop {
+ prove_window_owner(pid, request.window_id)?;
+ let window_id = request.window_id;
+ let tree =
+ tokio::task::spawn_blocking(move || crate::atspi::walk_tree(pid, window_id, None))
+ .await
+ .map_err(|error| {
+ refusal(
+ BrowserRefusalCode::BrowserRouteUnavailable,
+ format!("could not inspect the browser consent UI: {error}"),
+ )
+ })?;
+ let prompt_present = remote_debugging_prompt_present(&tree.nodes);
+ saw_prompt |= prompt_present;
+ match exact_allow_button(&tree.nodes, &tree.bounds)? {
+ Some(index) => {
+ tokio::task::spawn_blocking(move || crate::atspi::perform_action(pid, index))
+ .await
+ .map_err(|error| {
+ refusal(
+ BrowserRefusalCode::BrowserRouteUnavailable,
+ format!("could not dispatch the exact browser consent action: {error}"),
+ )
+ })?
+ .map_err(|error| {
+ refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ format!("the exact browser consent action failed: {error}"),
+ )
+ })?;
+ return Ok(BrowserConsentOutcome::Accepted);
+ }
+ None if saw_prompt && !prompt_present => {
+ return Err(refusal(
+ BrowserRefusalCode::BrowserConsentRevoked,
+ "the person dismissed the browser consent prompt",
+ ));
+ }
+ None if Instant::now() >= deadline => {
+ return Err(refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ format!(
+ "no exact Chromium remote-debugging consent prompt appeared for reconnect attempt {}",
+ request.attempt
+ ),
+ ));
+ }
+ None => tokio::time::sleep(Duration::from_millis(100)).await,
+ }
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn node(role: &str, name: &str, actions: &[&str]) -> AtspiNode {
+ AtspiNode {
+ element_index: (!actions.is_empty()).then_some(7),
+ role: role.to_owned(),
+ name: Some(name.to_owned()),
+ value: None,
+ checked: None,
+ description: None,
+ actions: actions.iter().map(|value| (*value).to_owned()).collect(),
+ element_key: 0,
+ depth: 0,
+ parent_element_index: None,
+ in_web_content: false,
+ }
+ }
+
+ fn prompt() -> Vec<AtspiNode> {
+ vec![
+ node("heading", "Allow remote debugging?", &[]),
+ node(
+ "static",
+ "An external app wants full control. This includes access to your saved data, cookies and site data, and the ability to navigate to any URL.",
+ &[],
+ ),
+ node("push button", "Cancel", &["click"]),
+ node("push button", "Allow", &["click"]),
+ ]
+ }
+
+ #[test]
+ fn matcher_requires_exact_security_prompt_and_unique_allow_action() {
+ assert_eq!(exact_allow_button(&prompt(), &[]).unwrap(), Some(7));
+ assert!(
+ exact_allow_button(&[node("push button", "Allow", &["click"])], &[])
+ .unwrap()
+ .is_none()
+ );
+ }
+
+ #[test]
+ fn matcher_refuses_ambiguous_allow_actions() {
+ let mut nodes = prompt();
+ nodes.push(node("push button", "Allow", &["click"]));
+ assert_eq!(
+ exact_allow_button(&nodes, &[]).unwrap_err().code,
+ BrowserRefusalCode::BrowserWrongTargetRefused
+ );
+ }
+
+ #[test]
+ fn matcher_collapses_duplicate_atspi_paths_for_one_physical_button() {
+ let mut nodes = prompt();
+ let mut duplicate = node("push button", "Allow", &["click"]);
+ duplicate.element_index = Some(8);
+ duplicate.element_key = 8;
+ duplicate.depth = 2;
+ nodes.last_mut().unwrap().depth = 1;
+ nodes.push(duplicate);
+ let bounds = vec![(7, 10, 20, 80, 30), (8, 10, 20, 80, 30)];
+ assert_eq!(exact_allow_button(&nodes, &bounds).unwrap(), Some(8));
+ }
+
+ #[test]
+ fn matcher_ignores_a_spoofed_prompt_inside_web_content() {
+ let mut nodes = prompt();
+ let mut document = node("document web", "Example page", &[]);
+ document.element_index = Some(42);
+ nodes.insert(0, document);
+ for child in &mut nodes[1..] {
+ child.parent_element_index = Some(42);
+ child.in_web_content = true;
+ }
+ assert_eq!(exact_allow_button(&nodes, &[]).unwrap(), None);
+ }
+}
diff --git a/libs/cua-driver/rust/crates/platform-linux/src/browser_platform.rs b/libs/cua-driver/rust/crates/platform-linux/src/browser_platform.rs
index 6b4b32bef5..3495892e8c 100644
--- a/libs/cua-driver/rust/crates/platform-linux/src/browser_platform.rs
+++ b/libs/cua-driver/rust/crates/platform-linux/src/browser_platform.rs
@@ -4,14 +4,16 @@ use std::collections::HashSet;
use std::time::Duration;
use async_trait::async_trait;
+use cua_driver_core::browser::existing_profile_setup_descriptor;
use cua_driver_core::browser::platform::{
- BrowserPlatform, PrepareAction, PrepareOutcome, PrepareRequest,
+ BrowserConsentOutcome, BrowserConsentRequest, BrowserPlatform, ExistingProfileSetupOutcome,
+ ExistingProfileSetupRequest, PrepareAction, PrepareOutcome, PrepareRequest,
};
use cua_driver_core::browser::refusal::{BrowserRefusal, BrowserRefusalCode};
use cua_driver_core::browser::types::{
- BrowserClassification, BrowserEngineFamily, EndpointOwnershipMethod, EndpointOwnershipProof,
- NativeOwnershipMethod, NativeOwnershipProof, NativeWindowInfo, OwnedEndpoint,
- ProcessFingerprint, Rect,
+ BrowserClassification, BrowserEngineFamily, BrowserProduct, EndpointOwnershipMethod,
+ EndpointOwnershipProof, NativeOwnershipMethod, NativeOwnershipProof, NativeWindowInfo,
+ OwnedEndpoint, ProcessFingerprint, Rect,
};
use tokio::io::{AsyncReadExt, AsyncWriteExt};
@@ -42,6 +44,35 @@ fn is_firefox(name: &str) -> bool {
})
}
+fn browser_product(identity: &str) -> BrowserProduct {
+ let tokens = identity
+ .to_ascii_lowercase()
+ .split(|ch: char| !ch.is_ascii_alphanumeric())
+ .filter(|token| !token.is_empty())
+ .map(str::to_owned)
+ .collect::<Vec<_>>();
+ let has = |values: &[&str]| tokens.iter().any(|token| values.contains(&token.as_str()));
+ if has(&["google"]) && has(&["chrome"]) {
+ BrowserProduct::GoogleChrome
+ } else if has(&["msedge"]) || (has(&["microsoft"]) && has(&["edge"])) {
+ BrowserProduct::MicrosoftEdge
+ } else if has(&["chromium"]) {
+ BrowserProduct::Chromium
+ } else if has(&["brave"]) {
+ BrowserProduct::Brave
+ } else if has(&["vivaldi"]) {
+ BrowserProduct::Vivaldi
+ } else if has(&["opera"]) {
+ BrowserProduct::Opera
+ } else if has(&["electron"]) {
+ BrowserProduct::Electron
+ } else if has(&["firefox"]) {
+ BrowserProduct::Firefox
+ } else {
+ BrowserProduct::Other
+ }
+}
+
fn loopback_websocket_port(url: &str) -> Option<u16> {
["ws://127.0.0.1:", "ws://localhost:", "ws://[::1]:"]
.iter()
@@ -202,23 +233,30 @@ impl BrowserPlatform for LinuxBrowserPlatform {
format!("pid {pid} is outside the Linux process-id range"),
)
})?;
- let process = tokio::task::spawn_blocking(move || {
- crate::proc_fs::list_processes()
+ let (process, executable) = tokio::task::spawn_blocking(move || {
+ let process = crate::proc_fs::list_processes()
.into_iter()
- .find(|process| process.pid == pid_u32)
+ .find(|process| process.pid == pid_u32);
+ let executable = std::fs::read_link(format!("/proc/{pid}/exe"))
+ .ok()
+ .map(|path| path.to_string_lossy().into_owned());
+ (process, executable)
})
.await
.ok()
- .flatten()
+ .and_then(|(process, executable)| process.map(|process| (process, executable)))
.ok_or_else(|| {
refusal(
BrowserRefusalCode::BrowserBindingStale,
format!("browser process {pid} is no longer available"),
)
})?;
- let identity = format!("{} {}", process.name, process.cmdline);
+ let identity = executable
+ .filter(|path| !path.is_empty())
+ .unwrap_or_else(|| process.name.clone());
let chromium = is_chromium(&identity);
let gecko = is_firefox(&identity);
+ let product_kind = browser_product(&identity);
Ok(BrowserClassification {
is_browser: chromium || gecko,
engine: if chromium {
@@ -228,6 +266,7 @@ impl BrowserPlatform for LinuxBrowserPlatform {
} else {
BrowserEngineFamily::Unknown
},
+ product_kind,
product: Some(process.name),
channel: None,
supports_cdp: chromium,
@@ -409,6 +448,288 @@ impl BrowserPlatform for LinuxBrowserPlatform {
Ok(None)
}
+ async fn discover_existing_profile_endpoint(
+ &self,
+ pid: i64,
+ ) -> Result<Option<OwnedEndpoint>, BrowserRefusal> {
+ let ports = tokio::task::spawn_blocking(move || loopback_ports_for_pid(pid))
+ .await
+ .map_err(|error| {
+ refusal(
+ BrowserRefusalCode::BrowserRouteUnavailable,
+ format!("listener inspection task failed: {error}"),
+ )
+ })??;
+ let mut discovered = Vec::new();
+ for port in ports {
+ if let Some(ws_url) = browser_websocket_url(port).await {
+ discovered.push((port, ws_url));
+ }
+ }
+ match discovered.as_slice() {
+ [] => Ok(None),
+ [(port, ws_url)] => Ok(Some(OwnedEndpoint {
+ ws_url: ws_url.clone(),
+ http_port: Some(*port),
+ ownership: EndpointOwnershipProof {
+ method: EndpointOwnershipMethod::ListeningSocketPid,
+ owner_pid: pid,
+ detail: Some("/proc owner plus /json/version".to_owned()),
+ },
+ })),
+ _ => Err(refusal(
+ BrowserRefusalCode::BrowserBindingAmbiguous,
+ "multiple browser-level DevTools endpoints are owned by the approved process",
+ )),
+ }
+ }
+
+ async fn reprove_existing_profile_endpoint(
+ &self,
+ pid: i64,
+ expected_ws_url: &str,
+ ) -> Result<Option<OwnedEndpoint>, BrowserRefusal> {
+ let Some(port) = loopback_websocket_port(expected_ws_url) else {
+ return Err(refusal(
+ BrowserRefusalCode::BrowserEndpointOwnerMismatch,
+ "the approved existing-profile endpoint is not loopback-only",
+ ));
+ };
+ let ports = tokio::task::spawn_blocking(move || loopback_ports_for_pid(pid))
+ .await
+ .map_err(|error| {
+ refusal(
+ BrowserRefusalCode::BrowserRouteUnavailable,
+ format!("listener inspection task failed: {error}"),
+ )
+ })??;
+ if !ports.contains(&port) {
+ return Ok(None);
+ }
+ Ok(Some(OwnedEndpoint {
+ ws_url: expected_ws_url.to_owned(),
+ http_port: Some(port),
+ ownership: EndpointOwnershipProof {
+ method: EndpointOwnershipMethod::ListeningSocketPid,
+ owner_pid: pid,
+ detail: Some("/proc owner of exact approved endpoint".to_owned()),
+ },
+ }))
+ }
+
+ async fn setup_existing_profile_endpoint(
+ &self,
+ request: ExistingProfileSetupRequest,
+ ) -> Result<ExistingProfileSetupOutcome, BrowserRefusal> {
+ let descriptor = existing_profile_setup_descriptor(request.browser).ok_or_else(|| {
+ refusal(
+ BrowserRefusalCode::BrowserRouteUnavailable,
+ format!(
+ "approved existing-profile setup is not implemented for {:?}",
+ request.browser
+ ),
+ )
+ })?;
+ let pid_u32 = u32::try_from(request.pid).map_err(|_| {
+ refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ "the approved browser pid is outside the Linux process-id range",
+ )
+ })?;
+ if self
+ .is_only_exact_native_window(request.pid, request.window_id)
+ .await?
+ != Some(true)
+ {
+ return Err(refusal(
+ BrowserRefusalCode::BrowserBindingAmbiguous,
+ "existing-profile setup on Linux requires exactly one PID-owned native window; generic Wayland and multi-window processes are refused",
+ ));
+ }
+ let window_id = request.window_id;
+ let listeners_before =
+ tokio::task::spawn_blocking(move || loopback_ports_for_pid(request.pid))
+ .await
+ .map_err(|error| {
+ refusal(
+ BrowserRefusalCode::BrowserRouteUnavailable,
+ format!("listener inspection task failed: {error}"),
+ )
+ })??;
+ let handle = tokio::task::spawn_blocking(move || {
+ crate::browser_setup_ui::enable(pid_u32, window_id, descriptor)
+ })
+ .await
+ .map_err(|error| {
+ refusal(
+ BrowserRefusalCode::BrowserRouteUnavailable,
+ format!(
+ "could not inspect {}'s remote-debugging setup UI: {error}",
+ descriptor.product_name
+ ),
+ )
+ })??;
+ let opened_setup_page = handle.opened_setup_page;
+ let enabled_remote_debugging = handle.enabled_remote_debugging;
+ let focused_setup_address_field = handle.focused_setup_address_field;
+ let foregrounded_window = handle.foregrounded_window;
+ let injected_global_input = handle.injected_global_input;
+
+ let deadline = std::time::Instant::now() + Duration::from_secs(6);
+ let endpoint_result = loop {
+ let ports = match tokio::task::spawn_blocking(move || {
+ loopback_ports_for_pid(request.pid)
+ })
+ .await
+ {
+ Ok(Ok(ports)) => ports,
+ Ok(Err(error)) => break Err(error),
+ Err(error) => {
+ break Err(refusal(
+ BrowserRefusalCode::BrowserRouteUnavailable,
+ format!("listener inspection task failed: {error}"),
+ ))
+ }
+ };
+ let mut endpoints = Vec::new();
+ for port in &ports {
+ if let Some(ws_url) = browser_websocket_url(*port).await {
+ endpoints.push((*port, ws_url, "/proc owner plus /json/version"));
+ }
+ }
+ if endpoints.is_empty() {
+ let correlated = ports
+ .iter()
+ .copied()
+ .filter(|port| !listeners_before.contains(port))
+ .collect::<Vec<_>>();
+ if let [port] = correlated.as_slice() {
+ endpoints.push((
+ *port,
+ format!("ws://127.0.0.1:{port}/devtools/browser"),
+ "new PID-owned listener correlated with exact approved setup",
+ ));
+ } else if correlated.len() > 1 {
+ break Err(refusal(
+ BrowserRefusalCode::BrowserBindingAmbiguous,
+ format!(
+ "{} exposed multiple newly correlated PID-owned listeners",
+ descriptor.product_name
+ ),
+ ));
+ }
+ }
+ match endpoints.as_slice() {
+ [(port, ws_url, detail)] => {
+ break Ok(OwnedEndpoint {
+ ws_url: ws_url.clone(),
+ http_port: Some(*port),
+ ownership: EndpointOwnershipProof {
+ method: EndpointOwnershipMethod::ListeningSocketPid,
+ owner_pid: request.pid,
+ detail: Some((*detail).to_owned()),
+ },
+ })
+ }
+ [] if std::time::Instant::now() < deadline => {
+ tokio::time::sleep(Duration::from_millis(100)).await;
+ }
+ [] => {
+ break Err(refusal(
+ BrowserRefusalCode::BrowserRequiresSetup,
+ format!(
+ "{} did not expose a uniquely PID-owned loopback endpoint after the exact setup action",
+ descriptor.product_name
+ ),
+ ))
+ }
+ _ => {
+ break Err(refusal(
+ BrowserRefusalCode::BrowserBindingAmbiguous,
+ format!(
+ "{} exposed multiple PID-owned endpoint candidates after the exact setup action",
+ descriptor.product_name
+ ),
+ ))
+ }
+ }
+ };
+ let endpoint = match endpoint_result {
+ Ok(endpoint) => endpoint,
+ Err(error) => {
+ let error = tokio::task::spawn_blocking(move || handle.abort(error))
+ .await
+ .map_err(|join_error| {
+ refusal(
+ BrowserRefusalCode::BrowserRouteUnavailable,
+ format!("could not roll back browser setup: {join_error}"),
+ )
+ })?;
+ return Err(error);
+ }
+ };
+ crate::browser_setup_ui::retain_pending(pid_u32, window_id, handle)?;
+
+ Ok(ExistingProfileSetupOutcome {
+ opened_setup_page,
+ closed_setup_page: false,
+ enabled_remote_debugging,
+ focused_setup_address_field,
+ foregrounded_window,
+ injected_global_input,
+ endpoint: Some(endpoint),
+ })
+ }
+
+ async fn commit_existing_profile_setup(
+ &self,
+ request: ExistingProfileSetupRequest,
+ ) -> Result<bool, BrowserRefusal> {
+ let pid = u32::try_from(request.pid).map_err(|_| {
+ refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ "the approved browser pid is outside the Linux process-id range",
+ )
+ })?;
+ tokio::task::spawn_blocking(move || {
+ crate::browser_setup_ui::commit_pending(pid, request.window_id)
+ })
+ .await
+ .map_err(|error| {
+ refusal(
+ BrowserRefusalCode::BrowserRouteUnavailable,
+ format!("could not commit exact browser setup cleanup: {error}"),
+ )
+ })?
+ }
+
+ async fn abort_existing_profile_setup(
+ &self,
+ request: ExistingProfileSetupRequest,
+ error: BrowserRefusal,
+ ) -> BrowserRefusal {
+ let Ok(pid) = u32::try_from(request.pid) else {
+ return error;
+ };
+ tokio::task::spawn_blocking(move || {
+ crate::browser_setup_ui::abort_pending(pid, request.window_id, error)
+ })
+ .await
+ .unwrap_or_else(|join_error| {
+ refusal(
+ BrowserRefusalCode::BrowserRouteUnavailable,
+ format!("could not roll back exact browser setup: {join_error}"),
+ )
+ })
+ }
+
+ async fn handle_existing_profile_consent(
+ &self,
+ request: BrowserConsentRequest,
+ ) -> Result<BrowserConsentOutcome, BrowserRefusal> {
+ crate::browser_consent_ui::handle(request).await
+ }
+
async fn process_fingerprint(&self, pid: i64) -> Result<ProcessFingerprint, BrowserRefusal> {
let (start_time, executable) = tokio::task::spawn_blocking(move || process_identity(pid))
.await
@@ -436,6 +757,7 @@ impl BrowserPlatform for LinuxBrowserPlatform {
endpoint: Some(endpoint),
message: "An owned loopback DevTools endpoint is already available.".to_owned(),
side_effects: Default::default(),
+ attachment: None,
});
}
Err(refusal(
@@ -471,6 +793,22 @@ mod tests {
assert!(!is_chromium("ledger-service"));
}
+ #[test]
+ fn product_classification_uses_executable_identity_not_page_arguments() {
+ assert_eq!(
+ browser_product("/usr/lib/firefox/firefox"),
+ BrowserProduct::Firefox
+ );
+ assert_eq!(
+ browser_product("/snap/chromium/current/usr/lib/chromium-browser/chrome"),
+ BrowserProduct::Chromium
+ );
+ assert_eq!(
+ browser_product("/opt/google/chrome/chrome"),
+ BrowserProduct::GoogleChrome
+ );
+ }
+
#[test]
fn firefox_classifier_uses_product_tokens() {
assert!(is_firefox("firefox --new-instance"));
diff --git a/libs/cua-driver/rust/crates/platform-linux/src/browser_setup_ui.rs b/libs/cua-driver/rust/crates/platform-linux/src/browser_setup_ui.rs
new file mode 100644
index 0000000000..f33219b4ec
--- /dev/null
+++ b/libs/cua-driver/rust/crates/platform-linux/src/browser_setup_ui.rs
@@ -0,0 +1,545 @@
+//! Exact Linux AT-SPI setup for Chromium existing-profile attachment.
+
+use std::time::{Duration, Instant};
+use std::{
+ collections::HashMap,
+ sync::{Mutex, OnceLock},
+};
+
+use cua_driver_core::browser::{
+ BrowserRefusal, BrowserRefusalCode, BrowserSetupDescriptor,
+ EXISTING_PROFILE_SETUP_READY_TIMEOUT,
+};
+
+use crate::atspi::AtspiNode;
+
+fn refusal(code: BrowserRefusalCode, message: impl Into<String>) -> BrowserRefusal {
+ BrowserRefusal::new(code, message)
+}
+
+fn field_equals(node: &AtspiNode, expected: &str) -> bool {
+ [
+ node.name.as_deref(),
+ node.value.as_deref(),
+ node.description.as_deref(),
+ ]
+ .into_iter()
+ .flatten()
+ .any(|value| value.trim().eq_ignore_ascii_case(expected))
+}
+
+fn role_is(node: &AtspiNode, accepted: &[&str]) -> bool {
+ let role = node.role.trim().to_ascii_lowercase();
+ accepted.iter().any(|candidate| role == *candidate)
+}
+
+fn setup_page_proven(
+ nodes: &[AtspiNode],
+ descriptor: &BrowserSetupDescriptor,
+ trusted_navigation: bool,
+) -> bool {
+ let has_contradictory_address_bar = nodes.iter().any(|node| {
+ role_is(node, &["entry", "text"])
+ && field_equals(node, "Address and search bar")
+ && node.value.as_deref().is_some_and(|value| {
+ !value.trim().is_empty() && !value.trim().eq_ignore_ascii_case(descriptor.setup_url)
+ })
+ });
+ let exact_url = nodes.iter().any(|node| {
+ role_is(node, &["entry", "text"])
+ && field_equals(node, "Address and search bar")
+ && node
+ .value
+ .as_deref()
+ .or(node.name.as_deref())
+ .is_some_and(|value| value.trim().eq_ignore_ascii_case(descriptor.setup_url))
+ });
+ let exact_heading = nodes.iter().any(|node| {
+ role_is(node, &["heading", "section", "static"])
+ && field_equals(node, descriptor.page_heading)
+ });
+ let exact_page = nodes.iter().any(|node| {
+ role_is(node, &["document web", "document frame"])
+ && descriptor
+ .page_titles
+ .iter()
+ .any(|title| field_equals(node, title))
+ });
+ (exact_url || (trusted_navigation && !has_contradictory_address_bar))
+ && exact_page
+ && exact_heading
+}
+
+fn exact_setup_checkbox<'a>(
+ nodes: &'a [AtspiNode],
+ descriptor: &BrowserSetupDescriptor,
+ trusted_navigation: bool,
+) -> Result<Option<&'a AtspiNode>, BrowserRefusal> {
+ if !setup_page_proven(nodes, descriptor, trusted_navigation) {
+ return Ok(None);
+ }
+ let matches = nodes
+ .iter()
+ .filter(|node| {
+ role_is(node, &["check box", "checkbox"])
+ && field_equals(node, descriptor.checkbox_label)
+ && !node.actions.is_empty()
+ && node.element_index.is_some()
+ })
+ .collect::<Vec<_>>();
+ match matches.as_slice() {
+ [] => Ok(None),
+ [node] => Ok(Some(*node)),
+ _ => Err(refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ "multiple exact remote-debugging checkboxes were exposed",
+ )),
+ }
+}
+
+fn exact_setup_navigation<'a>(
+ nodes: &'a [AtspiNode],
+ descriptor: &BrowserSetupDescriptor,
+) -> Result<Option<&'a AtspiNode>, BrowserRefusal> {
+ let exact_page = nodes.iter().any(|node| {
+ role_is(node, &["document web", "document frame"])
+ && descriptor
+ .page_titles
+ .iter()
+ .any(|title| field_equals(node, title))
+ });
+ if !exact_page {
+ return Ok(None);
+ }
+ let matches = nodes
+ .iter()
+ .filter(|node| {
+ role_is(node, &["push button", "button"])
+ && field_equals(node, descriptor.page_heading)
+ && !node.actions.is_empty()
+ && node.element_index.is_some()
+ })
+ .collect::<Vec<_>>();
+ match matches.as_slice() {
+ [] => Ok(None),
+ [node] => Ok(Some(*node)),
+ _ => Err(refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ "multiple exact remote-debugging navigation controls were exposed",
+ )),
+ }
+}
+
+fn setup_not_ready_message(descriptor: &BrowserSetupDescriptor) -> String {
+ format!(
+ "the exact {} remote-debugging setup page did not become ready; on Linux, existing-profile setup requires the browser's complete AT-SPI tree (launch Chromium-family browsers with --force-renderer-accessibility, or use a screen reader that enables full renderer accessibility)",
+ descriptor.product_name
+ )
+}
+
+fn with_target_foreground<T>(
+ pid: u32,
+ window_id: u64,
+ body: impl FnOnce() -> anyhow::Result<T>,
+) -> anyhow::Result<T> {
+ if std::env::var_os("WAYLAND_DISPLAY").is_some() {
+ let window = crate::wayland::sway_ipc::window_for_id(window_id)
+ .filter(|window| window.pid == pid)
+ .ok_or_else(|| anyhow::anyhow!("no exact Sway container owns the approved window"))?;
+ crate::wayland::sway_ipc::with_focused_container(window.id, body)
+ } else {
+ crate::input::with_x11_foreground(window_id, 80, body)
+ }
+}
+
+fn close_tab(pid: u32, window_id: u64) -> anyhow::Result<()> {
+ with_target_foreground(pid, window_id, || {
+ if std::env::var_os("WAYLAND_DISPLAY").is_some() {
+ crate::wayland::hotkey(window_id, &["ctrl".to_owned(), "w".to_owned()])
+ } else {
+ crate::input::send_key_xtest("w", &["ctrl"])
+ }
+ })
+}
+
+fn trusted_keyboard_setup_navigation(
+ pid: u32,
+ window_id: u64,
+ descriptor: &BrowserSetupDescriptor,
+) -> anyhow::Result<()> {
+ let (base, _fragment) = descriptor
+ .setup_url
+ .split_once("/#")
+ .ok_or_else(|| anyhow::anyhow!("the fixed setup URL has no /# delimiter"))?;
+ let wayland = std::env::var_os("WAYLAND_DISPLAY").is_some();
+ with_target_foreground(pid, window_id, || {
+ if wayland {
+ crate::wayland::hotkey_focused(&["ctrl".to_owned(), "t".to_owned()])?;
+ std::thread::sleep(Duration::from_millis(100));
+ crate::wayland::hotkey_focused(&["ctrl".to_owned(), "l".to_owned()])?;
+ crate::wayland::type_text_then_key_focused(base, "enter")
+ } else {
+ crate::input::send_key_xtest("t", &["ctrl"])?;
+ std::thread::sleep(Duration::from_millis(100));
+ crate::input::send_key_xtest("l", &["ctrl"])?;
+ crate::input::send_type_text_xtest(base)?;
+ crate::input::send_key_xtest("enter", &[])
+ }
+ })?;
+
+ // Avoid keyboard-layout-dependent `/#` synthesis on X11 and punctuation
+ // loss on fresh wlroots virtual-keyboard seats. Open the fixed base page,
+ // then invoke its unique semantic navigation control in the exact PID.
+ let deadline = Instant::now() + EXISTING_PROFILE_SETUP_READY_TIMEOUT;
+ loop {
+ let tree = crate::atspi::walk_tree(pid, window_id, None);
+ let navigation = exact_setup_navigation(&tree.nodes, descriptor)
+ .map_err(|error| anyhow::anyhow!(error.message))?;
+ match navigation {
+ Some(node) => {
+ return crate::atspi::perform_action(
+ pid,
+ node.element_index.expect("actionable navigation index"),
+ )
+ .map(|_| ())
+ }
+ None if Instant::now() < deadline => {
+ std::thread::sleep(Duration::from_millis(100));
+ }
+ None => anyhow::bail!(
+ "the exact {} setup navigation control did not become ready",
+ descriptor.product_name
+ ),
+ }
+ }
+}
+
+pub struct SetupUiHandle {
+ pid: u32,
+ window_id: u64,
+ descriptor: &'static BrowserSetupDescriptor,
+ trusted_setup_navigation: bool,
+ pub opened_setup_page: bool,
+ pub enabled_remote_debugging: bool,
+ pub focused_setup_address_field: bool,
+ pub foregrounded_window: bool,
+ pub injected_global_input: bool,
+}
+
+impl SetupUiHandle {
+ fn rollback_remote_debugging(&mut self) -> bool {
+ if !self.enabled_remote_debugging {
+ return true;
+ }
+ let tree = crate::atspi::walk_tree(self.pid, self.window_id, None);
+ let restored =
+ exact_setup_checkbox(&tree.nodes, self.descriptor, self.trusted_setup_navigation)
+ .ok()
+ .flatten()
+ .filter(|node| node.checked == Some(true))
+ .and_then(|node| node.element_index)
+ .is_some_and(|index| crate::atspi::perform_action(self.pid, index).is_ok());
+ if restored {
+ self.enabled_remote_debugging = false;
+ }
+ restored
+ }
+
+ pub fn abort(mut self, error: BrowserRefusal) -> BrowserRefusal {
+ let enabled_remote_debugging = self.enabled_remote_debugging;
+ let restored_remote_debugging = self.rollback_remote_debugging();
+ let opened_setup_page = self.opened_setup_page;
+ let focused_setup_address_field = self.focused_setup_address_field;
+ let foregrounded_window = self.foregrounded_window;
+ let injected_global_input = self.injected_global_input;
+ let closed_setup_page = self.close().unwrap_or(false);
+ let mut error = error;
+ let cause = error.detail.take();
+ error.with_detail(serde_json::json!({
+ "setup_side_effects": {
+ "opened_setup_page": opened_setup_page,
+ "closed_setup_page": closed_setup_page,
+ "focused_setup_address_field": focused_setup_address_field,
+ "enabled_remote_debugging": enabled_remote_debugging,
+ "foregrounded_window": foregrounded_window,
+ "injected_global_input": injected_global_input,
+ "restored_remote_debugging": restored_remote_debugging,
+ },
+ "cause": cause,
+ }))
+ }
+
+ pub fn close_for_success(mut self) -> Result<Option<bool>, BrowserRefusal> {
+ if !self.opened_setup_page {
+ return Ok(None);
+ }
+ let tree = crate::atspi::walk_tree(self.pid, self.window_id, None);
+ if !setup_page_proven(&tree.nodes, self.descriptor, self.trusted_setup_navigation) {
+ let error = refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ "the temporary setup page was no longer exact before cleanup",
+ );
+ return Err(self.abort(error));
+ }
+ if let Err(error) = close_tab(self.pid, self.window_id) {
+ let error = refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ format!("could not close the exact temporary setup tab: {error}"),
+ );
+ return Err(self.abort(error));
+ }
+ self.opened_setup_page = false;
+ Ok(Some(true))
+ }
+
+ pub fn close(self) -> Option<bool> {
+ if !self.opened_setup_page {
+ return None;
+ }
+ let tree = crate::atspi::walk_tree(self.pid, self.window_id, None);
+ Some(
+ setup_page_proven(&tree.nodes, self.descriptor, self.trusted_setup_navigation)
+ && close_tab(self.pid, self.window_id).is_ok(),
+ )
+ }
+}
+
+type PendingSetupKey = (u32, u64);
+
+fn pending_setups() -> &'static Mutex<HashMap<PendingSetupKey, SetupUiHandle>> {
+ static PENDING: OnceLock<Mutex<HashMap<PendingSetupKey, SetupUiHandle>>> = OnceLock::new();
+ PENDING.get_or_init(|| Mutex::new(HashMap::new()))
+}
+
+pub fn retain_pending(
+ pid: u32,
+ window_id: u64,
+ handle: SetupUiHandle,
+) -> Result<(), BrowserRefusal> {
+ let mut pending = pending_setups().lock().unwrap();
+ if pending.contains_key(&(pid, window_id)) {
+ drop(pending);
+ return Err(handle.abort(refusal(
+ BrowserRefusalCode::BrowserBindingAmbiguous,
+ "another approved browser setup is already pending for this exact window",
+ )));
+ }
+ pending.insert((pid, window_id), handle);
+ Ok(())
+}
+
+pub fn commit_pending(pid: u32, window_id: u64) -> Result<bool, BrowserRefusal> {
+ let handle = pending_setups()
+ .lock()
+ .unwrap()
+ .remove(&(pid, window_id))
+ .ok_or_else(|| {
+ refusal(
+ BrowserRefusalCode::BrowserBindingStale,
+ "the exact pending browser setup cleanup handle is missing",
+ )
+ })?;
+ Ok(handle.close_for_success()?.unwrap_or(false))
+}
+
+pub fn abort_pending(pid: u32, window_id: u64, error: BrowserRefusal) -> BrowserRefusal {
+ match pending_setups().lock().unwrap().remove(&(pid, window_id)) {
+ Some(handle) => handle.abort(error),
+ None => error.with_detail(serde_json::json!({
+ "setup_cleanup": "the exact pending browser setup cleanup handle was missing"
+ })),
+ }
+}
+
+pub fn enable(
+ pid: u32,
+ window_id: u64,
+ descriptor: &'static BrowserSetupDescriptor,
+) -> Result<SetupUiHandle, BrowserRefusal> {
+ let initial = crate::atspi::walk_tree(pid, window_id, None);
+ let initial_checkbox = exact_setup_checkbox(&initial.nodes, descriptor, false)?;
+ let mut handle = if initial_checkbox.is_some() {
+ SetupUiHandle {
+ pid,
+ window_id,
+ descriptor,
+ trusted_setup_navigation: false,
+ opened_setup_page: false,
+ enabled_remote_debugging: false,
+ focused_setup_address_field: false,
+ foregrounded_window: false,
+ injected_global_input: false,
+ }
+ } else {
+ let handle = SetupUiHandle {
+ pid,
+ window_id,
+ descriptor,
+ trusted_setup_navigation: true,
+ opened_setup_page: true,
+ enabled_remote_debugging: false,
+ focused_setup_address_field: true,
+ foregrounded_window: true,
+ injected_global_input: true,
+ };
+ if let Err(error) = trusted_keyboard_setup_navigation(pid, window_id, descriptor) {
+ return Err(handle.abort(refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ format!(
+ "could not navigate the exact {} window to its fixed setup page: {error}",
+ descriptor.product_name
+ ),
+ )));
+ }
+ handle
+ };
+
+ let deadline = Instant::now() + EXISTING_PROFILE_SETUP_READY_TIMEOUT;
+ loop {
+ let tree = crate::atspi::walk_tree(pid, window_id, None);
+ match exact_setup_checkbox(&tree.nodes, descriptor, handle.trusted_setup_navigation) {
+ Ok(Some(node)) => match node.checked {
+ Some(true) => return Ok(handle),
+ Some(false) if !handle.enabled_remote_debugging => {
+ let index = node.element_index.expect("actionable checkbox index");
+ if let Err(error) = crate::atspi::perform_action(pid, index) {
+ return Err(handle.abort(refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ format!("the exact checkbox action failed: {error}"),
+ )));
+ }
+ handle.enabled_remote_debugging = true;
+ }
+ Some(false) => {}
+ None => {
+ return Err(handle.abort(refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ "AT-SPI did not expose the exact checkbox checked state",
+ )))
+ }
+ },
+ Ok(None) => {}
+ Err(error) => return Err(handle.abort(error)),
+ }
+ if Instant::now() >= deadline {
+ return Err(handle.abort(refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ setup_not_ready_message(descriptor),
+ )));
+ }
+ std::thread::sleep(Duration::from_millis(100));
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use cua_driver_core::browser::{existing_profile_setup_descriptor, BrowserProduct};
+
+ fn descriptor() -> &'static BrowserSetupDescriptor {
+ existing_profile_setup_descriptor(BrowserProduct::GoogleChrome).unwrap()
+ }
+
+ fn node(role: &str, name: &str, value: Option<&str>, actions: &[&str]) -> AtspiNode {
+ AtspiNode {
+ element_index: (!actions.is_empty()).then_some(0),
+ role: role.to_owned(),
+ name: Some(name.to_owned()),
+ value: value.map(str::to_owned),
+ checked: None,
+ description: None,
+ actions: actions.iter().map(|value| (*value).to_owned()).collect(),
+ element_key: 0,
+ depth: 0,
+ parent_element_index: None,
+ in_web_content: false,
+ }
+ }
+
+ #[test]
+ fn checkbox_requires_exact_url_heading_and_unique_action() {
+ let mut checkbox = node("check box", descriptor().checkbox_label, None, &["toggle"]);
+ checkbox.checked = Some(false);
+ let nodes = vec![
+ node(
+ "entry",
+ "Address and search bar",
+ Some(descriptor().setup_url),
+ &["activate"],
+ ),
+ node("document web", descriptor().page_titles[0], None, &[]),
+ node("heading", descriptor().page_heading, None, &[]),
+ checkbox,
+ ];
+ assert_eq!(
+ exact_setup_checkbox(&nodes, descriptor(), false)
+ .unwrap()
+ .unwrap()
+ .checked,
+ Some(false)
+ );
+
+ let addressless = nodes[1..].to_vec();
+ assert!(
+ exact_setup_checkbox(&addressless, descriptor(), false)
+ .unwrap()
+ .is_none(),
+ "page labels alone must not authorize a setup action"
+ );
+ assert!(
+ exact_setup_checkbox(&addressless, descriptor(), true)
+ .unwrap()
+ .is_some(),
+ "the exact compositor-routed fixed navigation may substitute for hidden browser chrome"
+ );
+
+ let mut redacted_address = nodes.clone();
+ redacted_address[0].value = None;
+ assert!(
+ exact_setup_checkbox(&redacted_address, descriptor(), true)
+ .unwrap()
+ .is_some(),
+ "an address control with a withheld value is not contradictory evidence"
+ );
+
+ let mut contradictory = nodes;
+ contradictory[0].value = Some("https://example.test/spoof".to_owned());
+ assert!(
+ exact_setup_checkbox(&contradictory, descriptor(), true)
+ .unwrap()
+ .is_none(),
+ "trusted navigation must not override a visible contradictory address bar"
+ );
+ }
+
+ #[test]
+ fn setup_timeout_explains_linux_renderer_accessibility_precondition() {
+ let message = setup_not_ready_message(descriptor());
+ assert!(message.contains("complete AT-SPI tree"));
+ assert!(message.contains("--force-renderer-accessibility"));
+ }
+
+ #[test]
+ fn setup_navigation_requires_one_actionable_control_on_the_exact_page() {
+ let nodes = vec![
+ node("document web", descriptor().page_titles[0], None, &[]),
+ node("push button", descriptor().page_heading, None, &["press"]),
+ node("heading", descriptor().page_heading, None, &[]),
+ ];
+ assert!(exact_setup_navigation(&nodes, descriptor())
+ .unwrap()
+ .is_some());
+ assert!(exact_setup_navigation(&nodes[1..], descriptor())
+ .unwrap()
+ .is_none());
+
+ let mut ambiguous = nodes;
+ ambiguous.push(node(
+ "push button",
+ descriptor().page_heading,
+ None,
+ &["press"],
+ ));
+ assert!(exact_setup_navigation(&ambiguous, descriptor()).is_err());
+ }
+}
diff --git a/libs/cua-driver/rust/crates/platform-linux/src/lib.rs b/libs/cua-driver/rust/crates/platform-linux/src/lib.rs
index 7482074e98..4f98d69563 100644
--- a/libs/cua-driver/rust/crates/platform-linux/src/lib.rs
+++ b/libs/cua-driver/rust/crates/platform-linux/src/lib.rs
@@ -32,6 +32,12 @@ pub mod proc_fs;
#[cfg(target_os = "linux")]
pub mod browser_platform;
+#[cfg(target_os = "linux")]
+mod browser_setup_ui;
+
+#[cfg(target_os = "linux")]
+mod browser_consent_ui;
+
#[cfg(target_os = "linux")]
pub mod installed_apps;
diff --git a/libs/cua-driver/rust/crates/platform-linux/src/wayland/mod.rs b/libs/cua-driver/rust/crates/platform-linux/src/wayland/mod.rs
index 7aa572fc2f..b5dd150ca0 100644
--- a/libs/cua-driver/rust/crates/platform-linux/src/wayland/mod.rs
+++ b/libs/cua-driver/rust/crates/platform-linux/src/wayland/mod.rs
@@ -1111,10 +1111,9 @@ pub fn open_vptr_session(activate_window_id: Option<u64>) -> anyhow::Result<Vptr
anyhow::bail!("compositor does not expose zwlr_foreign_toplevel_manager_v1");
}
- let seat = state
- .seat
- .clone()
- .ok_or_else(|| anyhow::anyhow!("compositor exposed no wl_seat for virtual-pointer input"))?;
+ let seat = state.seat.clone().ok_or_else(|| {
+ anyhow::anyhow!("compositor exposed no wl_seat for virtual-pointer input")
+ })?;
if let Some(id) = activate_window_id {
let handle = matching_handle(&state, id)
@@ -1315,8 +1314,7 @@ fn click_vptr(
sess.vptr.frame();
sess.queue.roundtrip(&mut sess.state)?;
std::thread::sleep(std::time::Duration::from_millis(15));
- sess.vptr
- .button(event_time_ms(), btn, ButtonState::Pressed);
+ sess.vptr.button(event_time_ms(), btn, ButtonState::Pressed);
sess.vptr.frame();
sess.queue.roundtrip(&mut sess.state)?;
std::thread::sleep(std::time::Duration::from_millis(20));
@@ -1345,9 +1343,7 @@ pub fn scroll(window_id: u64, direction: &str, amount: u32) -> anyhow::Result<()
/// coordinates when the active compositor exposes the target geometry.
pub fn window_local_to_output(window_id: u64, x: i32, y: i32) -> (i32, i32) {
window_geometry(window_id)
- .map(|(window_x, window_y, _, _)| {
- (window_x.saturating_add(x), window_y.saturating_add(y))
- })
+ .map(|(window_x, window_y, _, _)| (window_x.saturating_add(x), window_y.saturating_add(y)))
.unwrap_or((x, y))
}
@@ -1473,8 +1469,7 @@ fn scroll_vptr(
std::thread::sleep(std::time::Duration::from_millis(25));
}
sess.vptr.axis_source(AxisSource::Wheel);
- sess.vptr
- .axis_discrete(event_time_ms(), axis, value, sign);
+ sess.vptr.axis_discrete(event_time_ms(), axis, value, sign);
sess.vptr.frame();
sess.queue.roundtrip(&mut sess.state)?;
}
@@ -1589,8 +1584,7 @@ fn drag_vptr(
sess.vptr.frame();
sess.queue.roundtrip(&mut sess.state)?;
std::thread::sleep(std::time::Duration::from_millis(15));
- sess.vptr
- .button(event_time_ms(), btn, ButtonState::Pressed);
+ sess.vptr.button(event_time_ms(), btn, ButtonState::Pressed);
sess.vptr.frame();
sess.queue.roundtrip(&mut sess.state)?;
let n = steps.max(1);
@@ -1599,8 +1593,7 @@ fn drag_vptr(
let ix = (from_x as f64 + (to_x - from_x) as f64 * t).round() as i32;
let iy = (from_y as f64 + (to_y - from_y) as f64 * t).round() as i32;
let (cx, cy) = clamp_xy(ix, iy);
- sess.vptr
- .motion_absolute(event_time_ms(), cx, cy, w, h);
+ sess.vptr.motion_absolute(event_time_ms(), cx, cy, w, h);
sess.vptr.frame();
sess.queue.roundtrip(&mut sess.state)?;
std::thread::sleep(std::time::Duration::from_millis(8));
@@ -1659,6 +1652,53 @@ pub fn type_text(window_id: u64, text: &str) -> anyhow::Result<()> {
}
}
+/// Type into a surface whose exact Sway container is already held focused by
+/// the caller. This avoids re-resolving a title that can change mid-sequence
+/// (for example after opening a Chromium tab).
+pub fn type_text_focused(text: &str) -> anyhow::Result<()> {
+ if text.is_empty() {
+ return Ok(());
+ }
+ let result = std::process::Command::new("wtype")
+ .args(["-k", "Shift_L", "--"])
+ .arg(text)
+ .output();
+ match result {
+ Ok(out) if out.status.success() => Ok(()),
+ other => with_wtype_libei_fallback(
+ || {
+ libei_wait_keyboard_ready()?;
+ libei_type_text(text)
+ },
+ other.map(|out| String::from_utf8_lossy(&out.stderr).into_owned()),
+ ),
+ }
+}
+
+/// Type text and press one key while an outer exact-container focus guard is
+/// active. Keeping both operations in one virtual-keyboard lifetime avoids a
+/// headless wlroots seat dropping the first event from a second `wtype`
+/// process after the text has landed.
+pub fn type_text_then_key_focused(text: &str, key: &str) -> anyhow::Result<()> {
+ let keysym = key_to_keysym(key);
+ let result = std::process::Command::new("wtype")
+ .args(["-k", "Shift_L", "-s", "30"])
+ .arg(text)
+ .args(["-s", "50", "-k", &keysym])
+ .output();
+ match result {
+ Ok(out) if out.status.success() => Ok(()),
+ other => with_wtype_libei_fallback(
+ || {
+ libei_wait_keyboard_ready()?;
+ libei_type_text(text)?;
+ libei_press_key(key)
+ },
+ other.map(|out| String::from_utf8_lossy(&out.stderr).into_owned()),
+ ),
+ }
+}
+
/// Press a single named key into the focused Wayland surface via `wtype -k`.
pub fn press_key(window_id: u64, key: &str) -> anyhow::Result<()> {
activate_window_for_input(window_id)?;
@@ -1682,6 +1722,24 @@ pub fn press_key(window_id: u64, key: &str) -> anyhow::Result<()> {
}
}
+/// Press one key while an outer exact-container focus guard is active.
+pub fn press_key_focused(key: &str) -> anyhow::Result<()> {
+ let keysym = key_to_keysym(key);
+ let result = std::process::Command::new("wtype")
+ .args(["-k", "Shift_L", "-k", &keysym])
+ .output();
+ match result {
+ Ok(out) if out.status.success() => Ok(()),
+ other => with_wtype_libei_fallback(
+ || {
+ libei_wait_keyboard_ready()?;
+ libei_press_key(key)
+ },
+ other.map(|out| String::from_utf8_lossy(&out.stderr).into_owned()),
+ ),
+ }
+}
+
/// Press a key combination (modifiers + final key) via `wtype`. Each modifier
/// is pressed before the key, then released after, exactly like
/// `wtype -M ctrl -M shift -k key -m shift -m ctrl`. Unknown values pass
@@ -1723,18 +1781,48 @@ pub fn hotkey(window_id: u64, keys: &[String]) -> anyhow::Result<()> {
}
}
+/// Send a chord while an outer exact-container focus guard is active.
+pub fn hotkey_focused(keys: &[String]) -> anyhow::Result<()> {
+ let (mods, final_key) = partition_modifiers(keys)?;
+ if let Ok(()) = virtual_keyboard::hotkey(&mods, &final_key) {
+ return Ok(());
+ }
+ let keysym = key_to_keysym(&final_key);
+ let args = wtype_hotkey_args(&mods, &keysym);
+ let result = std::process::Command::new("wtype").args(&args).output();
+ match result {
+ Ok(out) if out.status.success() => Ok(()),
+ other => {
+ let stderr = other.map(|out| String::from_utf8_lossy(&out.stderr).into_owned());
+ #[cfg(feature = "portal-input")]
+ {
+ return with_wtype_libei_fallback(
+ || {
+ libei::wait_keyboard_ready()?;
+ libei_hotkey(&mods, &final_key)
+ },
+ stderr,
+ );
+ }
+ #[cfg(not(feature = "portal-input"))]
+ {
+ anyhow::bail!(
+ "wtype {} failed: {}",
+ args.join(" "),
+ stderr.unwrap_or_else(|_| "wtype unavailable".into())
+ );
+ }
+ }
+ }
+}
+
fn wtype_hotkey_args(mods: &[String], keysym: &str) -> Vec<String> {
// Keep the same harmless first-event primer used by `press_key`. A fresh
// virtual-keyboard object on headless seats can drop its first event. Give
// wlroots one event cycle after the primer and modifier transitions;
// otherwise Chromium can miss a coalesced shortcut even though wtype exits
// successfully.
- let mut args: Vec<String> = vec![
- "-k".into(),
- "Shift_L".into(),
- "-s".into(),
- "30".into(),
- ];
+ let mut args: Vec<String> = vec!["-k".into(), "Shift_L".into(), "-s".into(), "30".into()];
for m in mods {
args.push("-M".into());
args.push(m.clone());
@@ -1823,12 +1911,12 @@ fn with_wtype_libei_fallback(
#[cfg(feature = "portal-input")]
{
match wtype_err {
- Ok(stderr) => tracing::info!(
- "wtype failed ({stderr}); falling back to libei/portal typing"
- ),
- Err(e) => tracing::info!(
- "wtype unavailable ({e}); falling back to libei/portal typing"
- ),
+ Ok(stderr) => {
+ tracing::info!("wtype failed ({stderr}); falling back to libei/portal typing")
+ }
+ Err(e) => {
+ tracing::info!("wtype unavailable ({e}); falling back to libei/portal typing")
+ }
}
run()
}
@@ -2036,59 +2124,59 @@ fn libei_hotkey(mods: &[String], key: &str) -> anyhow::Result<()> {
/// known mapping so the caller can fail loudly.
fn key_to_evdev(key: &str) -> Option<u32> {
let code = match key.to_lowercase().as_str() {
- "enter" | "return" => 28, // KEY_ENTER
- "tab" => 15, // KEY_TAB
- "esc" | "escape" => 1, // KEY_ESC
- "space" => 57, // KEY_SPACE
- "backspace" => 14, // KEY_BACKSPACE
- "delete" | "del" => 111, // KEY_DELETE
- "up" => 103, // KEY_UP
- "down" => 108, // KEY_DOWN
- "left" => 105, // KEY_LEFT
- "right" => 106, // KEY_RIGHT
- "home" => 102, // KEY_HOME
- "end" => 107, // KEY_END
- "pageup" | "page_up" => 104, // KEY_PAGEUP
+ "enter" | "return" => 28, // KEY_ENTER
+ "tab" => 15, // KEY_TAB
+ "esc" | "escape" => 1, // KEY_ESC
+ "space" => 57, // KEY_SPACE
+ "backspace" => 14, // KEY_BACKSPACE
+ "delete" | "del" => 111, // KEY_DELETE
+ "up" => 103, // KEY_UP
+ "down" => 108, // KEY_DOWN
+ "left" => 105, // KEY_LEFT
+ "right" => 106, // KEY_RIGHT
+ "home" => 102, // KEY_HOME
+ "end" => 107, // KEY_END
+ "pageup" | "page_up" => 104, // KEY_PAGEUP
"pagedown" | "page_down" => 109, // KEY_PAGEDOWN
// Letters a-z. evdev codes follow the QWERTY scancode layout, not the
// alphabet, so each is listed explicitly (linux/input-event-codes.h).
- "a" => 30, // KEY_A
- "b" => 48, // KEY_B
- "c" => 46, // KEY_C
- "d" => 32, // KEY_D
- "e" => 18, // KEY_E
- "f" => 33, // KEY_F
- "g" => 34, // KEY_G
- "h" => 35, // KEY_H
- "i" => 23, // KEY_I
- "j" => 36, // KEY_J
- "k" => 37, // KEY_K
- "l" => 38, // KEY_L
- "m" => 50, // KEY_M
- "n" => 49, // KEY_N
- "o" => 24, // KEY_O
- "p" => 25, // KEY_P
- "q" => 16, // KEY_Q
- "r" => 19, // KEY_R
- "s" => 31, // KEY_S
- "t" => 20, // KEY_T
- "u" => 22, // KEY_U
- "v" => 47, // KEY_V
- "w" => 17, // KEY_W
- "x" => 45, // KEY_X
- "y" => 21, // KEY_Y
- "z" => 44, // KEY_Z
+ "a" => 30, // KEY_A
+ "b" => 48, // KEY_B
+ "c" => 46, // KEY_C
+ "d" => 32, // KEY_D
+ "e" => 18, // KEY_E
+ "f" => 33, // KEY_F
+ "g" => 34, // KEY_G
+ "h" => 35, // KEY_H
+ "i" => 23, // KEY_I
+ "j" => 36, // KEY_J
+ "k" => 37, // KEY_K
+ "l" => 38, // KEY_L
+ "m" => 50, // KEY_M
+ "n" => 49, // KEY_N
+ "o" => 24, // KEY_O
+ "p" => 25, // KEY_P
+ "q" => 16, // KEY_Q
+ "r" => 19, // KEY_R
+ "s" => 31, // KEY_S
+ "t" => 20, // KEY_T
+ "u" => 22, // KEY_U
+ "v" => 47, // KEY_V
+ "w" => 17, // KEY_W
+ "x" => 45, // KEY_X
+ "y" => 21, // KEY_Y
+ "z" => 44, // KEY_Z
// Digits. KEY_1=2 .. KEY_9=10, KEY_0=11 (input-event-codes.h).
- "1" => 2, // KEY_1
- "2" => 3, // KEY_2
- "3" => 4, // KEY_3
- "4" => 5, // KEY_4
- "5" => 6, // KEY_5
- "6" => 7, // KEY_6
- "7" => 8, // KEY_7
- "8" => 9, // KEY_8
- "9" => 10, // KEY_9
- "0" => 11, // KEY_0
+ "1" => 2, // KEY_1
+ "2" => 3, // KEY_2
+ "3" => 4, // KEY_3
+ "4" => 5, // KEY_4
+ "5" => 6, // KEY_5
+ "6" => 7, // KEY_6
+ "7" => 8, // KEY_7
+ "8" => 9, // KEY_8
+ "9" => 10, // KEY_9
+ "0" => 11, // KEY_0
// Function keys. KEY_F1=59 .. KEY_F10=68, then KEY_F11=87, KEY_F12=88.
"f1" => 59,
"f2" => 60,
@@ -2131,8 +2219,29 @@ const INJECT_PROTO_HELLO: &str = "cua-inject v1";
/// whitelist in `cua_key_named` (cua_compositor_patch.py). Compared
/// case-insensitively, matching the compositor's `strcasecmp`.
const INJECT_NAMED_KEYS: &[&str] = &[
- "enter", "return", "tab", "escape", "esc", "backspace", "space", "up", "down", "left", "right",
- "f1", "f2", "f3", "f4", "f5", "f6", "f7", "f8", "f9", "f10", "f11", "f12",
+ "enter",
+ "return",
+ "tab",
+ "escape",
+ "esc",
+ "backspace",
+ "space",
+ "up",
+ "down",
+ "left",
+ "right",
+ "f1",
+ "f2",
+ "f3",
+ "f4",
+ "f5",
+ "f6",
+ "f7",
+ "f8",
+ "f9",
+ "f10",
+ "f11",
+ "f12",
];
/// The control socket path, when running against the nested cua-compositor.
@@ -2323,7 +2432,10 @@ fn parse_inject_geometry(line: &str) -> anyhow::Result<((i32, i32), (i32, i32))>
if let Some(reason) = line.trim().strip_prefix("err") {
anyhow::bail!("cua-compositor geometry query failed: {}", reason.trim());
}
- anyhow::bail!("unexpected cua-compositor geometry response: {:?}", line.trim())
+ anyhow::bail!(
+ "unexpected cua-compositor geometry response: {:?}",
+ line.trim()
+ )
}
/// Return the offset that rebases native Wayland accessibility coordinates into
@@ -2650,8 +2762,7 @@ pub fn list_windows_dispatch(filter_pid: Option<u32>) -> Vec<WindowInfo> {
}
}
Ok(_) => {
- if let Some(ws) =
- shell_helper::list_windows(filter_pid).filter(|ws| !ws.is_empty())
+ if let Some(ws) = shell_helper::list_windows(filter_pid).filter(|ws| !ws.is_empty())
{
return ws;
}
@@ -2661,17 +2772,14 @@ pub fn list_windows_dispatch(filter_pid: Option<u32>) -> Vec<WindowInfo> {
}
}
Err(e) => {
- if let Some(ws) =
- shell_helper::list_windows(filter_pid).filter(|ws| !ws.is_empty())
+ if let Some(ws) = shell_helper::list_windows(filter_pid).filter(|ws| !ws.is_empty())
{
tracing::debug!(
"native Wayland protocols unavailable ({e}); using compositor helper"
);
return ws;
}
- tracing::warn!(
- "native Wayland list_windows failed: {e}; trying AT-SPI registry"
- );
+ tracing::warn!("native Wayland list_windows failed: {e}; trying AT-SPI registry");
let ws = wayland_atspi_windows(filter_pid);
if !ws.is_empty() {
return ws;
@@ -2981,7 +3089,12 @@ mod tests {
assert_eq!(enriched[0].xid, 77);
assert_eq!(enriched[0].pid, Some(123));
assert_eq!(
- (enriched[0].x, enriched[0].y, enriched[0].width, enriched[0].height),
+ (
+ enriched[0].x,
+ enriched[0].y,
+ enriched[0].width,
+ enriched[0].height
+ ),
(20, 30, 800, 600)
);
}
@@ -2993,7 +3106,10 @@ mod tests {
let enriched = enrich_native_windows(native, vec![accessible], true);
assert_eq!(enriched[0].xid, 123 << 16);
assert_eq!(enriched[0].pid, Some(123));
- assert_eq!(identity_for(enriched[0].xid).unwrap().title, "CuaTestHarness");
+ assert_eq!(
+ identity_for(enriched[0].xid).unwrap().title,
+ "CuaTestHarness"
+ );
}
#[test]
@@ -3007,8 +3123,8 @@ mod tests {
source
.write_to(&mut encoded, image::ImageFormat::Png)
.expect("encode fixture PNG");
- let cropped = crop_png_to_rect(encoded.get_ref(), 2, 1, 3, 4, "fixture")
- .expect("crop fixture PNG");
+ let cropped =
+ crop_png_to_rect(encoded.get_ref(), 2, 1, 3, 4, "fixture").expect("crop fixture PNG");
let decoded = image::load_from_memory(&cropped).expect("decode cropped PNG");
assert_eq!((decoded.width(), decoded.height()), (3, 4));
}
@@ -3023,7 +3139,14 @@ mod tests {
#[test]
fn injectable_text_rejects_unicode_and_other_controls() {
- for bad in ["café", "emoji 😀", "bell\u{07}", "null\u{00}", "delete\u{7f}", "cr\r"] {
+ for bad in [
+ "café",
+ "emoji 😀",
+ "bell\u{07}",
+ "null\u{00}",
+ "delete\u{7f}",
+ "cr\r",
+ ] {
assert!(
validate_injectable_text(bad).is_err(),
"{bad:?} must be rejected before it reaches the compositor"
@@ -3033,7 +3156,9 @@ mod tests {
#[test]
fn injectable_key_accepts_whitelist_case_insensitively() {
- for good in ["enter", "Enter", "RETURN", "tab", "Escape", "esc", "space", "up", "Left", "f1", "F12"] {
+ for good in [
+ "enter", "Enter", "RETURN", "tab", "Escape", "esc", "space", "up", "Left", "f1", "F12",
+ ] {
validate_injectable_key(good).unwrap_or_else(|e| panic!("{good:?} should pass: {e}"));
}
}
@@ -3065,8 +3190,8 @@ mod tests {
assert_eq!(
args,
[
- "-k", "Shift_L", "-s", "30", "-M", "ctrl", "-M", "shift", "-s", "20",
- "-k", "7", "-s", "20", "-m", "shift", "-m", "ctrl",
+ "-k", "Shift_L", "-s", "30", "-M", "ctrl", "-M", "shift", "-s", "20", "-k", "7",
+ "-s", "20", "-m", "shift", "-m", "ctrl",
]
);
}
diff --git a/libs/cua-driver/rust/crates/platform-linux/src/wayland/sway_ipc.rs b/libs/cua-driver/rust/crates/platform-linux/src/wayland/sway_ipc.rs
index 4ee52148e5..971b846166 100644
--- a/libs/cua-driver/rust/crates/platform-linux/src/wayland/sway_ipc.rs
+++ b/libs/cua-driver/rust/crates/platform-linux/src/wayland/sway_ipc.rs
@@ -171,6 +171,60 @@ pub fn window_for_app_id(app_id: &str) -> Option<Window> {
.max_by_key(|window| (window.focused, window.visible))
}
+fn focus_container(id: u64) -> bool {
+ let selector = format!("[con_id={id}]");
+ Command::new("swaymsg")
+ .args([selector.as_str(), "focus"])
+ .stdin(Stdio::null())
+ .stdout(Stdio::null())
+ .stderr(Stdio::null())
+ .status()
+ .is_ok_and(|status| status.success())
+}
+
+/// Briefly focus one compositor-attested container, run `body`, then restore
+/// the previously focused container. The caller must already have verified the
+/// target container's PID and id through [`window_for_id`].
+pub fn with_focused_container<T>(
+ id: u64,
+ body: impl FnOnce() -> anyhow::Result<T>,
+) -> anyhow::Result<T> {
+ let prior = list_windows()
+ .ok_or_else(|| anyhow::anyhow!("Sway IPC tree is unavailable"))?
+ .into_iter()
+ .find(|window| window.focused)
+ .map(|window| window.id);
+ if !focus_container(id) {
+ anyhow::bail!("Sway refused to focus exact container {id}");
+ }
+ std::thread::sleep(std::time::Duration::from_millis(80));
+ if !window_for_id(id).is_some_and(|window| window.focused) {
+ anyhow::bail!("Sway did not confirm focus on exact container {id}");
+ }
+ let result = body();
+ let restore = prior
+ .filter(|prior| *prior != id)
+ .map(|prior| {
+ if !focus_container(prior) {
+ anyhow::bail!("Sway could not restore prior container {prior}");
+ }
+ std::thread::sleep(std::time::Duration::from_millis(80));
+ if !window_for_id(prior).is_some_and(|window| window.focused) {
+ anyhow::bail!("Sway did not confirm restored container {prior}");
+ }
+ Ok(())
+ })
+ .transpose();
+ match (result, restore) {
+ (Ok(value), Ok(_)) => Ok(value),
+ (Err(error), Ok(_)) => Err(error),
+ (Ok(_), Err(error)) => Err(error),
+ (Err(error), Err(restore)) => Err(error.context(format!(
+ "the prior Sway focus also could not be restored: {restore}"
+ ))),
+ }
+}
+
pub fn window_origin_for_pid(pid: u32) -> Option<(i32, i32)> {
window_for_pid(pid).map(|window| (window.x, window.y))
}
diff --git a/libs/cua-driver/rust/crates/platform-macos/src/apps/mod.rs b/libs/cua-driver/rust/crates/platform-macos/src/apps/mod.rs
index 61471b3eec..edf86c35e6 100644
--- a/libs/cua-driver/rust/crates/platform-macos/src/apps/mod.rs
+++ b/libs/cua-driver/rust/crates/platform-macos/src/apps/mod.rs
@@ -31,74 +31,45 @@ pub struct AppInfo {
}
/// Enumerate running apps with NSApplicationActivationPolicyRegular.
-/// Uses `osascript` to query System Events — no Accessibility permission needed.
+///
+/// This stays entirely inside AppKit so listing or classifying an application
+/// never triggers the macOS Automation permission for System Events.
pub fn list_running_apps() -> Vec<AppInfo> {
- // Use `ps` + NSWorkspace via a brief Swift one-liner via swift-sh is heavy;
- // instead use the Obj-C bridge via `osascript`.
- // Fallback: parse `ps -axo pid,command` and cross-reference with bundle IDs.
- // Better: use a native call via core-foundation bindings.
list_running_apps_native()
}
fn list_running_apps_native() -> Vec<AppInfo> {
- // Use `lsappinfo list` which is a macOS system tool available on all versions.
- // Alternatively we can use NSWorkspace via objc2 — but for simplicity and
- // to match the Swift reference, we use a subprocess call to `osascript`.
- let script = r#"
-set output to ""
-tell application "System Events"
- set appList to every application process whose background only is false
- repeat with proc in appList
- set procName to name of proc
- set procPid to unix id of proc
- set bundleId to bundle identifier of proc
- if bundleId is missing value then set bundleId to ""
- set isFront to "0"
- if frontmost of proc then set isFront to "1"
- set output to output & procName & "|" & procPid & "|" & bundleId & "|" & isFront & linefeed
- end repeat
-end tell
-return output
-"#;
-
- let out = Command::new("osascript")
- .arg("-e")
- .arg(script)
- .output();
-
- match out {
- Err(_) => vec![],
- Ok(o) => {
- let text = String::from_utf8_lossy(&o.stdout);
- parse_osascript_app_list(&text)
- }
- }
-}
+ use objc2_app_kit::{NSApplicationActivationPolicy, NSWorkspace};
-fn parse_osascript_app_list(text: &str) -> Vec<AppInfo> {
let mut apps = Vec::new();
- for line in text.lines() {
- let parts: Vec<&str> = line.splitn(4, '|').collect();
- if parts.len() < 2 { continue; }
- let name = parts[0].trim().to_owned();
- let pid: i32 = parts[1].trim().parse().unwrap_or(0);
- let bundle_id = if parts.len() > 2 && !parts[2].trim().is_empty() {
- Some(parts[2].trim().to_owned())
- } else {
- None
- };
- let active = parts.get(3).map(|s| s.trim() == "1").unwrap_or(false);
- if name.is_empty() || pid == 0 { continue; }
- apps.push(AppInfo {
- name,
- pid,
- bundle_id,
- running: true,
- active,
- launch_path: None,
- kind: Some("desktop".to_owned()),
- last_used: None,
- });
+ unsafe {
+ let workspace = NSWorkspace::sharedWorkspace();
+ let running = workspace.runningApplications();
+ for index in 0..running.count() {
+ let app = running.objectAtIndex(index);
+ if app.isTerminated()
+ || app.activationPolicy() != NSApplicationActivationPolicy::Regular
+ {
+ continue;
+ }
+ let Some(name) = app.localizedName().map(|value| value.to_string()) else {
+ continue;
+ };
+ let pid = app.processIdentifier();
+ if name.is_empty() || pid <= 0 {
+ continue;
+ }
+ apps.push(AppInfo {
+ name,
+ pid,
+ bundle_id: app.bundleIdentifier().map(|value| value.to_string()),
+ running: true,
+ active: app.isActive(),
+ launch_path: None,
+ kind: Some("desktop".to_owned()),
+ last_used: None,
+ });
+ }
}
apps
}
diff --git a/libs/cua-driver/rust/crates/platform-macos/src/ax/tree.rs b/libs/cua-driver/rust/crates/platform-macos/src/ax/tree.rs
index c49f15aa93..0927426beb 100644
--- a/libs/cua-driver/rust/crates/platform-macos/src/ax/tree.rs
+++ b/libs/cua-driver/rust/crates/platform-macos/src/ax/tree.rs
@@ -11,7 +11,7 @@
//! - Tree is walked depth-first; element_index is assigned in DFS order.
use super::bindings::*;
-use core_foundation::base::{CFRelease, CFRetain, CFTypeRef};
+use core_foundation::base::{CFEqual, CFRelease, CFRetain, CFTypeRef};
use std::collections::HashSet;
use std::sync::{Mutex, OnceLock};
@@ -172,8 +172,14 @@ pub fn walk_tree_bounded(
let mut top_level = from_children;
for w in from_windows {
- // Deduplicate by raw pointer identity.
- if !top_level.iter().any(|&e| e == w) {
+ // AXChildren and AXWindows can return different proxy pointers for
+ // the same native window. CFEqual compares their AX identity;
+ // pointer equality alone duplicates the whole subtree and can turn
+ // one exact dialog action into a false ambiguity.
+ if !top_level
+ .iter()
+ .any(|&e| CFEqual(e as CFTypeRef, w as CFTypeRef) != 0)
+ {
top_level.push(w);
} else {
// Already present — release the extra retain from copy_ax_windows.
diff --git a/libs/cua-driver/rust/crates/platform-macos/src/browser/consent_ui.rs b/libs/cua-driver/rust/crates/platform-macos/src/browser/consent_ui.rs
new file mode 100644
index 0000000000..1840138770
--- /dev/null
+++ b/libs/cua-driver/rust/crates/platform-macos/src/browser/consent_ui.rs
@@ -0,0 +1,218 @@
+//! Exact macOS handling for Chrome's browser-owned remote-debugging consent.
+
+use std::time::{Duration, Instant};
+
+use core_foundation::base::{CFRelease, CFTypeRef};
+use cua_driver_core::browser::{
+ BrowserConsentOutcome, BrowserConsentRequest, BrowserRefusal, BrowserRefusalCode,
+};
+
+use crate::ax::bindings::{kAXErrorSuccess, perform_action, AXUIElementRef};
+use crate::ax::tree::{walk_tree, AXNode};
+
+fn refusal(code: BrowserRefusalCode, message: impl Into<String>) -> BrowserRefusal {
+ BrowserRefusal::new(code, message)
+}
+
+fn normalized_text(node: &AXNode) -> String {
+ [
+ node.title.as_deref(),
+ node.value.as_deref(),
+ node.description.as_deref(),
+ node.help.as_deref(),
+ ]
+ .into_iter()
+ .flatten()
+ .collect::<Vec<_>>()
+ .join(" ")
+ .trim()
+ .to_ascii_lowercase()
+}
+
+fn release_actionable_nodes(nodes: &[AXNode]) {
+ for node in nodes.iter().filter(|node| node.element_index.is_some()) {
+ unsafe { CFRelease(node.element_ptr as CFTypeRef) };
+ }
+}
+
+fn remote_debugging_sheet_present(nodes: &[AXNode]) -> bool {
+ nodes.iter().enumerate().any(|(sheet_index, sheet)| {
+ if sheet.role != "AXSheet" {
+ return false;
+ }
+ let end = nodes
+ .iter()
+ .enumerate()
+ .skip(sheet_index + 1)
+ .find(|(_, node)| node.depth <= sheet.depth)
+ .map_or(nodes.len(), |(index, _)| index);
+ nodes[sheet_index..end].iter().any(|node| {
+ let text = normalized_text(node);
+ text.contains("remote debugging") || text.contains("remote-debugging")
+ })
+ })
+}
+
+fn exact_allow_button(nodes: &[AXNode]) -> Result<Option<usize>, BrowserRefusal> {
+ let mut matches = Vec::new();
+ for (sheet_index, sheet) in nodes
+ .iter()
+ .enumerate()
+ .filter(|(_, node)| node.role == "AXSheet")
+ {
+ let end = nodes
+ .iter()
+ .enumerate()
+ .skip(sheet_index + 1)
+ .find(|(_, node)| node.depth <= sheet.depth)
+ .map_or(nodes.len(), |(index, _)| index);
+ let sheet_nodes = &nodes[sheet_index..end];
+ let prompt_is_remote_debugging = sheet_nodes.iter().any(|node| {
+ let text = normalized_text(node);
+ text.contains("remote debugging") || text.contains("remote-debugging")
+ });
+ if !prompt_is_remote_debugging {
+ continue;
+ }
+ for node in sheet_nodes {
+ if node.role != "AXButton" || !node.actions.iter().any(|action| action == "AXPress") {
+ continue;
+ }
+ let label = normalized_text(node);
+ let identifier = node
+ .identifier
+ .as_deref()
+ .unwrap_or_default()
+ .to_ascii_lowercase();
+ let semantic_allow = matches!(label.as_str(), "allow" | "allow remote debugging")
+ || (identifier.contains("allow")
+ && (identifier.contains("debug") || identifier.contains("confirm")));
+ if semantic_allow {
+ matches.push(node.element_ptr);
+ }
+ }
+ }
+ match matches.as_slice() {
+ [] => Ok(None),
+ [element] => Ok(Some(*element)),
+ _ => Err(refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ "multiple semantic allow actions matched the browser consent sheet",
+ )),
+ }
+}
+
+pub async fn handle(
+ request: BrowserConsentRequest,
+) -> Result<BrowserConsentOutcome, BrowserRefusal> {
+ let pid = i32::try_from(request.pid).map_err(|_| {
+ refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ "the approved browser pid is outside the macOS process-id range",
+ )
+ })?;
+ let window_id = u32::try_from(request.window_id).map_err(|_| {
+ refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ "the approved browser window is outside the macOS window-id range",
+ )
+ })?;
+ let deadline = Instant::now() + Duration::from_secs(4);
+ let mut saw_prompt = false;
+ loop {
+ let tree = tokio::task::spawn_blocking(move || walk_tree(pid, Some(window_id), None))
+ .await
+ .map_err(|error| {
+ refusal(
+ BrowserRefusalCode::BrowserRouteUnavailable,
+ format!("could not inspect the browser consent UI: {error}"),
+ )
+ })?;
+ let prompt_present = remote_debugging_sheet_present(&tree.nodes);
+ saw_prompt |= prompt_present;
+ let candidate = exact_allow_button(&tree.nodes);
+ match candidate {
+ Ok(Some(element)) => {
+ let pressed = unsafe { perform_action(element as AXUIElementRef, "AXPress") };
+ release_actionable_nodes(&tree.nodes);
+ if pressed != kAXErrorSuccess {
+ return Err(refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ "the exact browser consent action became stale before AXPress",
+ ));
+ }
+ return Ok(BrowserConsentOutcome::Accepted);
+ }
+ Ok(None) => release_actionable_nodes(&tree.nodes),
+ Err(error) => {
+ release_actionable_nodes(&tree.nodes);
+ return Err(error);
+ }
+ }
+ if saw_prompt && !prompt_present {
+ return Err(refusal(
+ BrowserRefusalCode::BrowserConsentRevoked,
+ "the person dismissed the browser consent sheet",
+ ));
+ }
+ if Instant::now() >= deadline {
+ return Err(refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ format!(
+ "no exact Chrome remote-debugging consent sheet appeared for reconnect attempt {}",
+ request.attempt
+ ),
+ ));
+ }
+ tokio::time::sleep(Duration::from_millis(100)).await;
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn node(role: &str, depth: usize, title: Option<&str>, actions: &[&str]) -> AXNode {
+ AXNode {
+ element_index: (!actions.is_empty()).then_some(0),
+ role: role.to_owned(),
+ title: title.map(str::to_owned),
+ value: None,
+ description: None,
+ identifier: None,
+ help: None,
+ actions: actions.iter().map(|value| (*value).to_owned()).collect(),
+ element_ptr: 7,
+ depth,
+ parent_element_index: None,
+ frame: None,
+ }
+ }
+
+ #[test]
+ fn matcher_requires_sheet_prompt_and_unique_press_action() {
+ let nodes = vec![
+ node("AXWindow", 0, Some("Chrome"), &[]),
+ node("AXSheet", 1, Some("Allow remote debugging?"), &[]),
+ node("AXButton", 2, Some("Cancel"), &["AXPress"]),
+ node("AXButton", 2, Some("Allow"), &["AXPress"]),
+ ];
+ assert_eq!(exact_allow_button(&nodes).unwrap(), Some(7));
+
+ let no_sheet = vec![node("AXButton", 1, Some("Allow"), &["AXPress"])];
+ assert_eq!(exact_allow_button(&no_sheet).unwrap(), None);
+ }
+
+ #[test]
+ fn matcher_refuses_ambiguous_allow_actions() {
+ let nodes = vec![
+ node("AXSheet", 1, Some("Allow remote debugging?"), &[]),
+ node("AXButton", 2, Some("Allow"), &["AXPress"]),
+ node("AXButton", 2, Some("Allow"), &["AXPress"]),
+ ];
+ assert_eq!(
+ exact_allow_button(&nodes).unwrap_err().code,
+ BrowserRefusalCode::BrowserWrongTargetRefused
+ );
+ }
+}
diff --git a/libs/cua-driver/rust/crates/platform-macos/src/browser/mod.rs b/libs/cua-driver/rust/crates/platform-macos/src/browser/mod.rs
index ece2a8c58f..859243557e 100644
--- a/libs/cua-driver/rust/crates/platform-macos/src/browser/mod.rs
+++ b/libs/cua-driver/rust/crates/platform-macos/src/browser/mod.rs
@@ -1,13 +1,15 @@
pub mod ax_page_reader;
pub mod browser_js;
pub mod cdp_client;
+mod consent_ui;
pub mod electron_js;
pub mod platform;
+mod setup_ui;
pub mod wk_web_view;
+pub use ax_page_reader::AXPageReader;
pub use browser_js::BrowserJs;
pub use cdp_client::{CdpClient, CdpSessionCache};
pub use electron_js::ElectronJs;
pub use platform::MacOsBrowserPlatform;
pub use wk_web_view::is_wk_web_view_app;
-pub use ax_page_reader::AXPageReader;
diff --git a/libs/cua-driver/rust/crates/platform-macos/src/browser/platform.rs b/libs/cua-driver/rust/crates/platform-macos/src/browser/platform.rs
index 734fced17d..7f62284f1f 100644
--- a/libs/cua-driver/rust/crates/platform-macos/src/browser/platform.rs
+++ b/libs/cua-driver/rust/crates/platform-macos/src/browser/platform.rs
@@ -5,14 +5,16 @@ use std::process::Stdio;
use std::time::Duration;
use async_trait::async_trait;
+use cua_driver_core::browser::existing_profile_setup_descriptor;
use cua_driver_core::browser::platform::{
- BrowserPlatform, PrepareAction, PrepareOutcome, PrepareRequest,
+ BrowserConsentOutcome, BrowserConsentRequest, BrowserPlatform, ExistingProfileSetupOutcome,
+ ExistingProfileSetupRequest, PrepareAction, PrepareOutcome, PrepareRequest,
};
use cua_driver_core::browser::refusal::{BrowserRefusal, BrowserRefusalCode};
use cua_driver_core::browser::types::{
- BrowserClassification, BrowserEngineFamily, EndpointOwnershipMethod, EndpointOwnershipProof,
- NativeOwnershipMethod, NativeOwnershipProof, NativeWindowInfo, OwnedEndpoint,
- ProcessFingerprint, Rect,
+ BrowserClassification, BrowserEngineFamily, BrowserProduct, EndpointOwnershipMethod,
+ EndpointOwnershipProof, NativeOwnershipMethod, NativeOwnershipProof, NativeWindowInfo,
+ OwnedEndpoint, ProcessFingerprint, Rect,
};
use tokio::io::{AsyncReadExt, AsyncWriteExt};
@@ -41,6 +43,34 @@ fn is_firefox(name: &str, bundle_id: &str) -> bool {
.any(|token| token == "firefox")
}
+fn browser_product(name: &str, bundle_id: &str) -> BrowserProduct {
+ let name = name.to_ascii_lowercase();
+ let bundle_id = bundle_id.to_ascii_lowercase();
+ if bundle_id.starts_with("com.google.chrome") || name == "google chrome" {
+ BrowserProduct::GoogleChrome
+ } else if bundle_id.starts_with("com.microsoft.edgemac") || name == "microsoft edge" {
+ BrowserProduct::MicrosoftEdge
+ } else if bundle_id.starts_with("org.chromium.chromium") || name == "chromium" {
+ BrowserProduct::Chromium
+ } else if bundle_id.starts_with("com.brave.browser") || name == "brave browser" {
+ BrowserProduct::Brave
+ } else if bundle_id.starts_with("com.vivaldi.vivaldi") || name == "vivaldi" {
+ BrowserProduct::Vivaldi
+ } else if bundle_id.starts_with("com.operasoftware.opera") || name == "opera" {
+ BrowserProduct::Opera
+ } else if bundle_id.starts_with("company.thebrowser.browser") || name == "arc" {
+ BrowserProduct::Arc
+ } else if bundle_id == "com.apple.safari" || name == "safari" {
+ BrowserProduct::Safari
+ } else if bundle_id.contains("firefox") || name == "firefox" {
+ BrowserProduct::Firefox
+ } else if bundle_id.contains("electron") || name == "electron" {
+ BrowserProduct::Electron
+ } else {
+ BrowserProduct::Other
+ }
+}
+
fn loopback_websocket_port(url: &str) -> Option<u16> {
["ws://127.0.0.1:", "ws://localhost:", "ws://[::1]:"]
.iter()
@@ -227,6 +257,7 @@ impl BrowserPlatform for MacOsBrowserPlatform {
let chromium = is_chromium(name, bundle_id);
let webkit = bundle_id == "com.apple.Safari" || name.eq_ignore_ascii_case("Safari");
let gecko = is_firefox(name, bundle_id);
+ let product_kind = browser_product(name, bundle_id);
Ok(BrowserClassification {
is_browser: chromium || webkit || gecko,
engine: if chromium {
@@ -238,6 +269,7 @@ impl BrowserPlatform for MacOsBrowserPlatform {
} else {
BrowserEngineFamily::Unknown
},
+ product_kind,
product: (!name.is_empty()).then(|| name.to_owned()),
channel: None,
supports_cdp: chromium,
@@ -332,6 +364,270 @@ impl BrowserPlatform for MacOsBrowserPlatform {
Ok(None)
}
+ async fn discover_existing_profile_endpoint(
+ &self,
+ pid: i64,
+ ) -> Result<Option<OwnedEndpoint>, BrowserRefusal> {
+ let ports = loopback_ports_for_pid(pid).await?;
+ let mut discovered = Vec::new();
+ for port in &ports {
+ if let Some(ws_url) = browser_websocket_url(*port).await {
+ discovered.push((*port, ws_url));
+ }
+ }
+ if discovered.len() == 1 {
+ let (port, ws_url) = discovered.pop().expect("one discovered endpoint");
+ return Ok(Some(OwnedEndpoint {
+ ws_url,
+ http_port: Some(port),
+ ownership: EndpointOwnershipProof {
+ method: EndpointOwnershipMethod::ListeningSocketPid,
+ owner_pid: pid,
+ detail: Some("lsof loopback listener owner plus /json/version".to_owned()),
+ },
+ }));
+ }
+ if discovered.len() > 1 {
+ return Err(refusal(
+ BrowserRefusalCode::BrowserBindingAmbiguous,
+ "multiple browser-level DevTools endpoints are owned by the approved process",
+ ));
+ }
+ // A bare listener is not enough to identify DevTools before approval:
+ // Chromium can own unrelated loopback services. The setup path below
+ // correlates a listener with the exact checkbox transition and the
+ // pooled WebSocket claim proves the protocol before attachment.
+ Ok(None)
+ }
+
+ async fn reprove_existing_profile_endpoint(
+ &self,
+ pid: i64,
+ expected_ws_url: &str,
+ ) -> Result<Option<OwnedEndpoint>, BrowserRefusal> {
+ let Some(port) = loopback_websocket_port(expected_ws_url) else {
+ return Err(refusal(
+ BrowserRefusalCode::BrowserEndpointOwnerMismatch,
+ "the approved existing-profile endpoint is not loopback-only",
+ ));
+ };
+ if !loopback_ports_for_pid(pid).await?.contains(&port) {
+ return Ok(None);
+ }
+ Ok(Some(OwnedEndpoint {
+ ws_url: expected_ws_url.to_owned(),
+ http_port: Some(port),
+ ownership: EndpointOwnershipProof {
+ method: EndpointOwnershipMethod::ListeningSocketPid,
+ owner_pid: pid,
+ detail: Some("lsof owner of exact approved endpoint".to_owned()),
+ },
+ }))
+ }
+
+ async fn setup_existing_profile_endpoint(
+ &self,
+ request: ExistingProfileSetupRequest,
+ ) -> Result<ExistingProfileSetupOutcome, BrowserRefusal> {
+ let descriptor = existing_profile_setup_descriptor(request.browser).ok_or_else(|| {
+ refusal(
+ BrowserRefusalCode::BrowserRouteUnavailable,
+ format!(
+ "approved existing-profile setup is not implemented for {:?}",
+ request.browser
+ ),
+ )
+ })?;
+ let pid = i32::try_from(request.pid).map_err(|_| {
+ refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ "the approved browser pid is outside the macOS process-id range",
+ )
+ })?;
+ let window_id = u32::try_from(request.window_id).map_err(|_| {
+ refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ "the approved browser window is outside the macOS window-id range",
+ )
+ })?;
+ let listeners_before = loopback_ports_for_pid(request.pid).await?;
+ let handle = crate::focus_guard::with_focus_suppressed_now(
+ Some(pid),
+ "browser_prepare.remote_debugging",
+ || async move {
+ tokio::task::spawn_blocking(move || {
+ super::setup_ui::enable(pid, window_id, descriptor)
+ })
+ .await
+ .map_err(|error| {
+ refusal(
+ BrowserRefusalCode::BrowserRouteUnavailable,
+ format!(
+ "could not inspect {}'s remote-debugging setup UI: {error}",
+ descriptor.product_name
+ ),
+ )
+ })?
+ },
+ )
+ .await?;
+ let opened_setup_page = handle.opened_setup_page;
+ let enabled_remote_debugging = handle.enabled_remote_debugging;
+ let focused_setup_address_field = handle.focused_setup_address_field;
+ let foregrounded_window = handle.foregrounded_window;
+ let injected_global_input = handle.injected_global_input;
+
+ let deadline = std::time::Instant::now() + Duration::from_secs(5);
+ let endpoint_result = loop {
+ let ports = match loopback_ports_for_pid(request.pid).await {
+ Ok(ports) => ports,
+ Err(error) => break Err(error),
+ };
+ let mut endpoints = Vec::new();
+ for port in &ports {
+ if let Some(ws_url) = browser_websocket_url(*port).await {
+ endpoints.push((*port, ws_url, "lsof owner plus /json/version"));
+ }
+ }
+ if endpoints.is_empty() {
+ let correlated = ports
+ .iter()
+ .copied()
+ .filter(|port| !listeners_before.contains(port))
+ .collect::<Vec<_>>();
+ if let [port] = correlated.as_slice() {
+ endpoints.push((
+ *port,
+ format!("ws://127.0.0.1:{port}/devtools/browser"),
+ "new PID-owned listener correlated with exact approved setup",
+ ));
+ } else if correlated.len() > 1 {
+ break Err(refusal(
+ BrowserRefusalCode::BrowserBindingAmbiguous,
+ format!(
+ "{} exposed multiple newly correlated PID-owned listeners",
+ descriptor.product_name
+ ),
+ ));
+ }
+ }
+ match endpoints.as_slice() {
+ [(port, ws_url, detail)] => {
+ break Ok(OwnedEndpoint {
+ ws_url: ws_url.clone(),
+ http_port: Some(*port),
+ ownership: EndpointOwnershipProof {
+ method: EndpointOwnershipMethod::ListeningSocketPid,
+ owner_pid: request.pid,
+ detail: Some((*detail).to_owned()),
+ },
+ })
+ }
+ [] if std::time::Instant::now() < deadline => {
+ tokio::time::sleep(Duration::from_millis(100)).await;
+ }
+ [] => {
+ break Err(refusal(
+ BrowserRefusalCode::BrowserRequiresSetup,
+ format!(
+ "{} did not expose a uniquely PID-owned loopback endpoint after the exact setup action",
+ descriptor.product_name
+ ),
+ ))
+ }
+ _ => {
+ break Err(refusal(
+ BrowserRefusalCode::BrowserBindingAmbiguous,
+ format!(
+ "{} exposed multiple PID-owned endpoint candidates after the exact setup action",
+ descriptor.product_name
+ ),
+ ))
+ }
+ }
+ };
+ let endpoint = match endpoint_result {
+ Ok(endpoint) => endpoint,
+ Err(error) => {
+ let error =
+ tokio::task::spawn_blocking(move || handle.abort(pid, window_id, error))
+ .await
+ .map_err(|join_error| {
+ refusal(
+ BrowserRefusalCode::BrowserRouteUnavailable,
+ format!("could not roll back browser setup: {join_error}"),
+ )
+ })?;
+ return Err(error);
+ }
+ };
+ super::setup_ui::retain_pending(pid, window_id, handle)?;
+
+ Ok(ExistingProfileSetupOutcome {
+ opened_setup_page,
+ closed_setup_page: false,
+ enabled_remote_debugging,
+ focused_setup_address_field,
+ foregrounded_window,
+ injected_global_input,
+ endpoint: Some(endpoint),
+ })
+ }
+
+ async fn commit_existing_profile_setup(
+ &self,
+ request: ExistingProfileSetupRequest,
+ ) -> Result<bool, BrowserRefusal> {
+ let pid = i32::try_from(request.pid).map_err(|_| {
+ refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ "the approved browser pid is outside the macOS process-id range",
+ )
+ })?;
+ let window_id = u32::try_from(request.window_id).map_err(|_| {
+ refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ "the approved browser window is outside the macOS window-id range",
+ )
+ })?;
+ tokio::task::spawn_blocking(move || super::setup_ui::commit_pending(pid, window_id))
+ .await
+ .map_err(|error| {
+ refusal(
+ BrowserRefusalCode::BrowserRouteUnavailable,
+ format!("could not commit exact browser setup cleanup: {error}"),
+ )
+ })?
+ }
+
+ async fn abort_existing_profile_setup(
+ &self,
+ request: ExistingProfileSetupRequest,
+ error: BrowserRefusal,
+ ) -> BrowserRefusal {
+ let Ok(pid) = i32::try_from(request.pid) else {
+ return error;
+ };
+ let Ok(window_id) = u32::try_from(request.window_id) else {
+ return error;
+ };
+ tokio::task::spawn_blocking(move || super::setup_ui::abort_pending(pid, window_id, error))
+ .await
+ .unwrap_or_else(|join_error| {
+ refusal(
+ BrowserRefusalCode::BrowserRouteUnavailable,
+ format!("could not roll back exact browser setup: {join_error}"),
+ )
+ })
+ }
+
+ async fn handle_existing_profile_consent(
+ &self,
+ request: BrowserConsentRequest,
+ ) -> Result<BrowserConsentOutcome, BrowserRefusal> {
+ super::consent_ui::handle(request).await
+ }
+
async fn process_fingerprint(&self, pid: i64) -> Result<ProcessFingerprint, BrowserRefusal> {
let (started, executable) = process_details(pid).await?;
Ok(ProcessFingerprint {
@@ -352,6 +648,7 @@ impl BrowserPlatform for MacOsBrowserPlatform {
endpoint: Some(endpoint),
message: "An owned loopback DevTools endpoint is already available.".to_owned(),
side_effects: Default::default(),
+ attachment: None,
});
}
Err(refusal(
diff --git a/libs/cua-driver/rust/crates/platform-macos/src/browser/setup_ui.rs b/libs/cua-driver/rust/crates/platform-macos/src/browser/setup_ui.rs
new file mode 100644
index 0000000000..d758f5ec87
--- /dev/null
+++ b/libs/cua-driver/rust/crates/platform-macos/src/browser/setup_ui.rs
@@ -0,0 +1,926 @@
+//! Exact macOS setup for Chrome's per-instance remote-debugging toggle.
+
+use std::time::{Duration, Instant};
+use std::{
+ collections::HashMap,
+ sync::{Mutex, OnceLock},
+};
+
+use core_foundation::base::{CFEqual, CFRelease, CFRetain, CFTypeRef};
+use cua_driver_core::browser::{
+ BrowserProduct, BrowserRefusal, BrowserRefusalCode, BrowserSetupDescriptor,
+ EXISTING_PROFILE_SETUP_READY_TIMEOUT,
+};
+
+use crate::ax::bindings::{
+ copy_number_attr, copy_string_attr, element_screen_center, focused_element_of_pid,
+ kAXErrorSuccess, perform_action, set_bool_attr_true, AXUIElementRef,
+};
+use crate::ax::tree::{walk_tree, AXNode};
+
+fn refusal(code: BrowserRefusalCode, message: impl Into<String>) -> BrowserRefusal {
+ BrowserRefusal::new(code, message)
+}
+
+fn field_equals(node: &AXNode, expected: &str) -> bool {
+ [
+ node.title.as_deref(),
+ node.value.as_deref(),
+ node.description.as_deref(),
+ node.help.as_deref(),
+ ]
+ .into_iter()
+ .flatten()
+ .any(|value| value.trim().eq_ignore_ascii_case(expected))
+}
+
+fn has_action(node: &AXNode, action: &str) -> bool {
+ node.actions.iter().any(|value| value == action)
+}
+
+fn release_actionable_nodes(nodes: &[AXNode]) {
+ for node in nodes.iter().filter(|node| node.element_index.is_some()) {
+ unsafe { CFRelease(node.element_ptr as CFTypeRef) };
+ }
+}
+
+fn unique_actionable(
+ nodes: &[AXNode],
+ role: &str,
+ label: &str,
+ action: &str,
+) -> Result<Option<usize>, BrowserRefusal> {
+ let matches = nodes
+ .iter()
+ .filter(|node| node.role == role && field_equals(node, label) && has_action(node, action))
+ .map(|node| node.element_ptr)
+ .collect::<Vec<_>>();
+ match matches.as_slice() {
+ [] => Ok(None),
+ [element] => Ok(Some(*element)),
+ _ => Err(refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ format!("multiple exact {role} controls matched {label:?}"),
+ )),
+ }
+}
+
+fn setup_page_proven(nodes: &[AXNode], descriptor: &BrowserSetupDescriptor) -> bool {
+ let exact_url = nodes.iter().any(|node| {
+ node.role == "AXTextField"
+ && field_equals(node, "Address and search bar")
+ && node
+ .value
+ .as_deref()
+ .is_some_and(|value| value.trim().eq_ignore_ascii_case(descriptor.setup_url))
+ });
+ let exact_page = nodes.iter().any(|node| {
+ node.role == "AXWebArea"
+ && descriptor
+ .page_titles
+ .iter()
+ .any(|title| field_equals(node, title))
+ });
+ let exact_heading = nodes
+ .iter()
+ .any(|node| node.role == "AXHeading" && field_equals(node, descriptor.page_heading));
+ exact_url && exact_page && exact_heading
+}
+
+fn exact_setup_checkbox(
+ nodes: &[AXNode],
+ descriptor: &BrowserSetupDescriptor,
+) -> Result<Option<usize>, BrowserRefusal> {
+ if !setup_page_proven(nodes, descriptor) {
+ return Ok(None);
+ }
+ unique_actionable(nodes, "AXCheckBox", descriptor.checkbox_label, "AXPress")
+}
+
+fn unique_omnibox(
+ nodes: &[AXNode],
+ descriptor: &BrowserSetupDescriptor,
+) -> Result<usize, BrowserRefusal> {
+ unique_actionable(nodes, "AXTextField", "Address and search bar", "AXPress")?.ok_or_else(|| {
+ refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ format!(
+ "the approved {} window has no exact address-and-search field",
+ descriptor.product_name
+ ),
+ )
+ })
+}
+
+fn new_tab_button(
+ nodes: &[AXNode],
+ descriptor: &BrowserSetupDescriptor,
+) -> Result<usize, BrowserRefusal> {
+ unique_actionable(nodes, "AXButton", "New Tab", "AXPress")?.ok_or_else(|| {
+ refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ format!(
+ "the approved {} window has no exact New Tab button",
+ descriptor.product_name
+ ),
+ )
+ })
+}
+
+fn is_same_element(left: usize, right: usize) -> bool {
+ unsafe { CFEqual(left as CFTypeRef, right as CFTypeRef) != 0 }
+}
+
+fn select_new_tab_close_button(
+ before: &[AXNode],
+ after: &[AXNode],
+ same_element: impl Fn(usize, usize) -> bool,
+ descriptor: &BrowserSetupDescriptor,
+) -> Result<Option<usize>, BrowserRefusal> {
+ let prior_tabs = before
+ .iter()
+ .filter(|node| node.role == "AXRadioButton" && node.element_index.is_some())
+ .map(|node| node.element_ptr)
+ .collect::<Vec<_>>();
+ let new_tabs = after
+ .iter()
+ .enumerate()
+ .filter(|(_, node)| {
+ node.role == "AXRadioButton"
+ && node.element_index.is_some()
+ && !prior_tabs
+ .iter()
+ .any(|prior| same_element(*prior, node.element_ptr))
+ })
+ .collect::<Vec<_>>();
+ let (tab_index, tab) = match new_tabs.as_slice() {
+ [(index, tab)] => (*index, *tab),
+ [] => return Ok(None),
+ _ => {
+ return Err(refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ format!(
+ "{} exposed multiple new tab candidates",
+ descriptor.product_name
+ ),
+ ))
+ }
+ };
+ let end = after
+ .iter()
+ .enumerate()
+ .skip(tab_index + 1)
+ .find(|(_, node)| node.depth <= tab.depth)
+ .map_or(after.len(), |(index, _)| index);
+ let close_buttons = after[tab_index + 1..end]
+ .iter()
+ .filter(|node| {
+ node.role == "AXButton"
+ && descriptor
+ .tab_close_labels
+ .iter()
+ .any(|label| field_equals(node, label))
+ && has_action(node, "AXPress")
+ })
+ .map(|node| node.element_ptr)
+ .collect::<Vec<_>>();
+ match close_buttons.as_slice() {
+ [element] => Ok(Some(*element)),
+ [] => Err(refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ format!(
+ "the newly created {} tab has no exact Close button",
+ descriptor.product_name
+ ),
+ )),
+ _ => Err(refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ format!(
+ "the newly created {} tab has multiple Close buttons",
+ descriptor.product_name
+ ),
+ )),
+ }
+}
+
+fn new_tab_close_button(
+ before: &[AXNode],
+ after: &[AXNode],
+ descriptor: &BrowserSetupDescriptor,
+) -> Result<Option<usize>, BrowserRefusal> {
+ let element = select_new_tab_close_button(before, after, is_same_element, descriptor)?;
+ if let Some(element) = element {
+ unsafe { CFRetain(element as CFTypeRef) };
+ }
+ Ok(element)
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum CheckboxState {
+ Off,
+ On,
+}
+
+fn checkbox_state(value: Option<f64>) -> Result<CheckboxState, BrowserRefusal> {
+ match value {
+ Some(value) if value.abs() < f64::EPSILON => Ok(CheckboxState::Off),
+ Some(value) if (value - 1.0).abs() < f64::EPSILON => Ok(CheckboxState::On),
+ _ => Err(refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ "the exact remote-debugging checkbox had an unknown checked state",
+ )),
+ }
+}
+
+pub struct SetupUiHandle {
+ descriptor: &'static BrowserSetupDescriptor,
+ close_button: Option<usize>,
+ enable_attempted: bool,
+ trusted_checkbox_fallback_attempted: bool,
+ pub opened_setup_page: bool,
+ pub enabled_remote_debugging: bool,
+ pub focused_setup_address_field: bool,
+ pub foregrounded_window: bool,
+ pub injected_global_input: bool,
+}
+
+impl SetupUiHandle {
+ fn rollback_remote_debugging(&mut self, pid: i32, window_id: u32) -> bool {
+ if !self.enabled_remote_debugging {
+ return true;
+ }
+ let deadline = Instant::now() + Duration::from_secs(2);
+ let mut pressed_rollback = false;
+ let mut trusted_fallback_attempted = false;
+ loop {
+ let tree = walk_tree(pid, Some(window_id), None);
+ let checkbox = exact_setup_checkbox(&tree.nodes, self.descriptor);
+ let result = match checkbox {
+ Ok(Some(element)) => {
+ let value = unsafe { copy_number_attr(element as AXUIElementRef, "AXValue") };
+ match checkbox_state(value) {
+ Ok(CheckboxState::Off) => Some(true),
+ Ok(CheckboxState::On) => {
+ if !pressed_rollback {
+ let pressed =
+ unsafe { perform_action(element as AXUIElementRef, "AXPress") };
+ if pressed == kAXErrorSuccess {
+ pressed_rollback = true;
+ None
+ } else {
+ Some(false)
+ }
+ } else if self.descriptor.product == BrowserProduct::MicrosoftEdge
+ && !trusted_fallback_attempted
+ {
+ let center =
+ unsafe { element_screen_center(element as AXUIElementRef) };
+ trusted_fallback_attempted = true;
+ release_actionable_nodes(&tree.nodes);
+ let Some((x, y)) = center else {
+ return false;
+ };
+ self.foregrounded_window = true;
+ self.injected_global_input = true;
+ let restored = crate::input::skylight::with_foreground_assist(
+ pid,
+ window_id,
+ || {
+ std::thread::sleep(Duration::from_millis(60));
+ if crate::apps::frontmost_pid() != Some(pid) {
+ anyhow::bail!(
+ "the approved browser lost foreground before the rollback click"
+ );
+ }
+ crate::input::mouse::click_at_xy_desktop_preserving_cursor(
+ x, y,
+ )?;
+ std::thread::sleep(Duration::from_millis(60));
+ Ok(())
+ },
+ )
+ .unwrap_or(false);
+ if !restored {
+ return false;
+ }
+ std::thread::sleep(Duration::from_millis(100));
+ continue;
+ } else {
+ None
+ }
+ }
+ Err(_) => Some(false),
+ }
+ }
+ Ok(None) => None,
+ Err(_) => Some(false),
+ };
+ release_actionable_nodes(&tree.nodes);
+ if let Some(done) = result {
+ if done {
+ self.enabled_remote_debugging = false;
+ }
+ return done;
+ }
+ if Instant::now() >= deadline {
+ return false;
+ }
+ std::thread::sleep(Duration::from_millis(100));
+ }
+ }
+
+ pub fn abort(mut self, pid: i32, window_id: u32, error: BrowserRefusal) -> BrowserRefusal {
+ let enabled_remote_debugging = self.enabled_remote_debugging;
+ let restored_remote_debugging = self.rollback_remote_debugging(pid, window_id);
+ let opened_setup_page = self.opened_setup_page;
+ let focused_setup_address_field = self.focused_setup_address_field;
+ let foregrounded_window = self.foregrounded_window;
+ let injected_global_input = self.injected_global_input;
+ let closed_setup_page = self.close().unwrap_or(false);
+ let mut error = error;
+ let cause = error.detail.take();
+ error.with_detail(serde_json::json!({
+ "setup_side_effects": {
+ "opened_setup_page": opened_setup_page,
+ "closed_setup_page": closed_setup_page,
+ "focused_setup_address_field": focused_setup_address_field,
+ "enabled_remote_debugging": enabled_remote_debugging,
+ "foregrounded_window": foregrounded_window,
+ "injected_global_input": injected_global_input,
+ "restored_remote_debugging": restored_remote_debugging,
+ },
+ "cause": cause,
+ }))
+ }
+
+ pub fn close_for_success(
+ mut self,
+ pid: i32,
+ window_id: u32,
+ ) -> Result<Option<bool>, BrowserRefusal> {
+ let Some(element) = self.close_button.take() else {
+ return Ok(None);
+ };
+ let result = unsafe { perform_action(element as AXUIElementRef, "AXPress") };
+ unsafe { CFRelease(element as CFTypeRef) };
+ if result == kAXErrorSuccess {
+ return Ok(Some(true));
+ }
+ let product_name = self.descriptor.product_name;
+ Err(self.abort(
+ pid,
+ window_id,
+ refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ format!(
+ "{}'s exact temporary-tab Close action became stale before AXPress",
+ product_name
+ ),
+ ),
+ ))
+ }
+
+ /// Close the temporary setup tab. `None` means the approved window was
+ /// already displaying the exact setup page and no tab was opened.
+ pub fn close(mut self) -> Option<bool> {
+ let element = self.close_button.take()?;
+ let result = unsafe { perform_action(element as AXUIElementRef, "AXPress") };
+ unsafe { CFRelease(element as CFTypeRef) };
+ Some(result == kAXErrorSuccess)
+ }
+}
+
+impl Drop for SetupUiHandle {
+ fn drop(&mut self) {
+ if let Some(element) = self.close_button.take() {
+ let _ = unsafe { perform_action(element as AXUIElementRef, "AXPress") };
+ unsafe { CFRelease(element as CFTypeRef) };
+ }
+ }
+}
+
+type PendingSetupKey = (i32, u32);
+
+fn pending_setups() -> &'static Mutex<HashMap<PendingSetupKey, SetupUiHandle>> {
+ static PENDING: OnceLock<Mutex<HashMap<PendingSetupKey, SetupUiHandle>>> = OnceLock::new();
+ PENDING.get_or_init(|| Mutex::new(HashMap::new()))
+}
+
+pub fn retain_pending(
+ pid: i32,
+ window_id: u32,
+ handle: SetupUiHandle,
+) -> Result<(), BrowserRefusal> {
+ let mut pending = pending_setups().lock().unwrap();
+ if pending.contains_key(&(pid, window_id)) {
+ drop(pending);
+ return Err(handle.abort(
+ pid,
+ window_id,
+ refusal(
+ BrowserRefusalCode::BrowserBindingAmbiguous,
+ "another approved browser setup is already pending for this exact window",
+ ),
+ ));
+ }
+ pending.insert((pid, window_id), handle);
+ Ok(())
+}
+
+pub fn commit_pending(pid: i32, window_id: u32) -> Result<bool, BrowserRefusal> {
+ let handle = pending_setups()
+ .lock()
+ .unwrap()
+ .remove(&(pid, window_id))
+ .ok_or_else(|| {
+ refusal(
+ BrowserRefusalCode::BrowserBindingStale,
+ "the exact pending browser setup cleanup handle is missing",
+ )
+ })?;
+ Ok(handle.close_for_success(pid, window_id)?.unwrap_or(false))
+}
+
+pub fn abort_pending(pid: i32, window_id: u32, error: BrowserRefusal) -> BrowserRefusal {
+ match pending_setups().lock().unwrap().remove(&(pid, window_id)) {
+ Some(handle) => handle.abort(pid, window_id, error),
+ None => error.with_detail(serde_json::json!({
+ "setup_cleanup": "the exact pending browser setup cleanup handle was missing"
+ })),
+ }
+}
+
+pub fn enable(
+ pid: i32,
+ window_id: u32,
+ descriptor: &'static BrowserSetupDescriptor,
+) -> Result<SetupUiHandle, BrowserRefusal> {
+ let initial = walk_tree(pid, Some(window_id), None);
+ let initial_checkbox = exact_setup_checkbox(&initial.nodes, descriptor);
+ let mut handle = match initial_checkbox {
+ Ok(Some(_)) => SetupUiHandle {
+ descriptor,
+ close_button: None,
+ enable_attempted: false,
+ trusted_checkbox_fallback_attempted: false,
+ opened_setup_page: false,
+ enabled_remote_debugging: false,
+ focused_setup_address_field: false,
+ foregrounded_window: false,
+ injected_global_input: false,
+ },
+ Ok(None) => {
+ let new_tab = new_tab_button(&initial.nodes, descriptor);
+ let new_tab = match new_tab {
+ Ok(element) => element,
+ Err(error) => {
+ release_actionable_nodes(&initial.nodes);
+ return Err(error);
+ }
+ };
+ let pressed = unsafe { perform_action(new_tab as AXUIElementRef, "AXPress") };
+ if pressed != kAXErrorSuccess {
+ release_actionable_nodes(&initial.nodes);
+ return Err(refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ format!(
+ "{}'s exact New Tab action became stale before AXPress",
+ descriptor.product_name
+ ),
+ ));
+ }
+ let deadline = Instant::now() + Duration::from_secs(2);
+ let (created, close_button) = loop {
+ let created = walk_tree(pid, Some(window_id), None);
+ match new_tab_close_button(&initial.nodes, &created.nodes, descriptor) {
+ Ok(Some(element)) => break (created, element),
+ Ok(None) if Instant::now() < deadline => {
+ release_actionable_nodes(&created.nodes);
+ std::thread::sleep(Duration::from_millis(100));
+ }
+ Ok(None) => {
+ release_actionable_nodes(&initial.nodes);
+ release_actionable_nodes(&created.nodes);
+ return Err(refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ format!(
+ "{} did not expose exactly one newly created tab",
+ descriptor.product_name
+ ),
+ )
+ .with_detail(serde_json::json!({
+ "setup_side_effects": {
+ "opened_setup_page": "unknown",
+ "closed_setup_page": false,
+ "enabled_remote_debugging": false,
+ }
+ })));
+ }
+ Err(error) => {
+ release_actionable_nodes(&initial.nodes);
+ release_actionable_nodes(&created.nodes);
+ return Err(error.with_detail(serde_json::json!({
+ "setup_side_effects": {
+ "opened_setup_page": "unknown",
+ "closed_setup_page": false,
+ "enabled_remote_debugging": false,
+ }
+ })));
+ }
+ }
+ };
+ release_actionable_nodes(&initial.nodes);
+ let mut handle = SetupUiHandle {
+ descriptor,
+ close_button: Some(close_button),
+ enable_attempted: false,
+ trusted_checkbox_fallback_attempted: false,
+ opened_setup_page: true,
+ enabled_remote_debugging: false,
+ focused_setup_address_field: false,
+ foregrounded_window: false,
+ injected_global_input: false,
+ };
+ let omnibox = unique_omnibox(&created.nodes, descriptor);
+ let omnibox = match omnibox {
+ Ok(element) => element,
+ Err(error) => {
+ release_actionable_nodes(&created.nodes);
+ return Err(handle.abort(pid, window_id, error));
+ }
+ };
+ let pressed = unsafe { perform_action(omnibox as AXUIElementRef, "AXPress") };
+ let focused = unsafe { set_bool_attr_true(omnibox as AXUIElementRef, "AXFocused") };
+ if pressed != kAXErrorSuccess || focused != kAXErrorSuccess {
+ release_actionable_nodes(&created.nodes);
+ return Err(handle.abort(
+ pid,
+ window_id,
+ refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ format!(
+ "{}'s exact address field rejected the bounded setup navigation",
+ descriptor.product_name
+ ),
+ ),
+ ));
+ }
+ handle.focused_setup_address_field = true;
+ let exact_focus = unsafe {
+ focused_element_of_pid(pid).is_some_and(|focused_element| {
+ let equal = is_same_element(focused_element as usize, omnibox);
+ CFRelease(focused_element as CFTypeRef);
+ equal
+ })
+ };
+ if !exact_focus {
+ release_actionable_nodes(&created.nodes);
+ return Err(handle.abort(pid, window_id, refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ format!(
+ "{}'s exact address field lost focus before setup navigation could be confirmed",
+ descriptor.product_name
+ ),
+ )));
+ }
+ if let Err(error) = crate::input::keyboard::hotkey(pid, "a", &["cmd"]).and_then(|_| {
+ crate::input::keyboard::type_text_with_delay(pid, descriptor.setup_url, 30)
+ }) {
+ release_actionable_nodes(&created.nodes);
+ return Err(handle.abort(
+ pid,
+ window_id,
+ refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ format!(
+ "could not type {}'s fixed setup URL into the exact address field: {error}",
+ descriptor.product_name
+ ),
+ ),
+ ));
+ }
+ let exact_value = unsafe { copy_string_attr(omnibox as AXUIElementRef, "AXValue") }
+ .is_some_and(|value| value.trim().eq_ignore_ascii_case(descriptor.setup_url));
+ if !exact_value {
+ release_actionable_nodes(&created.nodes);
+ return Err(handle.abort(
+ pid,
+ window_id,
+ refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ format!(
+ "{}'s exact address field did not retain the fixed setup URL",
+ descriptor.product_name
+ ),
+ ),
+ ));
+ }
+ let navigation = if descriptor.product == BrowserProduct::MicrosoftEdge {
+ handle.foregrounded_window = true;
+ handle.injected_global_input = true;
+ crate::input::skylight::with_foreground_assist(pid, window_id, || {
+ std::thread::sleep(Duration::from_millis(60));
+ if crate::apps::frontmost_pid() != Some(pid) {
+ anyhow::bail!(
+ "the approved browser lost foreground before setup navigation"
+ );
+ }
+ crate::input::keyboard::press_key_global("return", &[])?;
+ std::thread::sleep(Duration::from_millis(60));
+ Ok(())
+ })
+ .and_then(|fronted| {
+ if fronted {
+ Ok(())
+ } else {
+ Err(anyhow::anyhow!(
+ "the bounded Microsoft Edge foreground assist was unavailable"
+ ))
+ }
+ })
+ } else {
+ crate::input::keyboard::press_key(pid, "return", &[])
+ };
+ release_actionable_nodes(&created.nodes);
+ if let Err(error) = navigation {
+ return Err(handle.abort(
+ pid,
+ window_id,
+ refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ format!(
+ "could not confirm {}'s bounded setup navigation: {error}",
+ descriptor.product_name
+ ),
+ ),
+ ));
+ }
+ handle
+ }
+ Err(error) => {
+ release_actionable_nodes(&initial.nodes);
+ return Err(error);
+ }
+ };
+ if !handle.opened_setup_page {
+ release_actionable_nodes(&initial.nodes);
+ }
+
+ let deadline = Instant::now() + EXISTING_PROFILE_SETUP_READY_TIMEOUT;
+ loop {
+ let tree = walk_tree(pid, Some(window_id), None);
+ let checkbox = exact_setup_checkbox(&tree.nodes, descriptor);
+ match checkbox {
+ Ok(Some(element)) => {
+ let value = unsafe { copy_number_attr(element as AXUIElementRef, "AXValue") };
+ match checkbox_state(value) {
+ Ok(CheckboxState::On) => {
+ if handle.enable_attempted {
+ handle.enabled_remote_debugging = true;
+ }
+ release_actionable_nodes(&tree.nodes);
+ return Ok(handle);
+ }
+ Ok(CheckboxState::Off) => {
+ if !handle.enable_attempted {
+ handle.enable_attempted = true;
+ let pressed =
+ unsafe { perform_action(element as AXUIElementRef, "AXPress") };
+ release_actionable_nodes(&tree.nodes);
+ if pressed != kAXErrorSuccess {
+ return Err(handle.abort(pid, window_id, refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ "the exact remote-debugging checkbox became stale before AXPress",
+ )));
+ }
+ continue;
+ }
+
+ if descriptor.product == BrowserProduct::MicrosoftEdge
+ && !handle.trusted_checkbox_fallback_attempted
+ {
+ let center =
+ unsafe { element_screen_center(element as AXUIElementRef) };
+ handle.trusted_checkbox_fallback_attempted = true;
+ release_actionable_nodes(&tree.nodes);
+ let Some((x, y)) = center else {
+ return Err(handle.abort(
+ pid,
+ window_id,
+ refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ "the exact remote-debugging checkbox had no stable screen center",
+ ),
+ ));
+ };
+ handle.foregrounded_window = true;
+ handle.injected_global_input = true;
+ let clicked = crate::input::skylight::with_foreground_assist(
+ pid,
+ window_id,
+ || {
+ std::thread::sleep(Duration::from_millis(60));
+ if crate::apps::frontmost_pid() != Some(pid) {
+ anyhow::bail!(
+ "the approved browser lost foreground before the setup click"
+ );
+ }
+ crate::input::mouse::click_at_xy_desktop_preserving_cursor(x, y)?;
+ std::thread::sleep(Duration::from_millis(60));
+ Ok(())
+ },
+ )
+ .and_then(|fronted| {
+ if fronted {
+ Ok(())
+ } else {
+ Err(anyhow::anyhow!(
+ "the bounded Microsoft Edge foreground assist was unavailable"
+ ))
+ }
+ });
+ if let Err(error) = clicked {
+ return Err(handle.abort(
+ pid,
+ window_id,
+ refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ format!(
+ "could not toggle the exact Microsoft Edge remote-debugging checkbox: {error}"
+ ),
+ ),
+ ));
+ }
+ continue;
+ }
+
+ release_actionable_nodes(&tree.nodes);
+ }
+ Err(error) => {
+ release_actionable_nodes(&tree.nodes);
+ return Err(handle.abort(pid, window_id, error));
+ }
+ }
+ }
+ Ok(None) => release_actionable_nodes(&tree.nodes),
+ Err(error) => {
+ release_actionable_nodes(&tree.nodes);
+ return Err(handle.abort(pid, window_id, error));
+ }
+ }
+ if Instant::now() >= deadline {
+ return Err(handle.abort(
+ pid,
+ window_id,
+ refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ format!(
+ "the exact {} remote-debugging setup page did not become ready",
+ descriptor.product_name
+ ),
+ ),
+ ));
+ }
+ std::thread::sleep(Duration::from_millis(100));
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use cua_driver_core::browser::{existing_profile_setup_descriptor, BrowserProduct};
+
+ fn chrome() -> &'static BrowserSetupDescriptor {
+ existing_profile_setup_descriptor(BrowserProduct::GoogleChrome).unwrap()
+ }
+
+ fn node(role: &str, title: Option<&str>, value: Option<&str>, actions: &[&str]) -> AXNode {
+ AXNode {
+ element_index: (!actions.is_empty()).then_some(0),
+ role: role.to_owned(),
+ title: title.map(str::to_owned),
+ value: value.map(str::to_owned),
+ description: None,
+ identifier: None,
+ help: None,
+ actions: actions.iter().map(|value| (*value).to_owned()).collect(),
+ element_ptr: 7,
+ depth: 0,
+ parent_element_index: None,
+ frame: None,
+ }
+ }
+
+ fn tree_node(role: &str, title: Option<&str>, pointer: usize, depth: usize) -> AXNode {
+ let mut node = node(role, title, None, &["AXPress"]);
+ node.element_ptr = pointer;
+ node.depth = depth;
+ node
+ }
+
+ #[test]
+ fn checkbox_requires_exact_internal_page_proof() {
+ let nodes = vec![
+ node("AXWebArea", Some(chrome().page_titles[0]), None, &[]),
+ node("AXHeading", Some(chrome().page_heading), None, &[]),
+ node(
+ "AXTextField",
+ Some("Address and search bar"),
+ Some(chrome().setup_url),
+ &["AXPress"],
+ ),
+ node(
+ "AXCheckBox",
+ Some(chrome().checkbox_label),
+ None,
+ &["AXPress"],
+ ),
+ ];
+ assert_eq!(exact_setup_checkbox(&nodes, chrome()).unwrap(), Some(7));
+
+ let mut wrong_url = nodes.clone();
+ wrong_url[2].value = Some("https://example.test/".to_owned());
+ assert_eq!(exact_setup_checkbox(&wrong_url, chrome()).unwrap(), None);
+ }
+
+ #[test]
+ fn checkbox_matcher_refuses_ambiguity() {
+ let nodes = vec![
+ node("AXWebArea", Some(chrome().page_titles[0]), None, &[]),
+ node("AXHeading", Some(chrome().page_heading), None, &[]),
+ node(
+ "AXTextField",
+ Some("Address and search bar"),
+ Some(chrome().setup_url),
+ &["AXPress"],
+ ),
+ node(
+ "AXCheckBox",
+ Some(chrome().checkbox_label),
+ None,
+ &["AXPress"],
+ ),
+ node(
+ "AXCheckBox",
+ Some(chrome().checkbox_label),
+ None,
+ &["AXPress"],
+ ),
+ ];
+ assert_eq!(
+ exact_setup_checkbox(&nodes, chrome()).unwrap_err().code,
+ BrowserRefusalCode::BrowserWrongTargetRefused
+ );
+ }
+
+ #[test]
+ fn new_tab_cleanup_selects_only_the_new_tabs_close_control() {
+ let before = vec![
+ tree_node("AXRadioButton", Some("Original"), 10, 1),
+ tree_node("AXButton", Some("Close"), 11, 2),
+ ];
+ let after = vec![
+ tree_node("AXRadioButton", Some("Original"), 10, 1),
+ tree_node("AXButton", Some("Close"), 11, 2),
+ tree_node("AXRadioButton", Some("New Tab"), 20, 1),
+ tree_node("AXButton", Some("Close"), 21, 2),
+ ];
+ assert_eq!(
+ select_new_tab_close_button(&before, &after, |left, right| left == right, chrome(),)
+ .unwrap(),
+ Some(21)
+ );
+ }
+
+ #[test]
+ fn new_tab_cleanup_refuses_multiple_new_tabs() {
+ let before = vec![tree_node("AXRadioButton", Some("Original"), 10, 1)];
+ let after = vec![
+ tree_node("AXRadioButton", Some("Original"), 10, 1),
+ tree_node("AXRadioButton", Some("New Tab"), 20, 1),
+ tree_node("AXButton", Some("Close"), 21, 2),
+ tree_node("AXRadioButton", Some("Another"), 30, 1),
+ tree_node("AXButton", Some("Close"), 31, 2),
+ ];
+ assert_eq!(
+ select_new_tab_close_button(&before, &after, |left, right| left == right, chrome(),)
+ .unwrap_err()
+ .code,
+ BrowserRefusalCode::BrowserWrongTargetRefused
+ );
+ }
+
+ #[test]
+ fn unknown_checkbox_values_refuse() {
+ assert_eq!(checkbox_state(Some(0.0)).unwrap(), CheckboxState::Off);
+ assert_eq!(checkbox_state(Some(1.0)).unwrap(), CheckboxState::On);
+ assert_eq!(
+ checkbox_state(None).unwrap_err().code,
+ BrowserRefusalCode::BrowserWrongTargetRefused
+ );
+ assert_eq!(
+ checkbox_state(Some(0.5)).unwrap_err().code,
+ BrowserRefusalCode::BrowserWrongTargetRefused
+ );
+ }
+}
diff --git a/libs/cua-driver/rust/crates/platform-macos/src/input/keyboard.rs b/libs/cua-driver/rust/crates/platform-macos/src/input/keyboard.rs
index aeb7a288f0..775203884d 100644
--- a/libs/cua-driver/rust/crates/platform-macos/src/input/keyboard.rs
+++ b/libs/cua-driver/rust/crates/platform-macos/src/input/keyboard.rs
@@ -17,7 +17,7 @@ pub fn press_key(pid: i32, key: &str, modifiers: &[&str]) -> anyhow::Result<()>
if key == "+" || key.to_lowercase() == "plus" {
let flags = modifier_flags(&["shift"]);
let eq_code = key_name_to_code("=")?;
- post_key(pid, eq_code, true, modifier_flags(modifiers) | flags)?;
+ post_key(pid, eq_code, true, modifier_flags(modifiers) | flags)?;
std::thread::sleep(std::time::Duration::from_millis(8));
post_key(pid, eq_code, false, modifier_flags(modifiers) | flags)?;
return Ok(());
@@ -121,6 +121,31 @@ pub fn press_key_no_auth(pid: i32, key: &str, modifiers: &[&str]) -> anyhow::Res
Ok(())
}
+/// Press and release one key on the global HID queue.
+///
+/// This is reserved for an explicitly approved, bounded foreground assist.
+/// Callers must prove and temporarily activate the exact target window before
+/// invoking it; unlike the PID-routed helpers above, the HID queue itself has
+/// no process addressing.
+pub fn press_key_global(key: &str, modifiers: &[&str]) -> anyhow::Result<()> {
+ use core_graphics::event::CGEventTapLocation;
+
+ let key_code = key_name_to_code(key)?;
+ let flags = modifier_flags(modifiers);
+ let source = CGEventSource::new(CGEventSourceStateID::HIDSystemState)
+ .map_err(|_| anyhow::anyhow!("CGEventSource::new failed"))?;
+ let down = CGEvent::new_keyboard_event(source.clone(), key_code, true)
+ .map_err(|_| anyhow::anyhow!("CGEvent keyboard down failed"))?;
+ down.set_flags(flags);
+ down.post(CGEventTapLocation::HID);
+ std::thread::sleep(std::time::Duration::from_millis(8));
+ let up = CGEvent::new_keyboard_event(source, key_code, false)
+ .map_err(|_| anyhow::anyhow!("CGEvent keyboard up failed"))?;
+ up.set_flags(flags);
+ up.post(CGEventTapLocation::HID);
+ Ok(())
+}
+
/// Post a keyboard event to `pid` via SLEventPostToPid (with auth message for
/// Chromium/Electron support) or fall back to CGEvent::post_to_pid.
fn post_keyboard_event(pid: i32, event: &CGEvent) {
@@ -144,7 +169,12 @@ fn post_key(pid: i32, key_code: u16, key_down: bool, flags: CGEventFlags) -> any
Ok(())
}
-fn post_key_no_auth(pid: i32, key_code: u16, key_down: bool, flags: CGEventFlags) -> anyhow::Result<()> {
+fn post_key_no_auth(
+ pid: i32,
+ key_code: u16,
+ key_down: bool,
+ flags: CGEventFlags,
+) -> anyhow::Result<()> {
let source = CGEventSource::new(CGEventSourceStateID::HIDSystemState)
.map_err(|_| anyhow::anyhow!("CGEventSource::new failed"))?;
let event = CGEvent::new_keyboard_event(source, key_code, key_down)
@@ -195,15 +225,65 @@ fn key_name_to_code(key: &str) -> anyhow::Result<u16> {
"right" | "right_arrow" => 124,
"down" | "down_arrow" => 125,
"up" | "up_arrow" => 126,
- "f1" => 122, "f2" => 120, "f3" => 99, "f4" => 118, "f5" => 96,
- "f6" => 97, "f7" => 98, "f8" => 100, "f9" => 101, "f10" => 109,
- "f11" => 103, "f12" => 111,
- "a" => 0, "s" => 1, "d" => 2, "f" => 3, "h" => 4, "g" => 5, "z" => 6, "x" => 7,
- "c" => 8, "v" => 9, "b" => 11, "q" => 12, "w" => 13, "e" => 14, "r" => 15, "y" => 16,
- "t" => 17, "1" => 18, "2" => 19, "3" => 20, "4" => 21, "6" => 22, "5" => 23, "=" => 24,
- "9" => 25, "7" => 26, "-" => 27, "8" => 28, "0" => 29, "]" => 30, "o" => 31, "u" => 32,
- "[" => 33, "i" => 34, "p" => 35, "l" => 37, "j" => 38, "'" => 39, "k" => 40, ";" => 41,
- "\\" => 42, "," => 43, "/" => 44, "n" => 45, "m" => 46, "." => 47, "`" => 50,
+ "f1" => 122,
+ "f2" => 120,
+ "f3" => 99,
+ "f4" => 118,
+ "f5" => 96,
+ "f6" => 97,
+ "f7" => 98,
+ "f8" => 100,
+ "f9" => 101,
+ "f10" => 109,
+ "f11" => 103,
+ "f12" => 111,
+ "a" => 0,
+ "s" => 1,
+ "d" => 2,
+ "f" => 3,
+ "h" => 4,
+ "g" => 5,
+ "z" => 6,
+ "x" => 7,
+ "c" => 8,
+ "v" => 9,
+ "b" => 11,
+ "q" => 12,
+ "w" => 13,
+ "e" => 14,
+ "r" => 15,
+ "y" => 16,
+ "t" => 17,
+ "1" => 18,
+ "2" => 19,
+ "3" => 20,
+ "4" => 21,
+ "6" => 22,
+ "5" => 23,
+ "=" => 24,
+ "9" => 25,
+ "7" => 26,
+ "-" => 27,
+ "8" => 28,
+ "0" => 29,
+ "]" => 30,
+ "o" => 31,
+ "u" => 32,
+ "[" => 33,
+ "i" => 34,
+ "p" => 35,
+ "l" => 37,
+ "j" => 38,
+ "'" => 39,
+ "k" => 40,
+ ";" => 41,
+ "\\" => 42,
+ "," => 43,
+ "/" => 44,
+ "n" => 45,
+ "m" => 46,
+ "." => 47,
+ "`" => 50,
_ => anyhow::bail!("Unknown key name: {key}"),
};
Ok(code)
diff --git a/libs/cua-driver/rust/crates/platform-macos/src/input/mouse.rs b/libs/cua-driver/rust/crates/platform-macos/src/input/mouse.rs
index 83a01a78a1..0726951522 100644
--- a/libs/cua-driver/rust/crates/platform-macos/src/input/mouse.rs
+++ b/libs/cua-driver/rust/crates/platform-macos/src/input/mouse.rs
@@ -87,6 +87,25 @@ pub fn click_at_xy_desktop(x: f64, y: f64, count: usize, button: &str) -> anyhow
Ok(())
}
+/// Click one exact desktop point, then restore the user's cursor position.
+///
+/// This is intentionally narrower than the public desktop click path. It is
+/// used only by approved, bounded setup flows after an accessibility element
+/// has proven the exact target point and window.
+pub fn click_at_xy_desktop_preserving_cursor(x: f64, y: f64) -> anyhow::Result<()> {
+ use core_graphics::display::CGDisplay;
+
+ let source = CGEventSource::new(CGEventSourceStateID::HIDSystemState)
+ .map_err(|_| anyhow::anyhow!("CGEventSource::new failed"))?;
+ let prior = CGEvent::new(source)
+ .map_err(|_| anyhow::anyhow!("CGEvent::new failed"))?
+ .location();
+ let result = click_at_xy_desktop(x, y, 1, "left");
+ let _ = CGDisplay::warp_mouse_cursor_position(prior);
+ unsafe { CGAssociateMouseAndMouseCursorPosition(true) };
+ result
+}
+
extern "C" {
/// Reconnect the mouse-delta stream to the (just-warped) cursor position so a
/// synthesized click hit-tests at the new location, not the pre-warp one.
@@ -929,15 +948,9 @@ pub fn scroll_wheel_at_xy(
// into a bounded line delta for the event API.
let wheel_y = (delta_y_per_tick / 120).clamp(-10, 10);
let wheel_x = (delta_x_per_tick / 120).clamp(-10, 10);
- let event = CGEvent::new_scroll_event(
- source,
- ScrollEventUnit::LINE,
- 2,
- wheel_y,
- wheel_x,
- 0,
- )
- .map_err(|_| anyhow::anyhow!("CGEvent::new_scroll_event failed"))?;
+ let event =
+ CGEvent::new_scroll_event(source, ScrollEventUnit::LINE, 2, wheel_y, wheel_x, 0)
+ .map_err(|_| anyhow::anyhow!("CGEvent::new_scroll_event failed"))?;
let event_ptr = event.as_ptr() as *mut std::ffi::c_void;
diff --git a/libs/cua-driver/rust/crates/platform-windows/src/browser_consent_ui.rs b/libs/cua-driver/rust/crates/platform-windows/src/browser_consent_ui.rs
new file mode 100644
index 0000000000..e30e607cf9
--- /dev/null
+++ b/libs/cua-driver/rust/crates/platform-windows/src/browser_consent_ui.rs
@@ -0,0 +1,257 @@
+//! Exact Windows UIA handling for Chromium's browser-owned debugging consent.
+
+use std::time::{Duration, Instant};
+
+use cua_driver_core::browser::{
+ BrowserConsentOutcome, BrowserConsentRequest, BrowserRefusal, BrowserRefusalCode,
+};
+use windows::core::Interface;
+use windows::Win32::Foundation::HWND;
+use windows::Win32::UI::Accessibility::{
+ IUIAutomationElement, IUIAutomationInvokePattern, UIA_InvokePatternId,
+};
+use windows::Win32::UI::WindowsAndMessaging::GetWindowThreadProcessId;
+
+use crate::uia::UiaNode;
+
+fn refusal(code: BrowserRefusalCode, message: impl Into<String>) -> BrowserRefusal {
+ BrowserRefusal::new(code, message)
+}
+
+fn normalized_text(node: &UiaNode) -> String {
+ [
+ node.name.as_deref(),
+ node.value.as_deref(),
+ node.automation_id.as_deref(),
+ node.help_text.as_deref(),
+ ]
+ .into_iter()
+ .flatten()
+ .collect::<Vec<_>>()
+ .join(" ")
+ .trim()
+ .to_ascii_lowercase()
+}
+
+fn release_nodes(nodes: &[UiaNode]) {
+ for node in nodes.iter().filter(|node| node.element_ptr != 0) {
+ unsafe { drop(IUIAutomationElement::from_raw(node.element_ptr as *mut _)) };
+ }
+}
+
+fn is_in_web_content(nodes: &[UiaNode], node: &UiaNode) -> bool {
+ let mut parent = node.parent_element_index;
+ for _ in 0..nodes.len() {
+ let Some(parent_index) = parent else {
+ return false;
+ };
+ let Some(parent_node) = nodes
+ .iter()
+ .find(|candidate| candidate.element_index == Some(parent_index))
+ else {
+ return false;
+ };
+ if parent_node.control_type.eq_ignore_ascii_case("Document") {
+ return true;
+ }
+ parent = parent_node.parent_element_index;
+ }
+ true
+}
+
+fn trusted_prompt_nodes(nodes: &[UiaNode]) -> impl Iterator<Item = &UiaNode> {
+ nodes.iter().filter(|node| {
+ !node.in_web_content
+ && !node.control_type.eq_ignore_ascii_case("Document")
+ && !is_in_web_content(nodes, node)
+ })
+}
+
+fn remote_debugging_prompt_present(nodes: &[UiaNode]) -> bool {
+ let has_title =
+ trusted_prompt_nodes(nodes).any(|node| normalized_text(node) == "allow remote debugging?");
+ let body = trusted_prompt_nodes(nodes)
+ .map(normalized_text)
+ .collect::<Vec<_>>()
+ .join(" ");
+ has_title
+ && body.contains("external app wants full control")
+ && body.contains("saved data, cookies and site data")
+ && body.contains("navigate to any url")
+}
+
+fn exact_allow_button(nodes: &[UiaNode]) -> Result<Option<usize>, BrowserRefusal> {
+ if !remote_debugging_prompt_present(nodes) {
+ return Ok(None);
+ }
+ let matches = trusted_prompt_nodes(nodes)
+ .filter(|node| {
+ node.control_type == "Button"
+ && normalized_text(node) == "allow"
+ && node.actions.iter().any(|action| action == "invoke")
+ && node.element_ptr != 0
+ })
+ .map(|node| node.element_ptr)
+ .collect::<Vec<_>>();
+ match matches.as_slice() {
+ [] => Ok(None),
+ [element] => Ok(Some(*element)),
+ _ => Err(refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ "multiple exact Allow actions matched the browser consent prompt",
+ )),
+ }
+}
+
+unsafe fn invoke(element_ptr: usize) -> Result<(), BrowserRefusal> {
+ let element = IUIAutomationElement::from_raw(element_ptr as *mut _);
+ let result = element
+ .GetCurrentPattern(UIA_InvokePatternId)
+ .and_then(|pattern| pattern.cast::<IUIAutomationInvokePattern>())
+ .and_then(|pattern| pattern.Invoke());
+ std::mem::forget(element);
+ result.map_err(|error| {
+ refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ format!("the exact browser consent action failed: {error}"),
+ )
+ })
+}
+
+fn prove_window_owner(hwnd: u64, pid: u32) -> Result<(), BrowserRefusal> {
+ let mut owner = 0u32;
+ unsafe { GetWindowThreadProcessId(HWND(hwnd as *mut _), Some(&mut owner)) };
+ if owner != pid {
+ return Err(refusal(
+ BrowserRefusalCode::BrowserBindingStale,
+ "the approved browser window changed ownership before consent",
+ ));
+ }
+ Ok(())
+}
+
+pub async fn handle(
+ request: BrowserConsentRequest,
+) -> Result<BrowserConsentOutcome, BrowserRefusal> {
+ let pid = u32::try_from(request.pid).map_err(|_| {
+ refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ "the approved browser pid is outside the Windows process-id range",
+ )
+ })?;
+ prove_window_owner(request.window_id, pid)?;
+ let deadline = Instant::now() + Duration::from_secs(4);
+ let mut saw_prompt = false;
+ loop {
+ prove_window_owner(request.window_id, pid)?;
+ let hwnd = request.window_id;
+ let tree = tokio::task::spawn_blocking(move || crate::uia::walk_tree(hwnd, None))
+ .await
+ .map_err(|error| {
+ refusal(
+ BrowserRefusalCode::BrowserRouteUnavailable,
+ format!("could not inspect the browser consent UI: {error}"),
+ )
+ })?;
+ let prompt_present = remote_debugging_prompt_present(&tree.nodes);
+ saw_prompt |= prompt_present;
+ match exact_allow_button(&tree.nodes) {
+ Ok(Some(element)) => {
+ let invoked = unsafe { invoke(element) };
+ release_nodes(&tree.nodes);
+ invoked?;
+ return Ok(BrowserConsentOutcome::Accepted);
+ }
+ Ok(None) => release_nodes(&tree.nodes),
+ Err(error) => {
+ release_nodes(&tree.nodes);
+ return Err(error);
+ }
+ }
+ if saw_prompt && !prompt_present {
+ return Err(refusal(
+ BrowserRefusalCode::BrowserConsentRevoked,
+ "the person dismissed the browser consent prompt",
+ ));
+ }
+ if Instant::now() >= deadline {
+ return Err(refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ format!(
+ "no exact Chromium remote-debugging consent prompt appeared for reconnect attempt {}",
+ request.attempt
+ ),
+ ));
+ }
+ tokio::time::sleep(Duration::from_millis(100)).await;
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn node(control_type: &str, name: &str, actions: &[&str]) -> UiaNode {
+ UiaNode {
+ element_index: (!actions.is_empty()).then_some(0),
+ control_type: control_type.to_owned(),
+ name: Some(name.to_owned()),
+ value: None,
+ automation_id: None,
+ help_text: None,
+ actions: actions.iter().map(|value| (*value).to_owned()).collect(),
+ element_ptr: 7,
+ center_x: 0,
+ center_y: 0,
+ rect: None,
+ msaa_role: None,
+ depth: 0,
+ parent_element_index: None,
+ in_web_content: false,
+ }
+ }
+
+ fn prompt() -> Vec<UiaNode> {
+ vec![
+ node("Text", "Allow remote debugging?", &[]),
+ node(
+ "Text",
+ "An external app wants full control. This includes access to your saved data, cookies and site data, and the ability to navigate to any URL.",
+ &[],
+ ),
+ node("Button", "Cancel", &["invoke"]),
+ node("Button", "Allow", &["invoke"]),
+ ]
+ }
+
+ #[test]
+ fn matcher_requires_exact_security_prompt_and_unique_allow_action() {
+ assert_eq!(exact_allow_button(&prompt()).unwrap(), Some(7));
+ assert_eq!(
+ exact_allow_button(&[node("Button", "Allow", &["invoke"])]).unwrap(),
+ None
+ );
+ }
+
+ #[test]
+ fn matcher_refuses_ambiguous_allow_actions() {
+ let mut nodes = prompt();
+ nodes.push(node("Button", "Allow", &["invoke"]));
+ assert_eq!(
+ exact_allow_button(&nodes).unwrap_err().code,
+ BrowserRefusalCode::BrowserWrongTargetRefused
+ );
+ }
+
+ #[test]
+ fn matcher_ignores_a_spoofed_prompt_inside_web_content() {
+ let mut nodes = prompt();
+ nodes.insert(0, node("Document", "Example page", &[]));
+ nodes[0].element_index = Some(42);
+ for child in &mut nodes[1..] {
+ child.parent_element_index = Some(42);
+ child.in_web_content = true;
+ }
+ assert_eq!(exact_allow_button(&nodes).unwrap(), None);
+ }
+}
diff --git a/libs/cua-driver/rust/crates/platform-windows/src/browser_platform.rs b/libs/cua-driver/rust/crates/platform-windows/src/browser_platform.rs
index e4f1955e34..ca0011c04e 100644
--- a/libs/cua-driver/rust/crates/platform-windows/src/browser_platform.rs
+++ b/libs/cua-driver/rust/crates/platform-windows/src/browser_platform.rs
@@ -4,14 +4,16 @@ use std::process::Stdio;
use std::time::Duration;
use async_trait::async_trait;
+use cua_driver_core::browser::existing_profile_setup_descriptor;
use cua_driver_core::browser::platform::{
- BrowserPlatform, PrepareAction, PrepareOutcome, PrepareRequest,
+ BrowserConsentOutcome, BrowserConsentRequest, BrowserPlatform, ExistingProfileSetupOutcome,
+ ExistingProfileSetupRequest, PrepareAction, PrepareOutcome, PrepareRequest,
};
use cua_driver_core::browser::refusal::{BrowserRefusal, BrowserRefusalCode};
use cua_driver_core::browser::types::{
- BrowserClassification, BrowserEngineFamily, EndpointOwnershipMethod, EndpointOwnershipProof,
- NativeOwnershipMethod, NativeOwnershipProof, NativeWindowInfo, OwnedEndpoint,
- ProcessFingerprint, Rect,
+ BrowserClassification, BrowserEngineFamily, BrowserProduct, EndpointOwnershipMethod,
+ EndpointOwnershipProof, NativeOwnershipMethod, NativeOwnershipProof, NativeWindowInfo,
+ OwnedEndpoint, ProcessFingerprint, Rect,
};
use tokio::io::{AsyncReadExt, AsyncWriteExt};
use windows::Win32::Foundation::{CloseHandle, FILETIME, HWND, RECT};
@@ -45,6 +47,26 @@ fn is_firefox(name: &str) -> bool {
.any(|token| token == "firefox")
}
+fn browser_product(name: &str) -> BrowserProduct {
+ let executable = name
+ .rsplit(['/', '\\'])
+ .next()
+ .unwrap_or(name)
+ .to_ascii_lowercase();
+ match executable.trim_end_matches(".exe") {
+ "chrome" => BrowserProduct::GoogleChrome,
+ "chromium" => BrowserProduct::Chromium,
+ "msedge" => BrowserProduct::MicrosoftEdge,
+ "brave" => BrowserProduct::Brave,
+ "vivaldi" => BrowserProduct::Vivaldi,
+ "opera" => BrowserProduct::Opera,
+ "arc" => BrowserProduct::Arc,
+ "electron" => BrowserProduct::Electron,
+ "firefox" => BrowserProduct::Firefox,
+ _ => BrowserProduct::Other,
+ }
+}
+
fn loopback_websocket_port(url: &str) -> Option<u16> {
["ws://127.0.0.1:", "ws://localhost:", "ws://[::1]:"]
.iter()
@@ -228,6 +250,7 @@ impl BrowserPlatform for WindowsBrowserPlatform {
})?;
let chromium = is_chromium(&name);
let gecko = is_firefox(&name);
+ let product_kind = browser_product(&name);
Ok(BrowserClassification {
is_browser: chromium || gecko,
engine: if chromium {
@@ -237,6 +260,7 @@ impl BrowserPlatform for WindowsBrowserPlatform {
} else {
BrowserEngineFamily::Unknown
},
+ product_kind,
product: Some(name),
channel: None,
supports_cdp: chromium,
@@ -340,6 +364,246 @@ impl BrowserPlatform for WindowsBrowserPlatform {
Ok(None)
}
+ async fn discover_existing_profile_endpoint(
+ &self,
+ pid: i64,
+ ) -> Result<Option<OwnedEndpoint>, BrowserRefusal> {
+ let pid_u32 = u32::try_from(pid).map_err(|_| {
+ refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ format!("pid {pid} is outside the Windows process-id range"),
+ )
+ })?;
+ let mut discovered = Vec::new();
+ for port in loopback_ports_for_pid(pid_u32).await? {
+ if let Some(ws_url) = browser_websocket_url(port).await {
+ discovered.push((port, ws_url));
+ }
+ }
+ match discovered.as_slice() {
+ [] => Ok(None),
+ [(port, ws_url)] => Ok(Some(OwnedEndpoint {
+ ws_url: ws_url.clone(),
+ http_port: Some(*port),
+ ownership: EndpointOwnershipProof {
+ method: EndpointOwnershipMethod::ListeningSocketPid,
+ owner_pid: pid,
+ detail: Some("Windows listener owner plus /json/version".to_owned()),
+ },
+ })),
+ _ => Err(refusal(
+ BrowserRefusalCode::BrowserBindingAmbiguous,
+ "multiple browser-level DevTools endpoints are owned by the approved process",
+ )),
+ }
+ }
+
+ async fn reprove_existing_profile_endpoint(
+ &self,
+ pid: i64,
+ expected_ws_url: &str,
+ ) -> Result<Option<OwnedEndpoint>, BrowserRefusal> {
+ let pid_u32 = u32::try_from(pid).map_err(|_| {
+ refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ format!("pid {pid} is outside the Windows process-id range"),
+ )
+ })?;
+ let Some(port) = loopback_websocket_port(expected_ws_url) else {
+ return Err(refusal(
+ BrowserRefusalCode::BrowserEndpointOwnerMismatch,
+ "the approved existing-profile endpoint is not loopback-only",
+ ));
+ };
+ if !loopback_ports_for_pid(pid_u32).await?.contains(&port) {
+ return Ok(None);
+ }
+ Ok(Some(OwnedEndpoint {
+ ws_url: expected_ws_url.to_owned(),
+ http_port: Some(port),
+ ownership: EndpointOwnershipProof {
+ method: EndpointOwnershipMethod::ListeningSocketPid,
+ owner_pid: pid,
+ detail: Some("Windows owner of exact approved endpoint".to_owned()),
+ },
+ }))
+ }
+
+ async fn setup_existing_profile_endpoint(
+ &self,
+ request: ExistingProfileSetupRequest,
+ ) -> Result<ExistingProfileSetupOutcome, BrowserRefusal> {
+ let descriptor = existing_profile_setup_descriptor(request.browser).ok_or_else(|| {
+ refusal(
+ BrowserRefusalCode::BrowserRouteUnavailable,
+ format!(
+ "approved existing-profile setup is not implemented for {:?}",
+ request.browser
+ ),
+ )
+ })?;
+ let pid_u32 = u32::try_from(request.pid).map_err(|_| {
+ refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ "the approved browser pid is outside the Windows process-id range",
+ )
+ })?;
+ let hwnd = request.window_id;
+ let listeners_before = loopback_ports_for_pid(pid_u32).await?;
+ let handle =
+ tokio::task::spawn_blocking(move || crate::browser_setup_ui::enable(hwnd, descriptor))
+ .await
+ .map_err(|error| {
+ refusal(
+ BrowserRefusalCode::BrowserRouteUnavailable,
+ format!(
+ "could not inspect {}'s remote-debugging setup UI: {error}",
+ descriptor.product_name
+ ),
+ )
+ })??;
+ let opened_setup_page = handle.opened_setup_page;
+ let enabled_remote_debugging = handle.enabled_remote_debugging;
+ let focused_setup_address_field = handle.focused_setup_address_field;
+ let foregrounded_window = handle.foregrounded_window;
+ let injected_global_input = handle.injected_global_input;
+
+ let deadline = std::time::Instant::now() + Duration::from_secs(6);
+ let endpoint_result = loop {
+ let ports = match loopback_ports_for_pid(pid_u32).await {
+ Ok(ports) => ports,
+ Err(error) => break Err(error),
+ };
+ let mut endpoints = Vec::new();
+ for port in &ports {
+ if let Some(ws_url) = browser_websocket_url(*port).await {
+ endpoints.push((*port, ws_url, "Windows owner plus /json/version"));
+ }
+ }
+ if endpoints.is_empty() {
+ let correlated = ports
+ .iter()
+ .copied()
+ .filter(|port| !listeners_before.contains(port))
+ .collect::<Vec<_>>();
+ if let [port] = correlated.as_slice() {
+ endpoints.push((
+ *port,
+ format!("ws://127.0.0.1:{port}/devtools/browser"),
+ "new PID-owned listener correlated with exact approved setup",
+ ));
+ } else if correlated.len() > 1 {
+ break Err(refusal(
+ BrowserRefusalCode::BrowserBindingAmbiguous,
+ format!(
+ "{} exposed multiple newly correlated PID-owned listeners",
+ descriptor.product_name
+ ),
+ ));
+ }
+ }
+ match endpoints.as_slice() {
+ [(port, ws_url, detail)] => {
+ break Ok(OwnedEndpoint {
+ ws_url: ws_url.clone(),
+ http_port: Some(*port),
+ ownership: EndpointOwnershipProof {
+ method: EndpointOwnershipMethod::ListeningSocketPid,
+ owner_pid: request.pid,
+ detail: Some((*detail).to_owned()),
+ },
+ })
+ }
+ [] if std::time::Instant::now() < deadline => {
+ tokio::time::sleep(Duration::from_millis(100)).await;
+ }
+ [] => {
+ break Err(refusal(
+ BrowserRefusalCode::BrowserRequiresSetup,
+ format!(
+ "{} did not expose a uniquely PID-owned loopback endpoint after the exact setup action",
+ descriptor.product_name
+ ),
+ ))
+ }
+ _ => {
+ break Err(refusal(
+ BrowserRefusalCode::BrowserBindingAmbiguous,
+ format!(
+ "{} exposed multiple PID-owned endpoint candidates after the exact setup action",
+ descriptor.product_name
+ ),
+ ))
+ }
+ }
+ };
+ let endpoint = match endpoint_result {
+ Ok(endpoint) => endpoint,
+ Err(error) => {
+ let error = tokio::task::spawn_blocking(move || handle.abort(error))
+ .await
+ .map_err(|join_error| {
+ refusal(
+ BrowserRefusalCode::BrowserRouteUnavailable,
+ format!("could not roll back browser setup: {join_error}"),
+ )
+ })?;
+ return Err(error);
+ }
+ };
+ crate::browser_setup_ui::retain_pending(hwnd, handle)?;
+
+ Ok(ExistingProfileSetupOutcome {
+ opened_setup_page,
+ closed_setup_page: false,
+ enabled_remote_debugging,
+ focused_setup_address_field,
+ foregrounded_window,
+ injected_global_input,
+ endpoint: Some(endpoint),
+ })
+ }
+
+ async fn commit_existing_profile_setup(
+ &self,
+ request: ExistingProfileSetupRequest,
+ ) -> Result<bool, BrowserRefusal> {
+ tokio::task::spawn_blocking(move || {
+ crate::browser_setup_ui::commit_pending(request.window_id)
+ })
+ .await
+ .map_err(|error| {
+ refusal(
+ BrowserRefusalCode::BrowserRouteUnavailable,
+ format!("could not commit exact browser setup cleanup: {error}"),
+ )
+ })?
+ }
+
+ async fn abort_existing_profile_setup(
+ &self,
+ request: ExistingProfileSetupRequest,
+ error: BrowserRefusal,
+ ) -> BrowserRefusal {
+ tokio::task::spawn_blocking(move || {
+ crate::browser_setup_ui::abort_pending(request.window_id, error)
+ })
+ .await
+ .unwrap_or_else(|join_error| {
+ refusal(
+ BrowserRefusalCode::BrowserRouteUnavailable,
+ format!("could not roll back exact browser setup: {join_error}"),
+ )
+ })
+ }
+
+ async fn handle_existing_profile_consent(
+ &self,
+ request: BrowserConsentRequest,
+ ) -> Result<BrowserConsentOutcome, BrowserRefusal> {
+ crate::browser_consent_ui::handle(request).await
+ }
+
async fn process_fingerprint(&self, pid: i64) -> Result<ProcessFingerprint, BrowserRefusal> {
let pid_u32 = u32::try_from(pid).map_err(|_| {
refusal(
@@ -374,6 +638,7 @@ impl BrowserPlatform for WindowsBrowserPlatform {
endpoint: Some(endpoint),
message: "An owned loopback DevTools endpoint is already available.".to_owned(),
side_effects: Default::default(),
+ attachment: None,
});
}
Err(refusal(
diff --git a/libs/cua-driver/rust/crates/platform-windows/src/browser_setup_ui.rs b/libs/cua-driver/rust/crates/platform-windows/src/browser_setup_ui.rs
new file mode 100644
index 0000000000..9f9f4d9a2b
--- /dev/null
+++ b/libs/cua-driver/rust/crates/platform-windows/src/browser_setup_ui.rs
@@ -0,0 +1,650 @@
+//! Exact Windows UIA setup for Chromium existing-profile attachment.
+
+use std::time::{Duration, Instant};
+use std::{
+ collections::HashMap,
+ sync::{Mutex, OnceLock},
+};
+
+use cua_driver_core::browser::{
+ BrowserRefusal, BrowserRefusalCode, BrowserSetupDescriptor,
+ EXISTING_PROFILE_SETUP_READY_TIMEOUT,
+};
+use windows::core::{Interface, BSTR};
+use windows::Win32::UI::Accessibility::{
+ IUIAutomationElement, IUIAutomationInvokePattern, IUIAutomationTogglePattern,
+ IUIAutomationValuePattern, ToggleState_Off, ToggleState_On, UIA_InvokePatternId,
+ UIA_TogglePatternId, UIA_ValuePatternId,
+};
+
+use crate::uia::UiaNode;
+
+fn refusal(code: BrowserRefusalCode, message: impl Into<String>) -> BrowserRefusal {
+ BrowserRefusal::new(code, message)
+}
+
+fn field_equals(node: &UiaNode, expected: &str) -> bool {
+ [
+ node.name.as_deref(),
+ node.value.as_deref(),
+ node.automation_id.as_deref(),
+ node.help_text.as_deref(),
+ ]
+ .into_iter()
+ .flatten()
+ .any(|value| value.trim().eq_ignore_ascii_case(expected))
+}
+
+fn release_nodes(nodes: &[UiaNode]) {
+ for node in nodes.iter().filter(|node| node.element_ptr != 0) {
+ unsafe { drop(IUIAutomationElement::from_raw(node.element_ptr as *mut _)) };
+ }
+}
+
+fn unique_actionable(
+ nodes: &[UiaNode],
+ control_type: &str,
+ label: &str,
+ action: &str,
+) -> Result<Option<usize>, BrowserRefusal> {
+ let matches = nodes
+ .iter()
+ .filter(|node| {
+ node.control_type == control_type
+ && field_equals(node, label)
+ && node.actions.iter().any(|value| value == action)
+ })
+ .map(|node| node.element_ptr)
+ .collect::<Vec<_>>();
+ match matches.as_slice() {
+ [] => Ok(None),
+ [element] => Ok(Some(*element)),
+ _ => Err(refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ format!("multiple exact {control_type} controls matched {label:?}"),
+ )),
+ }
+}
+
+fn setup_page_proven(nodes: &[UiaNode], descriptor: &BrowserSetupDescriptor) -> bool {
+ let exact_url = nodes.iter().any(|node| {
+ node.control_type == "Edit"
+ && field_equals(node, "Address and search bar")
+ && node
+ .value
+ .as_deref()
+ .is_some_and(|value| value.trim().eq_ignore_ascii_case(descriptor.setup_url))
+ });
+ let exact_heading = nodes.iter().any(|node| {
+ matches!(node.control_type.as_str(), "Header" | "Text")
+ && field_equals(node, descriptor.page_heading)
+ });
+ let exact_page = nodes.iter().any(|node| {
+ node.control_type == "Document"
+ && descriptor
+ .page_titles
+ .iter()
+ .any(|title| field_equals(node, title))
+ });
+ exact_url && exact_page && exact_heading
+}
+
+fn exact_setup_checkbox(
+ nodes: &[UiaNode],
+ descriptor: &BrowserSetupDescriptor,
+) -> Result<Option<usize>, BrowserRefusal> {
+ if !setup_page_proven(nodes, descriptor) {
+ return Ok(None);
+ }
+ unique_actionable(nodes, "CheckBox", descriptor.checkbox_label, "toggle")
+}
+
+unsafe fn invoke(element_ptr: usize) -> Result<(), BrowserRefusal> {
+ let element = IUIAutomationElement::from_raw(element_ptr as *mut _);
+ let result = element
+ .GetCurrentPattern(UIA_InvokePatternId)
+ .and_then(|pattern| pattern.cast::<IUIAutomationInvokePattern>())
+ .and_then(|pattern| pattern.Invoke());
+ std::mem::forget(element);
+ result.map_err(|error| {
+ refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ format!("the exact UIA Invoke action failed: {error}"),
+ )
+ })
+}
+
+unsafe fn set_value(element_ptr: usize, value: &str) -> Result<(), BrowserRefusal> {
+ let element = IUIAutomationElement::from_raw(element_ptr as *mut _);
+ let result = element
+ .GetCurrentPattern(UIA_ValuePatternId)
+ .and_then(|pattern| pattern.cast::<IUIAutomationValuePattern>())
+ .and_then(|pattern| pattern.SetValue(&BSTR::from(value)));
+ std::mem::forget(element);
+ result.map_err(|error| {
+ refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ format!("the exact UIA Value action failed: {error}"),
+ )
+ })
+}
+
+fn force_setup_foreground(target: windows::Win32::Foundation::HWND) -> (bool, bool) {
+ use windows::Win32::UI::Input::KeyboardAndMouse::{
+ keybd_event, KEYBD_EVENT_FLAGS, KEYEVENTF_KEYUP,
+ };
+
+ if unsafe { crate::input::force_foreground_attached(target) } {
+ return (true, false);
+ }
+
+ // The approved setup transition is allowed to be visible. Claim the
+ // foreground-lock token with Windows' reserved no-name key, which has no
+ // application action, then retry the exact HWND a bounded number of times.
+ const VK_NONAME: u8 = 0xFC;
+ unsafe {
+ keybd_event(VK_NONAME, 0, KEYBD_EVENT_FLAGS(0), 0);
+ keybd_event(VK_NONAME, 0, KEYEVENTF_KEYUP, 0);
+ }
+ for _ in 0..3 {
+ if unsafe { crate::input::force_foreground_attached(target) } {
+ return (true, true);
+ }
+ std::thread::sleep(Duration::from_millis(25));
+ }
+ (false, true)
+}
+
+fn confirm_setup_navigation(
+ hwnd: u64,
+ element_ptr: usize,
+ foregrounded_window: &mut bool,
+ injected_global_input: &mut bool,
+ focused_setup_address_field: &mut bool,
+) -> Result<(), BrowserRefusal> {
+ use windows::Win32::Foundation::HWND;
+ use windows::Win32::UI::WindowsAndMessaging::GetForegroundWindow;
+
+ let target = HWND(hwnd as *mut _);
+ let prior = unsafe { GetForegroundWindow() };
+ let navigation = (|| {
+ let (fronted, injected) = force_setup_foreground(target);
+ *injected_global_input |= injected;
+ if !fronted {
+ return Err(refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ "Windows refused the bounded foreground assist for the exact browser window",
+ ));
+ }
+ *foregrounded_window = true;
+
+ let element = unsafe { IUIAutomationElement::from_raw(element_ptr as *mut _) };
+ let focused = unsafe {
+ element
+ .SetFocus()
+ .and_then(|_| element.CurrentHasKeyboardFocus())
+ };
+ std::mem::forget(element);
+ match focused {
+ Ok(value) if value.as_bool() => *focused_setup_address_field = true,
+ Ok(_) => {
+ return Err(refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ "the exact address-and-search field did not acquire keyboard focus",
+ ));
+ }
+ Err(error) => {
+ return Err(refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ format!("could not focus the exact address-and-search field: {error}"),
+ ));
+ }
+ }
+
+ *injected_global_input = true;
+ crate::input::keyboard::send_key_synthesized(hwnd, "enter", &[]).map_err(|error| {
+ refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ format!("could not confirm the bounded setup navigation: {error}"),
+ )
+ })
+ })();
+
+ let restored = if prior.0.is_null() || prior == target {
+ true
+ } else {
+ let (restored, injected) = force_setup_foreground(prior);
+ *injected_global_input |= injected;
+ restored
+ };
+ if !restored {
+ return Err(refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ "the setup navigation completed, but Windows refused to restore the prior foreground window",
+ ));
+ }
+ navigation
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum CheckboxState {
+ Off,
+ On,
+}
+
+unsafe fn checkbox_state(element_ptr: usize) -> Result<CheckboxState, BrowserRefusal> {
+ let element = IUIAutomationElement::from_raw(element_ptr as *mut _);
+ let result = element
+ .GetCurrentPattern(UIA_TogglePatternId)
+ .and_then(|pattern| pattern.cast::<IUIAutomationTogglePattern>())
+ .and_then(|pattern| pattern.CurrentToggleState());
+ std::mem::forget(element);
+ match result {
+ Ok(state) if state == ToggleState_Off => Ok(CheckboxState::Off),
+ Ok(state) if state == ToggleState_On => Ok(CheckboxState::On),
+ Ok(_) => Err(refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ "the exact remote-debugging checkbox had an indeterminate state",
+ )),
+ Err(error) => Err(refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ format!("could not read the exact remote-debugging checkbox: {error}"),
+ )),
+ }
+}
+
+unsafe fn toggle(element_ptr: usize) -> Result<(), BrowserRefusal> {
+ let element = IUIAutomationElement::from_raw(element_ptr as *mut _);
+ let result = element
+ .GetCurrentPattern(UIA_TogglePatternId)
+ .and_then(|pattern| pattern.cast::<IUIAutomationTogglePattern>())
+ .and_then(|pattern| pattern.Toggle());
+ std::mem::forget(element);
+ result.map_err(|error| {
+ refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ format!("the exact UIA Toggle action failed: {error}"),
+ )
+ })
+}
+
+pub struct SetupUiHandle {
+ hwnd: u64,
+ descriptor: &'static BrowserSetupDescriptor,
+ pub opened_setup_page: bool,
+ pub enabled_remote_debugging: bool,
+ pub focused_setup_address_field: bool,
+ pub foregrounded_window: bool,
+ pub injected_global_input: bool,
+ enable_attempted: bool,
+}
+
+impl SetupUiHandle {
+ fn rollback_remote_debugging(&mut self) -> bool {
+ if !self.enabled_remote_debugging {
+ return true;
+ }
+ let tree = crate::uia::walk_tree(self.hwnd, None);
+ let checkbox = exact_setup_checkbox(&tree.nodes, self.descriptor);
+ let restored = match checkbox {
+ Ok(Some(element)) => unsafe {
+ matches!(checkbox_state(element), Ok(CheckboxState::On)) && toggle(element).is_ok()
+ },
+ _ => false,
+ };
+ release_nodes(&tree.nodes);
+ if restored {
+ self.enabled_remote_debugging = false;
+ }
+ restored
+ }
+
+ pub fn abort(mut self, error: BrowserRefusal) -> BrowserRefusal {
+ let enabled_remote_debugging = self.enabled_remote_debugging;
+ let restored_remote_debugging = self.rollback_remote_debugging();
+ let opened_setup_page = self.opened_setup_page;
+ let focused_setup_address_field = self.focused_setup_address_field;
+ let foregrounded_window = self.foregrounded_window;
+ let injected_global_input = self.injected_global_input;
+ let closed_setup_page = self.close().unwrap_or(false);
+ let mut error = error;
+ let cause = error.detail.take();
+ error.with_detail(serde_json::json!({
+ "setup_side_effects": {
+ "opened_setup_page": opened_setup_page,
+ "closed_setup_page": closed_setup_page,
+ "focused_setup_address_field": focused_setup_address_field,
+ "enabled_remote_debugging": enabled_remote_debugging,
+ "foregrounded_window": foregrounded_window,
+ "injected_global_input": injected_global_input,
+ "restored_remote_debugging": restored_remote_debugging,
+ },
+ "cause": cause,
+ }))
+ }
+
+ pub fn close_for_success(mut self) -> Result<Option<bool>, BrowserRefusal> {
+ if !self.opened_setup_page {
+ return Ok(None);
+ }
+ let tree = crate::uia::walk_tree(self.hwnd, None);
+ let proven = setup_page_proven(&tree.nodes, self.descriptor);
+ release_nodes(&tree.nodes);
+ if !proven {
+ let error = refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ "the temporary setup page was no longer exact before cleanup",
+ );
+ return Err(self.abort(error));
+ }
+ if let Err(error) = crate::input::keyboard::send_key_synthesized(self.hwnd, "w", &["ctrl"])
+ {
+ let error = refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ format!("could not close the exact temporary setup tab: {error}"),
+ );
+ return Err(self.abort(error));
+ }
+ self.opened_setup_page = false;
+ Ok(Some(true))
+ }
+
+ pub fn close(self) -> Option<bool> {
+ if !self.opened_setup_page {
+ return None;
+ }
+ let tree = crate::uia::walk_tree(self.hwnd, None);
+ let proven = setup_page_proven(&tree.nodes, self.descriptor);
+ release_nodes(&tree.nodes);
+ Some(
+ proven
+ && crate::input::keyboard::send_key_synthesized(self.hwnd, "w", &["ctrl"]).is_ok(),
+ )
+ }
+}
+
+fn pending_setups() -> &'static Mutex<HashMap<u64, SetupUiHandle>> {
+ static PENDING: OnceLock<Mutex<HashMap<u64, SetupUiHandle>>> = OnceLock::new();
+ PENDING.get_or_init(|| Mutex::new(HashMap::new()))
+}
+
+pub fn retain_pending(hwnd: u64, handle: SetupUiHandle) -> Result<(), BrowserRefusal> {
+ let mut pending = pending_setups().lock().unwrap();
+ if pending.contains_key(&hwnd) {
+ drop(pending);
+ return Err(handle.abort(refusal(
+ BrowserRefusalCode::BrowserBindingAmbiguous,
+ "another approved browser setup is already pending for this exact window",
+ )));
+ }
+ pending.insert(hwnd, handle);
+ Ok(())
+}
+
+pub fn commit_pending(hwnd: u64) -> Result<bool, BrowserRefusal> {
+ let handle = pending_setups()
+ .lock()
+ .unwrap()
+ .remove(&hwnd)
+ .ok_or_else(|| {
+ refusal(
+ BrowserRefusalCode::BrowserBindingStale,
+ "the exact pending browser setup cleanup handle is missing",
+ )
+ })?;
+ Ok(handle.close_for_success()?.unwrap_or(false))
+}
+
+pub fn abort_pending(hwnd: u64, error: BrowserRefusal) -> BrowserRefusal {
+ match pending_setups().lock().unwrap().remove(&hwnd) {
+ Some(handle) => handle.abort(error),
+ None => error.with_detail(serde_json::json!({
+ "setup_cleanup": "the exact pending browser setup cleanup handle was missing"
+ })),
+ }
+}
+
+pub fn enable(
+ hwnd: u64,
+ descriptor: &'static BrowserSetupDescriptor,
+) -> Result<SetupUiHandle, BrowserRefusal> {
+ let initial = crate::uia::walk_tree(hwnd, None);
+ let initial_checkbox = exact_setup_checkbox(&initial.nodes, descriptor);
+ let mut handle = match initial_checkbox {
+ Ok(Some(_)) => SetupUiHandle {
+ hwnd,
+ descriptor,
+ opened_setup_page: false,
+ enabled_remote_debugging: false,
+ focused_setup_address_field: false,
+ foregrounded_window: false,
+ injected_global_input: false,
+ enable_attempted: false,
+ },
+ Ok(None) => {
+ let tab_count_before = initial
+ .nodes
+ .iter()
+ .filter(|node| node.control_type == "TabItem")
+ .count();
+ let new_tab = match unique_actionable(&initial.nodes, "Button", "New Tab", "invoke") {
+ Ok(Some(element)) => element,
+ Ok(None) => {
+ release_nodes(&initial.nodes);
+ return Err(refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ format!(
+ "the approved {} window has no exact New Tab button",
+ descriptor.product_name
+ ),
+ ));
+ }
+ Err(error) => {
+ release_nodes(&initial.nodes);
+ return Err(error);
+ }
+ };
+ let invoked = unsafe { invoke(new_tab) };
+ release_nodes(&initial.nodes);
+ invoked?;
+
+ let mut handle = SetupUiHandle {
+ hwnd,
+ descriptor,
+ opened_setup_page: true,
+ enabled_remote_debugging: false,
+ focused_setup_address_field: false,
+ foregrounded_window: false,
+ injected_global_input: false,
+ enable_attempted: false,
+ };
+
+ let deadline = Instant::now() + Duration::from_secs(3);
+ let mut created = loop {
+ let tree = crate::uia::walk_tree(hwnd, None);
+ let tab_count_after = tree
+ .nodes
+ .iter()
+ .filter(|node| node.control_type == "TabItem")
+ .count();
+ if tab_count_after == tab_count_before + 1 {
+ break tree;
+ }
+ release_nodes(&tree.nodes);
+ if Instant::now() >= deadline {
+ return Err(handle.abort(refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ format!(
+ "{} did not expose exactly one newly created tab",
+ descriptor.product_name
+ ),
+ )));
+ }
+ std::thread::sleep(Duration::from_millis(100));
+ };
+ let omnibox = unique_actionable(
+ &created.nodes,
+ "Edit",
+ "Address and search bar",
+ "set_value",
+ )?
+ .ok_or_else(|| {
+ refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ format!(
+ "the approved {} window has no exact address-and-search field",
+ descriptor.product_name
+ ),
+ )
+ });
+ let omnibox = match omnibox {
+ Ok(element) => element,
+ Err(error) => {
+ release_nodes(&created.nodes);
+ return Err(handle.abort(error));
+ }
+ };
+ if let Err(error) = unsafe { set_value(omnibox, descriptor.setup_url) } {
+ release_nodes(&created.nodes);
+ return Err(handle.abort(error));
+ }
+ release_nodes(&created.nodes);
+ created = crate::uia::walk_tree(hwnd, None);
+ let refreshed_omnibox = created
+ .nodes
+ .iter()
+ .find(|node| {
+ node.control_type == "Edit"
+ && field_equals(node, "Address and search bar")
+ && node.value.as_deref().is_some_and(|value| {
+ value.trim().eq_ignore_ascii_case(descriptor.setup_url)
+ })
+ })
+ .map(|node| node.element_ptr);
+ let Some(refreshed_omnibox) = refreshed_omnibox else {
+ release_nodes(&created.nodes);
+ return Err(handle.abort(refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ "the exact address field did not retain the setup URL",
+ )));
+ };
+ if let Err(error) = confirm_setup_navigation(
+ hwnd,
+ refreshed_omnibox,
+ &mut handle.foregrounded_window,
+ &mut handle.injected_global_input,
+ &mut handle.focused_setup_address_field,
+ ) {
+ release_nodes(&created.nodes);
+ return Err(handle.abort(error));
+ }
+ release_nodes(&created.nodes);
+ handle
+ }
+ Err(error) => {
+ release_nodes(&initial.nodes);
+ return Err(error);
+ }
+ };
+ if !handle.opened_setup_page {
+ release_nodes(&initial.nodes);
+ }
+
+ let deadline = Instant::now() + EXISTING_PROFILE_SETUP_READY_TIMEOUT;
+ loop {
+ let tree = crate::uia::walk_tree(hwnd, None);
+ let checkbox = exact_setup_checkbox(&tree.nodes, descriptor);
+ match checkbox {
+ Ok(Some(element)) => {
+ let state = unsafe { checkbox_state(element) };
+ let outcome = match state {
+ Ok(CheckboxState::On) => {
+ if handle.enable_attempted {
+ handle.enabled_remote_debugging = true;
+ }
+ Ok(true)
+ }
+ Ok(CheckboxState::Off) if !handle.enable_attempted => unsafe {
+ toggle(element).map(|_| false)
+ },
+ Ok(CheckboxState::Off) => Ok(false),
+ Err(error) => Err(error),
+ };
+ release_nodes(&tree.nodes);
+ match outcome {
+ Ok(true) => return Ok(handle),
+ Ok(false) => handle.enable_attempted = true,
+ Err(error) => return Err(handle.abort(error)),
+ }
+ }
+ Ok(None) => release_nodes(&tree.nodes),
+ Err(error) => {
+ release_nodes(&tree.nodes);
+ return Err(handle.abort(error));
+ }
+ }
+ if Instant::now() >= deadline {
+ return Err(handle.abort(refusal(
+ BrowserRefusalCode::BrowserWrongTargetRefused,
+ format!(
+ "the exact {} remote-debugging setup page did not become ready",
+ descriptor.product_name
+ ),
+ )));
+ }
+ std::thread::sleep(Duration::from_millis(100));
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use cua_driver_core::browser::{existing_profile_setup_descriptor, BrowserProduct};
+
+ fn descriptor() -> &'static BrowserSetupDescriptor {
+ existing_profile_setup_descriptor(BrowserProduct::GoogleChrome).unwrap()
+ }
+
+ fn node(control_type: &str, name: &str, value: Option<&str>, actions: &[&str]) -> UiaNode {
+ UiaNode {
+ element_index: (!actions.is_empty()).then_some(0),
+ control_type: control_type.to_owned(),
+ name: Some(name.to_owned()),
+ value: value.map(str::to_owned),
+ automation_id: None,
+ help_text: None,
+ actions: actions.iter().map(|value| (*value).to_owned()).collect(),
+ element_ptr: 7,
+ center_x: 0,
+ center_y: 0,
+ rect: None,
+ msaa_role: None,
+ depth: 0,
+ parent_element_index: None,
+ in_web_content: false,
+ }
+ }
+
+ #[test]
+ fn checkbox_requires_exact_url_heading_and_unique_toggle() {
+ let nodes = vec![
+ node(
+ "Edit",
+ "Address and search bar",
+ Some(descriptor().setup_url),
+ &["set_value"],
+ ),
+ node("Document", descriptor().page_titles[0], None, &[]),
+ node("Header", descriptor().page_heading, None, &[]),
+ node("CheckBox", descriptor().checkbox_label, None, &["toggle"]),
+ ];
+ assert_eq!(exact_setup_checkbox(&nodes, descriptor()).unwrap(), Some(7));
+
+ let mut wrong_url = nodes.clone();
+ wrong_url[0].value = Some("https://example.test/".to_owned());
+ assert_eq!(
+ exact_setup_checkbox(&wrong_url, descriptor()).unwrap(),
+ None
+ );
+ }
+}
diff --git a/libs/cua-driver/rust/crates/platform-windows/src/lib.rs b/libs/cua-driver/rust/crates/platform-windows/src/lib.rs
index cbe83405d5..06164cf7cc 100644
--- a/libs/cua-driver/rust/crates/platform-windows/src/lib.rs
+++ b/libs/cua-driver/rust/crates/platform-windows/src/lib.rs
@@ -46,6 +46,11 @@ pub mod win32;
#[cfg(target_os = "windows")]
pub mod browser_platform;
+#[cfg(target_os = "windows")]
+mod browser_consent_ui;
+#[cfg(target_os = "windows")]
+mod browser_setup_ui;
+
#[cfg(target_os = "windows")]
pub mod uia;
diff --git a/libs/cua-driver/rust/crates/platform-windows/src/msaa.rs b/libs/cua-driver/rust/crates/platform-windows/src/msaa.rs
index 5a43c91e0d..6caa5046e3 100644
--- a/libs/cua-driver/rust/crates/platform-windows/src/msaa.rs
+++ b/libs/cua-driver/rust/crates/platform-windows/src/msaa.rs
@@ -96,10 +96,21 @@ unsafe fn walk_unsafe(hwnd: u64) -> UiaTreeResult {
let mut counter = 0usize;
let mut total = 0usize;
- walk(&root, 0, None, &mut nodes, &mut lines, &mut counter, &mut total);
+ walk(
+ &root,
+ 0,
+ None,
+ &mut nodes,
+ &mut lines,
+ &mut counter,
+ &mut total,
+ );
let tree_markdown = render_lines(&lines);
- UiaTreeResult { tree_markdown, nodes }
+ UiaTreeResult {
+ tree_markdown,
+ nodes,
+ }
}
#[allow(clippy::too_many_arguments)]
@@ -188,6 +199,7 @@ unsafe fn walk(
msaa_role: role_int,
depth,
parent_element_index: parent_index,
+ in_web_content: false,
}
} else {
UiaNode {
@@ -205,6 +217,7 @@ unsafe fn walk(
msaa_role: role_int,
depth,
parent_element_index: parent_index,
+ in_web_content: false,
}
};
// Track this node as the parent_index for its descendants only when
@@ -221,7 +234,15 @@ unsafe fn walk(
// accChild returns IDispatch — query for IAccessible.
if let Ok(child_disp) = acc.get_accChild(&child_var) {
if let Ok(child_acc) = child_disp.cast::<IAccessible>() {
- walk(&child_acc, depth + 1, next_parent, nodes, lines, counter, total);
+ walk(
+ &child_acc,
+ depth + 1,
+ next_parent,
+ nodes,
+ lines,
+ counter,
+ total,
+ );
}
}
}
@@ -235,7 +256,15 @@ unsafe fn walk(
let child_var = VARIANT::from(i);
if let Ok(child_disp) = acc.get_accChild(&child_var) {
if let Ok(child_acc) = child_disp.cast::<IAccessible>() {
- walk(&child_acc, depth + 1, parent_index, nodes, lines, counter, total);
+ walk(
+ &child_acc,
+ depth + 1,
+ parent_index,
+ nodes,
+ lines,
+ counter,
+ total,
+ );
}
}
}
diff --git a/libs/cua-driver/rust/crates/platform-windows/src/uia/mod.rs b/libs/cua-driver/rust/crates/platform-windows/src/uia/mod.rs
index 914bb1112c..7c22217467 100644
--- a/libs/cua-driver/rust/crates/platform-windows/src/uia/mod.rs
+++ b/libs/cua-driver/rust/crates/platform-windows/src/uia/mod.rs
@@ -80,6 +80,9 @@ pub struct UiaNode {
/// `element_index` of the nearest actionable ancestor, if any.
/// Mirrors the markdown's parent-of-this-row.
pub parent_element_index: Option<usize>,
+ /// True when this node is below a UIA Document control. Browser-owned
+ /// consent chrome must never match renderer-controlled descendants.
+ pub in_web_content: bool,
}
pub struct UiaTreeResult {
@@ -254,6 +257,7 @@ unsafe fn walk_tree_unsafe(
&root_elem,
0,
None,
+ false,
&mut nodes,
&mut lines,
&mut counter,
@@ -474,6 +478,7 @@ unsafe fn walk_root_by_pid(
&cached,
0,
None,
+ false,
nodes,
lines,
counter,
@@ -497,6 +502,7 @@ unsafe fn walk_cached(
element,
depth,
None,
+ false,
nodes,
lines,
counter,
@@ -511,6 +517,7 @@ unsafe fn walk_cached_bounded(
element: &IUIAutomationElement,
depth: usize,
parent_index: Option<usize>,
+ in_web_content: bool,
nodes: &mut Vec<UiaNode>,
lines: &mut Vec<(usize, String)>,
counter: &mut usize,
@@ -566,6 +573,7 @@ unsafe fn walk_cached_bounded(
msaa_role: None,
depth,
parent_element_index: parent_index,
+ in_web_content,
}
} else {
UiaNode {
@@ -583,6 +591,7 @@ unsafe fn walk_cached_bounded(
msaa_role: None,
depth,
parent_element_index: parent_index,
+ in_web_content,
}
};
@@ -599,6 +608,7 @@ unsafe fn walk_cached_bounded(
&child,
depth + 1,
emitted_parent,
+ in_web_content || control_type.eq_ignore_ascii_case("Document"),
nodes,
lines,
counter,
diff --git a/scripts/ci/run-rust-standalone-browser-e2e.sh b/scripts/ci/run-rust-standalone-browser-e2e.sh
index e7ab102833..2df1b20f41 100755
--- a/scripts/ci/run-rust-standalone-browser-e2e.sh
+++ b/scripts/ci/run-rust-standalone-browser-e2e.sh
@@ -90,6 +90,8 @@ fi
tests=(
standalone_browser_background_type
+ standalone_browser_existing_profile
+ standalone_browser_existing_profile_setup
standalone_browser_frames
standalone_browser_multi_tab
standalone_browser_prepare_isolated
diff --git a/scripts/ci/windows/run-rust-standalone-browser-e2e.ps1 b/scripts/ci/windows/run-rust-standalone-browser-e2e.ps1
index 6fa85c5c99..d9b623c681 100644
--- a/scripts/ci/windows/run-rust-standalone-browser-e2e.ps1
+++ b/scripts/ci/windows/run-rust-standalone-browser-e2e.ps1
@@ -117,6 +117,8 @@ if (-not (Test-Path $env:CUA_TEST_DRIVER_BIN)) {
$tests = @(
"standalone_browser_background_type",
+ "standalone_browser_existing_profile",
+ "standalone_browser_existing_profile_setup",
"standalone_browser_frames",
"standalone_browser_multi_tab",
"standalone_browser_prepare_isolated",