docs(aios-v2): add ADR-004 tenant isolation decision

2026-07-20 11:53:04 +08:00
parent f23b694ad3
commit efd99e620c
1 changed files with 58 additions and 0 deletions
@@ -0,0 +1,58 @@
+# ADR-004: 多租户隔离默认拒绝
+
+- Status: Accepted
+- Date: 2026-07-20
+
+## Context
+
+AIOS V2 同时承载 Web 请求、控制面状态、OpenClaw 命令、Hermes 队列、执行证据、审计和 GitOps 状态。任何一层缺失租户边界都可能造成数据泄露或跨租户副作用。
+
+## Decision
+
+多租户隔离采用“显式上下文 + 默认拒绝 + 全链路传播”模型。
+
+每个控制请求至少包含：
+
+- `tenant_id`
+- `principal_id`
+- `trace_id`
+- `policy_version`
+
+每个执行请求还必须包含：
+
+- `task_id`
+- `command_id` 或 `job_id`
+- `idempotency_key`
+
+Hermes 额外使用：
+
+- `cell_id`
+- `profile_id`
+- `worker_id`
+
+## Enforcement
+
+- API 不信任客户端提供的租户覆盖值；可信代理删除同名头后重新注入。
+- Control Plane 所有资源带不可为空的 `tenant_id`。
+- OpenClaw 签名覆盖 tenant/task/trace/payload。
+- Hermes 按 tenant/cell/profile 分区 claim。
+- Audit 与 Execution Evidence 只按当前租户查询。
+- 跨租户访问返回拒绝或“未找到”，不得泄露资源存在性。
+- Secret、Cache、Memory、Artifact、Logs 和 Metrics 均使用租户命名空间。
+
+## Consequences
+
+优点：
+
+- 统一安全模型；
+- Runtime 无法绕过租户边界；
+- 负向测试可自动化。
+
+成本：
+
+- 所有接口和数据模型必须传播租户上下文；
+- 生产数据层必须增加 RLS 或物理隔离证据。
+
+## Compliance
+
+任何新模块没有显式 `tenant_id`、负向测试或审计映射时，不得进入 Candidate。