verify-atom

验证服务（“原子”）—— v1 后端

验证原子的生产后端：**“帮我检查这一件事，并证明你确实做了。”**客户端 POST 一个问题（对 URL 执行 http_observation）；服务会进行真实观测，并返回一个带有透明成本核算的签名证明数据包。每次验证都会追加到公开、永久的账本——公告板。

先说明一些事实：

• 每个数据包中的 cost_usd 都是由运营方配置的估算值，并非云账单的计量值（"cost_basis": "estimate"）。在定价前请重新校准。
• **付款功能已停用。**v1 中没有集成支付服务提供商；若 payments.enabled 为 true 但未配置支付服务提供商，服务将拒绝启动。
• 本服务不对收入作出任何声明。标注的价格只是报价；目前无法收费，因此不会收取任何费用。

架构

MCP 服务（mcp/）

此仓库还提供一个 Model Context Protocol 服务，将验证原子作为 MCP 工具开放，以便兼容 MCP 的 Agent 直接请求签名证明数据包。

• 安装：uvx verify-atom-mcp（已在 PyPI 上发布，包名为 verify-atom-mcp）
• 已列入官方 MCP 注册表，名称为 io.github.asherengos/verify-atom
• **传输方式：**stdio · 工具：verify — 对 URL 执行 HTTP 观测，并返回 Ed25519 签名的证明数据包
• 源码：mcp/mcp_server.py（零依赖；详情见 mcp/README.md）

文件	作用
app.py	Flask 应用：路由、带 SSRF 防护的 HTTP 观测、数据包组装
signing.py	Ed25519 密钥管理与签名/验证（加密核心来自 Asher AI Studios Work Kernel，并以 vendored 方式引入，日期为 2026-09-25；纯 Python，符合 RFC 8032，零依赖）
costs.py / cost_model.yaml	每次验证的用量测量 × 运营方配置的费率
ledger.py	只追加的 JSONL 账本（data/ledger.jsonl）：公告板的事实来源，也是诚实循环的输入
mini_yaml.py	严格的 YAML 子集读取器（将依赖限制为 flask + waitress；不是通用解析器）
config.yaml	服务配置：端口、数据目录、价格、护栏、付款开关
tests/test_service.py	独立运行的 pytest 测试套件（本地 stub 服务；不访问外部网络）

一次验证的流程：POST /verify → SSRF 防护 → 真实的套接字级 HTTP 获取（单次 DNS 解析；已检查的地址就是实际连接的地址；绝不跟随重定向）→ 观测与证据 → 成本核算 → 对规范 JSON 进行 Ed25519 签名 → 追加到账本 → 证明数据包。

快速开始

cd ~/workspace/verify-service
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt   # flask + waitress only; free
.venv/bin/python app.py                     # serves on 127.0.0.1:5057 via waitress

首次运行时会在 data/keys/ 下生成一对 Ed25519 密钥（权限为 0600）。data/ 已加入 gitignore：账本、密钥和运行时状态都不会进入仓库。

开发环境（Flask 内置服务器，请勿用于生产环境）：

.venv/bin/python -m flask --app app:create_app run -p 5057

API 参考

POST /verify — 执行验证

curl -s -X POST http://127.0.0.1:5057/verify \
  -H 'Content-Type: application/json' \
  -d '{"type":"http_observation","url":"https://example.com"}' | python3 -m json.tool

响应：签名证明数据包。

{
  "id": "VRF-20260926-3f9a2c1d",
  "type": "http_observation",
  "verdict": "CONFIRMED",
  "target": {"url": "https://example.com"},
  "observation": {
    "reachable": true,
    "http_status": 200,
    "page_title": "Example Domain",
    "body_sha256": "…",
    "tls": {"subject": "…", "issuer": "…", "not_after": "…"},
    "dns": {"host": "example.com", "addresses": ["93.184.216.34"]}
  },
  "evidence": [{"kind": "http_status", "value": 200}, …],
  "timestamp_utc": "2026-09-26T02:30:00Z",
  "usage": {"wall_time_s": 0.41, "bytes_in": 1830, "http_requests": 1},
  "cost_usd": 0.0000109,
  "cost_basis": "estimate",
  "price_quote_usd": 0.005,
  "margin_usd": 0.0049891,
  "below_cost": false,
  "signature": "<64-byte ed25519 hex>",
  "signing": {"algorithm": "Ed25519", "public_key_hex": "…",
              "signed_fields": "all fields except 'signature' and 'signing'"}
}

判定结果：CONFIRMED（已获取，HTTP 2xx）、UNCONFIRMED（已获取，但状态码不同——这是一条真实的否定观测）、ERROR（请求被拒绝或失败；observation.reason 会说明原因）。未知的 type → 400 unknown_type。

抽查数据包（无需信任）：

# fetch the service public key, then verify the signature offline:
curl -s http://127.0.0.1:5057/key

签名覆盖除 signature 和 signing 之外的所有数据包字段的规范 JSON（键已排序，分隔符紧凑）。使用任意 Ed25519 实现重新计算并验证即可。

GET /verify/ — 获取已存储的证明数据包（未知时返回 404）

curl -s http://127.0.0.1:5057/verify/VRF-20260926-3f9a2c1d | python3 -m json.tool

GET /board/feed — 公开的只追加信息流，按时间从早到晚排列

