aios/plugins/aios-tenant-boundary/README.zh-CN.md

AIOS OpenClaw Run Provenance Writer

本插件为 AIOS V2R1 提供 Owner 签名的运行授权、持久 Provenance Store 与专用 Evidence Writer。它不授予通用 Shell 或任意文件写权限。

安全边界

• 签名合同：aios.run-provenance/v1，Ed25519，授权最长 15 分钟。
• 授权绑定：run_id、sender_id、任务、执行器实例、当前 Claim OID、Candidate OID 与任务分支。
• 路径：仅允许七个 .agent/*.json Evidence 文件。
• 操作：仅允许 create/update，随后执行固定 argv 的 git add、git commit 和当前任务分支普通 push。
• 通用 exec/shell/bash/write/edit/apply_patch/file_write 始终拒绝。
• toolCallId permit 只能消费一次；参数摘要变化、过期、签名篡改、Run/Sender 不匹配均拒绝。
• Writer 拒绝 symlink、路径逃逸、脏 Worktree、错误分支、错误 HEAD、Candidate 非祖先及暂存范围扩大。
• Gateway 以服务用户调用 Git 时，仅对配置中的精确 writerRepoRoot 注入命令级 safe.directory，不写全局 Git 配置。
• 禁止 reset、rebase、amend、Tag 和 force push。提交后 push 失败时保留可审计的 local-ahead 状态，不伪造回滚。

组件

• issuer.mjs：在受保护边界读取现有 Ed25519 材料，生成公开验签材料并原子写入一次性签发记录。
• provenance.js：严格 Schema、canonical JSON、Ed25519 sign/verify 和安全 Store 读取。
• index.js：OpenClaw hook、Owner/Run/Sender 验证与一次性 permit。
• writer.js：限定路径原子写入、固定 Git 操作和追加式审计。

部署与回滚

部署必须先备份运行插件和 OpenClaw 配置，再安装 Git 中已测试的完整目录，配置绝对路径、Key ID、任务分支和审计路径，执行 openclaw plugins doctor 后才重启 Gateway。回滚只恢复备份插件与配置并重启，不修改任务分支历史或业务状态。

验证

执行：

node --test test/*.test.js

验收还必须包含受保护签发、Heartbeat 实际 commit/push、审计链验证，以及 README.md 等未授权路径的拒绝测试。