obsign-verify 0.1.0__py3-none-any.whl

obsign_verify/__init__.py

@@ -0,0 +1,27 @@
+"""Verify an Obsign receipt: re-derive the number yourself, offline.
+
+    from obsign_verify import verify, load_receipt
+    result = verify(load_receipt(open("receipt.json", encoding="utf-8").read()))
+
+Imports NOTHING from the engine that produced the receipt. That independence is
+the point -- if this package imported the producer, "it verifies" would mean "the
+producer agrees with itself".
+"""
+
+from .canonical import canonical_sha256, claim_of, load_receipt
+from .verify import verify
+
+__all__ = ["verify", "load_receipt", "claim_of", "canonical_sha256", "__version__"]
+__version__ = "0.1.0"
+
+
+def data_path(*parts: str):
+    """Absolute path to a file shipped INSIDE the package.
+
+    The conformance vectors and the challenge bundles are package data, not repo
+    files. A `pip install` has to give a stranger everything the README tells them
+    to run -- the first cut shipped neither, so `obsign-verify challenge/...` and
+    `pytest` both failed for anyone who installed rather than cloned.
+    """
+    from pathlib import Path
+    return Path(__file__).resolve().parent.joinpath("data", *parts)

obsign_verify/canonical.py

@@ -0,0 +1,80 @@
+"""Canonical form and the claim hash.
+
+The whole verifier stands on this file. If canonicalisation is off by one byte, a
+genuine receipt reports as tampered and the product's central promise inverts.
+
+THE INT/FLOAT TRAP, which the spec calls out by name
+
+Python writes `1.0` for a float and `1` for an int, and the two canonicalise to
+DIFFERENT bytes and therefore different hashes. A reader that erases the
+distinction -- notably JavaScript's `JSON.parse`, where every number is a double --
+will canonicalise `gamma: 0.0` as `0` and report an honest receipt as tampered.
+
+Python's `json` preserves it, so this implementation can parse normally. That is
+luck, not design, and `tests/` pins it so a future "cleanup" to a float-normalising
+parser fails loudly instead of silently rejecting every receipt in the field.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+#: Fields the spec excludes from the claim. `env` is informational, `signature`
+#: and `case` are post-hoc, `receipt_sha256` is the hash itself, `_`-prefixed keys
+#: are helpers. A verifier that hashed these would report a genuine receipt as
+#: tampered the moment anyone recorded a different platform.
+NON_CLAIM = ("receipt_sha256", "env", "signature", "case")
+
+
+def claim_of(receipt: dict) -> dict:
+    """The subset of a receipt that its `receipt_sha256` covers."""
+    return {k: v for k, v in receipt.items()
+            if k not in NON_CLAIM and not k.startswith("_")}
+
+
+def canonical_bytes(obj: Any) -> bytes:
+    """Canonical JSON exactly as docs/SPEC.md defines it.
+
+    `allow_nan=False` is load-bearing, not tidiness: NaN and Infinity have no JSON
+    representation, so permitting them would let two different receipts share a
+    canonical form.
+    """
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"),
+                      ensure_ascii=True, allow_nan=False).encode("utf-8")
+
+
+def canonical_sha256(obj: Any) -> str:
+    return hashlib.sha256(canonical_bytes(obj)).hexdigest()
+
+
+def load_receipt(text: str) -> dict:
+    """Parse receipt TEXT into a dict, preserving the int/float distinction.
+
+    Takes text rather than a path so the caller controls I/O, and so a port to
+    another language has an obvious seam at the only place the trap can bite.
+    """
+    obj = json.loads(text)
+    if not isinstance(obj, dict):
+        raise ValueError("a receipt must be a JSON object")
+    return obj
+
+
+def integrity(receipt: dict) -> tuple[bool, str]:
+    """Step 1 of the trust ladder: does `receipt_sha256` recompute from the claim?
+
+    Returns (ok, detail). Never raises on a hostile receipt -- a verifier that
+    crashes on malformed input has failed open in the eyes of whoever supplied it.
+    """
+    stated = receipt.get("receipt_sha256")
+    if not isinstance(stated, str) or not stated:
+        return False, "no receipt_sha256 to check against"
+    try:
+        recomputed = canonical_sha256(claim_of(receipt))
+    except (ValueError, TypeError) as exc:
+        return False, f"claim is not canonicalisable ({type(exc).__name__}: {exc})"
+    if recomputed != stated:
+        return False, (f"INTEGRITY FAIL - states {stated[:16]}.., "
+                       f"recomputes {recomputed[:16]}..")
+    return True, "integrity OK"

obsign_verify/cli.py

@@ -0,0 +1,121 @@
+"""`obsign-verify receipt.json` -- the one command PG-1 is about.
+
+Exit code is the interface: 0 means every named receipt verified, 1 means at least
+one did not. A script wrapping this must be able to branch on that alone.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__
+from .canonical import load_receipt
+from .verify import verify
+
+
+def _report(path: Path, res: dict, quiet: bool) -> None:
+    if quiet:
+        return
+    mark = "VERIFIED" if res["verified"] else "REFUSED"
+    print(f"  [{mark:^8}] {path.name}")
+    print(f"      integrity   {'ok' if res['integrity'] else 'FAIL'}")
+    print(f"      re-derived  {'ok' if res['reproduced'] else 'FAIL'}")
+    sig = res.get("signature") or {}
+    if not sig.get("present"):
+        print("      signature   absent (integrity and re-derivation still hold)")
+    else:
+        who = sig.get("attributed_signer")
+        # Never print a signer name the signature did not cover. A v1 signature's
+        # name can be rewritten by anyone with a text editor and no key.
+        ident = (f"attributed to {who!r}" if sig.get("identity_bound")
+                 else f"NOT identity-bound (file claims {sig.get('claimed_signer')!r})")
+        print(f"      signature   {'ok' if sig.get('valid') else 'FAIL'} - {ident}")
+    for note in res["notes"]:
+        print(f"      - {note}")
+
+
+def _self_check(quiet: bool) -> int:
+    """Run the challenge that ships INSIDE the package.
+
+    A stranger who `pip install`ed has no `challenge/` directory to point at, so the
+    README's "run the forgeries" instruction was unfollowable for exactly the people
+    it was written for. This needs no files of their own and no arguments.
+
+    Exit 0 means every bundle got the verdict it declares -- the honest ones
+    verified, and every forgery refused. Refusing the forgeries is the job, so a
+    clean run is NOT "9 verified".
+    """
+    from . import data_path
+    bundles = sorted(data_path("challenge", "bundles").glob("*/receipt.json"))
+    if not bundles:
+        print("no bundles shipped with this package -- the install is incomplete",
+              file=sys.stderr)
+        return 1
+
+    wrong = 0
+    for path in bundles:
+        receipt = load_receipt(path.read_text(encoding="utf-8"))
+        declared = receipt.get("_challenge", {}).get("expect_verified")
+        got = verify(receipt)["verified"]
+        ok = got is declared
+        wrong += not ok
+        if not quiet:
+            print(f"  {'ok  ' if ok else '!!  '}{path.parent.name:<36}"
+                  f"{'VERIFIED' if got else 'REFUSED':<9}"
+                  f"(expected {'VERIFIED' if declared else 'REFUSED'})")
+    if not quiet:
+        n = len(bundles)
+        print()
+        print(f"{n - wrong}/{n} bundles behaved as declared."
+              + ("" if wrong else "  Every forgery was refused, including the resealed"
+                                  " one whose signature is intact and whose claim is false."))
+    return 1 if wrong else 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(
+        prog="obsign-verify",
+        description="Re-derive an Obsign receipt's claim on your own machine.")
+    ap.add_argument("receipts", nargs="*", type=Path)
+    ap.add_argument("--self-check", action="store_true",
+                    help="verify the bundled challenge: 2 honest receipts and 7 "
+                         "forgeries that must be refused. Needs no files of your own.")
+    ap.add_argument("--json", action="store_true", help="machine-readable output")
+    ap.add_argument("--quiet", action="store_true")
+    ap.add_argument("--version", action="version", version=f"obsign-verify {__version__}")
+    args = ap.parse_args(argv)
+
+    if args.self_check:
+        return _self_check(args.quiet)
+    if not args.receipts:
+        ap.error("give one or more receipt files, or --self-check")
+
+    report, failures = [], 0
+    for path in args.receipts:
+        try:
+            receipt = load_receipt(path.read_text(encoding="utf-8"))
+        except Exception as exc:
+            failures += 1
+            report.append({"file": str(path), "verified": False,
+                           "notes": [f"unreadable: {type(exc).__name__}: {exc}"]})
+            if not args.quiet:
+                print(f"  [ REFUSED ] {path.name}: unreadable ({exc})")
+            continue
+        res = verify(receipt)
+        failures += 0 if res["verified"] else 1
+        report.append({"file": str(path), **res})
+        _report(path, res, args.quiet)
+
+    if args.json:
+        print(json.dumps(report, indent=2))
+    elif not args.quiet:
+        total = len(report)
+        print(f"\n{total - failures}/{total} receipt(s) verified on THIS machine.")
+    return 1 if failures else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

