proof-engine-registry 1.33.0__py3-none-any.whl

proof_engine_registry/__init__.py

@@ -0,0 +1,4 @@
+"""proof-engine-registry — Proof Registry protocol implementation."""
+
+__version__ = "1.33.0"
+__protocol_version__ = "0.1"

proof_engine_registry/badge.py

@@ -0,0 +1,141 @@
+"""Proof badge: compact certificate for claim verification.
+
+Two artifacts per proof:
+  - badge.json — machine-readable payload
+  - badge.svg  — shields-style inline SVG for direct <img> embedding
+
+The SVG uses a fixed sans-serif stack and estimated text widths. It won't be
+pixel-perfect at all zoom levels, but it renders without external fonts and
+is byte-identical across builds (important so git diffs stay clean).
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from proof_engine_registry.emit import (
+    claim_text, verdict_string, confidence_from_proof,
+)
+from proof_engine_registry.hashing import hash_claim
+
+
+# Locked color map — see test_build_badge_pinned_colors.
+VERDICT_COLORS: dict[str, str] = {
+    "PROVED": "#2d8f5f",
+    "SUPPORTED": "#5eb88a",
+    "PARTIALLY VERIFIED": "#d4a017",
+    "UNDETERMINED": "#888888",
+    "DISPROVED": "#c75450",
+}
+
+BADGE_SCHEMA_VERSION = "1.0"
+
+
+def _color_for(verdict: str) -> str:
+    """Pick a color by the leading verdict family (ignoring any qualifier)."""
+    for family, color in VERDICT_COLORS.items():
+        if verdict.startswith(family):
+            return color
+    return VERDICT_COLORS["UNDETERMINED"]
+
+
+def build_badge(proof: dict, slug: str, doi: Optional[str],
+                base_url: str) -> dict:
+    """Build the badge payload from a v3 proof.json dict.
+
+    `slug` and `doi` are passed explicitly because they live outside
+    proof.json (slug is the dir name; DOI is in a sibling doi.json).
+    """
+    base = base_url.rstrip("/")
+    claim = claim_text(proof)
+    verdict = verdict_string(proof)
+    gen = proof.get("generator") or {}
+    return {
+        "schema_version": BADGE_SCHEMA_VERSION,
+        "slug": slug,
+        "claim": claim,
+        "claim_hash": hash_claim(claim),
+        "verdict": verdict,
+        "confidence": confidence_from_proof(proof),
+        "doi": doi,
+        "proof_url": f"{base}/proofs/{slug}/",
+        "badge_svg_url": f"{base}/proofs/{slug}/badge.svg",
+        "generated_at": gen.get("generated_at", ""),
+        "colors": {
+            "verdict_bg": _color_for(verdict),
+            "verdict_fg": "#ffffff",
+        },
+    }
+
+
+# SVG layout constants — keep in one place for easy theming.
+_FONT_STACK = (
+    "-apple-system,BlinkMacSystemFont,Segoe UI,Roboto,Helvetica,Arial,sans-serif"
+)
+_LABEL_BG = "#555555"
+_LABEL_FG = "#ffffff"
+_CHAR_WIDTH = 6.5  # px, estimated for 11px sans-serif
+_PADDING = 10
+_HEIGHT = 20
+
+
+def _text_width(text: str) -> int:
+    return int(len(text) * _CHAR_WIDTH) + 2 * _PADDING
+
+
+def render_badge_svg(badge: dict) -> str:
+    label = "proof"
+    value = badge["verdict"]
+    label_w = _text_width(label)
+    value_w = _text_width(value)
+    total_w = label_w + value_w
+    value_bg = badge["colors"]["verdict_bg"]
+    # Defense-in-depth: verdict is a controlled enum today, but escape on
+    # the way into XML attributes and text nodes so a future qualifier
+    # string with `<` / `&` / `"` cannot break the SVG.
+    value_esc = _escape_html(value)
+    label_esc = _escape_html(label)
+
+    svg = (
+        f'<svg xmlns="http://www.w3.org/2000/svg" '
+        f'width="{total_w}" height="{_HEIGHT}" role="img" '
+        f'aria-label="proof: {value_esc}">'
+        f'<title>proof: {value_esc}</title>'
+        f'<linearGradient id="s" x2="0" y2="100%">'
+        f'<stop offset="0" stop-color="#bbb" stop-opacity=".1"/>'
+        f'<stop offset="1" stop-opacity=".1"/>'
+        f'</linearGradient>'
+        f'<rect width="{total_w}" height="{_HEIGHT}" rx="3" fill="{_LABEL_BG}"/>'
+        f'<rect x="{label_w}" width="{value_w}" height="{_HEIGHT}" rx="3" fill="{value_bg}"/>'
+        f'<rect width="{total_w}" height="{_HEIGHT}" rx="3" fill="url(#s)"/>'
+        f'<g fill="{_LABEL_FG}" text-anchor="middle" '
+        f'font-family="{_FONT_STACK}" font-size="11">'
+        f'<text x="{label_w // 2}" y="14">{label_esc}</text>'
+        f'<text x="{label_w + value_w // 2}" y="14">{value_esc}</text>'
+        f'</g></svg>'
+    )
+    return svg
+
+
+def render_embed_snippets(badge: dict) -> dict[str, str]:
+    """Return the three copy-paste-ready embeds."""
+    proof_url = badge["proof_url"]
+    svg_url = badge["badge_svg_url"]
+    claim = badge["claim"]
+    return {
+        "html": (
+            f'<a href="{proof_url}" title="{_escape_html(claim)}">'
+            f'<img src="{svg_url}" alt="proof: {badge["verdict"]}"/></a>'
+        ),
+        "markdown": f'[![proof]({svg_url})]({proof_url})',
+        "url": svg_url,
+    }
+
+
+def _escape_html(s: str) -> str:
+    return (
+        s.replace("&", "&amp;")
+         .replace("<", "&lt;")
+         .replace(">", "&gt;")
+         .replace('"', "&quot;")
+    )

proof_engine_registry/cli.py

@@ -0,0 +1,163 @@
+"""proof-registry CLI: serve | lookup | publish | emit."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from dataclasses import asdict
+from pathlib import Path
+
+from proof_engine_registry import __version__
+from proof_engine_registry.client import RegistryClient
+from proof_engine_registry.config import load_registries, Registry
+from proof_engine_registry.emit import emit_registry_files
+from proof_engine_registry.server import RegistryServer
+
+
+def _cmd_serve(args) -> int:
+    token = os.environ.get(args.token_env) if args.token_env else None
+    srv = RegistryServer(
+        proofs_dir=Path(args.proofs_dir),
+        name=args.name,
+        base_url=args.base_url or f"http://{args.bind}:{args.port}",
+        bind=args.bind, port=args.port,
+        auth_token=token,
+        cors_origin=args.cors_origin,
+        log_json=args.log_json,
+    )
+    if args.print_port_to:
+        Path(args.print_port_to).write_text(str(srv.port))
+    print(f"proof-registry serving {args.proofs_dir} on http://{args.bind}:{srv.port}",
+          file=sys.stderr)
+    try:
+        srv.serve_forever()
+    except KeyboardInterrupt:
+        srv.shutdown()
+    return 0
+
+
+def _cmd_emit(args) -> int:
+    emit_registry_files(
+        proofs_dir=Path(args.proofs_dir),
+        output_dir=Path(args.output_dir),
+        base_url=args.base_url,
+        registry_name=args.name,
+        publishes_supported=False,
+    )
+    print(f"emitted registry to {args.output_dir}", file=sys.stderr)
+    return 0
+
+
+def _cmd_lookup(args) -> int:
+    registries = load_registries()
+    if not registries:
+        print("error: no registries configured (expected ~/.config/proof-engine/registries.toml)",
+              file=sys.stderr)
+        return 2
+    client = RegistryClient(registries)
+    hit = client.lookup(args.claim)
+    if hit is None:
+        if args.json:
+            sys.stdout.write(json.dumps({"hit": False}) + "\n")
+        else:
+            sys.stdout.write("no hit\n")
+        return 1
+    payload = asdict(hit.entry) | {"registry_name": hit.registry_name}
+    if args.json:
+        sys.stdout.write(json.dumps(payload, indent=2 if args.pretty else None) + "\n")
+    else:
+        sys.stdout.write(f"{hit.registry_name}: {hit.slug} → {hit.proof_url}\n")
+    return 0
+
+
+def _cmd_publish(args) -> int:
+    # Find the one publish target.
+    registries = [r for r in load_registries() if r.publish]
+    if not registries:
+        print("error: no registry has publish = true", file=sys.stderr)
+        return 2
+    if len(registries) > 1:
+        print("error: more than one registry has publish = true (blocked by config loader)",
+              file=sys.stderr)
+        return 2
+    target = registries[0]
+    body = json.loads(Path(args.proof_json).read_text())
+    import requests
+    r = requests.post(
+        f"{target.url}/proofs",
+        json={"slug": body["slug"], "claim": body["claim"], "proof_json": body},
+        headers={"Authorization": f"Bearer {target.token}"} if target.token else {},
+        timeout=30,
+    )
+    if r.status_code == 201:
+        print(f"published {body['slug']} to {target.name}", file=sys.stderr)
+        return 0
+    print(f"publish failed: HTTP {r.status_code} {r.text}", file=sys.stderr)
+    return 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="proof-registry")
+    p.add_argument("--version", action="version", version=__version__)
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    s = sub.add_parser(
+        "serve",
+        help="Run a self-hosted registry server.",
+        description=(
+            "Stdlib HTTP server. Suitable for development and local team "
+            "deployments. For public deployment over the open internet, "
+            "front this with a TLS-terminating reverse proxy (nginx, Caddy, "
+            "Cloudflare, etc.) — bearer tokens travel in the Authorization "
+            "header and MUST NOT cross the network in cleartext."
+        ),
+    )
+    s.add_argument("proofs_dir")
+    s.add_argument("--name", default="Self-Hosted Proof Registry")
+    s.add_argument("--base-url", default=None)
+    s.add_argument("--bind", default="127.0.0.1")
+    s.add_argument("--port", type=int, default=8080)
+    s.add_argument("--token-env", default=None,
+                   help="Env var holding the bearer token required for publishing.")
+    s.add_argument("--cors-origin", default="*",
+                   help=("Value for Access-Control-Allow-Origin on read responses. "
+                         "Default '*' for public registries; pass a specific origin "
+                         "to restrict cross-origin browser access."))
+    s.add_argument("--log-json", action="store_true",
+                   help=("Emit one structured JSON access log line per request to "
+                         "stderr. Off by default; useful for compliance/audit. "
+                         "Authorization headers are NEVER logged."))
+    s.add_argument("--print-port-to", default=None,
+                   help="Write the bound port to this file (for test orchestration).")
+    s.set_defaults(func=_cmd_serve)
+
+    e = sub.add_parser("emit", help="Emit static registry JSON from a proofs dir.")
+    e.add_argument("proofs_dir")
+    e.add_argument("output_dir")
+    e.add_argument("--base-url", required=True)
+    e.add_argument("--name", default="Proof Registry")
+    e.set_defaults(func=_cmd_emit)
+
+    l = sub.add_parser("lookup", help="Look up a claim across configured registries.")
+    l.add_argument("claim")
+    l.add_argument("--json", action="store_true")
+    l.add_argument("--pretty", action="store_true")
+    l.set_defaults(func=_cmd_lookup)
+
+    pub = sub.add_parser("publish", help="Publish a proof.json to the publish-target registry.")
+    pub.add_argument("proof_json")
+    pub.set_defaults(func=_cmd_publish)
+
+    return p
+
+
+def main(argv=None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

proof_engine_registry/client.py

@@ -0,0 +1,100 @@
+"""Registry client. Talks the Registry Protocol v0.1.
+
+Respects configured registry order. Never performs implicit fallback — the
+caller must set fallback=True on a registry to permit querying it after a
+miss on the previous registry.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+import requests
+
+from proof_engine_registry import __protocol_version__
+from proof_engine_registry.config import Registry
+from proof_engine_registry.hashing import hash_claim
+from proof_engine_registry.schema import Discovery, IndexEntry, from_json
+
+
+class ProtocolVersionMismatch(Exception):
+    """Registry speaks a higher major protocol version than the client."""
+
+
+@dataclass(frozen=True)
+class LookupHit:
+    registry_name: str
+    entry: IndexEntry
+
+    # Convenience accessors mirror IndexEntry fields.
+    @property
+    def slug(self) -> str: return self.entry.slug
+    @property
+    def claim(self) -> str: return self.entry.claim
+    @property
+    def verdict(self) -> str: return self.entry.verdict
+    @property
+    def confidence(self) -> float: return self.entry.confidence
+    @property
+    def doi(self) -> Optional[str]: return self.entry.doi
+    @property
+    def proof_url(self) -> str: return self.entry.proof_url
+    @property
+    def badge_url(self) -> str: return self.entry.badge_url
+
+
+class RegistryClient:
+    def __init__(self, registries: list[Registry], timeout: float = 10.0):
+        self.registries = registries
+        self.timeout = timeout
+        self._client_major, self._client_minor = (
+            int(x) for x in __protocol_version__.split(".")
+        )
+
+    def _headers(self, registry: Registry) -> dict:
+        if registry.token:
+            return {"Authorization": f"Bearer {registry.token}"}
+        return {}
+
+    def _get(self, registry: Registry, path: str) -> Optional[dict]:
+        url = f"{registry.url}{path}"
+        resp = requests.get(url, headers=self._headers(registry),
+                            timeout=self.timeout)
+        if resp.status_code == 404:
+            return None
+        resp.raise_for_status()
+        return resp.json()
+
+    def discovery(self, registry: Registry) -> Discovery:
+        data = self._get(registry, "/.well-known/proof-registry.json")
+        if data is None:
+            raise RuntimeError(f"Registry {registry.name} has no discovery doc")
+        disco = from_json(Discovery, data)
+        major = int(disco.protocol_version.split(".")[0])
+        if major > self._client_major:
+            raise ProtocolVersionMismatch(
+                f"Registry {registry.name} speaks v{disco.protocol_version}, "
+                f"client supports v{__protocol_version__}"
+            )
+        return disco
+
+    def lookup(self, claim: str) -> Optional[LookupHit]:
+        """Return the first registry hit for the claim, or None.
+
+        Walks registries in order. If a registry returns 404, continues
+        only if the NEXT registry has fallback=True.
+        """
+        claim_hash_hex = hash_claim(claim)
+        previous_was_miss = False
+        for i, registry in enumerate(self.registries):
+            if i > 0 and previous_was_miss and not registry.fallback:
+                break  # explicit no-fallback boundary
+            data = self._get(registry, f"/claims/{claim_hash_hex}.json")
+            if data is not None:
+                return LookupHit(
+                    registry_name=registry.name,
+                    entry=from_json(IndexEntry, data),
+                )
+            previous_was_miss = True
+        return None

proof_engine_registry/config.py

@@ -0,0 +1,68 @@
+"""Load registry configuration from ~/.config/proof-engine/registries.toml.
+
+Tokens are never stored in the config file — only the NAME of the env var
+that holds the token.
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+
+class DuplicatePublishError(Exception):
+    """More than one registry configured with publish = true."""
+
+
+@dataclass(frozen=True)
+class Registry:
+    name: str
+    url: str
+    token: Optional[str] = None
+    publish: bool = False
+    fallback: bool = False  # implicit fallback from prior registry
+
+
+def default_config_path() -> Path:
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    base = Path(xdg) if xdg else Path.home() / ".config"
+    return base / "proof-engine" / "registries.toml"
+
+
+def load_registries() -> list[Registry]:
+    return load_registries_from_path(default_config_path())
+
+
+def load_registries_from_path(path: Path) -> list[Registry]:
+    if not path.exists():
+        return []
+    data = tomllib.loads(path.read_text())
+    raw_list = data.get("registry", [])
+    regs: list[Registry] = []
+    for raw in raw_list:
+        token = None
+        if "token_env" in raw:
+            env_name = raw["token_env"]
+            token = os.environ.get(env_name)
+            if token is None:
+                raise RuntimeError(
+                    f"Registry {raw.get('name', '?')!r} expects env var "
+                    f"{env_name!r} but it is not set."
+                )
+        regs.append(Registry(
+            name=raw["name"],
+            url=raw["url"].rstrip("/"),
+            token=token,
+            publish=bool(raw.get("publish", False)),
+            fallback=bool(raw.get("fallback", False)),
+        ))
+    publish_targets = [r for r in regs if r.publish]
+    if len(publish_targets) > 1:
+        raise DuplicatePublishError(
+            f"Multiple publish targets configured: "
+            f"{[r.name for r in publish_targets]}"
+        )
+    return regs