该 API 的设计前提是：每一次调用都可能产生直接的财务影响，并可能访问敏感的服务器凭据。因此安全要求显著高于一般 REST 默认水平。
已部署的安全控制
- HMAC-SHA256: 每个请求都使用 HMAC-SHA256 对方法、路径、时间戳、随机数与请求体哈希进行签名。验证过程采用恒定时间比较（hash_equals）。
- AES-256-GCM: 密钥仅以 AES-256-GCM 密文形式持久化存储（libsodium）。主密钥保存在数据库之外，位于 /etc/kh-reseller-api/master.key.v{N}。
- Replay protection: 时间戳容忍窗口 +-300 秒，随机数缓存 600 秒。已成功签名的请求无法再次发送。
- Scope-based authorization: 每个密钥拥有显式的权限范围列表。写入类与敏感类权限范围必须显式启用。
- IP whitelist (optional): 每个密钥可选配置 IP 白名单（CIDR 表示法，支持 IPv4 与 IPv6）。
- Rate limit: 多层速率限制：按密钥（分钟与日）与按 IP（分钟）分别计算。令牌桶算法，允许一定突发。
- Idempotency: 订单与具有破坏性的服务操作必须携带 Idempotency-Key，提供 24 小时重放保护，应对网络重试。
- Tenant isolation: 每条数据库查询都强制按您的账户 ID 过滤。跨租户访问在设计上完全不可能。
- Tamper-evident audit log: 每个请求都写入审计日志并附带链式哈希（chain_hash[n] = sha256(chain_hash[n-1] || row_n)）。事后篡改会导致哈希断裂，可立即被发现。
- Credentials.read alerting: 每次 credentials.read 调用都会生成专门的审计条目，并可选向账户所有者发送确认邮件。
- SSRF-guarded webhooks: Webhook URL 在保存前会经过校验：仅允许 HTTPS，DNS 解析必须仅返回公网 IP（禁止 RFC1918，禁止链路本地地址）。
客户侧最佳实践
- 将 secret 保存在密钥管理工具中（HashiCorp Vault、AWS Secrets Manager、Doppler、1Password），切勿写入代码，切勿提交至 Git 仓库。
- 定期轮换 secret（至少每年一次，或在人员变动后轮换）。在客户门户中一键完成轮换，旧 secret 立即失效。
- 每个使用场景使用专用密钥，并赋予最小权限范围（条件允许时使用只读）。避免「万能权限」密钥。
- 如果您的集成从固定 IP 运行（云平台、堡垒机），请设置 IP 白名单。
- 在服务器端生成并持久化 Idempotency-Key，切勿在每次重试时重新生成。建议：每笔逻辑订单使用一个 UUIDv4。
- 将 Webhook 指向您自己的 URL，至少监听 order.created 与 credentials.read 事件流。
安全披露
请将安全问题通过保密渠道报告至 security@kernelhost.com。如需 PGP 公钥可索取。承诺 24 小时内响应。漏洞赏金计划正在筹备中。
