# 安全说明

本插件把本机 DeepSeek Harness 暴露给 IM。默认姿态是拒绝，而不是信任所有能发到机器人的人。

## 默认姿态

1. **入站先验身份**：`handleInbound()` 在斜杠命令、工具审批和注入之前检查 `msg.userId`。
2. **私聊未配置即拒绝**：私聊白名单为空，或消息没有 `userId`，不处理。
3. **群聊不用绑定**：群聊只需 @ 机器人；不进待批准、不查白名单。
4. **私聊只有扫码用户免批**：微信扫码用户和飞书 / Lark 扫码用户自动进入白名单；其他私聊用户必须在设置页批准。
5. **群聊仍需 @ 当前机器人**：未 @ 机器人、或只 @ 其他成员的群消息直接忽略，也不会写入待批准；准确 @ 机器人后默认放行。
6. **工具审批更严**：回复「批准 / 拒绝」只在私聊且发送者已在白名单时生效。群聊里的批准词不会授予 harness 权限。
7. **不恢复开放模式**：不再提供 `allowAllUsers` 或钉钉「配对 / 开放模式」。安全路径必须是默认路径。

## 威胁模型

- 任何人私聊或在群里 @ 机器人，都可能试图驱动本机 agent。
- 「批准」「yes」这类短文本若不做身份校验，会直接放行待处理的工具权限。
- Telegram 等凭据型机器人默认接受所有私聊，必须靠白名单拦住。

## 管理面

- 设置页使用 `/api/dsh-im-connect`。每个请求都先通过宿主公开的 `connection.requestRejection` 认证，再进入插件业务分发。该接口同时执行 Host/trustedHosts、Origin、跨站标记与绑定访问地址的浏览器 Cookie 校验；本机请求同样需要登录。路径前缀、自定义请求头及回环代理来源都不是身份凭据。
- 该 REST 前缀遵循其他 DSH 插件的 `/api/<插件名>` 约定，并通过具名路径与宿主 Gateway 共存；不注册第二个 `/api` RPC interceptor，也不改变宿主 Gateway。接口仍为 REST JSON，不是 Remote RPC envelope；既有业务路径、GET/POST 方法、参数和成功返回结构不变。
- 每次请求通过 `ctx.get('connection')` 读取当前活动服务，不缓存认证实例、不暴露 inactive 服务。宿主缺少公开认证接口或服务暂不可用时返回 503，提示稍后重试或升级；认证异常不会降级为匿名本地访问。
- 反代应保留外部 Host、Cookie 和 Origin，在宿主 `client-connection.trustedHosts` 配置实际访问地址，并通过该地址的 DSH 登录入口取得 Cookie。不要将 Host 改成 localhost 来绕过校验，不接受插件专用 token 或转发头作为认证。公网入口应使用 HTTPS。
- 管理回包统一 `Cache-Control: no-store`，前端使用同源 Cookie 且禁用缓存。
- 所有写接口必须使用 `Content-Type: application/json`，并携带 `x-dsh-im-connect-client: 1`；读取和写入均需宿主登录 Cookie。请求体仍按实际接收字节限制为 1 MiB，普通跨站表单不能触发连接、批准、删除或权限修改。
- 失败返回 JSON `{ "ok": false, "error": "说明" }`：未登录/无效 Cookie 为 401；不可信 Host、跨站请求或写请求缺客户端标记为 403；认证服务不可用为 503。非法 JSON 为 400，超限为 413，非 JSON 写请求为 415；业务路由其余错误码保持原行为。认证失败不会进入业务读写。
- 待批准列表保存在 `channels.json` 的 `pending`，白名单保存在 `allowlist`。
- 浏览器回包不返回 token、secret、原始凭据或内部异常详情。

## 本地凭据

- 微信 `botToken` 与其他渠道 Secret 一样优先写入 Host `ctx.credentials`，不会继续写入 `wechat-state.json`；旧版本明文 token 会在首次启动时迁移。
- Host 没有 credentials 服务时会回退到 `secrets.json`。POSIX 文件权限强制为 `0600`；Windows 继承当前用户目录 ACL。该文件仍含明文凭据，不应同步、共享或提交到版本库。
- `gateway.log` 只保留当前文件和一个轮转归档；对外聊天只显示通用错误，详细异常仅写本机日志。

## 报告

发现安全问题请走仓库的私下安全报告渠道，不要公开 issue。