runback-verify 2.1.0__tar.gz → 2.2.0__tar.gz

runback_verify-2.2.0/.gitignore

@@ -0,0 +1,55 @@
+node_modules/
+# Worktrees symlink node_modules from the main checkout; a symlink is a file,
+# which "node_modules/" (directories only) does not match.
+node_modules
+/web/node_modules
+.next/
+.next-*/
+out/
+dist/
+.env
+.community-check-scratch/
+.env.local
+*.tsbuildinfo
+next-env.d.ts
+.DS_Store
+.vercel
+
+# secrets — belt & suspenders (keep .env.example committable)
+.env.*
+!.env.example
+# native/syscall build artifacts
+*.dylib
+*.so
+.secrets/
+
+# Python (packages/sdk-python)
+__pycache__/
+*.pyc
+*.egg-info/
+.venv/
+.pytest_cache/
+build/
+*.egg
+
+# Saved auth for local QA scripts — holds a live Supabase access_token, so a
+# stray `git add -A` would publish working credentials.
+session.json
+# Throwaway browser-driving scripts used to click through the app by hand.
+check_*.mjs
+# Generated by packages/sdk-replay/scripts/copy-licence.mjs from LICENSE-COMMUNITY.
+packages/sdk-replay/LICENSE
+
+# Agent worktrees. These are full checkouts created by the Agent tool's
+# isolation mode, and they live inside the repo — 1.8GB of them at the time of
+# writing.
+#
+# They were already excluded locally via .git/info/exclude, so git never saw
+# them. The Vercel CLI does not read that file: it falls back to .gitignore,
+# which is tracked. So a deploy uploaded 3,516 files / 3.6MB instead of the
+# usual 1,261 / ~800KB — stale duplicate copies of the whole application,
+# shipped to the build machine for no reason.
+#
+# Listed here rather than in .vercelignore so one rule covers both, and so the
+# next person reading .gitignore learns these exist.
+.claude/worktrees/