curl -s http://127.0.0.1:5057/board/feed | python3 -m json.tool

每条记录：{id, timestamp_utc, type, verdict, url}。

GET /health

curl -s http://127.0.0.1:5057/health
# {"status":"ok","version":"0.1.0","payments_enabled":false}

GET /key — 服务的 Ed25519 公钥

curl -s http://127.0.0.1:5057/key
# {"algorithm":"Ed25519","public_key_hex":"…"}

私钥绝不会被记录、提供，也不会离开 signing.py。

配置（config.yaml）

键	默认值	含义
service.port	5057	监听端口
service.data_dir	data	运行时状态（账本、密钥）；已加入 git 忽略
verify.base_price_usd	0.005	每次验证的报价（仅为报价，不会收费）
verify.timeout_s	10	每次观测的网络超时时间
verify.max_body_bytes	2097152	正文上限为 2 MB；超出时判定结果为 ERROR
verify.allow_private	false	生产环境中绝不可设为 true。 允许隔离测试使用 127.0.0.1 存根
cost_model	cost_model.yaml	运营方配置的费率文件路径
payments.enabled	false	总开关。若设为 true 但未配置支付提供方 → 拒绝启动

密钥管理

• 首次运行：KeyStore 会生成 Ed25519 密钥对，写入 data/keys/{private.key,public.key}（目录权限为 0700，文件权限为 0600；若密钥已存在则拒绝覆盖）。
• 将 private.key 离线备份；若丢失，该看板的信任链将无法延续 （旧数据包仍可使用已发布的公钥验证，但服务将无法再签名）。
• 轮换（v1 中未自动化）：生成新的密钥对，通过 /key 发布新的公钥并附带 key_id，保留旧公钥的发布状态以供历史验证。请参阅上线检查清单。

部署说明

$0 上线套件位于 deploy/ 中：

文件	作用
deploy/verify-service.service	加固的 systemd 单元（以非特权 verify 用户运行，设置 NoNewPrivileges、PrivateTmp、ProtectSystem=strict，并在失败时重启）
deploy/Caddyfile	带自动 TLS 的反向代理；转发真实客户端 IP（X-Forwarded-For）——应用仅信任来自 127.0.0.1/::1 的该标头
deploy/DEPLOY.md	面向非专业人员的有序操作手册：Oracle Cloud Always Free ARM VM、加固、首次启动时生成密钥对、systemd、Caddy、DNS、上线检查

内置滥用防护：POST /verify 会按客户端 IP 进行速率限制 （滑动 60 秒窗口，verify.rate_limit_per_minute，默认 30 次/分钟）。 超过上限 → 返回带有 Retry-After 标头的 429 JSON。将 rate_limit_per_minute: 0 设为禁用（公共端点绝不可禁用）。

每个数据目录只运行一个工作进程（v1 的账本不支持跨进程锁定）。服务仅绑定到 127.0.0.1；公共流量通过反向代理进入。

供人类和 Agent 使用的机器可读文档：GET /llms.txt （text/plain）——包含端点约定、证明数据包字段、如何离线验证签名以及诚信说明。

v1 的已知限制（如实说明）

• 仅支持 HTTP/1.1；绝不跟随重定向（记录为 UNCONFIRMED）。
• 不支持 HTTP/2，也不会渲染 JavaScript：观测内容是原始 HTTP 响应，哈希和签名的正是该响应。
• 每次验证只解析一次 DNS；若恶意 DNS 在解析和连接之间的几毫秒内切换应答，则超出 v1 的处理范围（已记录，但除单次解析设计外不作缓解）。
• 单个工作进程；账本扫描的复杂度为 O(n)。
• 纯 Python Ed25519：实现正确，但比 C 实现慢——足以应对 v1 的负载；扩展规模前应采用经过审查的 C 库。

上线检查清单

• 部署包（deploy/，构建于 2026-09-26）：加固版 systemd 单元、带自动 TLS 的 Caddyfile、DEPLOY.md 操作手册（Oracle Cloud Always Free ARM VM，人工操作步骤已标注）、POST /verify 按 IP 限流（默认 30 次/分钟，返回 429 + Retry-After）、 机器可读的 API 文档 /llms.txt。全部 $0，仅使用标准库，没有 支付代码路径。测试：26/26 通过。
• 托管：按照 deploy/DEPLOY.md 配置 VM；确定数据目录的 备份方案（操作手册中包含账本和密钥备份）。
• 支付提供商集成：尚未构建。实现扣款流程，将其接入 payments.provider，然后设为 enabled: true。
• 全新的生产密钥对：按照操作手册在首次启动时生成（切勿 从开发环境复制 data/）；发布公钥；将私钥离线备份。
• 实际成本校准：用计量值替换 cost_model.yaml 中的估算值； 运行一批校准；在报出实际价格前确认 margin_usd > 0。
• 条款与滥用政策：编写并发布可接受使用政策，以及验证失败 （ERROR）时的退款政策。（限流功能现已内置；剩下的是边缘策略。）
• TLS + 反向代理：由 deploy/Caddyfile 提供；替换占位域名， 验证配置并重新加载。
• 编写并演练密钥轮换流程。
• 监控：在 /health 上配置 UptimeRobot 免费监控；监控账本 增长、below_cost 次数和错误率——诚实的闭环必须在闭环变红时 通知相关人员。