spendshield 0.6.0__tar.gz

spendshield-0.6.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: spendshield
+Version: 0.6.0
+Summary: AI Agent 付款安全层: 干跑/预算/人工确认/审计 四道闸门
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=41
+
+# 💰 SpendShield — AI Agent 付款安全层
+
+> **AI 替你花钱之前，先过 SpendShield 这关。**
+
+让 AI Agent 下单、转账、调付费 API 之前，自动过四道闸门：
+**干跑预览 → 预算上限 → 人工确认 → 全量审计。**
+
+## 🩸 为什么会有这个项目（真实事故）
+
+2026 年 8 月 9 日，我的自动化系统测试下单。
+
+我传了 `dry: true`，以为只是试算价格。但服务器只认 `?dry=1` —— **4 单 99 元真实出码扣款，当天全部打水漂。**
+
+这不是我一个人的坑。AI Agent 时代正在到来：Agent 替你订餐、替你充值、替你调付费 API——**当 AI 开始花真钱，谁给它上闸门？**
+
+我把我踩过的坑，做成了一个库。
+
+## ✨ 四道闸门
+
+| 闸门 | 默认 | 作用 |
+|------|------|------|
+| 🧪 **dry_run** 干跑 | ✅ 开 | 只预览不执行——`dry` 参数失效也无所谓，库层面兜底 |
+| 💰 **budget** 预算 | 不限 | 总预算超支直接拒绝，绝不超花 |
+| 🚧 **max_amount** 单次上限 | 不限 | 单笔超限拦截（防"转 9999 给陌生人"） |
+| 🙋 **approval** 人工确认 | 关 | 花钱前必须人点头（console / 回调） |
+| 📜 **audit** 审计 | ✅ 开 | 每次尝试全留痕，导出 JSON 对账 |
+
+## 🔑 身份层（KYA 最小实现，v0.4）
+
+AI 没有法律人格，但必须有“数字身份”。每个 agent 注册专属策略，**未注册默认拒绝**：
+
+```python
+from spendshield import SpendShield, UnknownAgent
+
+guard = SpendShield(dry_run=False)
+guard.register_agent("mcd_bot", budget=50, max_amount=30,
+                     blacklist=["测试收款"], whitelist=["麦当劳"],
+                     rate_limit={"window_s": 60, "max_calls": 3})
+
+@guard.protect("下单", agent="mcd_bot")   # 或运行时传 agent=xx
+
+def place_order(amount, to):
+    return call_real_api(amount, to)
+```
+
+- 未注册的 agent 调用 → 直接拒绝（`UnknownAgent`），审计留痕 `blocked_unknown_agent`
+- `allow_unknown: true` 可回落全局策略（不推荐）
+- 每条审计记录带 `agent` 字段：**谁在花、花给谁、用户知不知道**
+- 策略即代码支持 `agents:` 段（YAML），预算/黑名单/频率/审批按 agent 隔离
+
+## 🎯 意图一致性（防提示注入，v0.5）
+
+AI 可能被劫持：提示注入、返利诱惑……闸门只知道“花多少、给谁”，不知道“这是用户要的吗”。
+解法：**敏感操作强制人工确认**——即使没配全局审批，新收款方/大额也默认拦下：
+
+```python
+# 新收款方（从未交易过）→ 必须确认；没配审批通道 → 直接拒绝
+# 金额 > approve_above → 必须确认
+guard = SpendShield(approve_new_recipient=True, approve_above=1000)
+```
+
+- 交易成功的收款方自动进入记忆，之后不再反复烦你
+- 白名单收款方永远跳过
+- 未配置审批通道时，敏感操作**直接拒绝**（宁可拦死，不放行）
+- 拦截记录 `blocked_approval` 带原因：新收款方 / 超阈值 / 未配置通道
+
+## 🔐 密钥保险库（v0.6）
+
+私钥不落地是 AI 支付的命门——**一次泄露，钱包被掏空**。密钥加密落盘，主密钥放环境变量，取用必须过闸门：
+
+```bash
+python -c "from spendshield import KeyVault; print(KeyVault.generate_key())"  # 生成主密钥(仅此一次)
+export SPENDGUARD_MASTER_KEY=<刚才的输出>   # 放环境变量, 别写进代码/仓库
+```
+
+```python
+from spendshield import SpendShield, KeyVault
+
+vault = KeyVault("vault.json")              # 主密钥从环境变量读
+vault.store("mcd_sk", "sk_live_xxxx")      # 加密落盘, 文件里只有密文
+
+guard = SpendShield(key_vault=vault)
+guard.register_agent("mcd_bot", whitelist=["mcd_sk"])
+sk = guard.get_secret("mcd_sk", agent="mcd_bot")   # 过身份+意图闸门才能取
+```
+
+- 落盘文件无明文（AES128-CBC + HMAC）；主密钥不落盘
+- 取密钥 = 敏感操作：未注册 agent 拒绝；新密钥名无审批通道默认拒绝（防提示注入偷密钥）
+- 每次取用留审计 `secret_access`：谁、何时、取了哪个密钥
+
+## 🚀 快速开始
+
+```bash
+pip install spendshield   # 或直接 clone 用
+```
+
+```python
+from spendshield import SpendShield
+
+guard = SpendShield(budget=200, dry_run=True, whitelist=["麦当劳"])   # 默认干跑 + 信任收款方
+
+@guard.protect("下单")
+def place_order(amount, to):
+    return call_real_api(amount, to)            # 真实下单逻辑
+
+# 干跑模式: 报错提示, 绝不真花
+place_order(amount=99, to="麦当劳")
+# => [SpendShield] dry_run: 下单 ¥99.0 -> 麦当劳 (未执行)
+# => DryRunBlocked: 关掉 dry_run 才会真花
+
+# 确认无误后放行, 预算闸门兜底
+guard.dry_run = False
+for i in range(4):
+    place_order(amount=99, to="麦当劳")          # 第3单被 BudgetExceeded 拦住
+```
+
+> 💡 新收款方默认需人工确认(意图一致性, 防提示注入)——把常用收款方加白名单或注册 Agent 身份可免。
+
+## 🎯 谁需要它
+
+- **AI Agent 框架用户**：给你的 Agent 工具加装饰器，一行接入
+- **自动化系统运维**：批量任务/定时下单，防误操作真扣款
+- **MCP / Function Call 开发者**：LLM 生成的工具调用，过闸门再执行
+- **所有被"测试单变真单"坑过的人** 🩸
+
+## 🗺 Roadmap
+
+- [x] v0.1 四道闸门 + 审计 + 装饰器接入
+- [ ] 收款方黑名单/白名单（陌生收款方强制确认）
+- [ ] 频率限制（同一收款方短时间 N 次）
+- [ ] MCP server 版（Agent 工具调用直接过闸）
+- [ ] 远程审批（企业微信/Telegram 确认）
+- [ ] 多策略插件（风控规则引擎）
+
+## 🧪 测试
+
+```bash
+python3 tests/test_guard.py   # 6 个测试全过
+```
+
+## 📄 License
+
+MIT — 拿去用。愿 AI 时代，没人再被"测试单"坑第二次。
+
+---
+
+**⭐ 如果这个项目对你有用，点个 star，让更多被坑过的人看到。**
+
+## 🤖 MCP Server（AI Agent 直接调用）
+
+让 Claude Code / OpenClaw 等 MCP 兼容 agent 直接通过工具调用过闸门：
+
+```bash
+# 启动(stdio 模式, agent 配置里指向它)
+python -m spendshield.mcp_server --policy spendshield.yaml
+# 或安装后: spendshield-mcp --policy spendshield.yaml
+```
+
+**工具**：
+- `spend_protect(action, amount, to)` — 保护一次花钱操作（走全部闸门）
+- `spend_status()` — 预算/已花/拦截统计
+- `spend_audit(limit)` — 最近审计记录
+- `spend_reset()` — 重置会话已花
+
+```json
+// agent 调用示例
+{"name": "spend_protect", "arguments": {"action": "下单", "amount": 99, "to": "麦当劳"}}
+// => {"ok": false, "reason": "[干跑] 下单 ¥99.0 -> 麦当劳 (未执行...)", "spent": 0.0}
+```

