superior-api-security

卓越的 API 安全

在服务器端信任边界保护 API，同时保留其文档化契约。根据实际参与方、资源、业务影响、部署拓扑和现有安全架构制定控制措施；不要仅凭清单添加安全中间件。

明确安全契约

修改代码前，先确定：

• 暴露的操作、版本和调用方；
• 公共、已认证、特权、内部、Webhook 和机器对机器调用方；
• 敏感资源、属性、操作和业务流程；
• 身份在何处建立，授权在何处执行；
• 代理、网关、缓存、队列、第三方服务和出站网络访问；
• 预期流量、突发行为、载荷大小、操作成本和故障容忍度；
• 哪些安全控制由基础设施负责，哪些由应用负责。

追踪实际请求路径。在配置和行为得到验证之前，不要假定网关、框架默认设置或客户端检查能够满足要求。

根据风险选择控制措施

阅读 references/api-security-controls.md，了解身份验证、对象／功能／属性授权、输入和输出边界、资源消耗、敏感业务流程、SSRF、面向浏览器的控制措施、错误、机密、清单和第三方 API 调用。

优先采用能够阻止调用方执行以下操作的控制措施：

• 冒用其他身份或超出其授权范围行事；
• 读取或修改属于其他主体的对象；
• 设置或接收其无权访问的属性；
• 调用特权操作或绕过工作流约束；
• 耗尽计算、存储、带宽、付费集成或稀缺库存；
• 诱使服务器联系非预期目标；
• 通过响应、日志、时序或元数据获知敏感内部信息。

保留维护中的身份、加密、架构验证和机密管理库。不要自行设计令牌格式、签名方案、密码存储方式或加密协议。

当会话、不记名令牌、刷新或重置凭据、API 密钥、签名 Webhook、密钥轮换、吊销或防重放机制属于范围时，请阅读 references/session-token-and-webhook-security.md。

谨慎实施速率限制和滥用控制

当速率限制、节流、配额、并发限制、凭据攻击、抓取、垃圾信息、枚举、昂贵操作或敏感业务流程自动化属于范围时，请阅读 references/rate-limiting-and-abuse-controls.md。

有效的限制应明确以下所有内容：

• 要控制的操作和危害；
• 用于计量的身份维度；
• 持续额度、突发额度、并发量和成本权重；
• 计数器的存放位置，以及分布式实例如何协调；
• 限流器或计数器存储故障时的行为；
• 拒绝请求的约定、可观测性、豁免和恢复路径；
• 能证明限制有效且允许合法突发流量的测试。

仅按 IP 统计请求数，很少足以应对已认证或分布式滥用。请求速率也无法限制载荷大小、查询复杂度、批次大小、执行时间、下游成本或并发工作量。

确保响应和遥测安全

• 使用既定的 HTTP 语义和项目的错误架构。对于应用层速率限制拒绝，返回 429 Too Many Requests；如果已知有意义的重试时间，则包含 Retry-After。
• 向客户端提供稳定且可操作的错误标识符，但不要泄露堆栈跟踪、机密、查询内容、内部主机名、令牌内容或授权策略详情。
• 记录与安全相关的结果，并在允许的情况下关联请求或跟踪信息、主体和租户标识符、控制决策以及经过清理的原因代码。
• 不要记录凭据、会话令牌、API 密钥、原始授权标头、密码重置凭据或不必要的敏感载荷。
• 将客户端可见的详情与诊断详情分开，并遵守仓库的隐私和保留规则。

声称具备防护前先验证

阅读 references/security-verification.md，了解由威胁驱动的测试矩阵，其中包括授权失败、令牌验证、架构变更、资源限制、限流器行为、并发、SSRF、错误信息泄露和代理边界检查。

完成安全工作必须在实际生效的执行点提供证据。运行范围最小且有意义的自动化测试，以及能够覆盖已部署路径的配置或集成检查。对于仅涉及设计的工作，应将测试标注为拟议的验证计划，而非防护证据。报告由其他位置强制执行的控制、未经验证的假设、推出风险，以及发布后所需的监控。

有针对性地组合技能

• 当安全只是更广泛的差异、分支或拉取请求审查中的一个风险领域时，使用 superior-code-review。
• 当工作还会改变业务不变量、持久化、事务、幂等性或领域行为时，使用 superior-logic。
• 当执行依赖于租户范围的架构、约束、查询归属、索引、迁移或敏感数据存储时，使用 superior-database。
• 当与安全相关的资源控制需要通过具有代表性的容量、延迟或饱和度测量来验证时，使用 superior-performance。
• 当安全边界由流水线身份、制品来源、发布流程或部署凭据决定时，使用 superior-delivery。
• 当滥用、依赖故障或恢复必须满足明确的可用性目标时，使用 superior-reliability。
• 当负向安全测试夹具、隔离、并发或已部署边界测试设计是主要关注点时，使用 superior-testing。
• 当安全模型、公开契约、运维配置或与事件响应相关的流程发生持久性变更时，使用 superior-docs。
• 使用 superior-lean 避免不必要的安全机制，但绝不要简化掉已识别风险所需的控制。

未经明确授权，不要将安全审查扩大为无关的渗透测试、基础设施变更或生产流量实验。