obsign_verify/data/challenge/ATTESTATION.md

@@ -0,0 +1,48 @@
+# Attestation — I ran the Receipt Challenge
+
+Fill in, publish anywhere, link it back if you're willing. A failure to break it
+is as useful as a break; a break is more useful.
+
+## Who
+- Name / handle:
+- Affiliation (optional):
+- Date (UTC):
+
+## Platform
+- OS + version:
+- CPU (and whether ARM / x86):
+- Python version:
+- numpy version:
+- Anything unusual (musl, emulation, BSD, big-endian, PyPy, WASM):
+
+## What I ran
+```
+python verify_challenge.py
+```
+Paste the full output:
+
+```
+
+```
+
+## SHA256SUMS I observed
+Confirm the bundle you ran matches what was published:
+```
+sha256sum -c SHA256SUMS      # or: python -c "..."
+```
+Result:
+
+## Verdict
+- [ ] Every valid receipt re-derived on my machine
+- [ ] Every forgery was refused
+- [ ] I found a forgery that VERIFIED  ← the interesting one
+- [ ] The valid receipt did NOT reproduce on my hardware  ← also interesting
+
+## Notes / anything you broke or tried to break
+
+<!-- Attacks attempted, near-misses, ambiguity in the spec, anything the
+     verifier fails to check. Negative findings welcome and wanted. -->
+
+## Independence
+- [ ] I confirmed `verify_challenge.py` imports nothing from the producing project
+- [ ] I read the verifier before running it

