# 安全政策

中文 | [English](docs/SECURITY.en.md) | [日本語](docs/SECURITY.ja.md) | [偽中国語](docs/SECURITY.pcn.md)

## 支持的版本

本插件随 DeepSeek Harness（DSH）宿主运行，**只有最新的 `main` 分支**接受安全修复。
历史提交不单独维护——如需旧版本，请自行 fork 并自行承担维护。

## 报告漏洞

请**不要**通过公开 issue 报告安全问题。请使用 GitHub 的
[私有漏洞报告](https://github.com/Kihara777/dsh-api-balance/security/advisories/new)
渠道，或发送邮件至维护者。

报告中请尽量包含：受影响版本 / 提交、复现步骤、期望与实际结果，以及你认为的
威胁模型（谁能触发、需要什么前置条件）。

## 响应时限

维护者（狐莉）为一级视力残疾，日常使用视障辅助智能体协作开发。我们尽力在
**7 天内**给出首次回复，复杂问题的完整评估可能更久——但**每一条都会得到回复**。

## 已知的设计边界

以下**不是**漏洞，而是有意为之的行为，报告前请先确认：

| 项 | 说明 |
|---|---|
| 从浏览器 Local Storage 读取平台令牌 | 「平台令牌」默认从**本机浏览器登录态自动扫描**取得，**默认开启且可在设置中关闭**；仅读取令牌，不采集浏览器内其他数据，令牌以 `0600` 落盘 |
| 令牌扫描的 6 小时节流 | `config.browserScanIntervalMs` 默认 6 小时；节流窗口内不重扫，但会回传上一次扫描报告 |
| 余额 / 用量查询需访问外部 API | `/user/balance` 与用量统计以插件配置的令牌请求 DeepSeek 官方接口——这是该插件的**核心功能**，非数据外泄 |
| 端点走 DSH 的 `/api` 通道 | 本插件的 HTTP 端点由 **DSH 宿主**提供认证与 Host authority（`trustedHosts`）边界；插件不自建认证层 |

## 已评估的外部报告（含关闭项）

以下报告均已经**逐条复核**并公开回复证据。**列出它们是为了让后续报告者不必重复提交同类问题**——
若你认为某条结论有误，欢迎指出，我们会重新评估。

| 编号 | 报告内容 | 结论 | 依据 |
|------|---------|------|------|
| PR #4 / #5（@anupamme，经扫描器自动生成） | 称 `/token`、`/token/clear`、`/voicepack`、`/tts` 缺少速率限制 | **误报，未合并** | 见下节「关于缺少速率限制的报告」 |
| PR #4 / #5 附带项 | 称 `/query` 缺少请求体体积上限 | **误报，未合并** | 该防护早已由 `readJsonBody` 的 **64 KiB** 上限提供（`lib/index.js`）；其新增的 `content-length` 检查可被 chunked 编码绕过，`text.length` 又是 UTF-16 码元数而非字节数 |

### 关于缺少速率限制的报告

多次扫描报告称若干端点缺少速率限制。**逐条核对后判定为误报**，理由如下：

**① 报告描述与 diff 不符。** PR 声称影响 `/token`、`/token/clear`、`/voicepack`、
`/tts` 四个端点，但其 **diff 实际只改了 `/query`** 一个路径。

**② 其限流键在本部署形态下不成立。** PR 用 `x-forwarded-for` 作为客户端标识，
而该头**由客户端自行提供、可任意伪造**；更关键的是，本插件的调用来自
**同源页面经 DSH `/api` 通道的 RPC**，该路径**不携带 `x-forwarded-for`**——
所有本机请求会落入同一个 `"unknown"` 桶，**正常用户反而会先被自己的限流挡住**。

**③ 关键端点已有节流。** `/token` 已有 **6 小时**服务端节流
（`browserScanIntervalMs`）；语音播报有 **30 分钟**限流。

**④ 本插件没有高频轮询。** 源码中唯一的 30 秒 `setInterval` 执行的是
`isPeakPricing()`（**纯本地时间判断**，用于峰谷计费提示），**不发任何网络请求**；
另有 15 分钟间隔的惰性轮询。按人类操作频率估计，最活跃的使用方式约为
**每分钟 5~10 次**——扫描器建议的 30 次/分钟已是其 3~6 倍，真人操作基本无法触达。

**⑤ 真正的边界不在应用层。** 端点的可达性由 **DSH 宿主的认证 + Host authority**
决定。能突破该边界者不会被一个每分钟 30 次的限制挡住；而该限制会误伤正常的
刷新操作（用户等待余额刷新时连续点击属正常行为）。

**结论与取舍**：**不为此改动代码**。若将来确实需要一层防御，正确做法是
**按认证主体而非 IP** 限流（IP 可伪造），且阈值须**远高于任何人类操作**
（如 60~120 次/分钟），定位为「防失控脚本」而非「防攻击」——并且应优先加固
宿主侧的边界，而非在应用层加一个既防不住谁、又可能误伤真人的限制。

> **欢迎指出上表结论有误**，并附可复现证据。我们按「先复核、再答复、附证据」
> 处理，而非直接照单接受。

### 关于重复提交

**上表已列出的同一结论，若再次提交且未提供新证据，将直接关闭并指向本节。**

| 会被受理 | 会被直接关闭 |
|---------|-------------|
| 上表未涵盖的**新**问题 | 与上表同一结论、且无新证据的重复报告 |
| 指出上表某条结论**有误**，并附可复现证据 | 仅重述上表已有结论 |
| 相同主题但有**不同的**威胁模型或可利用路径 | 同一规则的再次自动扫描输出 |

## 供应链说明

- 本仓库**不含**任何密钥；平台令牌在运行时从配置或本机浏览器登录态取得，
  以 `0600` 落盘于用户目录
- 不发布 npm 包（维护者视障，暂无法独立完成 npm 提交流程），
  经 GitHub 源码安装，或经 [NixKits](https://github.com/Kihara777/NixKits)
  的薄封装声明式安装

## 致谢

感谢所有认真复核并提交报告的研究者。即便报告最终判定为误报，
**复核过程本身也会带来真实改进**——上表中的体积上限核对即为一例。