# 安全与上线检查

## 凭证保管

API Key 授予持有者对应能力。保存在服务端密钥管理系统或受限制的环境变量中；避免在浏览器、移动客户端、玩家可下载模组、错误堆栈和聊天记录中出现。将日志中的 Authorization 头和 `#token=` 邀请片段清除。

Webhook 密钥与 API Key 是两种不同凭证：前者只用于验证通知签名，后者用于请求 API。不要交换用途，也不要把 API Key 作为回调验证密钥。

## 最小权限

- 只展示结果的机器人通常只需要 `public:read` 或 `records:read`。
- 只生成邀请的服务可使用 `invitations:write`；需要查看认领状态时加 `invitations:read`。
- 显示工单状态增加 `tickets:read`；显示剩余次数增加 `entitlements:read`。
- 每个组织、每个独立部署使用不同凭证，便于归属和撤销。
- 不让普通用户通过传入任意组织 ID 驱动一个全权后台代理。

## 平台防刷与客户端责任

平台在认证查询前做边缘突发限制，再原子检查密钥、账号、组织的分钟及每日共享配额。邀请创建有额外的分钟、小时、日配额；工单桥接有并发上限和超时。凭证变更、Webhook 验证、测试及重发有独立限制。具体阈值和响应头以[限流说明](/conventions/)为准。

请求体、路径、查询和分页都有大小上限；不接受 URL 凭证、重复或未知查询参数、压缩请求体。限流错误合并采样，避免一条恶意请求引出多条永久日志。Webhook 仍要求接收端所有权验证、公网 HTTPS、每次 DNS 检查、禁止重定向、签名及有限重试。

这些保护约束业务处理及存储放大，不能保证所有流量都在 Worker 调用前被拦截，也不是云平台费用的硬上限。接入方仍应在自己的入口验证操作人、限制玩家触发频率，并用有界队列、退避和凭证撤销应对异常。

## 数据处理

公开接口不意味着每项业务数据都可以无限复制。组织接口返回的是该组织授权范围内的数据。业务结束或权限撤销后，应依照自己的授权和数据管理要求清理不再需要的副本。

用户提供的公开备注、玩家名称等仍是不可信文本。网页展示时转义，机器人输出时防止提及所有人或格式注入，不把它们拼进 SQL、命令行或 AI 系统指令。

不要仅凭名字匹配就自动封禁玩家，也不要把 `warning` 转成 `cheating`。保留人工复核能力，并同步记录更正和删除。

## Webhook 接收端

按原始字节验签；校验时间戳；按事件 ID 持久化去重；严格核对组织。返回 2xx 前确保业务事件已处理或可靠入队。失败时返回非 2xx，让平台重试。

如果已返回 2xx 后还需要后台处理，必须使用自己的持久队列。示例中的 SQLite 收件箱适合单实例演示；多实例部署应使用共享数据库，并让收件箱写入和业务状态更新具备事务或可靠幂等语义。

## 上线前逐项验证

1. `/v1/me` 中的组织 ID 与应用配置一致。
2. A 组织密钥请求 B 组织时收到 403，且应用不会自动换组织。
3. 缺少 scope 时显示可理解的授权错误。
4. 使用同一请求编号重试邀请不会多开，改变正文会收到 409。
5. 密钥撤销、过期及创建者失去组织管理员身份时，应用停止对应任务。
6. Webhook 错误签名、过期时间戳、错误组织和重复事件都有测试。
7. 模拟接收端 500 和超时，确认重试不会重复执行业务动作。
8. 处理结果更正、删除、工单重开以及未找到记录。
9. 配置定期核对与失败告警，日志中不包含凭证或完整邀请链接。

## 凭证泄漏

立即在个人中心撤销对应密钥或停用回调，检查最近调用和投递记录，创建替代凭证并重新部署。修改密码会撤销该账号全部开发者凭证；正常轮换单个集成时，可以只撤销相关密钥。