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

AIOS OpenClaw Run Provenance Writer

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

AIOS Runtime HTTP 合同

插件在 OpenClaw loopback Gateway 内注册 /v1/health、/v1/execute 和 /v1/commands/<id>。执行请求必须同时通过本机 CredentialRef 比对与 Ed25519 签名验证；热路径只读取公钥，不读取 Candidate 私密签名材料。

Runtime 仅允许无副作用的 status 与在线验收专用 acceptance.delay。它不把 返回成功冒充为模型推理或任意 Agent 执行。命令身份、幂等键和终态以追加式 JSONL 持久化；Gateway 重启时遗留的 RUNNING 命令会收敛为 FAILED/restart_interrupted，避免把重启误报成真实超时。

取消只对当前进程内仍在执行的命令生效，超时由签名命令的 expires_at 与 30 秒硬上限共同约束。未知 action、错误签名、过期命令、跨 tenant 状态查询、 冲突的 command_id 或幂等键均失败关闭。

安全边界

• 签名合同：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 等未授权路径的拒绝测试。

Candidate task-plane transport

protectedDispatchTransport=task-plane 仅用于隔离 Candidate 验证。它要求：

• TaskPlan 与服务器配置的 task_id、repository、patch branch、完整 base OID、允许路径和 capability 完全一致；
• Owner provenance 已通过现有签名校验，Policy approval 与 TaskPlan 摘要、Owner principal、有效期绑定；
• Broker 端点只能是 loopback HTTP，Bearer 凭据只能从绝对路径的受控凭据投影读取；
• Broker 返回 simulation=false、真实 provisioning 元数据和 secret-ref:// 引用，禁止返回 Token 或 Authorization 内容；
• Broker 不可达时直接失败，不回退到 mock 或 sandbox；
• 配置 protectedDispatchAuditPath 时仅写入脱敏 JSONL 审计记录。

该 Candidate 不修改生产插件或 Gateway；OpenClaw/Codex 原生子会话未完成前必须分别报告为未验证。