proof-engine-registry 1.42.0

Proof Registry protocol: client, reference server, and static-JSON emitter.

proof-engine-registry

Protocol, client, and reference server for the Proof Registry — the JSON-over-HTTPS layer that lets LLM wikis (and other tools) ask "is this claim already proven?" and either use the existing proof or commission a new one.

Spec: docs/registry-protocol.md.

Install

pip install proof-engine-registry

Config

~/.config/proof-engine/registries.toml

[[registry]]
name = "public"
url = "https://proofengine.info"

[[registry]]
name = "acme-internal"
url = "https://proofs.acme.com"
token_env = "ACME_PROOFS_TOKEN"
publish = true

Client

from proof_engine_registry import RegistryClient, load_registries
client = RegistryClient(load_registries())
hit = client.lookup("The sky is blue.")
if hit:
    print(hit.proof_url)

Self-host

proof-registry serve ./my-proofs --port 8080 --token-env MY_TOKEN

Useful flags:

Flag	Default	Purpose
--token-env	(none)	Env var holding the bearer token required for POST /proofs. Omit to disable publishing.
--cors-origin	*	Value for Access-Control-Allow-Origin on read responses. Use a specific origin to restrict access.
--log-json	off	Emit one JSON access record per request to stderr. Authorization headers are never logged.
--problem-type-base	https://proofengine.info/errors	Base URI for type fields in RFC 7807 error bodies. Override to point at your own docs.

Production deployment

The reference server uses plain stdlib HTTP and binds to 127.0.0.1 by default. Suitable for development and local team use. For public exposure over the open internet, front the server with a TLS-terminating reverse proxy (nginx, Caddy, Cloudflare, AWS ALB) and route only encrypted traffic from the proxy to the server. Bearer tokens MUST NOT travel the network in cleartext.

Embedding badges

Each proof has three badge representations:

• /proofs/SLUG/badge.svg — inline SVG, our own rendering. Self-contained, no third-party dependencies. Style is fixed.
• /proofs/SLUG/badge.json — structured payload (claim, verdict, confidence, doi, badge_svg_url) for tools that render their own UI.
• /proofs/SLUG/shields.json — shields.io endpoint format. Plug it into shields.io and pick any style:

[![proof](https://img.shields.io/endpoint?url=https://proofengine.info/proofs/SLUG/shields.json)](https://proofengine.info/proofs/SLUG/)

Style flexibility (?style=flat-square, ?style=for-the-badge, etc.) and CDN caching come from shields.io; we just emit the JSON.

Errors

JSON error responses follow RFC 7807 Problem Details:

HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{
  "type": "https://proofengine.info/errors/not-found",
  "status": 404,
  "title": "Resource not found",
  "detail": "no proof with that claim_hash",
  "code": "not_found"
}

The code field preserves the legacy short machine key for log-aggregation tooling. Full canonical-error table in the protocol spec.

Conformance

A protocol-version-aware conformance suite ships with the package:

cd packages/proof-engine-registry && python -m pytest tests/test_conformance.py -v

It runs against both the static-JSON emit and the reference server. Any third-party server claiming to speak the protocol can run the same suite.