obsign_verify/data/challenge/bundles/env_only_change_must_still_verify/receipt.json

@@ -0,0 +1,62 @@
+{
+  "_challenge": {
+    "expect_verified": true,
+    "note": "only `env` changed, which the spec excludes from the claim; this MUST still verify, or the format over-claims what it covers"
+  },
+  "env": {
+    "gpu": "NVIDIA GeForce RTX 5080 Laptop GPU",
+    "numpy": "2.3.5",
+    "platform": "some-other-os",
+    "python": "3.14.3",
+    "torch": "2.11.0+cu128"
+  },
+  "input": {
+    "kind": "generated",
+    "ref": "params",
+    "sha256": null
+  },
+  "kernel": "tau_field_fixed",
+  "output": {
+    "dtype": "int64",
+    "sha256": "a50bef430f745b12111225eed12cd0e4f86119ccb0fb47a878ed1f61d50b3ea3",
+    "shape": [
+      64,
+      64
+    ]
+  },
+  "params": {
+    "D": 0.14,
+    "dt": 0.15,
+    "frac_bits": 24,
+    "gamma": 0.02,
+    "grid": 64,
+    "sources": [
+      [
+        0.3,
+        0.3,
+        0.11,
+        0.01
+      ],
+      [
+        0.7,
+        0.7,
+        0.16,
+        0.008
+      ]
+    ],
+    "steps": 100
+  },
+  "producer": {
+    "name": "obsign",
+    "spec": "obsign/spec/1",
+    "version": "2.0.0"
+  },
+  "receipt_sha256": "b8b4f656b10646186ca9fe16d1e34eb106f4f2336d2db8f8f4cbb4a0660a5527",
+  "run": {
+    "backend": "cpu-fixed",
+    "deterministic": true,
+    "device": "numpy",
+    "dtype": "int64"
+  },
+  "spec": "obsign/receipt/v1"
+}

obsign_verify/data/challenge/bundles/forged_input_hash/receipt.json