{runback_verify-2.1.0 → runback_verify-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: runback-verify
-Version: 2.1.0
+Version: 2.2.0
 Summary: Verify tamper-evidence and integrity of Runback audit cassettes (runback.cassette/v1). No account required, no dependencies.
 Project-URL: Homepage, https://runback.dev
 Project-URL: Specification, https://runback.dev/spec
@@ -20,7 +20,7 @@ Description-Content-Type: text/markdown
 
 # runback-verify
 
-Verify the integrity of a Runback audit record — offline, with nothing installed.
+Verify the integrity of a Runback audit record offline, with nothing but Python's standard library.
 
 ```bash
 pip install runback-verify
@@ -34,6 +34,22 @@ result = verify_json(open("record.json").read())
 print(result["verdict"])   # "valid" | "unverified" | "invalid"
 ```
 
+Evidence packs (the signed PDF from `GET /api/compliance/pack`, 2.2.0) are
+detected by their `%PDF-` header:
+
+```bash
+python -m runback_verify runback-evidence-pack-2026-10-01-2026-10-31.pdf
+```
+
+```python
+from runback_verify import verify_pack
+verify_pack(open("pack.pdf", "rb").read())["verdict"]
+```
+
+Same checks and exit codes as `@runback/verify` 3.1: every byte outside the
+embedded manifest must match its SHA-256, the manifest must carry Runback's
+Ed25519 signature, and a SAMPLE pack is never `valid`.
+
 ## Zero dependencies, on purpose
 
 This package is separate from `runback-sdk` because the SDK needs `requests` and
@@ -54,7 +70,20 @@ from nothing, or edit a real one and re-chain it. Integrity alone proves only
 internal coherence; provenance is a separate question, answered only by a
 signature that verifies against a key you pinned **out of band**.
 
-Exit codes: `0` valid, `1` invalid, `2` unverified.
+Exit codes: `0` valid, `1` invalid, `2` unverified. The CLI also exits `2` when
+the file cannot be read or is not a Runback record, so a CI step should read
+the printed verdict (or `--json`) before treating `2` as "unverified".
+
+The CLI takes `--json` and nothing else. By default it pins Runback's published
+Ed25519 keys, so a record signed by a self-hosted deployment's own key reports
+`unverified`. Pin your key from Python instead:
+
+```python
+result = verify_json(raw, expected_public_key=open("audit_public.pem").read())
+```
+
+Legacy HMAC-signed records verify only with the shared secret:
+`verify_json(raw, signing_key=...)`.
 
 ## The format
 

{runback_verify-2.1.0 → runback_verify-2.2.0}/README.md

@@ -1,6 +1,6 @@
 # runback-verify
 
-Verify the integrity of a Runback audit record — offline, with nothing installed.
+Verify the integrity of a Runback audit record offline, with nothing but Python's standard library.
 
 ```bash
 pip install runback-verify
@@ -14,6 +14,22 @@ result = verify_json(open("record.json").read())
 print(result["verdict"])   # "valid" | "unverified" | "invalid"
 ```
 
+Evidence packs (the signed PDF from `GET /api/compliance/pack`, 2.2.0) are
+detected by their `%PDF-` header:
+
+```bash
+python -m runback_verify runback-evidence-pack-2026-10-01-2026-10-31.pdf
+```
+
+```python
+from runback_verify import verify_pack
+verify_pack(open("pack.pdf", "rb").read())["verdict"]
+```
+
+Same checks and exit codes as `@runback/verify` 3.1: every byte outside the
+embedded manifest must match its SHA-256, the manifest must carry Runback's
+Ed25519 signature, and a SAMPLE pack is never `valid`.
+
 ## Zero dependencies, on purpose
 
 This package is separate from `runback-sdk` because the SDK needs `requests` and
@@ -34,7 +50,20 @@ from nothing, or edit a real one and re-chain it. Integrity alone proves only
 internal coherence; provenance is a separate question, answered only by a
 signature that verifies against a key you pinned **out of band**.
 
-Exit codes: `0` valid, `1` invalid, `2` unverified.
+Exit codes: `0` valid, `1` invalid, `2` unverified. The CLI also exits `2` when
+the file cannot be read or is not a Runback record, so a CI step should read
+the printed verdict (or `--json`) before treating `2` as "unverified".
+
+The CLI takes `--json` and nothing else. By default it pins Runback's published
+Ed25519 keys, so a record signed by a self-hosted deployment's own key reports
+`unverified`. Pin your key from Python instead:
+
+```python
+result = verify_json(raw, expected_public_key=open("audit_public.pem").read())
+```
+
+Legacy HMAC-signed records verify only with the shared secret:
+`verify_json(raw, signing_key=...)`.
 
 ## The format
 

{runback_verify-2.1.0 → runback_verify-2.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "runback-verify"
-version = "2.1.0"
+version = "2.2.0"
 description = "Verify tamper-evidence and integrity of Runback audit cassettes (runback.cassette/v1). No account required, no dependencies."
 readme = "README.md"
 license = "MIT"

{runback_verify-2.1.0 → runback_verify-2.2.0}/runback_verify/__init__.py

@@ -565,6 +565,142 @@ def verify_json(raw: str, signing_key: Optional[str] = None, **kwargs) -> dict:
     return verify(json.loads(raw), signing_key, **kwargs)
 
 
+# ── Evidence packs (runback.pack/v1) ─────────────────────────────────────────
+#
+# A port of packages/verify/index.js verifyPack(); where they disagree the JS
+# reference is right. The pack is a PDF with one reserved region between two
+# marker lines; every byte outside it is hashed into a signed manifest held in
+# the region. No PDF parsing: the markers are found by byte search.
+
+PACK_SCHEMA = "runback.pack/v1"
+PACK_MANIFEST_BEGIN = b"%RUNBACK-PACK-MANIFEST-BEGIN\n"
+PACK_MANIFEST_END = b"\n%RUNBACK-PACK-MANIFEST-END"
+PACK_SIGNATURE_PREFIX = "runback-pack:"
+_HEX64 = re.compile(r"^[0-9a-f]{64}$")
+
+
+def _ed25519_verdict(payload: bytes, sig: Any, expected_public_key: PemList, revoked_public_keys: Optional[Sequence[str]]) -> tuple:
+    """(verdict, alg) for an Ed25519 {alg, value, pubkey?} signature: the JS signatureVerdict()."""
+    if not isinstance(sig, dict) or not sig.get("value"):
+        return "unsigned", None
+    if sig.get("alg") == "HMAC-SHA256":
+        return "no-key", "HMAC-SHA256"
+    if sig.get("alg") != "Ed25519":
+        return "invalid", None
+    raw_pinned = RUNBACK_AUDIT_PUBKEYS_PEM if expected_public_key == "__default__" else expected_public_key
+    pinned = [] if raw_pinned is None else [raw_pinned] if isinstance(raw_pinned, str) else list(raw_pinned)
+    revoked = list(RUNBACK_AUDIT_REVOKED_PUBKEYS_PEM if revoked_public_keys is None else revoked_public_keys)
+    candidates = [sig["pubkey"]] if sig.get("pubkey") else pinned
+    if not candidates:
+        return "no-key", "Ed25519"
+    try:
+        raw_sig = bytes.fromhex(str(sig["value"]))
+    except ValueError:
+        return "invalid", "Ed25519"
+    signer = None
+    for pem in candidates:
+        key = _spki_der(pem)
+        if key is not None and ed25519_verify(key, payload, raw_sig):
+            signer = key
+            break
+    if signer is None:
+        return "invalid", "Ed25519"
+    if any(_spki_der(p) == signer for p in revoked):
+        return "revoked", "Ed25519"
+    if not pinned:
+        return "valid-unpinned", "Ed25519"
+    return ("valid" if any(_spki_der(p) == signer for p in pinned) else "valid-unpinned"), "Ed25519"
+
+
+def _checkpoint_verdict(cp: Any, expected_public_key: PemList, revoked_public_keys: Optional[Sequence[str]]) -> str:
+    """valid | unverified | invalid for a runback.checkpoint/v3 document (verifyCheckpoint in JS)."""
+    if not isinstance(cp, dict):
+        return "invalid"
+    seq = cp.get("seq")
+    shape = (
+        cp.get("$schema") == "runback.checkpoint/v3"
+        and isinstance(cp.get("org_id"), str)
+        and isinstance(seq, int) and not isinstance(seq, bool) and seq >= 0
+        and isinstance(cp.get("head_hash"), str) and bool(_HEX64.match(cp["head_hash"]))
+        and isinstance(cp.get("merkle_root"), str) and bool(_HEX64.match(cp["merkle_root"]))
+        and (cp.get("tombstone_digest") is None or (isinstance(cp["tombstone_digest"], str) and bool(_HEX64.match(cp["tombstone_digest"]))))
+    )
+    payload = f"ledger:{cp.get('org_id')}:{seq}:{cp.get('head_hash')}:{cp.get('merkle_root')}"
+    if cp.get("tombstone_digest"):
+        payload += f":ts:{cp['tombstone_digest']}"
+    sig, _ = _ed25519_verdict(payload.encode("utf-8"), cp.get("signature"), expected_public_key, revoked_public_keys)
+    if not shape or sig in ("invalid", "revoked"):
+        return "invalid"
+    return "valid" if sig == "valid" else "unverified"
+
+
+def verify_pack(
+    data: bytes,
+    *,
+    expected_public_key: PemList = "__default__",
+    revoked_public_keys: Optional[Sequence[str]] = None,
+) -> dict:
+    """Verify a Runback evidence pack (the PDF from GET /api/compliance/pack).
+
+    "valid" only when every byte outside the manifest matches its signed
+    SHA-256 and the signer is a pinned key. A SAMPLE pack is never valid.
+    """
+    checks: dict = {"pdf": data[:5] == b"%PDF-", "manifest": False, "schema": False, "body_hash": False,
+                    "signature": "unsigned", "signature_alg": None, "checkpoint": None}
+
+    def fail(error: str) -> dict:
+        return {"valid": False, "verdict": "invalid", "sample": False, "checks": checks, "manifest": None, "error": error}
+
+    bi = data.find(PACK_MANIFEST_BEGIN)
+    if bi < 0:
+        return fail("no Runback manifest in this file")
+    if data.find(PACK_MANIFEST_BEGIN, bi + 1) >= 0:
+        return fail("the manifest begin marker appears more than once")
+    start = bi + len(PACK_MANIFEST_BEGIN)
+    ei = data.find(PACK_MANIFEST_END, start)
+    if ei < 0:
+        return fail("the manifest end marker is missing")
+    if data.find(PACK_MANIFEST_END, ei + 1) >= 0 or data[:bi].find(PACK_MANIFEST_END) >= 0:
+        return fail("the manifest end marker appears more than once")
+    try:
+        region = json.loads(data[start:ei].decode("utf-8").strip())
+        manifest_text = region["manifest"]
+        if not isinstance(manifest_text, str):
+            raise TypeError
+        manifest = json.loads(manifest_text)
+        if not isinstance(manifest, dict):
+            raise TypeError
+    except Exception:
+        return fail("the manifest region does not hold a readable manifest")
+    checks["manifest"] = True
+    checks["schema"] = manifest.get("$schema") == PACK_SCHEMA
+    computed = hashlib.sha256(data[:start] + data[ei:]).hexdigest()
+    claimed = (manifest.get("pdf") or {}).get("sha256")
+    checks["body_hash"] = isinstance(claimed, str) and bool(_HEX64.match(claimed)) and claimed == computed
+
+    sig, alg = _ed25519_verdict((PACK_SIGNATURE_PREFIX + manifest_text).encode("utf-8"), region.get("signature"),
+                                expected_public_key, revoked_public_keys)
+    checks["signature"], checks["signature_alg"] = sig, alg
+
+    cp = (manifest.get("ledger") or {}).get("checkpoint")
+    if cp:
+        verdict = _checkpoint_verdict(cp, expected_public_key, revoked_public_keys)
+        if not isinstance(cp, dict) or cp.get("org_id") != manifest.get("org_id"):
+            verdict = "invalid"
+        checks["checkpoint"] = verdict
+
+    sample = manifest.get("sample") is True
+    integrity = checks["pdf"] and checks["schema"] and checks["body_hash"] and checks["checkpoint"] != "invalid"
+    if not integrity or sig in ("invalid", "revoked"):
+        verdict = "invalid"
+    elif sig == "valid" and not sample:
+        verdict = "valid"
+    else:
+        verdict = "unverified"
+    return {"valid": verdict == "valid", "verdict": verdict, "sample": sample, "checks": checks,
+            "manifest": manifest, "computed_sha256": computed}
+
+
 def _main(argv: Sequence[str]) -> int:
     import sys
 
@@ -578,11 +714,18 @@ def _main(argv: Sequence[str]) -> int:
     # broken" rather than "check the path", and this is a tool whose whole job
     # is to be usable by someone who does not write Python.
     try:
-        with open(path, "r", encoding="utf-8") as fh:
-            raw = fh.read()
+        with open(path, "rb") as fh:
+            data = fh.read()
     except OSError as exc:
         print(f"cannot read {path}: {exc.strerror}", file=sys.stderr)
         return 2
+    if data[:5] == b"%PDF-":
+        return _main_pack(path, data, as_json)
+    try:
+        raw = data.decode("utf-8")
+    except UnicodeDecodeError:
+        print(f"{path} is not UTF-8 JSON or a Runback evidence pack.", file=sys.stderr)
+        return 2
     try:
         result = verify_json(raw)
     except json.JSONDecodeError as exc:
@@ -612,6 +755,29 @@ def _main(argv: Sequence[str]) -> int:
     return {"valid": 0, "invalid": 1, "unverified": 2}[result["verdict"]]
 
 
+def _main_pack(path: str, data: bytes, as_json: bool) -> int:
+    """An evidence pack (a PDF): the same report and exit codes as runback-verify on npm."""
+    result = verify_pack(data)
+    code = {"valid": 0, "invalid": 1, "unverified": 2}[result["verdict"]]
+    if as_json:
+        print(json.dumps(result, indent=2))
+        return code
+    c = result["checks"]
+    print(f"{path}: evidence pack {result['verdict'].upper()}")
+    if result.get("error"):
+        print(f"  {result['error']}")
+        return code
+    m = result["manifest"]
+    if result["sample"]:
+        print("  SAMPLE PACK: illustrative figures, not a record of any organisation. Not evidence.")
+    print(f"  org        {m.get('org_name', '')} ({m.get('org_id')})")
+    print(f"  period     {(m.get('period') or {}).get('start')} to {(m.get('period') or {}).get('end')} (UTC)")
+    print(f"  file       {'ok' if c['body_hash'] else 'CHANGED'} (sha256 {result['computed_sha256']})")
+    print(f"  signature  {c['signature']}" + (f" ({c['signature_alg']})" if c["signature_alg"] else ""))
+    print(f"  checkpoint {c['checkpoint'] or 'none cited'}")
+    return code
+
+
 def _console() -> int:
     """Console-script entry point declared in pyproject.toml."""
     import sys

runback_verify-2.2.0/tests/test_pack.py

@@ -0,0 +1,81 @@
+"""
+Evidence packs: the Python port must reach the JS reference's verdicts on the
+same files. packages/verify/testdata/packs/ is written by gen-packs.mjs with a
+throwaway key (only its public half is kept), and test/pack.test.js checks the
+same files in JS.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+_HERE = Path(__file__).resolve().parent
+_PACKS = _HERE.parents[1] / "verify" / "testdata" / "packs"
+
+sys.path.insert(0, str(_HERE.parent))
+
+from runback_verify import verify_pack  # noqa: E402
+
+KEY = (_PACKS / "key.pem").read_text()
+
+
+def _read(name: str) -> bytes:
+    return (_PACKS / name).read_bytes()
+
+
+def test_valid_pack_verifies_against_the_pinned_key():
+    r = verify_pack(_read("valid.pdf"), expected_public_key=KEY)
+    assert r["verdict"] == "valid"
+    assert r["checks"]["body_hash"] is True
+    assert r["checks"]["signature"] == "valid"
+    assert r["checks"]["checkpoint"] == "valid"
+    assert r["manifest"]["org_name"] == "Acme Insurance — 東京 \U0001F642"
+
+
+def test_changed_byte_is_invalid():
+    r = verify_pack(_read("tampered.pdf"), expected_public_key=KEY)
+    assert r["verdict"] == "invalid"
+    assert r["checks"]["body_hash"] is False
+
+
+def test_sample_is_never_valid():
+    r = verify_pack(_read("sample.pdf"), expected_public_key=KEY)
+    assert r["sample"] is True
+    assert r["verdict"] == "unverified"
+
+
+def test_unpinned_signer_is_unverified():
+    # Runback's published key is not the fixture key.
+    r = verify_pack(_read("valid.pdf"))
+    assert r["checks"]["signature"] == "valid-unpinned"
+    assert r["verdict"] == "unverified"
+
+
+def test_revoked_signer_is_invalid():
+    r = verify_pack(_read("valid.pdf"), expected_public_key=KEY, revoked_public_keys=[KEY])
+    assert r["verdict"] == "invalid"
+
+
+def test_edited_manifest_fails_the_signature():
+    data = bytearray(_read("valid.pdf"))
+    i = data.find(b'\\"total\\":120')
+    assert i > 0
+    data[i:i + 13] = b'\\"total\\":999'
+    r = verify_pack(bytes(data), expected_public_key=KEY)
+    assert r["checks"]["signature"] == "invalid"
+    assert r["verdict"] == "invalid"
+
+
+def test_no_manifest_is_invalid():
+    assert verify_pack(b"%PDF-1.7\n%%EOF\n")["error"] == "no Runback manifest in this file"
+
+
+def test_cli_exit_codes():
+    def run(name: str) -> int:
+        return subprocess.run([sys.executable, "-m", "runback_verify", str(_PACKS / name)],
+                              cwd=str(_HERE.parent), capture_output=True).returncode
+    assert run("tampered.pdf") == 1
+    assert run("sample.pdf") == 2
+    assert run("valid.pdf") == 2  # fixture key, not Runback's published one

runback_verify-2.1.0/.gitignore

@@ -1,35 +0,0 @@
-node_modules/
-.next/
-out/
-dist/
-.env
-.community-check-scratch/
-.env.local
-*.tsbuildinfo
-next-env.d.ts
-.DS_Store
-.vercel
-
-# secrets — belt & suspenders (keep .env.example committable)
-.env.*
-!.env.example
-# native/syscall build artifacts
-*.dylib
-*.so
-.secrets/
-
-# Python (packages/sdk-python)
-__pycache__/
-*.pyc
-*.egg-info/
-.venv/
-.pytest_cache/
-build/
-*.egg
-
-# Saved auth for local QA scripts — holds a live Supabase access_token, so a
-# stray `git add -A` would publish working credentials.
-session.json
-# Throwaway browser-driving scripts used to click through the app by hand.
-check_*.mjs
-packages/sdk/LICENSE