# Cerberus：面向 AI Agent 的链上支付防火墙

Cerberus 是面向 AI Agent 支付场景的安全中间件。每笔支付依次经过身份验证、风险控制和执行授权三道闸门；MCP 提供灵活的链下判断，链上 Policy 与 PaymentGateway 提供不可绕过、可审计的安全底线。

## 项目亮点

- 三层防火墙：Identity → Risk Control → Execution
- Agent Registry：查看已注册 Agent，并可暂停 / 激活（作用于 Layer 1）
- 链上 Policy：白名单和单笔金额上限由智能合约强制执行
- 用户钱包结算：防火墙通过后调用 `PaymentGateway.pay()`；`payByDelegate` 已在合约中预留，不是当前 Demo 默认路径
- MCP Server：可接入真实 Agent 客户端
- 可验证审计：保存逐层结果、哈希链和链上支付事件

## 架构

```text
Payment Request
      │
      ▼
┌─────────────────────────────────────┐
│ Layer 1：Identity                    │
│ Agent 注册、钱包绑定、Challenge      │
│ @cerberus/mcp-identity               │
├─────────────────────────────────────┤
│ Layer 2：Risk Control                │
│ 黑名单、金额、频率、Prompt Injection │
│ @cerberus/mcp-payment-guard          │
├─────────────────────────────────────┤
│ Layer 3：Execution                   │
│ 预算、链上 Policy、钱包签名 pay()    │
│ @cerberus/mcp-execution              │
└─────────────────────────────────────┘
      │
      ▼
 Approved / Blocked + Audit Log + Events
```

## 页面功能

- **Overview**：五种场景、三层结果和安全指标
- **Custom Payment**：从 Agent Registry 下拉选择 Agent，创建自定义支付
- **Agent Registry**：查看 Agent、暂停/激活（Layer 1）；新注册仅写入链下 Store
- **Policy Center**：查看预算、风险策略和链上白名单
- **Audit Log**：查看支付决定、哈希和逐层 Trace

## 新增内容

### Agent Registry

```http
GET    /api/agents
POST   /api/agents
GET    /api/agents/:agentId
PUT    /api/agents/:agentId
DELETE /api/agents/:agentId
```

注册示例：

```json
{
  "agentId": "agent-research-002",
  "name": "Research Agent",
  "walletAddress": "0x5555555555555555555555555555555555555555",
  "publicKey": "ed25519:demo-key"
}
```

当前 Registry 支持动态列表、详情、活动统计、新 Agent 注册（链下 Layer 1）以及 Suspend / Activate。Custom Payment 的 `agentId` 从 Registry 动态生成下拉框。

Policy Center 提供 **Authorize merchant（仅 owner）**：调用链上 `Policy.setWhitelist`。默认商家 `0x5555…5555`，不会改掉场景 3 使用的 `0x3333…`。

合约已预留委托支付（`setAgentDelegate` / `payByDelegate`），便于后续「用户出钱、Agent 签名」。**当前 Demo 默认路径仍是用户钱包调用 `PaymentGateway.pay()`**，避免决赛现场多一次签名、双钱包未接好导致失败。

## Agent 注册与钱包流程

### 当前 Demo 注册

```text
输入 Agent ID / 名称 / 钱包地址
          ↓
POST /api/agents → 内存 Agent Store
          ↓
Agent 出现在 Registry
          ↓
查看、暂停、激活
```

页面注册只写入内存 Store，用于 Layer 1 演示。链上付款请使用部署时登记的 `agent-shopping-001`。

委托支付（Mode B）的合约接口见 `docs/AGENT_REGISTRY_AND_DELEGATION_GUIDE.md`，不是决赛默认演示路径。

## API

```http
GET    /api/scenarios
GET    /api/evaluate?scenario=normal-payment
POST   /api/evaluate
GET    /api/audit
GET    /api/policy
PUT    /api/policy
DELETE /api/policy
GET    /api/chain
```

## 启动方法：模拟模式

要求 Node.js 18+：

```powershell
npm install
npm run demo
```

打开 [http://localhost:3000](http://localhost:3000)。没有链上环境变量时显示 `Simulated`。

## 启动方法：本地链上模式

终端 1：

```powershell
npm run node
```

终端 2：

```powershell
npm run compile
npm run deploy:local
```

终端 3：

```powershell
npm run demo
```

部署会生成 `apps/demo/.env.local` 和 `apps/demo/public/deployed-addresses.json`。

MetaMask 网络：

```text
Network name: Localhost 8545
RPC URL: http://127.0.0.1:8545
Chain ID: 31337
Currency symbol: ETH
```

Hardhat Account #0 私钥：

```text
0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
```

测试步骤：导入 Account #0 → 切换到 Localhost 8545 → Overview 运行 **4 · Successful Payment** → Connect Wallet → 确认 `approve` 和 `PaymentGateway.pay()` → 可选：Agent Registry 暂停 Agent 展示 Layer 1，或打开 Audit Log 查看逐层结果。

Hardhat 节点重启会清空状态，需要重新部署。

## Base Sepolia 测试网

准备专用测试钱包和测试 ETH：

```powershell
$env:PRIVATE_KEY="0x你的测试钱包私钥"
$env:RPC_URL="https://sepolia.base.org"
npm run deploy:base-sepolia
npm run demo
```

MetaMask：`Base Sepolia`、RPC `https://sepolia.base.org`、Chain ID `84532`、Explorer `https://sepolia.basescan.org`。

项目中的 MockUSDC 是测试代币，不是真实 USDC。不要将测试私钥用于主网或提交到 Git。

## MCP Server

```powershell
npm run mcp:identity
npm run mcp:guard
npm run mcp:execution
```

工具包括：`verify_agent`、`issue_challenge`、`screen_payment`、`validate_on_chain_policy`、`record_payment`、`get_policy`。

## 项目结构

```text
cerberus/
├── apps/demo/                  # Next.js 控制台、API、wagmi 钱包连接
├── packages/core/              # 三层防火墙、Store、viem 链上客户端
├── packages/mcp-identity/      # 身份 MCP Server
├── packages/mcp-payment-guard/ # 风控 MCP Server
├── packages/mcp-execution/     # 执行 MCP Server
├── packages/contracts/         # Policy、Gateway、Registry、MockUSDC
└── docs/                       # 项目指南和 Agent Registry 文档
```

## 安全边界

- 本项目用于本地链和测试网 Demo，不是生产资金系统。
- 生产环境应使用 EIP-712、真实公钥验证、nonce 过期和数据库持久化。
- Agent 密钥应使用 KMS、HSM、MPC 或 Session Key 管理。
- Hardhat 私钥是公开测试私钥，只能用于本地链。

## 许可证

MIT