# 安全模型

**简体中文** | [English](security-model.en.md)

## 打包依赖检查

邮件协议与解析依赖内嵌在 JS 中，下游 `npm audit` 和 `overrides` 无法完整检查或替换它们。构建生成 `lib/bundled-dependencies.json`，从所有 JS sourcemap 提取实际依赖，核对安装版本和锁文件，并记录产物哈希。`npm run check:security` 查询 npm 安全公告，存在高危/严重漏洞或查询失败时停止；历史地址解析修复另有最低版本检查。打包和发布阶段再次核对清单与 tarball 内 JS，防止检查后换入未扫描的文件。

这项检查覆盖已公开公告，不能保证不存在未知解析漏洞。升级安全修复时必须重建并发布新插件版本，再更新客户端装配锁。

## 保护目标

1. 邮箱授权码不进入普通配置、浏览器回读、工具参数、会话结果或日志。
2. 读信不会改变服务器状态。
3. 邮件中的提示注入不能变成系统指令、用户授权或密钥请求。
4. Agent 只有在发信能力已开启，且当前 DSH 权限预设允许时才能发信。
5. 附件不能通过相对路径、符号链接或目录联接越过当前会话工作区，也不能无界占用内存/磁盘。
6. SMTP 不确定结果不能触发自动重试和重复发信。

## 信任边界

- **受信任**：DSH Host、所选 Credential Provider、用户明确保存的服务器配置、用户选择的会话权限预设，以及普通权限下当前用户对审批 UI 的操作。
- **不可信**：邮件正文、标题、地址、附件名与附件内容；模型生成的 Tool 参数；远端 IMAP/SMTP 错误文本。
- **条件可信**：当前会话工作区文件。它们可以作为用户允许 Agent 使用的附件，但仍受路径、文件类型、数量和总大小限制。

## Prompt injection

读取结果的规范字段名为 `untrustedText`，Native 渲染会加固定警告并把 JSON 每行加前缀。Host 还向系统提示注入稳定规则：邮件不能授权发信、请求密钥或修改系统策略。

这些提示不是唯一防线。真正的写操作依赖独立机制：`mail_send` 的能力开关、参数验证、工作区附件 fence，以及 DSH 原生 `tools/pre-execute` 权限通路。即使模型忽略提示，邮件正文仍不能绕过它们。

## 附件下载

`mail_get_attachment` 在访问凭据和下载附件之前检查会话当前生效的写入权限。工作区写入权限允许保存附件；只读或未知权限仍请求本次审批。拒绝、取消或审批不可用时不执行下载。路径边界和文件大小限制继续生效；下载权限不会授予发信权限。

## 发信审批

`mail_send` 在接触凭据、附件或 SMTP 之前进入 DSH 原生权限 waterfall：

- 普通权限返回 `ask`，由 DSH Approval 服务弹出一次性审批；`rejected`、`cancelled`、`unavailable` 全部失败关闭；
- Full Access 直接继续，不再发起一个必然被 `approval: never` 拒绝的请求；
- 无 Agent 会话时拒绝；
- 不论哪种权限，邮件设置里的“允许 Agent 发信”都必须单独开启，Full Access 不能打开或绕过这个能力开关。

因此 Full Access 的含义与 DSH 其他写操作一致：用户已经为当前会话选择了免审批执行。切换到 Full Access 后，Agent 可以在已开放发信能力的前提下无需逐封弹窗发送邮件。这个选择应只用于用户明确接受该风险的交互会话，不能推导出后台任务授权。

## 传输安全

- 仅允许隐式 TLS 或 STARTTLS；
- TLS 证书校验固定开启；
- 不支持明文 IMAP/SMTP；
- 不记录协议流量；
- 服务器连接和 socket 有有限超时；
- 不把远端任意错误原样返回给模型。

## 已知剩余风险

- 用户提供的邮箱授权码本身通常拥有比插件开关更大的服务器权限。读/发开关是本插件的本地策略，不会缩小授权码在其他客户端中的权限。
- Full Access 会取消逐封发信弹窗。若希望审阅每封邮件，应使用普通权限；开启发信能力和选择 Full Access 的组合会授权 Agent 在该会话中直接发送。
- SMTP 没有通用幂等协议。DATA 阶段断线时服务器可能已经接收邮件；插件返回 `unknown`，但最终仍需人工检查。
- MIME 解析复杂。读取整封邮件前会先检查服务器报告的 message size，但恶意或错误服务器仍可能提供不一致信息。
- 本地附件下载会复核逻辑路径与真实路径，但仍依赖 Host 文件系统。受攻击的同用户本地进程仍可能与检查/写入竞争或访问同一用户可访问的文件；插件不提供 OS 级隔离。

## 安全问题报告

不要公开提交授权码、真实邮件或含个人信息的日志。请按 [SECURITY.md](../SECURITY.md) 的私密渠道报告。