Skip to content
Back to search

verify-atom

Verification Service ("the atom") — v1 backend

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/asherengos--verify-atom/badge.svg)](/listings/asherengos--verify-atom)

HTML

<a href="/listings/asherengos--verify-atom"><img src="/api/listings/asherengos--verify-atom/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

First run generates an Ed25519 keypair under `data/keys/` (0600). `data/` is gitignored: ledger, keys, and runtime state never enter the repo.

Development (Flask built-in server, do not use in production):

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 232 lines
  1. # Verification Service ("the atom") — v1 backend
  2. The production backend for the verification atom: **"check this one thing
  3. for me, and prove you did."** A client POSTs one question
  4. (`http_observation` of a URL); the service performs a real observation and
  5. returns a signed proof packet with transparent cost accounting. Every
  6. verification is appended to a public, permanent ledger — the board.
  7. **Honesty, up front:**
  8. * `cost_usd` on every packet is an **operator-configured estimate**, not a
  9. metered cloud bill (`"cost_basis": "estimate"`). Recalibrate before pricing.
  10. * **Payments are disabled.** There is no payment provider integration in v1,
  11. and the service refuses to start if `payments.enabled` is true without one.
  12. * This service makes **no revenue claims**. Quoted prices are quotes; nothing
  13. is charged, because nothing can be charged yet.
  14. ## Architecture
  15. ## MCP server (`mcp/`)
  16. This repo also ships a [Model Context Protocol](https://modelcontextprotocol.io) server that exposes the verification atom as an MCP tool, so MCP-compatible agents can request signed proof packets directly.
  17. - **Install:** `uvx verify-atom-mcp` (published on PyPI as `verify-atom-mcp`)
  18. - **Listed in the official MCP registry** as `io.github.asherengos/verify-atom`
  19. - **Transport:** stdio · **Tool:** `verify` — performs an HTTP observation of a URL and returns the Ed25519-signed proof packet
  20. - Source: `mcp/mcp_server.py` (zero dependencies; `mcp/README.md` has the details)
  21. | File | Role |
  22. |---|---|
  23. | `app.py` | Flask app: routes, SSRF-guarded HTTP observation, packet assembly |
  24. | `signing.py` | Ed25519 key management + sign/verify (crypto core vendored from the Asher AI Studios Work Kernel, 2026-09-25; pure Python, RFC 8032, zero deps) |
  25. | `costs.py` / `cost_model.yaml` | Per-verification usage measurement × operator-configured rates |
  26. | `ledger.py` | Append-only JSONL ledger (`data/ledger.jsonl`): the board's source of truth and the honest loop's input |
  27. | `mini_yaml.py` | Strict subset YAML reader (keeps deps to flask + waitress; not a general parser) |
  28. | `config.yaml` | Service config: port, data dir, price, guardrails, payments switch |
  29. | `tests/test_service.py` | Hermetic pytest suite (local stub server; no external network) |
  30. A verification flows: `POST /verify` → SSRF guard → real socket-level HTTP
  31. fetch (single DNS resolution; the checked address is the connected address;
  32. redirects never followed) → observation + evidence → cost accounting →
  33. Ed25519 signature over canonical JSON → append to ledger → proof packet.
  34. ## Quick start
  35. ```bash
  36. cd ~/workspace/verify-service
  37. python3 -m venv .venv
  38. .venv/bin/pip install -r requirements.txt # flask + waitress only; free
  39. .venv/bin/python app.py # serves on 127.0.0.1:5057 via waitress
  40. ```
  41. First run generates an Ed25519 keypair under `data/keys/` (0600). `data/`
  42. is gitignored: ledger, keys, and runtime state never enter the repo.
  43. Development (Flask built-in server, do not use in production):
  44. ```bash
  45. .venv/bin/python -m flask --app app:create_app run -p 5057
  46. ```
  47. ## API reference
  48. ### POST /verify — perform a verification
  49. ```bash
  50. curl -s -X POST http://127.0.0.1:5057/verify \
  51. -H 'Content-Type: application/json' \
  52. -d '{"type":"http_observation","url":"https://example.com"}' | python3 -m json.tool
  53. ```
  54. Response: a signed proof packet.
  55. ```json
  56. {
  57. "id": "VRF-20260926-3f9a2c1d",
  58. "type": "http_observation",
  59. "verdict": "CONFIRMED",
  60. "target": {"url": "https://example.com"},
  61. "observation": {
  62. "reachable": true,
  63. "http_status": 200,
  64. "page_title": "Example Domain",
  65. "body_sha256": "…",
  66. "tls": {"subject": "…", "issuer": "…", "not_after": "…"},
  67. "dns": {"host": "example.com", "addresses": ["93.184.216.34"]}
  68. },
  69. "evidence": [{"kind": "http_status", "value": 200}, …],
  70. "timestamp_utc": "2026-09-26T02:30:00Z",
  71. "usage": {"wall_time_s": 0.41, "bytes_in": 1830, "http_requests": 1},
  72. "cost_usd": 0.0000109,
  73. "cost_basis": "estimate",
  74. "price_quote_usd": 0.005,
  75. "margin_usd": 0.0049891,
  76. "below_cost": false,
  77. "signature": "<64-byte ed25519 hex>",
  78. "signing": {"algorithm": "Ed25519", "public_key_hex": "…",
  79. "signed_fields": "all fields except 'signature' and 'signing'"}
  80. }
  81. ```
  82. Verdicts: `CONFIRMED` (fetched, HTTP 2xx), `UNCONFIRMED` (fetched, other
  83. status — a real negative observation), `ERROR` (refused or failed; the
  84. `observation.reason` explains why). Unknown `type` → `400 unknown_type`.
  85. Spot-checking a packet (no trust required):
  86. ```bash
  87. # fetch the service public key, then verify the signature offline:
  88. curl -s http://127.0.0.1:5057/key
  89. ```
  90. The signature covers the canonical JSON (sorted keys, compact separators)
  91. of every packet field except `signature` and `signing`. Recompute it and
  92. verify with any Ed25519 implementation.
  93. ### GET /verify/<id> — retrieve a stored proof packet (404 if unknown)
  94. ```bash
  95. curl -s http://127.0.0.1:5057/verify/VRF-20260926-3f9a2c1d | python3 -m json.tool
  96. ```
  97. ### GET /board/feed — public append-only feed, oldest first
  98. ```bash
  99. curl -s http://127.0.0.1:5057/board/feed | python3 -m json.tool
  100. ```
  101. Each entry: `{id, timestamp_utc, type, verdict, url}`.
  102. ### GET /health
  103. ```bash
  104. curl -s http://127.0.0.1:5057/health
  105. # {"status":"ok","version":"0.1.0","payments_enabled":false}
  106. ```
  107. ### GET /key — the service's Ed25519 public key
  108. ```bash
  109. curl -s http://127.0.0.1:5057/key
  110. # {"algorithm":"Ed25519","public_key_hex":"…"}
  111. ```
  112. The private key is never logged, never served, never leaves `signing.py`.
  113. ## Configuration (`config.yaml`)
  114. | Key | Default | Meaning |
  115. |---|---|---|
  116. | `service.port` | 5057 | Listen port |
  117. | `service.data_dir` | `data` | Runtime state (ledger, keys); gitignored |
  118. | `verify.base_price_usd` | 0.005 | Quoted price per verification (a quote, not a charge) |
  119. | `verify.timeout_s` | 10 | Network timeout per observation |
  120. | `verify.max_body_bytes` | 2097152 | 2 MB body cap; overage → ERROR verdict |
  121. | `verify.allow_private` | false | **Never true in production.** Lets the hermetic tests use a 127.0.0.1 stub |
  122. | `cost_model` | `cost_model.yaml` | Path to operator-configured rates |
  123. | `payments.enabled` | false | Master switch. `true` without a configured provider → **refuse to start** |
  124. ## Key management
  125. * First run: `KeyStore` generates an Ed25519 keypair into
  126. `data/keys/{private.key,public.key}` (directory 0700, files 0600; refuses
  127. to overwrite an existing key).
  128. * Back up `private.key` offline; losing it orphans the board's trust chain
  129. (old packets still verify against the published public key, but the
  130. service can no longer sign).
  131. * Rotation (not automated in v1): generate a new keypair, publish the new
  132. public key at `/key` with a `key_id`, keep the old public key published
  133. for historical verification. See go-live checklist.
  134. ## Deployment notes
  135. The `$0` go-live bundle lives in `deploy/`:
  136. | File | Role |
  137. |---|---|
  138. | `deploy/verify-service.service` | Hardened systemd unit (unprivileged `verify` user, `NoNewPrivileges`, `PrivateTmp`, `ProtectSystem=strict`, restart on failure) |
  139. | `deploy/Caddyfile` | Reverse proxy with automatic TLS; forwards the real client IP (`X-Forwarded-For`) — the app trusts that header **only** from 127.0.0.1/::1 |
  140. | `deploy/DEPLOY.md` | Ordered runbook for a non-expert: Oracle Cloud Always Free ARM VM, hardening, first-boot keypair, systemd, Caddy, DNS, go-live checks |
  141. Built-in abuse guard: `POST /verify` is rate-limited per client IP
  142. (sliding 60s window, `verify.rate_limit_per_minute`, default 30/min).
  143. Over the cap → `429` JSON with a `Retry-After` header. Set
  144. `rate_limit_per_minute: 0` to disable (never disable on a public endpoint).
  145. Run one worker per data directory (v1 has no cross-process locking on the
  146. ledger). The service binds 127.0.0.1 only; public traffic arrives via the
  147. reverse proxy.
  148. Machine-readable docs for humans and agents: `GET /llms.txt`
  149. (`text/plain`) — endpoint contract, proof-packet fields, how to verify a
  150. signature offline, and the honesty notes.
  151. ### Known v1 limitations (stated plainly)
  152. * HTTP/1.1 only; redirects are never followed (recorded as UNCONFIRMED).
  153. * No HTTP/2, no JavaScript rendering: the observation is the raw HTTP
  154. response, which is exactly what is hashed and signed.
  155. * DNS is resolved once per verification; a hostile DNS that flips answers
  156. between resolution and connect within milliseconds is out of scope for
  157. v1 (documented, not mitigated beyond the single-resolution design).
  158. * Single worker; ledger scans are O(n).
  159. * Pure-Python Ed25519: correct, but slower than a C implementation —
  160. fine at v1 volumes; adopt a vetted C library before scaling.
  161. ## Go-live checklist
  162. - [x] **Deploy bundle** (`deploy/`, built 2026-09-26): hardened systemd
  163. unit, Caddyfile with automatic TLS, `DEPLOY.md` runbook (Oracle
  164. Cloud Always Free ARM VM, human steps marked), in-app per-IP rate
  165. limiting on `POST /verify` (30/min default, `429` + `Retry-After`),
  166. `/llms.txt` machine-readable API docs. All $0, stdlib-only, no
  167. payment code paths. Tests: 26/26 green.
  168. - [ ] **Hosting**: provision the VM per `deploy/DEPLOY.md`; decide the
  169. data-dir backup story (ledger + key backup are in the runbook).
  170. - [ ] **Payment provider integration**: NOT BUILT. Implement the charge
  171. flow, wire it to `payments.provider`, then flip `enabled: true`.
  172. - [ ] **Fresh production keypair**: generated on first boot per the
  173. runbook (never copy `data/` from dev); publish the public key;
  174. back up the private key offline.
  175. - [ ] **Real cost calibration**: replace `cost_model.yaml` estimates with
  176. metered values; run a calibration batch; confirm `margin_usd > 0`
  177. before quoting real prices.
  178. - [ ] **Terms & abuse policy**: acceptable use, refund policy for failed
  179. (ERROR) verifications — written and published. (Rate limiting itself
  180. is now built in; the edge policy is the remaining piece.)
  181. - [ ] **TLS + reverse proxy**: covered by `deploy/Caddyfile`; replace the
  182. placeholder domain, validate, reload.
  183. - [ ] **Key rotation procedure** documented and rehearsed.
  184. - [ ] **Monitoring**: UptimeRobot free monitor on `/health`; ledger
  185. growth, `below_cost` counts, error rates — the honest loop must page
  186. someone when the loop turns red.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.