# 安全边界

## 前提：面向可信业务系统

本插件面向**可信的业务系统**——持有 client 私钥、通过签名认证接入的集成合作方。
它不是用来隔离不可信调用方的：**对不可信的业务系统无法做出完整防护**，本插件也不以此为目标。

```
业务系统(可信合作方) ──HTTP──▶ 桥接插件(本仓库) ──DSH API──▶ DSH Agent ──▶ 文件系统 / 网络
                                入口校验 + 能力约束          运行时沙箱（部署侧）
```

**通道可信，但内容不一定可信**：业务系统是可信的转发者，它递过来的文本与文件却可能来自
更上游（终端用户上传、第三方文档）。因此插件仍然做内容层防护——防的是**注入到内容里的指令**，
不是业务系统本身。

据此，入口校验的定位是四件事，而非"防住不可信方"：

1. **防误用**：参数、体量、URI 写错时早失败、给明确错误，而不是让 agent 去做错事；
2. **防跨租户串用**：多个可信合作方之间不互相可见（这是可信方之间仍然需要的边界）；
3. **防插件被当跳板**：可信方被攻破或配置失误时，不至于借插件探内网、读宿主；
4. **纵深**：以上之外的意外一律往安全侧收敛（默认拒绝）。

## 一、插件负责的部分

| 防护 | 说明 | 配置 |
|------|------|------|
| 请求签名 | RSA-SHA256 + 时间戳窗口 + nonce 防重放；未知 client 401 | `auth` |
| 权限隔离 | `stream`/`callback`/`admin` 三类 scope；跨 client 读写 403/404 | `auth.clients[].scope` |
| 方法/协议 | 业务接口仅 POST；URI 仅 `http(s)` | 内置 |
| SSRF | 拒绝内网/环回/链路本地地址，判定在 IP 字节层（含 IPv4 映射、NAT64、6to4）；重定向逐跳校验；同样约束 `callback_url` | `attachments.denyInternalHosts`、`maxRedirects` |
| 附件体量 | 单请求条数、单文件与总字节上限 | `attachments.maxItems` 等 |
| 路径越界 | 账本相对路径必须落在该 client 工作目录内；文件名净化 | 内置 |
| 下载鉴权 | 仅账本登记过的附件可下载，按 client 归属校验 | 内置 |
| 出站防泄露 | 默认排除密钥类文件（目录 + glob） | `attachments.outbound.exclude`、`sensitivePatterns` |
| 出站完整性 | 登记时记 SHA256，下载时校验，内容变更即拒绝 | 内置 |
| 错误脱敏 | 对外错误不含内部会话 ID | 内置 |
| 内容不可信声明 | 写入 agent 系统提示词，并附加在每条用户消息前 | `security.policySection` |
| 工具限制 | 在桥接会话作用域内移除指定工具能力 | `security.denyTools` |
| 沙箱模式 | `read-only` 时 DSH 拒绝该会话的一切写入与删除 | `security.sandboxMode` |

后三项注册在每个桥接会话自己的作用域（`agent.ctx` / 会话事件）上，不影响同进程的其它 agent。
其中**工具限制与沙箱模式是能力型约束**（不看模型是否配合），内容声明只是文本层纵深。

## 二、插件不负责的部分

- **读边界**：DSH 的读操作在**所有**沙箱模式下都不受边界限制
  （`fs-sandbox`：*Reads pass through untouched: every mode permits reading*）。
  插件**无法**把"读"限制在本 client 工作空间内。
- **危险操作确认**：递归删除、批量覆盖等没有内置的人机确认。
- **模型行为**：内容注入的最终防线仍是模型判断，不可量化、不可依赖。

## 三、部署侧建议

1. **运行时沙箱**：把插件与 DSH 放进独立容器 / 低权限账户；只挂载必要目录——
   这是唯一能真正关住"读"的一层，也是可信方被攻破时的兜底。
2. **收紧出网**：插件只有"拉取附件"与"投递回调"两处出站，按合作方实际域名做出口白名单。
3. **开启能力约束**：

   ```yaml
   security:
     sandboxMode: read-only                          # 不让改、不让删
     denyTools: [bash, pwsh, web_search, web_fetch]  # 移除执行与出网能力
   attachments:
     outbound:
       enabled: false                                # read-only 下产物必然为空
   ```

4. **凭据与文档分离**：client 公钥放 `<runtime>/clients/<clientId>.pem`（插件只读公钥）；
   私钥留在业务方本机，不要与说明文档同目录明文存放。
5. **监听面**：默认 `127.0.0.1`；需对外时把 `host` 改成本机网卡的具体 IP 字面量并配防火墙
   （**DSH 0.2.1 起通配地址 `0.0.0.0` 会在加载期被拒**）。

字段细节见 [`config.md`](config.md) §security；接口层语义见 [`api.md`](api.md) §14。