oh-my-muse/.agents/rules/security-and-reliability.md

规则:安全与可靠性 —— 可信边界、故障路径、可观测

类型:硬约束(rules) · 状态:生效 2026-06-19 · 门禁:现有测试/契约/边界门禁 + 代码评审兜底 上位:verification-and-anti-false-green.md、engineering-conventions.md 来源:蒸馏 docs/dev-baseline/global/05-安全开发规范.md、06-日志与可观测性规范.md,并吸收项目当前“真实后端/真实 PG/外部依赖 fail-closed”经验。

---

一、可信边界

• 认证、授权、租户隔离、数据归属校验必须在后端可信边界执行;前端隐藏按钮或本地状态不算安全控制。
• /admin-api/** 与 /app-api/** 必须保持调用身份隔离;管理员能力不得经 app API 暴露,普通用户能力不得依赖 admin 端兜底。
• 查询和写入必须带可信的 tenant_id / user_id / owner 条件;不得信任前端传来的 owner、tenant 或权限声明。
• AI runtime 不得自授权。授权事实必须来自授权/权限端口或已验证的快照,运行时只能消费;当前由 AiGrantRuntimeBoundaryArchTest 守住 runtime/任务执行侧不得直接依赖 ToolGrant 写模型,完整 grant/runtime 物理包拆分另行推进。

---

二、输入、文件与数据保护

• 所有外部输入必须校验:HTTP 请求、文件上传、SSE/WebSocket 消息、异步事件、外部回调都算外部输入。
• 优先使用框架校验与结构化解析;禁止用字符串拼接 SQL,禁止用正则/字符串切割代替可靠 parser。
• 文件路径、文件类型、文件大小、内容签名/格式都要校验;只看扩展名不够。写文件必须考虑部分写入、清理和路径穿越。
• 密码、token、API key、PG 密码、临时签名、授权快照不得写入代码、提交记录、日志、响应或错误信息。
• 用户隐私字段必须脱敏后展示或记录;完整手机号、邮箱、证件号、银行卡号不得进入普通日志。

---

三、外部依赖与异步可靠性

• 涉及外部服务、模型调用、对象存储、支付、通知、消息队列、异步任务时,必须设计超时、失败、重试、幂等、补偿和审计路径。
• 外部依赖未配置时必须 fail-closed:拒绝执行并给出可追踪错误,不得静默降级成假成功。
• 写路径必须有幂等键或命令记录;重试不得重复扣费、重复发放权益、重复创建投影或重复发送不可撤销通知。
• 异步投影必须有源事件、处理状态、重放或补偿策略;只写一侧而无法读回的设计不得声称端到端完成。
• 事务边界必须明确:跨 BC 写入优先通过端口/事件/投影,不得用跨域 DAL 拼接一个大事务。

三.A 跨域资产物化(market 安装下游物化特有红线)

由来:market KB 物化 D0-fork(见 ../knowledge/market-install-downstream-materialization.md)。把市场资产物化成下游可用实体时,以下三条是会导致静默失效或私有泄露的具体红线,是 §一/§三 通用原则在本场景的硬化,不得重蹈。

• 本地实体的本地键不得存外域 id:把市场资产物化成本地实体时,本地表的主键/外键(如知识库绑定的 kb_id)必须落本地新建/复用的主键,绝不能把市场资产 id 直接当本地主键写入。否则后续按本地键的查询永远落空,且表现为"无报错的静默省略"(检索 no_dataset),极难排查。外域 id 只能存进专门的来源引用列(如 source_market_asset_id)。
• 跨可见性隔离必须靠物理隔离,不得依赖运行时过滤字段:当一份数据源同时含公开与私有内容、且生命周期不冻结(发布后仍可加私有内容)时,隔离必须靠物理分离出只含公开快照的副本让消费方只读副本,不得依赖外部运行时的 metadata/过滤参数做隔离——这类参数可能字段名错配被静默忽略(RAGFlow metadata_filter vs metadata_condition 即是,见外部依赖坑),一旦失效就是私有泄露。隔离是安全边界,不能押在一个"可能不生效"的外部入参上。
• 物化前置依赖未就绪必须 fail-closed:物化依赖的下游副本/资源处于中间态(如 fork 的 pending/partial/failed)时,必须拒绝建立绑定并给可追踪错误,绝不建出"绑了但用不了"的迷惑态实体(这是 §三"未就绪不得静默降级成假成功"在物化场景的落点)。

---

四、日志、审计与追踪

• 关键业务状态变更、管理员操作、安全敏感操作、外部调用必须留下可追踪记录:who、what、when、where、result、commandId/traceId。
• ERROR 日志必须包含异常堆栈和足够定位的上下文;WARN 用于可恢复异常、降级、重试;INFO 记录关键业务事件;DEBUG 只用于开发诊断。
• 日志禁止输出大段正文、完整 prompt、完整 token、完整密钥、完整隐私字段。AI prompt 只记录模型、token 数、任务 ID、摘要性上下文。
• 前端请求应携带请求 ID 或等价关联信息;SSE/长连接需有 connectionId 关联事件流。
• 审计日志不得被业务普通删除路径修改或清除;敏感操作需要记录变更前后关键值或可重建来源。

---

五、故障处理与回滚

• 发现安全漏洞、数据错写、权限绕过、外部依赖异常时,先止血并保留证据,再修复;不得用“刷新缓存/重跑脚本”掩盖根因。
• 不可简单回滚的动作(删数据、发通知、扣费、授权发放、第三方永久写入)必须有人类确认、备份或补偿方案。
• 数据迁移必须可验证:迁移前后行数/关键约束/抽样数据有证据;大批量迁移要分批、可中断、可恢复。
• 配置变更应可独立回滚;敏感配置只通过仓库外环境或密钥系统注入。

---

六、机械门禁与人工评审边界

约束	机械落点
跨 BC 不直连他域实现 / DAL	BcBoundaryArchTest
AI runtime 不得自授权 / 不得直连 Tool Grant 写模型	AiGrantRuntimeBoundaryArchTest
API/DB 契约与迁移卫生	ContractFirstGateTest + openapi-diff
completed 必须有测试证据	P1rApiCoverageReportTest
真实 PG / 外部依赖 fail-closed 证据	P1r*IT 与总账证据
跨域物化:私有不泄露 + forkStatus fail-closed	P1rMarketKbForkMaterializationIT(真 PG + 真 RAGFlow 证私有探针不泄露 + AFTER_COMMIT 时序);kb_id 去污染目前由该 IT + 代码评审兜底,无独立 ArchUnit
.agents 规则索引	AgentsInfraIntegrityTest

目前尚无全量静态密钥扫描、SAST、依赖漏洞扫描门禁。涉及密钥、权限、支付、对象存储、模型调用、通知、生产数据迁移的变更,在补机械门禁前必须作为人工评审高风险项处理。