# Security Model

This plugin grants an LLM agent the ability to observe and operate the Windows
desktop. That is inherently a high-impact capability. The design assumes the
model can be wrong, adversarial, or compromised, so it fails closed wherever
possible and never treats on-screen text as authorization.

## Threat model

- **The agent can see screenshots and window titles.** Screenshots may contain
  private data. They are written under the OS temp directory
  (`%TEMP%\dsh-computer-use`) and deleted when their observation is
  invalidated or expires; a hard host crash can leave stale files, so treat the
  temp directory as sensitive and clear it when needed.
- **The agent can send mouse and keyboard input to arbitrary windows.**
  Mitigations below bound what it can target and what it can do without approval.

## Safety mechanisms

1. **Observation binding / stale-state rejection.** Every action is bound to an
   exact, unexpired `observation_id`. Clicking by `element_index` uses only
   elements from that observation. Coordinates and region-centers are validated
   against the target window; a point covered by another window is refused.
2. **Blocklists.** Processes (cmd, powershell, password managers, terminals,
   credential UI, the DSH host, system settings, and more) and window-title
   fragments (tray icons, IME, hidden/system windows) are refused. There is no
   way to bypass the blocklist from the model side.
3. **Allowlist (optional).** `allowedApps` config restricts targets to an
   explicit set of process names; when non-empty, everything else is refused
   even if not blocked.
4. **Risk classification + one-shot approval.** Mutating tools require a
   `risk` category (`none`/`external`/`sensitive`/`destructive`/`financial`/
   `install`/`permissions`/`medical`/`authentication`). A label heuristic upgrades
   submit/delete/pay/install/login-like labels. Non-`none` risk routes through
   the DSH approval service; a missing or rejecting approval service fails closed. `allowedExternalLabels` lets an operator allow-list specific send-type labels (external only); destructive/financial/install/permissions/authentication labels never allow-list.
5. **No password / auth entry.** Typing into a UI Automation password control is
   refused when UIA exposes one; apps without an accessibility tree rely on the
   model's risk classification instead (same tradeoff as Codex computer use).
6. **Desktop-lock and hidden-window refusal.** Actions are refused while the
   workstation is locked, and the native helper refuses invisible windows and
   invalid handles. Windows-key shortcuts are prohibited.
7. **Foreground / physical-input model.** Actions activate the target window and
   move the physical pointer. This is a foreground mode, not a silent background
   mode; the operator sees what the agent is doing.

## Known limitations

- **The risk category is model-supplied.** A determined model can label a risky
  action `none`. The label heuristic is a backstop, not a guarantee. Run
  high-stakes automation with `allowedApps` scoped tightly and approval prompts
  enabled (`requireApprovalForTyping` for typing).
- **Screenshots can be blank for cloaked/hidden apps** (e.g. WeChat closed to
  tray renders neither via PrintWindow nor screen capture until woken via its
  own tray/hotkey path — use `computer_hotkey` with Ctrl+Alt+W for WeChat).
  When the screen-copy fallback is used, the helper now detects occlusion and
  re-activates/retries; a still-occluded window fails with a clear error rather
  than silently capturing whichever window is on top.
- **`allowedExternalLabels` is an operator opt-in**, not a model escape hatch.
  It only suppresses the external (send/submit/post) heuristic for labels the
  operator names; a model cannot enable it and cannot use it to bypass
  delete/pay/install/login escalations.
- **WeChat and other self-drawn UIs expose an empty accessibility tree**, so
  `element_index` navigation is unavailable and control degrades to the
  screenshot + coordinate path.