# 安全策略

## 支持范围

| 版本 | 是否接收安全修复 |
|---|---|
| 0.2.x | ✅ |
| < 0.2 | ❌ |

## 这个项目接触哪些数据

本插件会把**用量计数**上报到你自己部署的团队服务器。请先明确边界：

**会上报**（每次一份聚合数字，不含对话内容）：

```json
{
  "displayName": "小明的 DSH",
  "machine": "PC-A",
  "monitoring": true,
  "project": "teamplugin",
  "projectPath": "D:\\Project\\DSHplugins\\teamplugin",
  "usage": { "tokens": 1200000, "cost": 3.5, "input": 800000, "cache": 300000, "output": 100000 },
  "lastUsedAt": 1790000000000
}
```

**绝不上报**：提示词、模型回复、文件内容、会话标题、代码、任何凭据。

**本机落盘**：`%DSH_HOME%/team-panel/state.json` —— 成员 ID、显示名、团队凭据（成员令牌）、
所选项目、各项目用量账本。**该文件含成员令牌，等同密码，不要提交或分享。**

## 信任模型

| 凭据 | 作用 | 泄露后果 |
|---|---|---|
| **邀请码**（8 位） | 加入团队 | 持有者可加入团队、看到全队用量 |
| **成员令牌**（48 位十六进制） | 以某成员身份上报数据 | 可伪造该成员的用量数据（服务器只存 sha256，无法反推） |
| **管理密钥**（32 位十六进制） | 打开管理页面、移除成员 | 可移除任意成员 |

- 成员令牌以 **sha256 哈希**存储在服务器数据文件里；服务器文件被拿走也还原不出令牌。
- 加入、上报、读快照都要求成员令牌；伪造令牌会被拒绝（有自检覆盖）。
- 邀请码空间为 31^8 ≈ 8.5×10¹¹，**没有限流**，因此邀请码本身必须当作秘密对待。

## 部署加固清单

自建团队服务器时，请至少做到：

- [ ] **优先用 Tailscale 之类的私有网络**，不要把 hub 直接暴露在公网；
- [ ] 若必须对公网开放，**前面套一层 HTTPS**（Caddy 自动证书最省事），否则邀请码与成员令牌明文过网；
- [ ] **不要把地址 + 邀请码发到公开渠道**（群公告、公开文档、截图里的 URL）；
- [ ] **不要提交 `data/` 与 `team-hub-data.json`**（已在 `.gitignore` 中）；
- [ ] 管理密钥只在本机使用，不要写进脚本或分享；
- [ ] 定期检查管理页面，移除已离职 / 不再使用的成员条目。

## 已知的设计取舍

- **团队服务器不校验数据真实性**：它信任持有成员令牌的一方上报的数字。这是"团队内部互信"模型，
  不是零信任模型——成员可以少报自己的用量。
- **无速率限制**：邀请码暴力破解在算力上不可行，但没有主动限流/封禁。
- **明文 HTTP 可用**：私有网络（局域网 / Tailscale）下这是有意的取舍；公网场景必须自己加 HTTPS。
- **`/admin` 页面用查询参数传管理密钥**：会出现在浏览器历史里。本机使用可接受，公网部署请注意。

## 报告漏洞

请**不要**通过公开 Issue 报告安全问题。使用 GitHub 的
[私密漏洞报告](https://docs.github.com/zh/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability)
（仓库 → Security → Report a vulnerability），或直接联系维护者。

报告中请包含：影响版本、复现步骤、影响范围、以及你建议的修复方向（可选）。

我们会在 7 天内确认收到，并在修复发布后致谢（如果你愿意署名）。