aios/docs/aios-v2/adr/ADR-009-provenance-least-privilege.md

ADR-009：Workflow Provenance 与最小权限子 Grant

• 状态：已采纳
• 日期：2026-07-21
• 决策范围：AIOS V2R1 生产授权、Runtime 调度、Evidence、Git、部署、回滚与审计

1. 背景

早期候选实现使用一个 Run Provenance 同时承载身份绑定和七类生产操作权限。该模型可以证明一次执行来自哪个租户、任务、Agent 与 Principal，但同一凭证能够授权 Runtime、Evidence、Git、部署、回滚、审计和代码变更，违反最小权限原则。任何持有该凭证的进程都可能获得超出职责的能力。

同时，Runtime Result 回写、Git 写入和部署包装器需要可撤销、可过期、可重放防护且可持久恢复的独立授权。仅依赖进程角色或环境变量不足以形成可审计的生产信任链。

2. 决策

采用两层 Provenance 模型：

1. Workflow Provenance 只绑定 run_id、tenant_id、task_id、agent_id、principal_id、签发者、TTL、Key ID、Nonce 和签名，不授予任何操作路径。
2. Provenance Grant 由 Workflow Provenance 派生，每个 Grant 只绑定一个 ExecutionPath，拥有独立的 TTL、Nonce、状态、撤销和重放记录。
3. Git Grant 还必须显式限定允许的 GitOperation，例如只允许 READ_REF 而不允许 PUSH。
4. 子 Grant 的身份字段必须与父 Workflow 完全一致，且子 Grant 的有效期不得超过父 Workflow。
5. 父 Workflow 被撤销或过期后，其全部子 Grant 自动失效。
6. 授权使用 (grant_id, execution_path, git_operation, request_digest) 建立唯一使用记录，重复请求默认拒绝。

3. Grant 类型

GrantType	唯一允许路径
code_change	code_change
git	git_operation
deployment	deployment
runtime	runtime_execute
evidence	evidence_write
rollback	rollback
audit	audit

Grant 类型与路径不一致时，构造阶段即拒绝。非 Git Grant 不得包含 Git 操作；Git Grant 未声明具体操作时不得签发。

4. 服务级 Scope

生产进程不得加载全部 Grant。ScopedLeastPrivilegeProvenanceWriter 只接受当前服务声明的路径和对应 Grant ID，多余 Grant 映射会导致启动失败。

默认 AIOS Application Scope 仅包含：

• runtime_execute
• evidence_write
• audit

Git、部署、回滚和代码变更必须由独立进程或包装器显式声明自己的单一路径 Scope。运维 CLI 的一次授权命令只接受一个 --grant-id，并要求它与 --path 一致。

5. Runtime 与 Dispatch 绑定

Runtime 执行还必须经过持久化 DispatchRecord。记录至少绑定：

• dispatch_id
• tenant_id
• task_id
• agent_id
• principal_id
• runtime
• runtime_execution_id
• trace_id
• provenance_id
• run_id
• authorization_id

OpenClaw/Hermes 结果只有在上述上下文完全匹配时才能由 Orchestrator 更新 Task。公开 Task API 不允许直接把任务推进到 RUNNING、COMPLETED 或 FAILED；Hermes 结果只通过内部 Runtime Reconcile 入口处理。

6. 密钥与签名

Workflow Provenance、子 Grant 和 OpenClaw Command 均采用 Ed25519。生产应用只读取公钥；私钥仅存在于受保护的签发端或 systemd credential。Git、日志、环境模板和审计中不得出现私钥内容。

Key ID 用于选择受信任密钥，不包含密钥材料。公钥 Fingerprint 使用恒定时间比较。OpenClaw Command 合同版本为 aios.openclaw.command.v2。

7. 备选方案

7.1 单一全权限 Provenance

拒绝。实现简单，但任何服务泄漏都可能获得全部生产能力，无法独立撤销 Runtime、Git 或部署权限。

7.2 仅依赖 RBAC

拒绝。RBAC 可以限制 API 调用者，但不能把具体 Run、Task、Agent、请求摘要和 Runtime Result 绑定到一次可验证授权。

7.3 每个操作重新签发完整 Workflow

拒绝。会复制身份数据和生命周期状态，难以统一撤销整次工作流，也增加签发和审计复杂度。

8. 正面影响

• 服务与操作权限按职责隔离。
• Runtime、Evidence、Git、部署、回滚和审计可以独立撤销。
• 父 Workflow 可作为整次 Run 的紧急停止开关。
• SQLite 持久化支持重启后的授权与 Dispatch 恢复。
• Receipt 明确记录 Grant、Scope、请求摘要和授权时间。
• Git Index 只有在 Grant 授权完成后才允许修改。

9. 负面影响与风险

• 签发和部署配置比单凭证模式复杂。
• 每个生产服务必须配置正确的 Grant ID。
• Grant 状态与 Dispatch 状态需要备份、迁移和容量治理。
• 当前候选实现使用 SQLite；高可用生产部署仍需外部持久化和并发容量证据。
• OpenClaw callback 目前只作为非权威审计事件；状态变化仍必须经过 Orchestrator 严格 Reconcile。

10. 迁移与回滚

迁移步骤：

1. 签发无操作权限的 Workflow Provenance。
2. 按所需路径签发独立子 Grant。
3. 为每个服务配置其最小 Grant ID。
4. 启用 AIOS_REQUIRE_RUN_PROVENANCE=true。
5. 验证 Scope 拒绝、撤销、过期、重放和重启恢复测试。
6. 完成预发布 Acceptance 后，禁止旧全权限 issue 命令进入生产流程。

回滚仅允许回到前一个已验证候选版本，不得回滚为生产全权限 Provenance。状态恢复必须保留父 Workflow、Grant 使用记录、Dispatch 和 Receipt，防止旧授权被再次使用。

11. 合规检查

必须满足：

• 父 Workflow 无操作路径。
• 子 Grant 只包含一个路径。
• 生产服务只加载职责所需 Grant。
• 上下文不匹配、签名错误、过期、撤销和重放全部 fail closed。
• Runtime Result 必须匹配持久 Dispatch。
• 测试与文档在同一分支提交。
• 正式 Gate A 结论必须基于实际执行 Acceptance，不得仅凭测试文件存在声明通过。

12. 受影响资产

代码：

• active-runtime/app/aios_v2/provenance.py
• active-runtime/app/aios_v2/provenance_grants.py
• active-runtime/app/aios_v2/provenance_scoped.py
• active-runtime/app/aios_v2/provenance_operations.py
• active-runtime/app/aios_v2/provenance_cli.py
• active-runtime/app/aios_v2/dispatch_store.py
• active-runtime/app/aios_v2/orchestrator.py
• active-runtime/app/aios_v2/execution_tracking.py
• active-runtime/app/aios_v2/provenance_git.py
• active-runtime/app/aios_openclaw/contract.py

测试：

• tests/aios_v2_candidate/test_provenance.py
• tests/aios_v2_candidate/test_provenance_grant_isolation.py
• tests/aios_v2_candidate/test_candidate_flow.py

部署与文档：

• deploy/aios-v2/env/aios-v2.env.example
• docs/aios-v2/04-MODULE-CONTRACTS.md
• docs/aios-v2/05-TRACEABILITY-MATRIX.md
• docs/aios-v2/AIOS-V2R1-HARDENING-GATE-A-REPORT.md