开发并审查多协议集成网关，不破坏权限检查

## 找到最近的指示，来源冲突时以正在运行的代码为准 先阅读仓库级指南，再为将要修改的文件查找最接近的领域专用说明。测试、插件、部署图表、文档、协议服务器和性能敏感型运行时可能各有不同的工作流。没有证据时，不要把一个领域的规则套用到另一个领域。 区分代码贡献者指南与最终用户运行时说明。为使用已部署系统的模型或客户端编写的材料，不会自动约束修改代码库的代理。 编辑前先梳理系统： - 应用入口点和环境配置。 - 验证模式、持久化模型和迁移。 - 业务服务、路由、中间件和协议传输。 - 身份验证、授权、插件和联邦边界。 - 测试、文档、部署资产和管理界面。 当信息来源相互冲突时，依次优先采用正在运行的代码和规范配置、受支持的构建目标和依赖项、环境示例，最后才是文档或注释。重复可能过时的数量或运行限制之前，应先确认当前实现。 优先检查有效源代码路径。除非请求明确包含，否则忽略临时工作区、日志、覆盖率输出、生成产物和延期任务文件夹。 ## 每次更改后运行项目检查和秘密检测 使用仓库支持的任务运行器和固定版本的工具链，不要用临时拼凑的标志直接调用底层工具。依据规范示例验证开发环境，运行必要的准备步骤或接口生成步骤，并选择与任务匹配的本地服务器或测试模式。 修改代码后： 1. 运行直接覆盖已更改语言和文件的格式、代码检查、类型、安全和文档检查。 2. 迭代期间使用聚焦检查，在提议完成之前再运行仓库要求的综合质量门禁。 3. 对于辅助系统语言或高性能运行时，运行其格式检查、将警告视为错误的代码检查器，以及相应的包或模块测试。 4. 当生成型管理资产或客户端资产的源文件发生变化时，重新构建这些资产。 5. 每项外部可见的行为更改都必须包含行为测试。 将秘密检测作为门禁。对于已核实的误报，仅在不会改变测试或示例行为的地方使用项目认可的行内抑制方式；否则应重新生成并审计获准的基线。绝不抑制真实凭据，也绝不把秘密写入已提交的配置。 优先扩展现有语言、构建和自动化技术栈。只有当项目现有能力无法安全满足具体需求时，才添加依赖项或新工具链。 ## 分别检查身份能看到什么、能做什么，未映射的路由默认拒绝 在每条受保护路径上维持两个相互独立的安全层： - 范围过滤决定某个身份可以看到哪些资源。 - 基于角色的授权决定该身份可以执行哪些操作。 通过其中一层绝不能替代另一层。平台公开范围表示平台内部的可见性，不等于允许互联网匿名访问。 通过一个规范策略函数统一处理每种令牌。对于自包含或旧版API令牌，缺少团队范围或团队范围为空时，必须按失败关闭原则降为仅公开范围可见；管理员绕过必须同时具备明确的绕过状态和已验证的管理员身份。对于基于会话的身份，服务器端持久化的成员关系和管理员状态具有权威性，令牌声明只能缩小访问范围。交集为空时必须按失败关闭原则处理。通过可信外部登录配置的身份也必须使用持久化的本地授权状态，而不能信任外部权限声明。 应用以下不变量： - 在建立传输会话或转发消息之前完成身份验证，然后在处理操作之前执行操作授权。 - 对没有明确授权映射的受保护路由默认拒绝。 - 从经过身份验证的服务器端状态推导所有权、团队和会话身份；绝不信任客户端提供的所有权字段。 - 绝不通过URL查询参数接受入站客户端凭据。 - 高风险传输和不受限制的跨域路由必须默认禁用。 - 跨网关流量必须使用明确的域名允许列表；空允许列表会阻止所有目的地。 - 通信双方的网关必须信任同一个签发者，并且只传递远程授权所需的凭据。 对于委托令牌交换，绝不把用户的入站令牌转发给下游服务。通过可信授权服务器进行交换，并且只转发交换后的令牌。将配置的交换目的地视为SSRF和出口边界：保存配置时验证目的地，只允许特权身份更改配置，记录关联标识符，并且绝不记录原始入站令牌或交换后令牌。 涉及安全的更改必须包含以下拒绝路径的回归测试：未通过身份验证、范围错误、权限不足、功能已禁用、目的地不受允许，以及其他应拒绝的情况。 ## 让跟踪和审计日志的写入与主事务分开 修改持久化代码前，先了解预期的事务边界。请求数据、可观测性记录和审计记录可能有意使用不同的会话和原子性保证。 尽力而为的可观测性写入可以使用立即提交的短期独立会话。这样即使主请求失败，也能保留跟踪和事件；但这也意味着遥测数据与请求不具备原子性，并且可能显示部分完成或仍在进行的状态。查询操作仍应使用请求作用域会话，以应用可见性和授权过滤。 审计日志也可以拥有自己的会话并隔离自身故障。不要仅为方便就把请求中已经提交的会话传给独立审计写入器；第二次提交或回滚可能使共享事务失效，并可能在主要资源已经持久化后向外暴露错误。如果审计记录必须与主要写入保持原子性，应将其视为需要审查、新故障语义和测试的明确设计更改。 独立跟踪可能为每个请求创建多个数据库会话。应测量并发量、监控连接池耗尽信号，并根据实际数据库和工作负载调整连接池大小，不要照搬固定容量说法。 没有证据时，不要把异步处理程序中有意采用的同步持久化策略判定为孤立缺陷。只转换个别调用点可能造成语义混杂；应改为提出协调一致的驱动程序和事务迁移方案。 ## 先确认当前迁移头，再添加数据库迁移 创建迁移前，先查询当前迁移头。新修订的父级必须引用这个已经验证的迁移头；绝不猜测，也不要从旧文件复制父级标识符。创建后，确认迁移历史仍然只有一个预期的迁移头。 当安装状态可能不同时，迁移步骤应具备幂等性。修改前检查当前模式；可选表不存在时安全跳过；避免添加已经存在的列或对象。保持全新数据库创建路径与升级路径一致。 如果降级依赖运行时配置，应使其具备封闭可复现性： 1. 升级期间，把每个必需的配置值存入以修订为键的迁移专属元数据。 2. 降级期间读取已保存的快照，而不是读取当前环境。 3. 只有对于在快照机制出现之前已完成升级的数据库，才把实时配置用作有文档说明的兼容性后备方案。 4. 降级完成时移除该快照。 如果迁移读取配置只是为了写入升级初始数据，而降级并不依赖该值，就不需要创建降级快照。 编辑后再次验证迁移头，并运行相关迁移测试和应用测试。如果目标数据库落后，应在生成新修订之前，把受控的开发或测试数据库更新到预期迁移头。没有明确授权和经过审查的计划，绝不能对生产环境执行这种纠正性升级。 ## 确认实际检查结果，推送前先获得许可 依据原始请求、最接近的领域指南和上述安全不变量审查最终差异。在适用时，确认代码检查、类型、安全扫描、测试、迁移、生成资产和文档的实际结果。不要仅凭查看代码就声称成功。 使用仓库要求的提交规范、签名策略、议题链接和拉取请求模板。在获得明确授权之前，不要推送、强制推送、修改贡献者分支或更改项目外部状态。 撰写公开审查意见和议题评论时： - 先说明哪些内容运行正常，再提出疑虑。 - 将阻塞性发现、建议和次要备注分开。 - 解释风险并提供问题或选项，不要发出不必要的命令。 - 表达应直接，但不要严厉或机械。 不要在产品差异或公开消息中加入内部助手署名、隐藏的运行说明、凭据或推测性工作量说法。只有在更改确实需要时，才创建新文件或文档。 分派工作时，应区分等待报告者提供信息的请求、存在依赖阻塞的任务，以及已接受但延期的事项。只有解决问题的更改已经合并后，才能把议题标记为已解决；仅在本地完成实现还不够。 完成前，确认敏感值仍在版本控制之外、安全拒绝路径已有测试、遵循了事实来源优先级，并且没有无关的临时内容进入差异。