trace-verify 0.1.0__py3-none-any.whl

trace_verify/__init__.py

@@ -0,0 +1,12 @@
+"""trace-verify: verify TRACE claim inclusion proofs against the public registry.
+
+Standard library only. Anchor format v1 (docs/anchor-format.md).
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+__anchor_format_version__ = 1
+__all__ = ["verify_inclusion", "canonical_claim_bytes"]
+
+from trace_verify._verify import canonical_claim_bytes, verify_inclusion

trace_verify/__main__.py

@@ -0,0 +1,169 @@
+"""CLI entry point for trace-verify.
+
+Usage:
+    trace-verify --claim CLAIM.json --proof PROOF.json --entry ENTRY.ndjson
+    trace-verify --claim CLAIM.json --proof PROOF.json --entry-url URL
+    python -m trace_verify ...
+
+Exit code 0: claim is proven included.
+Exit code 1: proof does not verify.
+Exit code 2: bad arguments or unreadable files.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+from trace_verify import __version__
+from trace_verify._verify import decode_hash, verify_inclusion
+
+
+def _load_json_file(path: Path) -> object:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except OSError as exc:
+        _die(f"cannot read {path}: {exc}")
+    except json.JSONDecodeError as exc:
+        _die(f"invalid JSON in {path}: {exc}")
+
+
+def _fetch_url(url: str) -> str:
+    try:
+        with urllib.request.urlopen(url, timeout=15) as resp:  # noqa: S310
+            return resp.read().decode("utf-8")
+    except urllib.error.URLError as exc:
+        _die(f"cannot fetch {url}: {exc}")
+
+
+def _load_entry(source: str, batch_id: str | None) -> dict:
+    """Load a registry entry from a local file path or a URL."""
+    if source.startswith("https://") or source.startswith("http://"):
+        raw = _fetch_url(source)
+    else:
+        path = Path(source)
+        try:
+            raw = path.read_text(encoding="utf-8")
+        except OSError as exc:
+            _die(f"cannot read {source}: {exc}")
+
+    lines = [ln for ln in raw.splitlines() if ln.strip()]
+    entries = []
+    for ln in lines:
+        try:
+            entries.append(json.loads(ln))
+        except json.JSONDecodeError as exc:
+            _die(f"invalid JSON line in entry source: {exc}")
+
+    if batch_id is not None:
+        entries = [e for e in entries if isinstance(e, dict) and e.get("batch_id") == batch_id]
+        if not entries:
+            _die(f"no entry with batch_id {batch_id!r} in {source}")
+
+    if len(entries) != 1:
+        _die(
+            f"{source} contains {len(entries)} entries; "
+            "use --batch-id to select one"
+        )
+    if not isinstance(entries[0], dict):
+        _die(f"entry in {source} is not a JSON object")
+    return entries[0]
+
+
+def _die(msg: str, code: int = 2) -> None:
+    print(f"error: {msg}", file=sys.stderr)
+    sys.exit(code)
+
+
+def _output(ok: bool, entry: dict, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps({
+            "verified": ok,
+            "batch_id": entry.get("batch_id"),
+            "merkle_root": entry.get("merkle_root"),
+            "ts": entry.get("ts"),
+        }))
+    elif ok:
+        print(
+            f"OK: claim is included in batch {entry.get('batch_id')!r} "
+            f"(root {entry.get('merkle_root')}, ts {entry.get('ts')})"
+        )
+    else:
+        print(
+            "FAIL: inclusion proof does not verify against the registry entry",
+            file=sys.stderr,
+        )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="trace-verify",
+        description=(
+            "Verify a TRACE claim inclusion proof against a registry entry. "
+            "Exit code 0 means the signed claim was provably anchored in the "
+            "registry at the entry timestamp."
+        ),
+    )
+    p.add_argument("--version", action="version", version=f"trace-verify {__version__}")
+    p.add_argument("--claim", required=True, metavar="FILE",
+                   help="signed claim JSON file")
+    p.add_argument("--proof", required=True, metavar="FILE",
+                   help='inclusion proof file: {"leaf_index": int, "audit_path": [...]}')
+
+    entry_group = p.add_mutually_exclusive_group(required=True)
+    entry_group.add_argument("--entry", metavar="FILE",
+                             help="registry entry file (single JSON object or .ndjson day file)")
+    entry_group.add_argument("--entry-url", metavar="URL",
+                             help="fetch the registry entry from this URL (e.g. a raw GitHub URL)")
+
+    p.add_argument("--batch-id", default=None, metavar="ID",
+                   help="select the entry with this batch_id from a multi-line day file")
+    p.add_argument("--json", action="store_true", dest="as_json",
+                   help="emit a machine-readable JSON result instead of plain text")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    claim = _load_json_file(Path(args.claim))
+    proof = _load_json_file(Path(args.proof))
+
+    entry_source = args.entry_url if args.entry_url else args.entry
+    entry = _load_entry(entry_source, args.batch_id)
+
+    try:
+        if not isinstance(claim, dict):
+            raise ValueError("claim is not a JSON object")
+        if not isinstance(proof, dict):
+            raise ValueError("proof is not a JSON object")
+        raw_path = proof.get("audit_path")
+        if not isinstance(raw_path, list):
+            raise ValueError("proof.audit_path must be a list")
+        audit_path = [decode_hash(h) for h in raw_path]
+        merkle_root = decode_hash(entry.get("merkle_root"))
+        ok = verify_inclusion(
+            claim,
+            proof.get("leaf_index"),
+            audit_path,
+            entry.get("leaf_count"),
+            merkle_root,
+        )
+    except ValueError as exc:
+        if args.as_json:
+            print(json.dumps({"verified": False, "error": str(exc)}))
+        else:
+            print(f"FAIL: {exc}", file=sys.stderr)
+        return 1
+
+    _output(ok, entry, args.as_json)
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