spendshield-0.6.0/README.md

@@ -0,0 +1,169 @@
+# 💰 SpendShield — AI Agent 付款安全层
+
+> **AI 替你花钱之前，先过 SpendShield 这关。**
+
+让 AI Agent 下单、转账、调付费 API 之前，自动过四道闸门：
+**干跑预览 → 预算上限 → 人工确认 → 全量审计。**
+
+## 🩸 为什么会有这个项目（真实事故）
+
+2026 年 8 月 9 日，我的自动化系统测试下单。
+
+我传了 `dry: true`，以为只是试算价格。但服务器只认 `?dry=1` —— **4 单 99 元真实出码扣款，当天全部打水漂。**
+
+这不是我一个人的坑。AI Agent 时代正在到来：Agent 替你订餐、替你充值、替你调付费 API——**当 AI 开始花真钱，谁给它上闸门？**
+
+我把我踩过的坑，做成了一个库。
+
+## ✨ 四道闸门
+
+| 闸门 | 默认 | 作用 |
+|------|------|------|
+| 🧪 **dry_run** 干跑 | ✅ 开 | 只预览不执行——`dry` 参数失效也无所谓，库层面兜底 |
+| 💰 **budget** 预算 | 不限 | 总预算超支直接拒绝，绝不超花 |
+| 🚧 **max_amount** 单次上限 | 不限 | 单笔超限拦截（防"转 9999 给陌生人"） |
+| 🙋 **approval** 人工确认 | 关 | 花钱前必须人点头（console / 回调） |
+| 📜 **audit** 审计 | ✅ 开 | 每次尝试全留痕，导出 JSON 对账 |
+
+## 🔑 身份层（KYA 最小实现，v0.4）
+
+AI 没有法律人格，但必须有“数字身份”。每个 agent 注册专属策略，**未注册默认拒绝**：
+
+```python
+from spendshield import SpendShield, UnknownAgent
+
+guard = SpendShield(dry_run=False)
+guard.register_agent("mcd_bot", budget=50, max_amount=30,
+                     blacklist=["测试收款"], whitelist=["麦当劳"],
+                     rate_limit={"window_s": 60, "max_calls": 3})
+
+@guard.protect("下单", agent="mcd_bot")   # 或运行时传 agent=xx
+
+def place_order(amount, to):
+    return call_real_api(amount, to)
+```
+
+- 未注册的 agent 调用 → 直接拒绝（`UnknownAgent`），审计留痕 `blocked_unknown_agent`
+- `allow_unknown: true` 可回落全局策略（不推荐）
+- 每条审计记录带 `agent` 字段：**谁在花、花给谁、用户知不知道**
+- 策略即代码支持 `agents:` 段（YAML），预算/黑名单/频率/审批按 agent 隔离
+
+## 🎯 意图一致性（防提示注入，v0.5）
+
+AI 可能被劫持：提示注入、返利诱惑……闸门只知道“花多少、给谁”，不知道“这是用户要的吗”。
+解法：**敏感操作强制人工确认**——即使没配全局审批，新收款方/大额也默认拦下：
+
+```python
+# 新收款方（从未交易过）→ 必须确认；没配审批通道 → 直接拒绝
+# 金额 > approve_above → 必须确认
+guard = SpendShield(approve_new_recipient=True, approve_above=1000)
+```
+
+- 交易成功的收款方自动进入记忆，之后不再反复烦你
+- 白名单收款方永远跳过
+- 未配置审批通道时，敏感操作**直接拒绝**（宁可拦死，不放行）
+- 拦截记录 `blocked_approval` 带原因：新收款方 / 超阈值 / 未配置通道
+
+## 🔐 密钥保险库（v0.6）
+
+私钥不落地是 AI 支付的命门——**一次泄露，钱包被掏空**。密钥加密落盘，主密钥放环境变量，取用必须过闸门：
+
+```bash
+python -c "from spendshield import KeyVault; print(KeyVault.generate_key())"  # 生成主密钥(仅此一次)
+export SPENDGUARD_MASTER_KEY=<刚才的输出>   # 放环境变量, 别写进代码/仓库
+```
+
+```python
+from spendshield import SpendShield, KeyVault
+
+vault = KeyVault("vault.json")              # 主密钥从环境变量读
+vault.store("mcd_sk", "sk_live_xxxx")      # 加密落盘, 文件里只有密文
+
+guard = SpendShield(key_vault=vault)
+guard.register_agent("mcd_bot", whitelist=["mcd_sk"])
+sk = guard.get_secret("mcd_sk", agent="mcd_bot")   # 过身份+意图闸门才能取
+```
+
+- 落盘文件无明文（AES128-CBC + HMAC）；主密钥不落盘
+- 取密钥 = 敏感操作：未注册 agent 拒绝；新密钥名无审批通道默认拒绝（防提示注入偷密钥）
+- 每次取用留审计 `secret_access`：谁、何时、取了哪个密钥
+
+## 🚀 快速开始
+
+```bash
+pip install spendshield   # 或直接 clone 用
+```
+
+```python
+from spendshield import SpendShield
+
+guard = SpendShield(budget=200, dry_run=True, whitelist=["麦当劳"])   # 默认干跑 + 信任收款方
+
+@guard.protect("下单")
+def place_order(amount, to):
+    return call_real_api(amount, to)            # 真实下单逻辑
+
+# 干跑模式: 报错提示, 绝不真花
+place_order(amount=99, to="麦当劳")
+# => [SpendShield] dry_run: 下单 ¥99.0 -> 麦当劳 (未执行)
+# => DryRunBlocked: 关掉 dry_run 才会真花
+
+# 确认无误后放行, 预算闸门兜底
+guard.dry_run = False
+for i in range(4):
+    place_order(amount=99, to="麦当劳")          # 第3单被 BudgetExceeded 拦住
+```
+
+> 💡 新收款方默认需人工确认(意图一致性, 防提示注入)——把常用收款方加白名单或注册 Agent 身份可免。
+
+## 🎯 谁需要它
+
+- **AI Agent 框架用户**：给你的 Agent 工具加装饰器，一行接入
+- **自动化系统运维**：批量任务/定时下单，防误操作真扣款
+- **MCP / Function Call 开发者**：LLM 生成的工具调用，过闸门再执行
+- **所有被"测试单变真单"坑过的人** 🩸
+
+## 🗺 Roadmap
+
+- [x] v0.1 四道闸门 + 审计 + 装饰器接入
+- [ ] 收款方黑名单/白名单（陌生收款方强制确认）
+- [ ] 频率限制（同一收款方短时间 N 次）
+- [ ] MCP server 版（Agent 工具调用直接过闸）
+- [ ] 远程审批（企业微信/Telegram 确认）
+- [ ] 多策略插件（风控规则引擎）
+
+## 🧪 测试
+
+```bash
+python3 tests/test_guard.py   # 6 个测试全过
+```
+
+## 📄 License
+
+MIT — 拿去用。愿 AI 时代，没人再被"测试单"坑第二次。
+
+---
+
+**⭐ 如果这个项目对你有用，点个 star，让更多被坑过的人看到。**
+
+## 🤖 MCP Server（AI Agent 直接调用）
+
+让 Claude Code / OpenClaw 等 MCP 兼容 agent 直接通过工具调用过闸门：
+
+```bash
+# 启动(stdio 模式, agent 配置里指向它)
+python -m spendshield.mcp_server --policy spendshield.yaml
+# 或安装后: spendshield-mcp --policy spendshield.yaml
+```
+
+**工具**：
+- `spend_protect(action, amount, to)` — 保护一次花钱操作（走全部闸门）
+- `spend_status()` — 预算/已花/拦截统计
+- `spend_audit(limit)` — 最近审计记录
+- `spend_reset()` — 重置会话已花
+
+```json
+// agent 调用示例
+{"name": "spend_protect", "arguments": {"action": "下单", "amount": 99, "to": "麦当劳"}}
+// => {"ok": false, "reason": "[干跑] 下单 ¥99.0 -> 麦当劳 (未执行...)", "spent": 0.0}
+```

