safehands-pharos

<p align="center"> <img src="assets/banner.svg" alt="SafeHands — 面向 Pharos Pacific Mainnet 上 AI 代理的交易安全网关" width="100%"> </p> # 安全之手 **面向 Pharos Pacific Mainnet 上 AI 代理的交易安全网关 — 合规检查点 Real-Fi 需要在任何代币化资产交易签名之前执行。** AI 代理几乎可以签署任何内容：无限代币批准、错误链上的交换、向恶意 x402 端点付款、将代币化资产转移给未经审查的对手方。安全之手是在签名之前运行的检查。确定性策略引擎评估每个操作并返回四个决策（`允许`、`阻止`、`需要确认`、`仅准备`）之一，并附有纯英文原因 — 所有中继验证的广播都在链上证明，建立了隐私保护审计跟踪和声誉层。您使用自己的钱包；安全之手从不持有密钥，从不为您签名。 它作为 MCP 服务器、HTTP API 和 CLI 交付，暴露了 33 种工具，Pharos 生态系统中的任何代理都可以调用。 ### 哪种安全之手适合我？ 安全之手是三个界面背后的一个确定性策略引擎 — 选择最适合您的界面： | 您是… | 使用 | 它是什么 | |---|---|---| | 只想进行安全检查的**用户或管理员代理** | **Anvita Flow 托管技能** | 零基础设施，只读，无密钥 — [`anvita/safehands/`](anvita/safehands/) 中的托管交付品（正在发布到 Anvita）。 | | 为自己的代理添加安全性的**开发者** | **npm 包** — MCP 服务器、CLI 和 SDK | `npx … --demo`，将其放入任何 MCP 客户端，或 `import { evaluateActionPolicy } from "safehands-pharos"`。默认只读；写入工具在环境标志 + 签名者后面保持开启。 | | 想要 HTTP API 的**操作员** | **自托管只读后端** | `node dist/api/server.js` → `http://localhost:4022` — 免费公共端点和可选的 x402-gated `/paid/*` 包。 | > **两种裁决词汇，一个逻辑。** 紧凑的托管引擎返回 `允许 / 警告 / 阻止` 风险建议；完整的策略引擎（npm/API）返回四值决策 `允许 / 阻止 / 需要确认 / 仅准备`。它们可以清晰地映射：`阻止 ↔ 阻止`，`警告 ↔ 需要确认`，`允许 ↔ 允许` 或 `仅准备` （安全 — 您自己签名）。 --- ## 🏆 Anvita Flow 上的安全之手 — 一个完全托管的服务代理（Agent Carnival 第二阶段，即将推出） 安全之手作为 **完全托管、零基础设施的服务代理** 为 [Anvita Flow](https://flow.anvita.xyz/home) （Pharos 代理嘉年华，第二阶段）打包。**一旦发布**，市场上的任何管理员代理都可以发现并调用它 — 无需服务器，无需密钥，运行系统中无需托管。 ``` 用户 → 管理员代理 → Anvita Flow 市场 → 安全之手（托管技能） │ 直接通过公共 RPC 读取 Pharos 主网（1672） + 官方 Pharos 代币和规范合约注册表 + GoPlus 威胁情报（黑客马拉松赞助商） │ 确定性裁决：风险评分 0–100 · 允许 / 警告 / 阻止 ``` **托管包存放在 [`anvita/safehands/`](anvita/safehands/)** — 一个 Pharos 技能，遵循官方技能引擎模式，由 **无依赖的确定性风险引擎** 驱动（[`safehands-engine.js`](anvita/safehands/scripts/safehands-engine.js)）： | 能力 | 它如何决定 | |---|---| | **代币冒名顶替检测** | 实时链上 `symbol()` 与 **官方 Pharos 代币注册表** 进行交叉检查 — 捕获假的 USDC/WPROS/WETH/LINK，干净的威胁源可能会漏掉这些 | | 蜂蜜罐 / 卖税 / 隐藏所有者 | **GoPlus 威胁情报** （无密钥公共 API，温和的故障转移） | | 恶意钱包标志 | GoPlus 地址安全：钓鱼、盗窃、网络犯罪 | | 规范基础设施识别 | 14 个官方 Pharos 规范合约（Safe、Permit2、EntryPoint 4337…） | | 转移 / 交换意图审查 | 执行前实时余额、历史和对手方检查 | | 链上风险记录和代理声誉 | 通过 `eth_call` 读取 SafeHands 注册表和证明合约 | 每个裁决都是 **通过代码计算，而不是通过 LLM 猜测** — AI 层仅处理对话。每个分析都链接到 [Pharosscan](https://www.pharosscan.xyz)，以便用户自己验证证据。引擎是确定性的，无依赖的，因此相同的输入总是会产生相同的裁决。 > **只读是功能，而不是限制：** 一个可以 **移动资金** 的安全层本身就是安全风险。安全之手不持有密钥，不签名，不托管 — 这就是为什么其他所有代理都可以信任它在交易之前。 [](https://github.com/SZtch/safehands-pharos/actions/workflows/ci.yml)      --- ## 10 秒内试用 **一条命令，零基础设施** — 无需配置，无需钱包，无需密钥，无需交易： ```bash npx -y github:SZtch/safehands-pharos --demo # （发布后：npx safehands-pharos --demo · 或本地：git clone → npm install → node dist/index.js --demo） ``` 在您的终端中观察确定性策略引擎对 Pharos Pacific 主网发出真正的 `允许` / `阻止` 决策。托管代理正在发布到 [Anvita Flow](https://flow.anvita.xyz/home) （代理嘉年华第二阶段） — 请参见上面的部分。 它在您的终端中运行十二个确定性安全检查（钱包健康、允许/阻止决策、代币注册表查找、x402 预飞行、SSRF 阻止、风险评分、RWA 转移合规性和结算场景），并且不涉及链上任何操作。 <details> <summary>样本输出 — 十二个检查之一</summary> ```text $ npx safehands-pharos --demo 🛡️ 安全之手-Pharos 确定性演示 环境：pacific-mainnet 链 ID：1672 模式：非破坏性演示，无真实交易广播 3. 无限批准预飞行：阻止 safehands_preflight_check { "success": true, "data": { "decision": "BLOCK", "riskLevel": "HIGH", "safeToExecute": false, "reasons": ["请求了无限批准。"], "requiredActions": ["使用有限的批准金额."] }, "error": null } ``` </details> --- ## 自行运行 API（可选自托管） 托管代理正在发布到 Anvita Flow（参见上文）。要直接使用 HTTP API，请在 Pharos Pacific 主网上自行托管零托管参考后端 — 公共界面不需要 API 密钥： ```bash npm install --include=dev && npm run build node dist/api/server.js # 只读 API 在 http://localhost:4022（使用 PORT 环境变量更改） ``` ```bash # 健康状况 + 网络配置 curl -s http://localhost:4022/health curl -s http://localhost:4022/public-config # 来自实时策略引擎的真实预飞行决策 curl -s -X POST http://localhost:4022/tools/safehands_preflight_check \ -H "content-type: application/json" \ -d '{"actionType":"approve_token","chainId":1672,"approvalToken":"USDC","spender":"0x000000000000000000000000000000000000dEaD","approvalAmount":"max"}' # 链上声誉读取（实时证明合约） curl -s -X POST http://localhost:4022/tools/get_agent_reputation \ -H "content-type: application/json" \ -d '{"address":"0x6730d3a2A217108AB53CCFe60ffdAd05D3C124e5"}' # x402-gated 端点 — 返回真正的 HTTP 402 挑战（主网 USDC，eip155:1672） curl -s -i http://localhost:4022/paid/risk-report ``` 交互式浏览器演示（当本地 API 运行）：**http://localhost:4022/demo**。 --- ## 它做什么 安全之手位于代理的 **意图** 和 **签名** 之间。在任何操作之前，代理调用 `safehands_preflight_check`（或其中一个专门的预飞行工具），并获得一个决策： <p align="center"> <img src="assets/architecture.svg" alt="安全之手架构 — 代理意图通过确定性策略引擎流向四值决策；用户使用自己的钱包签名；Pharos 主网记录证明审计跟踪、风险注册表和可组合的声誉" width="100%"> </p> 决策是 **确定性** 的：策略引擎做出决定，而不是模型。LLM 可以提供建议，但不能覆盖它不喜欢的策略。 ### 它能捕获什么 | 风险 | 没有安全之手 | 有安全之手 | |------|-------------------|----------------| | 无限代币批准 | 代理授予恶意花费者永久权限 | `阻止` — 默认情况下禁止无限批准 | | 不支持的链 | 代理针对非 Pharos 网络（例如以太坊） | `阻止` — 链 ID 守卫 | | 恶意 x402 端点 | 代理支付本地主机 / 私有 IP URL | `阻止` — SSRF + 重定向守卫 | | 钱包耗尽 | 代理在一次会话中过度消费 | `阻止` — 每个代理 + 每日消费上限 | | 未知代币 | 代理交换未经验证的合约 | `需要确认` | | 任意合约调用 | 代理调用未知合约 | `需要确认` | | 错误输入 | 代理传递 `-1` 或零地址 | `VALIDATION_ERROR` | | 未注册的代币化资产 | 代理批准未知资产合约给未经验证的支出者 | `需要确认` — 需要人工审查 | | 过大结算 | 代理结算的现实世界发票超过策略上限 | `阻止` — 确定性支出限制 | --- ## 为什么这对 Real-Fi 和 RWA 很重要 Pharos 是一个 Real-Fi 链，代币化的现实世界资产具有现实世界的义务，这些义务与 meme 代币不同：资产合法性、转移限制、审计跟踪、结算纪律、对手方信任。安全之手提供这一层 — 今天在主网上运行，而不是模拟： | RWA 要求 | 安全之手能力（实时） | |---|---| | 资产合法性 | 代币注册分类 + GoPlus 安全检查（铸造后门、蜂蜜罐） | | 转移限制 | 确定性每个代理策略：上限、批准限制、人工干预 `需要确认` | | 审计跟踪 | 每个中继验证广播的链上证明 — 哈希值，只有隐私保护 | | 可组合的风险内存 | Merkle 风险根 + `verifyRiskRecord` 链上视图 + 无密钥包含证明 | | 对手方信任 | `get_agent_reputation` — 链上验证的安全跟踪记录每个地址 | | 结算纪律 | x402/USDC 轨道带有 SSRF 守卫、代币白名单、每个调用和每日上限 | 演示场景 11-12 展示了端到端的 RWA 流程。完整的映射，带有诚实的实时与路线图分割： **[docs/REALFI_RWA_ALIGNMENT.md](docs/REALFI_RWA_ALIGNMENT.md)**。 --- ## 它是什么 — 不是什么 安全之手是一个 **安全层** ，不是钱包。它不是托管服务、私钥管理器、签名者、DEX 或桥。 在托管模式（Anvita Flow）下，它是 **只读和零托管** 的：它不持有密钥，不签名，不广播。它读取链状态，评估策略并返回决策。您始终使用自己的钱包签名和发送。 执行工具（`execute_swap`、`send_payment`、`approve_token` 等）存在于代码库中，但被显式环境标志阻止，仅适用于 **自行托管和单租户** ，在您控制的机器上运行。这些写入工具是 **实验性和未经审计的** — 它们禁用后发货，需要显式选择加入。公共服务器拒绝启用它们：公共主机上的引导守卫在 `NODE_ENV=production` 时快速失败（始终为自行托管部署设置它）。 --- ## 执行模式 | 模式 | 密钥 / 钱包 | 在哪里运行 | 用途 | |------|--------------|---------------|---------| | **只读预飞行**（默认） | 无 | 托管或本地 | 安全检查、风险分析、演示 | | **用户签名** | 您自己的钱包 | 任意位置 | 安全之手验证；您在外部签名，然后它验证 + 中继广播 | | **托管执行** | 本地加密钱包 | 仅限自托管 | 主网上的完全代理自主权，需选择加入 | | **环境钱包**（高级） | 环境变量中的 `PRIVATE_KEY` | 本地开发 | 本地主网开发 | 只读使用不需要 `.env`、私钥或授权。 --- ## 安装 ```bash npx skills add SZtch/safehands-pharos ``` ### Claude Desktop（或任何 MCP 客户端） 添加到 `claude_desktop_config.json` 并重启。默认是只读的，没有密钥、钱包或设置： ```json { "mcpServers": { "safehands": { "command": "npx", "args": ["-y", "github:SZtch/safehands-pharos"] } } } ``` 然后询问：**“对这个付款运行一个 SafeHands 预检查。”** 要运行 **自托管托管执行** 在您自己的机器上，请添加一个 `env` 块。安全之手在第一次运行时创建一个本地 AES-256-GCM 加密钱包；您从一个 faucet 中为其充值，并在您解锁写入工具之前授权： ```json { "mcpServers": { "safehands": { "command": "npx", "args": ["-y", "github:SZtch/safehands-pharos"], "env": { "WALLET_MODE": "managed-mainnet", "WRITE_TOOLS_ENABLED": "true" } } } } ``` ### CLI ```bash npx github:SZtch/safehands-pharos skill safehands_preflight_check \ '{"actionType":"approve_token","chainId":1672,"approvalToken":"USDC","spender":"0x000000000000000000000000000000000000dEaD","approvalAmount":"max"}' ``` 每个工具返回相同的信封：`{ "success": true, "data": { … }, "error": null, "timestamp": "…" }`。 --- ## 33 种工具 ### 安全预检查 — 公共，无需密钥或身份验证 | 工具 | 它做什么 | |------|--------------| | `safehands_preflight_check` | 策略预检查 → 公共决策（允许 / 阻止 / 需要确认 / 仅准备） | | `safehands_x402_preflight` | x402 调用前 URL + 支付安全性检查 | | `safehands_risk_report` | 带有链上注册表数据的人类可读风险摘要 | | `safehands_wallet_health` | 钱包、签名者、gas 和 x402 准备情况 | | `explain_risk` | 将决策翻译成纯英文 | | `token_registry_status` | 规范 / 自定义 / 未知代币检查 | | `query_risk_registry` | 从注册表中读取链上风险记录 | | `verify_risk_inclusion` | 证明目标的风险记录包含在提交的 Merkle 根（本地重建 + 链上 `verifyRiskRecord` 视图）。无密钥 | | `get_agent_reputation` | 读取地址的链上验证安全跟踪记录（次数 + 最近）。无密钥，可组合 | ### 风险 + 分析 | 工具 | 它做什么 | |------|--------------| | `assess_risk` | 5 维风险评分（0-100） | | `check_token_security` | 通过 GoPlus（主网）进行代币安全检查 | | `simulate_transaction` | 广播前模拟运行 | | `estimate_gas` | gas 估计 + 充足性检查 | | `check_allowance` | ERC-20 批准检查 | ### 市场 + 链上数据 | 工具 | 它做什么 | |------|--------------| | `get_token_price` | 通过 DODO 获取代币价格 | | `get_wallet_balance` | PROS / USDC / USDT 余额 | | `get_gas_price` | 当前 gas 价格 | | `get_pool_info` | 通过 DODO 获取池信息 | | `get_transaction_status` | 按哈希获取交易状态 | | `get_execution_history` | 钱包转账历史 | | `query_goldsky_subgraph` | 查询索引的证明 / 注册事件（Goldsky） | | `get_spv_proof` | `eth_getProof` 状态树证明对抗块状态根 | ### 执行 — 限制：`WRITE_TOOLS_ENABLED` + 策略 + 托管身份验证 > ⚠️ **实验性 / 未经审计。** 编写工具默认禁用，需选择加入，仅限自托管、单租户 — 审核表面是只读预检查层。 | 工具 | 它做什么 | |------|--------------| | `safehands_safe_execute` | 预检查 + 一键执行 | | `execute_swap` | 通过 FaroSwap / DODO 路由交换 | | `send_payment` | 发送原生 PROS | | `approve_token` | ERC-20 批准（默认阻止无限批准） | | `publish_risk_score` | 发布风险记录（旧版） | | `x402_pay_and_fetch` | 获取 x402 资源，支付后 402 | ### 代理策略 | 工具 | 它做什么 | |------|--------------| | `get_agent_policy` | 读取代理活动安全策略 | | `set_agent_policy` | 设置/更新策略（保守 / 平衡 / 高级 / 自定义） | ### 托管钱包 | 工具 | 它做什么 | |------|--------------| | `create_agent_wallet` | 创建托管钱包（AES-256-GCM 加密） | | `get_agent_wallet` | 钱包地址 + 元数据 | | `get_agent_wallet_balance` | 托管钱包余额 | --- ## 每个代理的策略 不同代理可以承担不同的风险阈值。硬安全规则（主网守卫，零地址，SSRF，未授权的托管执行）永远不能被任何配置文件覆盖。 | 配置文件 | 最大付款 | 最大交换 | 每日支出 | x402 | 批准 | |---------|-------------|----------|-------------|------|----------| | `conservative` | 0.1 PROS | 1 PROS | 5 PROS | 0.01 USDC | 10 USDC | | `balanced` *(默认)* | 1 PROS | 10 PROS | 25 PROS | 0.1 USDC | 50 USDC | | `advanced` | 100 PROS | 1000 PROS | 5000 PROS | 1 USDC | 500 USDC | | `custom` | 用户定义 | 用户定义 | 用户定义 | 用户定义 | 用户定义 | 策略存储在 `.agents/policies/` 中。提高限制需要显式保存的配置文件；运行时或提示注入不能无声地扩大它。 --- ## x402 SafeHands 通过在签署或结算之前验证 HTTP 402 要求，使基于代理的 x402 支付更加安全： - `safehands_x402_preflight` — 无支付，无授权，URL + 金额安全 - `x402_pay_and_fetch` — 在策略限制后执行受控 - 阻止 SSRF 和重定向-SSRF；强制执行支付金额、代币和每个代理的上限 - 重放/幂等性由持久存储支持（配置为 Upstash Redis，本地 JSON 备用） --- ## 链上注册 + 证明 SafeHands 在 Pharos Pacific 主网上部署了两个合约：一个**注册**合约（授权操作员/代理，Merkle 风险根，`verifyRiskRecord` 视图）和一个**证明**合约（隐私保护的已验证安全记录 + 声誉）。 | | | |---|---| | 注册 | [`0x428e02bf85412e7242d991cd6725ec59e8b06c8d`](https://www.pharosscan.xyz/address/0x428e02bf85412e7242d991cd6725ec59e8b06c8d) | | 证明 | [`0x71a7a87b3b1ab6d86204cad691bb32fd75b4588c`](https://www.pharosscan.xyz/address/0x71a7a87b3b1ab6d86204cad691bb32fd75b4588c) | | 网络 | Pharos Pacific 主网（链 `1672`） | | 来源 | `contracts/SafeHandsRegistry.sol`，`contracts/SafeHandsAttestation.sol` | 上述地址是规范的实时部署（请在浏览器上验证）。后端从 `SAFEHANDS_REGISTRY_ADDRESS` / `SAFEHANDS_ATTESTATION_ADDRESS` 读取它们，因此您可以指向自己的重新部署而无需修改代码。 **证明广播。** 如果 SafeHands 中继广播，它会证明它。当启用证明广播路径并且用户签名交易成功广播时，会在链上写入证明。记录仅发布哈希上下文（`preparedTransactionHash`，`policyHash`，`metadataHash`）以及 `txHash`，永远不会发布原始调用数据、密钥、金额、收件人或意图。证明的燃料由专用的 `SAFEHANDS_ATTESTER_PRIVATE_KEY` 支付，该密钥与任何用户钱包分开，并且从不签署用户交易。如果需要证明但未配置，则在广播之前交易将被拒绝；如果广播成功但证明延迟，则 `txHash` 将诚实地返回，`attestationStatus: pending_retry`。 --- ## 网络 | | Pharos Pacific 主网 | |---|---| | 链 ID | `1672` | | 原生代币 | `PROS` | | RPC | `https://rpc.pharos.xyz` | | 浏览器 | `https://www.pharosscan.xyz` | Pharos Atlantic 测试网（`688689`）仍然可读以进行旧版检查，但已弃用执行。 --- ## 安全默认值 SafeHands 默认关闭。没有任何操作会在没有明确启用的情况下运行： - `WRITE_TOOLS_ENABLED=false` — 无写入工具 - `WALLET_MODE=none` — 不创建钱包（`managed-mainnet` 是可选的，仅限自托管） - 阻止无限批准 - 在设置写入/签名环境门控之前，主网执行禁用 - 阻止 SSRF 敏感 URL - 响应或日志中从不返回私钥 - 强制执行每个代理的策略限制和每日支出上限 - 链上注册授权控制执行 - 启动防护措施拒绝在公共主机上执行托管/写入操作 --- ## 测试 ```bash npm run build # 编译 npm test # 密封确定性套件（策略，x402 门控，写入授权，风险包含；无网络） npm run demo # 终端中的实时安全检查 npm run test:contracts # Hardhat 合约测试（离线烟雾回退） npm run test:all # 构建 + 测试 + 演示 + 合约 ``` `npm test` 不需要钱包、密钥或网络 — 它运行一个密封的确定性套件（策略引擎，x402 门控，写入工具授权，风险包含）并且从不广播。针对 Pharos 主网的实时只读 RPC 检查单独通过 `npm run test:live` 运行。要在主网上使用实时用户签名广播路径，请显式启用： ```bash SAFEHANDS_USER_SIGNED_BROADCAST_ENABLED=true SAFEHANDS_LIVE_BROADCAST_TEST=true npm run test:live-broadcast ``` 一个可选的自托管助手（`scripts/local-wallet-helper.mjs`）允许操作员使用其自己的钱包通过标准验证广播路径进行签名。它需要 `SAFEHANDS_LOCAL_WALLET_HELPER_ENABLED=true` 和一个保留在本地环境中的密钥。请使用专用的测试钱包。 --- ## 配置 ```env # 只读默认值 — 预飞行检查无需 .env 文件 PHAROS_ENVIRONMENT=pacific-mainnet PHAROS_CHAIN_ID=1672 PHAROS_RPC_URL=https://rpc.pharos.xyz WRITE_TOOLS_ENABLED=false # Pharos Pacific 上的实时 SafeHands 合约（1672） SAFEHANDS_REGISTRY_ADDRESS=0x428e02bf85412e7242d991cd6725ec59e8b06c8d SAFEHANDS_ATTESTATION_ADDRESS=0x71a7a87b3b1ab6d86204cad691bb32fd75b4588c # 自托管托管执行（启用） WALLET_MODE=managed-mainnet # none | env | managed-mainnet WRITE_TOOLS_ENABLED=true DODO_API_KEY= # 需要用于价格 / 池 / 兑换 ``` 参见 [.env.example](.env.example) 以获取完整的引用。 --- ## 已知限制 - 托管钱包加密为 AES-256-GCM，不是 KMS/Vault 级别 — 不适用于大额资金托管。 - 用户签名广播（`POST /broadcast/signed`）实时但默认禁用；如果没有 `SAFEHANDS_USER_SIGNED_BROADCAST_ENABLED=true`，它运行仅验证。 - GoPlus 代币安全不涵盖 Pharos 测试网（`688689`）。 - DODO 反向路由偶尔可能缺乏异国情调的货币对的流动性。 --- ## 路线图 目标很简单：成为每个 AI 代理在链上行动之前运行的安全检查。每个阶段都有一条规则：**ALLOW/BLOCK 决策保持确定性。模型提供建议；策略引擎做出决定。** **已发布（v2.3.0）：** - 跨 MCP、HTTP 和 CLI 的 33 种工具代理接口：预飞行检查、风险评分、链上声誉预言机、Merkle 包含验证器、市场/链数据、门控执行、每个代理的策略、托管钱包 - 确定性策略引擎：主网防护、批准限制、SSRF 防护、支出上限 - 注册 + 证明合约在 Pharos Pacific 主网上运行，可在链上验证 - GoPlus 代币安全性和 Goldsky 索引集成 - x402 预飞行检查和门控 `pay_and_fetch`，具有 SSRF/重定向保护 **下一步：** L1 风险根提交器自动化、数据可用性服务终点、更广泛的跨代理声誉读取以及 RWA 流的合规提供商集成（TRM Labs 筛查、Circle CCTP 结算 — 目前路线图，未集成）。 --- ## 许可证 MIT © [SZtch](https://github.com/SZtch)