@@ -0,0 +1,62 @@
+{
+  "_challenge": {
+    "expect_verified": false,
+    "note": "claims the computation ran on data it did not run on"
+  },
+  "env": {
+    "gpu": "NVIDIA GeForce RTX 5080 Laptop GPU",
+    "numpy": "2.3.5",
+    "platform": "Windows-11-10.0.26200-SP0",
+    "python": "3.14.3",
+    "torch": "2.11.0+cu128"
+  },
+  "input": {
+    "kind": "generated",
+    "ref": "params",
+    "sha256": "1111111111111111111111111111111111111111111111111111111111111111"
+  },
+  "kernel": "tau_field_fixed",
+  "output": {
+    "dtype": "int64",
+    "sha256": "a50bef430f745b12111225eed12cd0e4f86119ccb0fb47a878ed1f61d50b3ea3",
+    "shape": [
+      64,
+      64
+    ]
+  },
+  "params": {
+    "D": 0.14,
+    "dt": 0.15,
+    "frac_bits": 24,
+    "gamma": 0.02,
+    "grid": 64,
+    "sources": [
+      [
+        0.3,
+        0.3,
+        0.11,
+        0.01
+      ],
+      [
+        0.7,
+        0.7,
+        0.16,
+        0.008
+      ]
+    ],
+    "steps": 100
+  },
+  "producer": {
+    "name": "obsign",
+    "spec": "obsign/spec/1",
+    "version": "2.0.0"
+  },
+  "receipt_sha256": "b8b4f656b10646186ca9fe16d1e34eb106f4f2336d2db8f8f4cbb4a0660a5527",
+  "run": {
+    "backend": "cpu-fixed",
+    "deterministic": true,
+    "device": "numpy",
+    "dtype": "int64"
+  },
+  "spec": "obsign/receipt/v1"
+}

obsign_verify/data/challenge/bundles/forged_output_hash/receipt.json

@@ -0,0 +1,62 @@
+{
+  "_challenge": {
+    "expect_verified": false,
+    "note": "claims a different result than the computation produces"
+  },
+  "env": {
+    "gpu": "NVIDIA GeForce RTX 5080 Laptop GPU",
+    "numpy": "2.3.5",
+    "platform": "Windows-11-10.0.26200-SP0",
+    "python": "3.14.3",
+    "torch": "2.11.0+cu128"
+  },
+  "input": {
+    "kind": "generated",
+    "ref": "params",
+    "sha256": null
+  },
+  "kernel": "tau_field_fixed",
+  "output": {
+    "dtype": "int64",
+    "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
+    "shape": [
+      64,
+      64
+    ]
+  },
+  "params": {
+    "D": 0.14,
+    "dt": 0.15,
+    "frac_bits": 24,
+    "gamma": 0.02,
+    "grid": 64,
+    "sources": [
+      [
+        0.3,
+        0.3,
+        0.11,
+        0.01
+      ],
+      [
+        0.7,
+        0.7,
+        0.16,
+        0.008
+      ]
+    ],
+    "steps": 100
+  },
+  "producer": {
+    "name": "obsign",
+    "spec": "obsign/spec/1",
+    "version": "2.0.0"
+  },
+  "receipt_sha256": "b8b4f656b10646186ca9fe16d1e34eb106f4f2336d2db8f8f4cbb4a0660a5527",
+  "run": {
+    "backend": "cpu-fixed",
+    "deterministic": true,
+    "device": "numpy",
+    "dtype": "int64"
+  },
+  "spec": "obsign/receipt/v1"
+}

obsign_verify/data/challenge/bundles/resealed_tampered_claim/receipt.json

@@ -0,0 +1,62 @@
+{
+  "_challenge": {
+    "expect_verified": false,
+    "note": "claim tampered AND re-sealed, so integrity is INTACT; only re-derivation catches it"
+  },
+  "env": {
+    "gpu": "NVIDIA GeForce RTX 5080 Laptop GPU",
+    "numpy": "2.3.5",
+    "platform": "Windows-11-10.0.26200-SP0",
+    "python": "3.14.3",
+    "torch": "2.11.0+cu128"
+  },
+  "input": {
+    "kind": "generated",
+    "ref": "params",
+    "sha256": null
+  },
+  "kernel": "tau_field_fixed",
+  "output": {
+    "dtype": "int64",
+    "sha256": "a50bef430f745b12111225eed12cd0e4f86119ccb0fb47a878ed1f61d50b3ea3",
+    "shape": [
+      64,
+      64
+    ]
+  },
+  "params": {
+    "D": 0.14,
+    "dt": 0.15,
+    "frac_bits": 24,
+    "gamma": 0.02,
+    "grid": 64,
+    "sources": [
+      [
+        0.3,
+        0.3,
+        0.11,
+        0.01
+      ],
+      [
+        0.7,
+        0.7,
+        0.16,
+        0.008
+      ]
+    ],
+    "steps": 120
+  },
+  "producer": {
+    "name": "obsign",
+    "spec": "obsign/spec/1",
+    "version": "2.0.0"
+  },
+  "receipt_sha256": "e03f51663e632151341b77a29b32b3967565167ea767517649930c76392ca775",
+  "run": {
+    "backend": "cpu-fixed",
+    "deterministic": true,
+    "device": "numpy",
+    "dtype": "int64"
+  },
+  "spec": "obsign/receipt/v1"
+}