spendshield-0.6.0/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "spendshield"
+version = "0.6.0"
+description = "AI Agent 付款安全层: 干跑/预算/人工确认/审计 四道闸门"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+dependencies = ["cryptography>=41"]
+
+[tool.setuptools]
+packages = ["spendshield"]
+
+[project.scripts]
+spendshield-mcp = "spendshield.mcp_server:main"

spendshield-0.6.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

spendshield-0.6.0/spendshield/__init__.py

@@ -0,0 +1,32 @@
+# -*- coding: utf-8 -*-
+"""
+SpendShield — AI Agent 付款安全层
+
+给 AI Agent 的「花钱动作」加上四道闸门:
+  1. dry_run    干跑模式(默认开): 只预览, 不真花
+  2. budget     预算上限: 超了直接拒绝
+  3. approval   人工确认: 花钱前必须人点头
+  4. audit      全量审计: 每次尝试都留痕
+
+血泪背景: 2026-08-09, 我让自动化系统测试下单, 因为 dry 参数没生效,
+4 单 99 元真实出码扣款。这个库就是那次事故的产物——
+AI 时代, 别让 Agent 替你花钱之前没有闸门。
+
+用法:
+    from spendshield import SpendShield
+
+    guard = SpendShield(budget=100, dry_run=True, approval="console")
+
+    @guard.protect("下单", max_amount=50)
+    def place_order(order_id, amount, to):
+        # ... 真实下单逻辑
+        return {"ok": True}
+"""
+from .guard import SpendShield, GuardedError, BudgetExceeded, NeedsApproval, DryRunBlocked, UnknownAgent, AuditRecord
+from .vault import KeyVault
+
+__version__ = "0.6.0"
+__all__ = [
+    "SpendShield", "GuardedError", "BudgetExceeded",
+    "NeedsApproval", "DryRunBlocked", "UnknownAgent", "AuditRecord", "KeyVault",
+]