trace_verify/_verify.py

@@ -0,0 +1,77 @@
+"""Core TRACE inclusion-proof verification algorithm.
+
+Implements the RFC 6962 Merkle tree and RFC 9162 inclusion-proof check
+as specified in docs/anchor-format.md. Standard library only.
+
+This module is the single source of truth for the algorithm. The standalone
+script tools/verify_inclusion.py in the repository is an auditable copy of
+this same logic kept in sync for third parties who want to inspect or
+reimplement it without installing the package.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+
+LEAF_PREFIX = b"\x00"
+NODE_PREFIX = b"\x01"
+_HASH_RE = re.compile(r"^sha256:[0-9a-f]{64}$")
+
+ANCHOR_FORMAT_VERSION = 1
+
+
+def canonical_claim_bytes(claim: dict) -> bytes:
+    """Canonical JSON bytes of a signed claim object (anchor-format.md section 1)."""
+    if not isinstance(claim, dict):
+        raise ValueError("claim must be a JSON object")
+    return json.dumps(
+        claim, sort_keys=True, separators=(",", ":"), ensure_ascii=True
+    ).encode("ascii")
+
+
+def decode_hash(value: object) -> bytes:
+    """Decode a 'sha256:<64 lowercase hex>' string to 32 raw bytes."""
+    if not isinstance(value, str) or not _HASH_RE.match(value):
+        raise ValueError(f"malformed hash value: {value!r}")
+    return bytes.fromhex(value.split(":", 1)[1])
+
+
+def verify_inclusion(
+    claim: dict,
+    leaf_index: int,
+    audit_path: list[bytes],
+    leaf_count: int,
+    merkle_root: bytes,
+) -> bool:
+    """Return True iff the claim's leaf is proven included under merkle_root.
+
+    Implements RFC 9162 s2.1.3.2 over an RFC 6962 tree (anchor-format.md s5).
+    """
+    if not isinstance(leaf_index, int) or isinstance(leaf_index, bool):
+        return False
+    if not isinstance(leaf_count, int) or isinstance(leaf_count, bool):
+        return False
+    if leaf_index < 0 or leaf_count < 1 or leaf_index >= leaf_count:
+        return False
+
+    r = hashlib.sha256(LEAF_PREFIX + canonical_claim_bytes(claim)).digest()
+    fn = leaf_index
+    sn = leaf_count - 1
+
+    for p in audit_path:
+        if sn == 0:
+            return False
+        if fn & 1 or fn == sn:
+            r = hashlib.sha256(NODE_PREFIX + p + r).digest()
+            if not fn & 1:
+                while fn and not fn & 1:
+                    fn >>= 1
+                    sn >>= 1
+        else:
+            r = hashlib.sha256(NODE_PREFIX + r + p).digest()
+        fn >>= 1
+        sn >>= 1
+
+    return sn == 0 and r == merkle_root

trace_verify-0.1.0.dist-info/METADATA

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: trace-verify
+Version: 0.1.0
+Summary: Verify TRACE claim inclusion proofs against the public registry
+Project-URL: Homepage, https://github.com/agentrust-io/trace-registry
+Project-URL: Documentation, https://github.com/agentrust-io/trace-registry/blob/main/docs/anchor-format.md
+Project-URL: Bug Tracker, https://github.com/agentrust-io/trace-registry/issues
+Project-URL: Changelog, https://github.com/agentrust-io/trace-registry/blob/main/CHANGELOG.md
+License: CC-BY-4.0
+License-File: LICENSE
+Keywords: ai-governance,audit,inclusion-proof,merkle,trace
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+[![License: CC BY 4.0](https://img.shields.io/badge/License-CC_BY_4.0-lightgrey.svg)](LICENSE)
+[![TRACE Spec](https://img.shields.io/badge/TRACE-Spec_v0.1-0ea5e9)](https://github.com/agentrust-io/trace-spec)
+[![Discord](https://dcbadge.limes.pink/api/server/9JWNpH7E?style=flat)](https://discord.gg/9JWNpH7E)
+
+# TRACE Registry
+
+The public accountability layer for TRACE claim anchors. Each entry records the
+Merkle root of a batch of signed TRACE Trust Records, committed to this
+repository as an append-only record. Git's commit history is the
+tamper-evidence layer: any rewrite of a published entry diverges the commit
+hashes that auditors and mirrors have already observed.
+
+## Current Registry State
+
+The registry currently contains one development entry (registry/2026/06/12.ndjson).
+This is a software-only example anchor with advisory enforcement and a zeroed
+measurement, committed as a launch-day example. It does not represent a production
+Trust Record. The first production entries will be added after Confidential Computing
+Summit launch on June 23, 2026.
+
+The anchor construction (canonical claim bytes, leaf hashing, RFC 6962 Merkle
+tree, inclusion proofs) is specified in
+[docs/anchor-format.md](docs/anchor-format.md). A third party can implement a
+verifier from that document alone; the reference tools in [tools/](tools/) are
+one implementation.
+
+> **Status.** The format, reference tooling, schema validation, and a first
+> real entry ([registry/2026/06/12.ndjson](registry/2026/06/12.ndjson)) are
+> live. Anchoring is currently manual and low volume; a continuous anchoring
+> cadence and a packaged `trace-verify` CLI on PyPI are planned but not yet
+> operational.
+
+## Why this exists
+
+Anyone holding a TRACE trust record and its inclusion proof can verify that the
+record was anchored in this registry without trusting the operator who issued
+it, using only this public git history and the verifier below. No single
+operator controls the audit trail.
+
+## Registry Format
+
+Each daily file in `registry/YYYY/MM/` is newline-delimited JSON, one anchor
+entry per line, validated by CI against
+[schema/registry-entry.schema.json](schema/registry-entry.schema.json):
+
+```json
+{"ts": "2026-06-12T18:09:41Z", "merkle_root": "sha256:9279...bada", "leaf_count": 1, "producer": "cmcp-gateway/0.1.0", "batch_id": "2026-06-12-001"}
+```
+
+Entries are append-only. See [docs/anchor-format.md](docs/anchor-format.md)
+for field semantics.
+
+## Verifying a claim
+
+You need three things: your signed claim (Trust Record), the inclusion proof
+your producer gave you, and the registry entry for the batch. Then:
+
+```bash
+git clone https://github.com/agentrust-io/trace-registry.git
+cd trace-registry
+python tools/verify_inclusion.py \
+  --claim samples/example-trust-record.json \
+  --proof samples/inclusion-proof.json \
+  --entry registry/2026/06/12.ndjson
+# OK: claim is included in batch '2026-06-12-001' (root sha256:9279..., ts 2026-06-12T18:09:41Z)
+```
+
+Exit code 0 means the claim is proven included; 1 means it is not. The
+verifier is a single standard-library Python file, so you can audit it (or
+reimplement it from the spec) rather than trust it. The `samples/` files above
+are a real anchored example you can use to exercise the tooling.
+
+Inclusion verification proves the signed claim bytes were anchored at the
+entry's timestamp. Validating the claim's signature against the producer key
+is a separate TRACE step.
+
+## Anchoring claims
+
+Producers batch signed claims and anchor them with:
+
+```bash
+python tools/anchor.py claim1.json claim2.json \
+  --producer my-gateway/1.0 --proof-dir proofs/ \
+  >> registry/2026/06/12.ndjson
+```
+
+This emits the registry entry line and writes one inclusion proof per claim to
+hand back to claim holders.
+
+## Canonical Registry
+
+This repository exists for independence: TRACE claim anchors can be checked
+without trusting any single operator's infrastructure, and the git history is
+auditable by anyone.
+
+## Community
+
+Questions, feedback, integration help: [Discord](https://discord.gg/9JWNpH7E).
+
+## License
+
+Creative Commons Attribution 4.0 International (CC BY 4.0). See [LICENSE](LICENSE).

trace_verify-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+trace_verify/__init__.py,sha256=04w6eWaQU0uFODv0tHsTihd1DPPpqniq3XSycrl3NqI,371
+trace_verify/__main__.py,sha256=n39tQRL-dC65W9iFoEmX8lDeEq7Ty5xpyyVegstC3Fo,5696
+trace_verify/_verify.py,sha256=2Ejjvl0ItE7mE9Ch6UgwJY7RGkTCI7wgjSpuB0Eal20,2437
+trace_verify-0.1.0.dist-info/METADATA,sha256=h1-zFwOlVWeuX__4-VYbdxz3h9mHMpnFFpvY-RaN7q4,5331
+trace_verify-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+trace_verify-0.1.0.dist-info/entry_points.txt,sha256=w_DKNZPdHbIZ1JY-jW_d1lAY1RJqibg3F6H7CqhJYyA,60
+trace_verify-0.1.0.dist-info/licenses/LICENSE,sha256=PACqbgsD3BOlGQlRVuuvVDMHA8GDKoieQ4oyvvnmRvA,271
+trace_verify-0.1.0.dist-info/RECORD,,

trace_verify-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

trace_verify-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+trace-verify = trace_verify.__main__:main

trace_verify-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,6 @@
+Creative Commons Attribution 4.0 International (CC BY 4.0)
+
+Copyright 2026 AgentTrust Contributors
+
+This work is licensed under the Creative Commons Attribution 4.0 International License.
+To view a copy of this license, visit https://creativecommons.org/licenses/by/4.0/