obsign_verify/data/challenge/bundles/swapped_dtype/receipt.json

@@ -0,0 +1,62 @@
+{
+  "_challenge": {
+    "expect_verified": false,
+    "note": "output metadata rewritten under an unchanged hash"
+  },
+  "env": {
+    "gpu": "NVIDIA GeForce RTX 5080 Laptop GPU",
+    "numpy": "2.3.5",
+    "platform": "Windows-11-10.0.26200-SP0",
+    "python": "3.14.3",
+    "torch": "2.11.0+cu128"
+  },
+  "input": {
+    "kind": "generated",
+    "ref": "params",
+    "sha256": null
+  },
+  "kernel": "tau_field_fixed",
+  "output": {
+    "dtype": "int32",
+    "sha256": "a50bef430f745b12111225eed12cd0e4f86119ccb0fb47a878ed1f61d50b3ea3",
+    "shape": [
+      64,
+      64
+    ]
+  },
+  "params": {
+    "D": 0.14,
+    "dt": 0.15,
+    "frac_bits": 24,
+    "gamma": 0.02,
+    "grid": 64,
+    "sources": [
+      [
+        0.3,
+        0.3,
+        0.11,
+        0.01
+      ],
+      [
+        0.7,
+        0.7,
+        0.16,
+        0.008
+      ]
+    ],
+    "steps": 100
+  },
+  "producer": {
+    "name": "obsign",
+    "spec": "obsign/spec/1",
+    "version": "2.0.0"
+  },
+  "receipt_sha256": "b8b4f656b10646186ca9fe16d1e34eb106f4f2336d2db8f8f4cbb4a0660a5527",
+  "run": {
+    "backend": "cpu-fixed",
+    "deterministic": true,
+    "device": "numpy",
+    "dtype": "int64"
+  },
+  "spec": "obsign/receipt/v1"
+}

obsign_verify/data/challenge/bundles/swapped_kernel/receipt.json

@@ -0,0 +1,62 @@
+{
+  "_challenge": {
+    "expect_verified": false,
+    "note": "same numbers, different operation"
+  },
+  "env": {
+    "gpu": "NVIDIA GeForce RTX 5080 Laptop GPU",
+    "numpy": "2.3.5",
+    "platform": "Windows-11-10.0.26200-SP0",
+    "python": "3.14.3",
+    "torch": "2.11.0+cu128"
+  },
+  "input": {
+    "kind": "generated",
+    "ref": "params",
+    "sha256": null
+  },
+  "kernel": "tau_field",
+  "output": {
+    "dtype": "int64",
+    "sha256": "a50bef430f745b12111225eed12cd0e4f86119ccb0fb47a878ed1f61d50b3ea3",
+    "shape": [
+      64,
+      64
+    ]
+  },
+  "params": {
+    "D": 0.14,
+    "dt": 0.15,
+    "frac_bits": 24,
+    "gamma": 0.02,
+    "grid": 64,
+    "sources": [
+      [
+        0.3,
+        0.3,
+        0.11,
+        0.01
+      ],
+      [
+        0.7,
+        0.7,
+        0.16,
+        0.008
+      ]
+    ],
+    "steps": 100
+  },
+  "producer": {
+    "name": "obsign",
+    "spec": "obsign/spec/1",
+    "version": "2.0.0"
+  },
+  "receipt_sha256": "b8b4f656b10646186ca9fe16d1e34eb106f4f2336d2db8f8f4cbb4a0660a5527",
+  "run": {
+    "backend": "cpu-fixed",
+    "deterministic": true,
+    "device": "numpy",
+    "dtype": "int64"
+  },
+  "spec": "obsign/receipt/v1"
+}