spendshield-0.6.0/spendshield/dashboard.py

@@ -0,0 +1,119 @@
+# -*- coding: utf-8 -*-
+"""SpendShield 审计 Dashboard — 可视化审计记录
+
+用法:
+  1. 程序里导出审计: guard.export_audit("audit.json")
+  2. 启动看板:      python -m spendshield.dashboard --file audit.json --port 8775
+  3. 打开 http://localhost:8775
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from urllib.parse import urlparse
+
+PAGE = """<!DOCTYPE html>
+<html lang="zh-CN"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>SpendShield 审计 Dashboard</title>
+<style>
+*{margin:0;padding:0;box-sizing:border-box}
+body{font-family:-apple-system,'PingFang SC','Microsoft YaHei',sans-serif;background:radial-gradient(900px 500px at 20% -10%,#1b1633 0%,#0b0e14 55%);color:#e6e8ee;padding:28px;min-height:100vh}
+h1{font-size:20px;font-weight:800;margin-bottom:4px}h1 span{color:#a78bfa}
+.sub{color:#7d8590;font-size:13px;margin-bottom:20px}
+.stats{display:grid;grid-template-columns:repeat(auto-fit,minmax(140px,1fr));gap:12px;margin-bottom:20px}
+.stat{background:#141b26;border:1px solid #21262d;border-radius:10px;padding:12px 14px}
+.stat .v{font-size:24px;font-weight:800;line-height:1.2}
+.stat .k{font-size:12px;color:#7d8590;margin-top:2px}
+.stat .v.green{color:#3fb950}.stat .v.red{color:#f85149}.stat .v.purple{color:#a78bfa}.stat .v.yellow{color:#d29922}
+table{width:100%;border-collapse:collapse;font-size:13px}
+th,td{padding:9px 12px;text-align:left;border-bottom:1px solid #21262d}
+th{color:#7d8590;font-weight:600;font-size:12px}
+.blocked{color:#f85149}.executed{color:#3fb950}.dry{color:#d29922}
+</style></head><body>
+<h1>💰 SpendShield <span>审计 Dashboard</span></h1>
+<div class="sub" id="meta">加载中...</div>
+<div class="stats" id="stats"></div>
+<table id="tbl"><thead><tr>
+<th>时间</th><th>操作</th><th>金额</th><th>收款方</th><th>决策</th><th>原因</th><th>累计已花</th>
+</tr></thead><tbody></tbody></table>
+<script>
+async function load(){
+  const r=await fetch('/api/audit');const d=await r.json();
+  const recs=d.records||[];
+  document.getElementById('meta').textContent=`${recs.length} 条记录 · 更新于 ${new Date().toLocaleTimeString()} · 30s 自动刷新`;
+  const executed=recs.filter(x=>x.decision==='executed');
+  const blocked=recs.filter(x=>x.decision.startsWith('blocked')||x.decision==='dry_run');
+  const spent=executed.reduce((s,x)=>s+(x.amount||0),0);
+  const maxAmt=Math.max(...recs.map(x=>x.amount||0),0);
+  document.getElementById('stats').innerHTML=
+   `<div class="stat"><div class="v purple">${recs.length}</div><div class="k">总尝试</div></div>
+    <div class="stat"><div class="v green">${executed.length}</div><div class="k">已放行</div></div>
+    <div class="stat"><div class="v red">${blocked.length}</div><div class="k">被拦截</div></div>
+    <div class="stat"><div class="v">¥${spent.toFixed(2)}</div><div class="k">累计已花</div></div>
+    <div class="stat"><div class="v yellow">¥${maxAmt.toFixed(2)}</div><div class="k">最大单笔</div></div>`;
+  const tb=document.querySelector('#tbl tbody');tb.innerHTML='';
+  for(const r of recs){
+    const cls=r.decision==='executed'?'executed':(r.decision==='dry_run'?'dry':'blocked');
+    const t=new Date(r.ts*1000).toLocaleString('zh-CN',{month:'2-digit',day:'2-digit',hour:'2-digit',minute:'2-digit',second:'2-digit'});
+    tb.insertAdjacentHTML('beforeend',
+      `<tr><td>${t}</td><td>${r.action}</td><td>¥${(r.amount||0).toFixed(2)}</td><td>${r.to}</td>
+       <td class="${cls}">${r.decision}</td><td style="color:#9da7b3">${r.reason||''}</td><td>¥${(r.spent_after||0).toFixed(2)}</td></tr>`);
+  }
+}
+load();setInterval(load,30000);
+</script></body></html>
+"""
+
+
+class Handler(BaseHTTPRequestHandler):
+    file = "audit.json"
+
+    def _json(self, obj):
+        body = json.dumps(obj, ensure_ascii=False).encode()
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_GET(self):
+        u = urlparse(self.path)
+        if u.path in ("/", "/index.html"):
+            body = PAGE.encode()
+            self.send_response(200)
+            self.send_header("Content-Type", "text/html; charset=utf-8")
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+        elif u.path == "/api/audit":
+            try:
+                with open(self.file, encoding="utf-8") as f:
+                    records = json.load(f)
+            except Exception:
+                records = []
+            self._json({"records": records})
+        else:
+            self._json({"error": "not found"})
+
+    def log_message(self, *a):
+        pass
+
+
+def main():
+    ap = argparse.ArgumentParser(prog="spendshield-dashboard")
+    ap.add_argument("--file", default="audit.json", help="审计 JSON 文件")
+    ap.add_argument("--port", type=int, default=8775)
+    args = ap.parse_args()
+    Handler.file = args.file
+    srv = ThreadingHTTPServer(("0.0.0.0", args.port), Handler)
+    print(f"SpendShield 审计看板: http://localhost:{args.port}  (file={args.file})")
+    srv.serve_forever()
+
+
+if __name__ == "__main__":
+    main()