safal207/ProofPath
GitHub: safal207/ProofPath
ProofPath 是一个执行前授权网关，为 AI agent 和 API 操作提供可验证意图、因果授权和防篡改审计链。
Stars: 2 | Forks: 1
# ProofPath
```
## NGI TALER reviewer path
ProofPath Agent Payment Guard was submitted to NGI TALER as an open-source auxiliary layer for privacy-preserving AI-agent payment authorization.
Start here:
- [`docs/NGI_TALER_REVIEWER_PATH.md`](docs/NGI_TALER_REVIEWER_PATH.md)
- [`docs/TALER_ALIGNMENT.md`](docs/TALER_ALIGNMENT.md)
- [`docs/AGENT_PAYMENT_GUARD_DEMO.md`](docs/AGENT_PAYMENT_GUARD_DEMO.md)
- [`docs/BUDGET_AND_MILESTONES.md`](docs/BUDGET_AND_MILESTONES.md)
Reviewer quick commands:
```bash
bash examples/agent-payment-guard/run_demo_check.sh
bash examples/agent-payment-guard/run_service_check.sh
bash examples/agent-payment-guard/run_e2e_evidence_demo.sh
bash examples/agent-payment-guard/run_mock_rail_demo.sh
```
资助元数据：
```
Application: 2026-08-00b
Fund: NGI TALER
Requested amount: EUR 50,000
Correct repository: https://github.com/safal207/ProofPath
```
```
**Verifiable intent for every critical action.**
> **HTTPS protects the connection. ProofPath protects the meaning of the action.**
>
> HTTPS secures the channel. ProofPath secures the intent.
ProofPath is an open protocol and gateway layer for adding verifiable intent, causal authorization, and auditable action chains to HTTPS APIs and AI-agent systems.
HTTPS proves that a connection is secure. ProofPath proves that an action was authorized, causally grounded, and accountable.
> HTTPS proves the channel. ProofPath proves the action.
## Agent Payment Guard
> **Model output is a proposal, not authorization.**
ProofPath is an external authorization and evidence layer for AI-agent payments.
It verifies signed human intent before execution and exports tamper-evident evidence for every ACCEPT, HOLD, or BLOCK decision.
```text
AI agents will need payment rails.
Payment rails need authorization.
Authorization needs evidence.
ProofPath provides that evidence.
```
**功能：**
- 在执行任何支付前，要求提供已签名的意图信封
- 执行策略：资产白名单、预算上限、接收方范围、定期审批
- 持久化已花费的 nonces —— 重放的 envelope 始终为 `BLOCK / INTENT_REPLAYED`
- 将每个决策写入在服务重启后依然存在的哈希链 `audit.jsonl` 中
- 导出可在没有实时服务的情况下离线验证的便携式证据包
**不包含的功能：** 没有真实的钱包，没有 token 转账，没有资产托管，没有私钥，没有 SDK，没有 RPC，没有 JWS，没有 EIP-712。
外部资料：
- [Agent Payment Guard 简介](docs/agent-payment-guard-brief.md)
- [90秒演示脚本](docs/agent-payment-guard-90-second-demo.md)
### 架构
```
flowchart TD
A(["AI Agent\n(model output = proposal)"])
B(["Payment Proposal\nJSON"])
C(["ProofPath\nGuard Service\n:8787"])
D(["Policy Engine\npayment_policy.json"])
E(["Signed Intent Verifier\ndemo-sha256-v0"])
F(["Replay Store\n.proofpath/replay-store.json"])
G(["Hash-Chained Audit Log\n.proofpath/audit.jsonl"])
H(["Evidence Export Bundle\nproofpath-evidence-bundle/"])
I(["Mock / Future Payment Rail"])
J(["ACCEPT"])
K(["BLOCK / HOLD"])
A -->|proposes| B
B -->|POST /v1/payment-proposals/evaluate| C
C -->|check asset, budget, recipient, scope| D
C -->|verify signature, expiry, nonce| E
E -->|nonce lookup| F
C -->|append record| G
G -->|export script| H
C --> J
C --> K
J -->|execution_allowed=true| I
K -->|execution_allowed=false| A
style J fill:#d4f1d4,stroke:#4a9e4a,color:#1a4a1a
style K fill:#f7d4d4,stroke:#9e4a4a,color:#4a1a1a
style H fill:#d4e8f7,stroke:#4a7a9e,color:#1a3a4a
```
完整架构图：[`docs/architecture.md`](docs/architecture.md)
API 契约：[`openapi/proofpath-guard-service-v0.1.yaml`](openapi/proofpath-guard-service-v0.1.yaml)
OpenAPI 说明：[`docs/openapi.md`](docs/openapi.md)
### 快速开始
```
# 安装：仅限 stdlib，无 dependencies
# 运行所有检查
bash examples/agent-payment-guard/run_demo_check.sh
bash examples/agent-payment-guard/run_service_check.sh
bash examples/agent-payment-guard/run_evidence_export_check.sh
# 完整 end-to-end story：ACCEPT -> replay BLOCK -> export -> verify
bash examples/agent-payment-guard/run_e2e_evidence_demo.sh
# mock payment rail：证明 ACCEPT 到达 rail；BLOCK/HOLD 永不 execute
bash examples/agent-payment-guard/run_mock_rail_demo.sh
```
预期输出：
```
[e2e] step 1 — valid signed intent: ACCEPT
decision: ACCEPT
execution_allowed: true
[e2e] step 2 — replay same envelope: BLOCK / INTENT_REPLAYED
decision: BLOCK
reason: INTENT_REPLAYED
execution_allowed: false
[e2e] step 3 — export evidence bundle
hash chain: chain valid (2 records)
bundle ready: proofpath-evidence-bundle/
[e2e] step 4 — verify bundled audit log
audit log: OK (2 records, chain valid)
[e2e] ✓ ProofPath Agent Payment Guard demo complete.
```
有关完整的预期输出，请参见 [`docs/demo-transcript-payment-guard.md`](docs/demo-transcript-payment-guard.md)。
## 60秒审阅者摘要
**ProofPath 是一个防御性的执行前网关，旨在防止有效的 AI-agent/API 凭证变成不安全、未经审计或不可逆的操作。**
ProofPath **不会**替代 HTTPS、OAuth、IAM、API 密钥或普通的基础设施安全。这些层仍然是必需的。ProofPath 在执行边界添加了一个操作级别的安全和审计层：在高风险的 AI-agent 或 API 操作到达受保护的上游系统之前对其进行拦截。
如果您是通过早期名称或框架下的已提交资助申请来到这里的，请从[已提交申请审阅者桥接](docs/SUBMITTED_APPLICATION_REVIEWER_BRIDGE.md)开始。要了解相关代码库是如何相互配合的，请查看[生态图](docs/ECOSYSTEM_GRAPH.md)。
### 三大产品形态
| 形态 | 路径 | 提供的功能 |
| --- | --- | --- |
| Agent Payment Guard | [`examples/agent-payment-guard/`](examples/agent-payment-guard/) | 用于 AI-agent 支付的授权和证据层。签名意图、策略、重放保护、哈希链审计、便携式证据包。 |
| CI 证据门禁 | [`action.yml`](action.yml), [`docs/GITHUB_ACTION_QUICKSTART.md`](docs/GITHUB_ACTION_QUICKSTART.md) | 将 ProofPath 审计日志转换为 CI 可验证的指标和通过/失败检查。 |
| Personal Agent Guard | [`examples/personal-agent-guard/`](examples/personal-agent-guard/) | 在 Claude Code / Codex 风格的 AI 编码工具周围添加本地审批边界和审计日志。 |
产品表述：
```
ProofPath turns action-boundary audit logs into CI-verifiable evidence.
```
个人工作流表述：
```
ProofPath Personal Agent Guard is a local seatbelt for AI coding tools.
```
### 为什么只有 HTTPS 是不够的
HTTPS 可以保护连接。API 身份验证可以证明凭证是有效的。IAM 可以定义广泛的权限。
但高风险的 AI-agent 系统需要一个额外的问题：
一个请求即使通过了身份验证也可能是不安全的。例如，AI agent 可能在尝试删除数据、修改基础设施、推送不安全的代码、触发金融工作流，或者在预期范围之外执行不可逆的管理操作时，拥有有效的凭证。
ProofPath 专注于解决这一空白。
### ProofPath 的作用
ProofPath 在执行前评估高风险操作，并可以生成明确的决策，例如 `ACCEPT`、`HOLD`、`REJECT`、`BLOCK` 或 `AUDIT`。
当前的原型展示了：
- 声明的意图检查；
- 因果父级检查；
- 范围检查；
- 可逆性分类；
- 针对不可逆操作的人工审批要求；
- Rust 验证器 crate；
- Axum 网关；
- 仅在 ProofPath 做出决策后才进行上游转发；
- 在不安全的不可逆操作到达受保护的 API 之前将其拦截；
- 哈希链 JSONL 审计日志；
- 危险操作和真实模型 agent 演示；
- 可复用的 GitHub Action 证据门禁；
- 用于 Claude Code / Codex 风格工具的本地 Personal Agent Guard；
- 具有签名意图、重放保护和便携式证据导出功能的 Agent Payment Guard。
### ACCEPT 与 BLOCK
概念上：
```
ACCEPT:
action has declared intent
action has causal parent
action is within scope
action is reversible or approved
gateway forwards upstream
BLOCK:
action is irreversible
action lacks required human approval
gateway blocks before upstream execution
decision is written to the audit log
```
### 为什么 Compute Witness 很重要
Compute Witness 将 AI/agent 计算转化为可审查的证据：作业清单在结果被信任之前声明意图、范围、因果授权和承诺。
该仓库包含 Python 一致性测试、审计包示例、挑战夹具、Rust 验证器适配器、Rust CLI、预期输出夹具、Rust 审计哈希验证以及 CI 回归检查。
审阅者可以在本地运行该路径，而无需信任隐藏的服务：从 [Compute Witness 资助审阅者路径](docs/COMPUTE_WITNESS_GRANT_REVIEWER_PATH.md)、[已提交申请审阅者桥接](docs/SUBMITTED_APPLICATION_REVIEWER_BRIDGE.md)、[生态图](docs/ECOSYSTEM_GRAPH.md)或 [Compute Witness 审阅者快速开始](examples/compute-witness/README.md#reviewer-quickstart)开始。
### 审阅者链接
- [从这里开始：ProofPath v0.1](docs/START_HERE_V0_1.md)
- [ProofPath v0.1 审阅者清单](docs/REVIEWER_CHECKLIST_V0_1.md)
- [干净检出审阅者运行手册](docs/reviewer-runbook.md)
- [审计日志验证](docs/audit-log-verification.md)
- [ProofPath v0.1 落地页](docs/LANDING_V0_1.md)
- [Personal Agent Guard](examples/personal-agent-guard/)
- [Agent Payment Guard](examples/agent-payment-guard/)
- [Agent Payment Guard 简介](docs/agent-payment-guard-brief.md)
- [Agent Payment Guard 90秒演示](docs/agent-payment-guard-90-second-demo.md)
- [架构图](docs/architecture.md)
- [Agent Payment Guard 演示文稿](docs/demo-transcript-payment-guard.md)
- [Agent Payment Guard 服务文档](docs/agent-payment-guard-service.md)
- [ProofPath Guard Service OpenAPI](openapi/proofpath-guard-service-v0.1.yaml)
- [OpenAPI 说明](docs/openapi.md)
- [审阅者摘要](docs/reviewer-summary.md)
- [ProofPath v0.1 产品里程碑](docs/RELEASE_V0_1.md)
- [证据包 v0.1](docs/EVIDENCE_PACKET_V0_1.md)
- [证据指标 v0.1](docs/EVIDENCE_METRICS_V0_1.md)
- [ProofPath GitHub Action 快速开始](docs/GITHUB_ACTION_QUICKSTART.md)
- [已提交申请审阅者桥接](docs/SUBMITTED_APPLICATION_REVIEWER_BRIDGE.md)
- [生态图](docs/ECOSYSTEM_GRAPH.md)
- [Compute Witness 资助审阅者路径](docs/COMPUTE_WITNESS_GRANT_REVIEWER_PATH.md)
- [TRC / TPU 证据计划](docs/TRC_TPU_EVIDENCE_PLAN.md)
- [Compute Witness 审阅者快速开始](examples/compute-witness/README.md#reviewer-quickstart)
- [Internet Action Layer](docs/internet-action-layer.md)
- [一致性夹具](conformance/README.md)
- [安全资助修订说明](docs/grant-updates/security-grant-revision-proofpath-update.md)
- [威胁模型](specs/threat-model.md)
- [模型护栏绕过威胁说明](docs/threats/model_guardrail_bypass.md)
- [HTTP action-context profile](specs/proofpath-http-profile-v0.1.md)
- [模拟支付轨道演示](examples/agent-payment-guard/run_mock_rail_demo.sh)
- [社区实验](COMMUNITY_EXPERIMENTS.md)
## 快速演示
运行一分钟 AI agent 危险操作演示：
```
python3 examples/upstream/demo_server.py
cargo run -p proofpath-gateway
bash examples/agent-dangerous-action/agent_delete_without_approval.sh
```
预期结果：
```
BLOCK IRREVERSIBLE_REQUIRES_HUMAN_APPROVAL
```
然后验证审计日志：
```
python3 scripts/verify_audit_log.py proofpath-audit.jsonl
```
## v0.1 价值主张
ProofPath v0.1 为 AI 安全、基础设施和平台团队提供了一种本地、可复现的方式来回答：
```
Did this agent action have enough declared intent and causal authorization to execute?
```
答案是在操作到达受保护的服务之前强制执行的，并写入 CI 可以验证的防篡改审计日志中。
## 包含的可运行示例
| 演示 | 命令 | 展示内容 |
| --- | --- | --- |
| 危险的不可逆操作 | `bash examples/agent-dangerous-action/agent_delete_without_approval.sh` | 在不可逆的删除请求到达上游 API 之前将其拦截。 |
| 安全的可逆操作 | `bash examples/agent-dangerous-action/agent_get_status.sh` | 允许安全的状态读取请求。 |
| 真实模型 agent | `python3 examples/real-model-agent/real_model_agent_demo.py --mode safe` / `--mode unsafe` | 表明即使是模型生成的请求也必须通过操作边界。 |
| CI 证据门禁 | `python3 scripts/check_audit_metrics.py proofpath-audit.jsonl --max-block-rate 0.5` | 将审计日志转化为 CI 通过/失败证据。 |
| Personal Agent Guard | `bash examples/personal-agent-guard/run_demo_check.sh` | Claude Code / Codex 风格工具的本地安全带（保护机制）。 |
| Agent Payment Guard | `bash examples/agent-payment-guard/run_e2e_evidence_demo.sh` | 签名意图、重放保护、哈希链审计和便携式证据包。 |
| 模拟支付轨道 | `bash examples/agent-payment-guard/run_mock_rail_demo.sh` | 证明 ACCEPT 能到达模拟轨道；BLOCK/HOLD 永不执行。 |
## v0.1 中的变化
早期关于 ProofPath 的讨论主要面向协议或网关。这个 v0.1 仓库现在展示了一个紧凑的产品路径：
```
agent/API action
-> ProofPath gateway
-> explicit ACCEPT/BLOCK decision
-> audit log
-> CI-verifiable evidence metrics
```
这使得 ProofPath 更易于审阅、资助和增量部署。
## 产品里程碑 v0.1
ProofPath v0.1 是一个小巧但完整的面向开发者的证据闭环：
```
agent/API action
-> pre-execution guard
-> ACCEPT/BLOCK decision
-> hash-chained audit log
-> metrics summary
-> CI pass/fail gate
```
有关完整的运行手册和验收检查，请参见 [ProofPath v0.1 产品里程碑](docs/RELEASE_V0_1.md)。
## 证据指标 v0.1
ProofPath 可以将哈希链审计日志转化为 CI 可验证的指标：
```
python3 scripts/check_audit_metrics.py proofpath-audit.jsonl --max-block-rate 0.5
```
输出示例：
```
{
"total": 2,
"accepted": 1,
"blocked": 1,
"accept_rate": 0.5,
"block_rate": 0.5,
"decisions": {
"ACCEPT": 1,
"BLOCK": 1
}
}
```
这提供了一个简单的发布门禁：
```
if block_rate > allowed_threshold:
fail CI
```
有关详细信息，请参见[证据指标 v0.1](docs/EVIDENCE_METRICS_V0_1.md)。
## GitHub Action 快速开始
ProofPath 可以用作可复用的 CI 门禁：
```
name: ProofPath Audit Gate
on: [pull_request]
jobs:
proofpath-audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: ./
with:
audit_log: proofpath-audit.jsonl
max_block_rate: "0.5"
```
有关可复制粘贴的工作流，请参见 [GitHub Action 快速开始](docs/GITHUB_ACTION_QUICKSTART.md)。
## 组件
```
ProofPath protocol
ProofPath gateway
Policy engine
Protected API
Append-only audit log
```
有关完整的 Mermaid 系统图，请参见 [`docs/architecture.md`](docs/architecture.md)。
## 计划中的组件
```
ProofPath CLI
ProofPath SDK
ProofPath Policy Packs
ProofPath Dashboard
```
## 状态
ProofPath v0.1 是一个实验性的安全和审计原型。
它旨在用于本地演示、资助审阅、早期集成实验以及面向安全的设计审阅。
它目前还不是可用于生产环境的安全基础设施。
## 许可证
MIT
标签：API网关, Streamlit, 可视化界面, 审计日志, 支付授权, 访问控制, 逆向工具