# 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。回滚只恢复备份插件与配置并重启，不修改任务分支历史或业务状态。

## 验证

执行：

```bash
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 原生子会话未完成前必须分别报告为未验证。