# dsh-browser 安全设计

## 1. 保护对象

dsh-browser 可以读取页面标题、URL、正文、表单值和交互元素，也可以导航、点击、输入、滚动、发送按键和执行页面表达式。获得该能力的攻击者可能读取私密页面、提交交易、修改账号数据或伪造自动化结果。

模型可见的工具参数和结果遵循 DeepSeek Harness 会话持久化策略。扩展默认可以访问浏览器 profile 中全部 HTTP/HTTPS 标签页；这些页面的数据可能进入模型提供方或本地会话日志。

## 2. 独立授权条件

一次浏览器操作必须同时满足适用的条件：

| 条件 | 执行者 | 作用 |
|---|---|---|
| 扩展身份 | Chromium NativeMessagingHosts + Native host | 只有安装时指定的扩展 ID 可以启动生产 host。 |
| bridge 认证 | BrowserBridge | 只有正确协议版本、Origin、token 和能力集的客户端进入 ready。 |
| 页面类型 | 浏览器扩展 | 只有 HTTP/HTTPS 标签页可以返回元数据或执行注入。 |
| Harness 审批 | ToolRuntime + browser-policy | 修改型工具只有在审批允许后才调用 `ctx.browser`。 |

任一条件拒绝都终止操作。`danger-full-access` 可以关闭 Harness 交互审批，但不能改变 HTTP/HTTPS 目标限制。

## 3. 浏览器主机权限与页面范围

扩展 manifest 声明 HTTP/HTTPS 主机权限，因为 `chrome.scripting.executeScript` 必须具备目标页面权限，自动化需要操作浏览器 profile 中的现有网页标签页。manifest 还声明 `debugger` 权限，供默认注册的 `browser_evaluate` 调用 CDP `Runtime.evaluate`。安装扩展即允许 dsh-browser 访问全部 HTTP/HTTPS 标签页，不存在逐站点授权表。

Popup 只显示自动连接状态和安装 Native host 所需的扩展 ID。每次列举、读取和操作都重新检查当前标签页使用 HTTP 或 HTTPS；注入函数和 CDP 隔离 execution context 还比较页面执行时的 `location.origin` 与命令开始时读取的 origin。表达式绑定到完成该检查的 `executionContextId`，导航后旧 context 失效。

Agent 首次操作可操控页面时，扩展会注入自有的控制提示、虚拟鼠标和 favicon 标记。提示使用 Shadow DOM，不进入正文快照、元素引用或文本等待。协议命令携带内部 Agent owner；请求结束只移除请求标识，连续浏览器工具之间仍保留指示，Agent 进入 idle、被销毁或连接断开时才释放 owner。没有 Agent owner 的直接调用至少显示一秒。页面导航会销毁旧提示，持续执行的命令在新的 HTTP/HTTPS 文档可注入时重新显示。该机制不为触发 Chromium 原生调试提示而附加 `chrome.debugger`，也不提供无法对应协议取消语义的伪取消按钮。

回环绑定、Native Messaging 和 token 约束连接来源与传输身份，但不会限制已连接 Agent 可以请求读取或操作哪些 HTTP/HTTPS 标签页。用户安装扩展时接受这一 profile 级访问范围；需要隔离敏感会话时，应使用独立浏览器 profile 或停用扩展。

`chrome://`、`edge://`、扩展页面、浏览器商店、`file://` 和空 URL 不可操控。导航只接受 HTTP/HTTPS URL；重定向到另一个 HTTP/HTTPS origin 后，后续命令可以继续操作新页面，但当前注入或 evaluation 在 origin 变化时失败。

## 4. 传输身份与凭据

生产 Native host 清单的 `allowed_origins` 只包含安装时提供的扩展 ID。Chrome 传入的扩展 origin 会被 host 规范化并与私有配置精确比较。

安装器生成至少 32 字节随机 token，写入权限为 `0600` 的 `$DSH_HOME/browser-native-host.json` 和 `$DSH_HOME/browser-native-host.env`。启动者显式导入后一个文件；安装器不把 token 写入 DSH 会自动加载的 `$DSH_HOME/.env`。可执行文件复制到 `$DSH_HOME/browser-native-host/`，避免浏览器进程因 macOS Documents/TCC 权限无法启动源目录中的文件。

Native host 向 bridge 注入 token，扩展不读取生产 token。Direct 开发模式通过扩展内部诊断消息接收与 Harness 相同的 token；bridge 还要求 WebSocket Origin 以 `chrome-extension://` 开头。bridge 只绑定 `127.0.0.1`，配置其他地址时加载失败。

token 不进入工具结果或普通连接日志。错误日志可以包含客户端名称、传输和稳定错误码，但不得输出认证值。

## 5. Harness 工具审批

默认无需审批的工具是 `browser_list_tabs`、`browser_snapshot` 和 `browser_wait`。以下工具默认返回 `ask`：

- `browser_new_tab`、`browser_navigate`、`browser_back`、`browser_forward` 和 `browser_reload`；
- `browser_click`、`browser_type`、`browser_scroll` 和 `browser_key`；
- `browser_evaluate`。

ToolRuntime 在审批得到 `allowed-once` 前不调用工具实现。拒绝、取消、没有审批通道或没有可审计 agent 都产生错误结果，页面命令不会发给扩展。

browser-policy 在 `workspace-write` 和 `read-only` 下返回 `ask`。默认 `danger-full-access` preset 已经表达无需交互审批，因此 policy 直接委托 ToolRuntime；该委托只跳过 Harness 提问，不跳过 HTTP/HTTPS 目标检查。

`browser_evaluate` 默认注册，profile 可以通过 `browser-tools.config.enableEvaluate: false` 显式移除。扩展为每次调用临时附加目标标签页，只使用建立隔离 context、验证 execution-time origin、执行调用方表达式和有界序列化所需的 CDP 方法，并在成功、失败或取消后 detach。该命令仍受 HTTP/HTTPS 目标检查、permission preset 策略、递归与条目上限、单个字符串与总字符上限以及协议消息大小限制。

## 6. 协议与生命周期控制

- 握手失败的连接不能替换当前有效客户端。
- 消息大小、JSON 字段、命令联合和回复值在进程边界校验。
- 调用取消、bridge 超时、连接替换、断线和插件卸载都会结算 pending 请求。
- 修改操作不跨连接自动重放；断线后的页面状态需要重新观察。
- `documentId + ref` 防止旧元素引用在新文档中指向不同元素。
- 文本、元素数量、等待时间、表达式结果和协议消息均有上限。

## 7. 威胁与控制

| 威胁 | 控制 |
|---|---|
| 普通网页连接本地 WebSocket 冒充扩展 | WebSocket Origin、token、版本和能力握手；握手前不替换当前连接。 |
| 其他扩展启动生产 Native host | NativeMessagingHosts `allowed_origins` 与 host 私有配置双重检查扩展 ID。 |
| 浏览器内部页或本地文件被操作 | 列表和每条命令只接受 HTTP/HTTPS URL；其他 scheme 返回 `UNSUPPORTED_URL`。 |
| 检查后页面跳转到另一 origin | 注入函数复核 `location.origin`，evaluate 使用已验证且导航后失效的 `executionContextId`。 |
| 恶意或损坏回复进入 Harness | bridge 对每种命令的回复字段进行运行时校验，失败时关闭连接。 |
| 重连后重复提交 | pending 请求失败且不重放，调用方重新快照后决定。 |
| 超大页面或表达式耗尽内存 | 获取上限、返回上限、递归/序列化限制和最大消息字节数。 |

## 8. 剩余风险

扩展安装后拥有广泛网页注入能力，因此扩展代码和更新来源本身属于高信任组件。连接成功后，Agent 可以读取浏览器 profile 中任何 HTTP/HTTPS 标签页，包括已经登录的私密页面；Harness 审批默认保护修改操作，不保护列表、快照和等待读取。

`debugger` 是强权限。产品代码只把它用于单次 `Runtime.evaluate`，但扩展被攻破后可以使用更广泛的 CDP 能力；用户还可能看到 Chromium 的调试附加提示，DevTools 或其他调试器占用目标时表达式执行会失败。v0.2 不提供通用 CDP、后台截图、跨进程 iframe 或完整可访问性树。

页面控制提示用于告知用户，不是安全边界。它位于页面 DOM 中，页面脚本或样式可能移除、遮挡或仿造提示；扩展会在同一命令的后续页面注入时恢复真实提示，但授权和审批不能依赖提示是否可见。