runback-verify 2.1.0__tar.gz

runback_verify-2.1.0/.gitignore

@@ -0,0 +1,35 @@
+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

runback_verify-2.1.0/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.5
+Name: runback-verify
+Version: 2.1.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
+Project-URL: Source, https://github.com/letsRunback/runback
+Author-email: Runback <contact@runback.dev>
+License-Expression: MIT
+Keywords: ai-agents,audit,cassette,ed25519,eu-ai-act,governance,runback,tamper-evident,verification
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Legal Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# runback-verify
+
+Verify the integrity of a Runback audit record — offline, with nothing installed.
+
+```bash
+pip install runback-verify
+runback-verify record.json
+```
+
+```python
+from runback_verify import verify_json
+
+result = verify_json(open("record.json").read())
+print(result["verdict"])   # "valid" | "unverified" | "invalid"
+```
+
+## Zero dependencies, on purpose
+
+This package is separate from `runback-sdk` because the SDK needs `requests` and
+`python-ulid` to do its job, and an auditor needs neither. Ed25519 verification
+is implemented here from RFC 8032 in plain Python, so the package installs and
+runs on a stock interpreter in a locked-down environment.
+
+## What the verdicts mean
+
+| verdict | meaning |
+|---|---|
+| `valid` | integrity holds **and** the signer is a key you pinned |
+| `unverified` | self-consistent, but the origin is unproven |
+| `invalid` | something failed — it is not the record it claims to be |
+
+The chain algorithm is public, so anyone can author a self-consistent record
+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.
+
+## The format
+
+`runback.cassette/v1` is specified at <https://runback.dev/spec>. The reference
+implementation is [`@runback/verify`](https://www.npmjs.com/package/@runback/verify)
+on npm; this package is a port held to the same generated conformance fixture,
+and where the two disagree the reference is authoritative.

runback_verify-2.1.0/README.md

@@ -0,0 +1,44 @@
+# runback-verify
+
+Verify the integrity of a Runback audit record — offline, with nothing installed.
+
+```bash
+pip install runback-verify
+runback-verify record.json
+```
+
+```python
+from runback_verify import verify_json
+
+result = verify_json(open("record.json").read())
+print(result["verdict"])   # "valid" | "unverified" | "invalid"
+```
+
+## Zero dependencies, on purpose
+
+This package is separate from `runback-sdk` because the SDK needs `requests` and
+`python-ulid` to do its job, and an auditor needs neither. Ed25519 verification
+is implemented here from RFC 8032 in plain Python, so the package installs and
+runs on a stock interpreter in a locked-down environment.
+
+## What the verdicts mean
+
+| verdict | meaning |
+|---|---|
+| `valid` | integrity holds **and** the signer is a key you pinned |
+| `unverified` | self-consistent, but the origin is unproven |
+| `invalid` | something failed — it is not the record it claims to be |
+
+The chain algorithm is public, so anyone can author a self-consistent record
+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.
+
+## The format
+
+`runback.cassette/v1` is specified at <https://runback.dev/spec>. The reference
+implementation is [`@runback/verify`](https://www.npmjs.com/package/@runback/verify)
+on npm; this package is a port held to the same generated conformance fixture,
+and where the two disagree the reference is authoritative.

runback_verify-2.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "runback-verify"
+version = "2.1.0"
+description = "Verify tamper-evidence and integrity of Runback audit cassettes (runback.cassette/v1). No account required, no dependencies."
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "Runback", email = "contact@runback.dev" }]
+requires-python = ">=3.9"
+keywords = [
+  "ai-agents",
+  "audit",
+  "governance",
+  "tamper-evident",
+  "verification",
+  "runback",
+  "cassette",
+  "eu-ai-act",
+  "ed25519",
+]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Legal Industry",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Security :: Cryptography",
+  "Topic :: Software Development :: Quality Assurance",
+]
+
+# Deliberately empty, and load-bearing.
+#
+# The version is pinned to @runback/verify's so the two ports of one format
+# carry one number — a record that verifies under runback-verify 2.1.0 verifies
+# identically under @runback/verify 2.1.0, and "which version checked this?" has
+# a single answer across languages.
+dependencies = []
+
+[project.scripts]
+runback-verify = "runback_verify:_console"
+
+[project.urls]
+Homepage = "https://runback.dev"
+Specification = "https://runback.dev/spec"
+Source = "https://github.com/letsRunback/runback"
+
+[tool.hatch.build.targets.wheel]
+packages = ["runback_verify"]
+
+[tool.hatch.build.targets.sdist]
+include = ["runback_verify", "README.md", "tests"]

runback_verify-2.1.0/runback_verify/__init__.py

@@ -0,0 +1,625 @@
+"""
+runback-verify — check a Runback audit record offline, with nothing installed.
+
+    pip install runback-verify
+    python3 -m runback_verify record.json
+
+    from runback_verify import verify_json
+    verify_json(open("record.json").read())["verdict"]   # valid|unverified|invalid
+
+ZERO DEPENDENCIES, ON PURPOSE
+
+This package exists separately from runback-sdk for one reason: the SDK needs
+requests and python-ulid to do its job, and an auditor does not need either. The
+claim the format makes is "you can check our evidence without us", and an
+auditor who must first get a Rust-building wheel past a locked-down build is an
+auditor who cannot check the record where the question was asked.
+
+So Ed25519 verification is implemented here from RFC 8032 in plain Python —
+about eighty lines of integer arithmetic, nothing imported beyond hashlib. It
+verifies in a few milliseconds, which is irrelevant when the alternative is
+being unable to verify at all. The same reasoning produced a zero-dependency
+@runback/verify on npm; this is that promise kept in a second language.
+
+WHAT "VALID" MEANS, AND WHAT IT DOES NOT
+
+The chain algorithm is public, so anyone can author a self-consistent record
+from nothing, or edit a real one and re-chain it. Integrity proves only internal
+coherence. Provenance is a separate question, answered only by a signature
+verifying against a key you pinned OUT OF BAND — hence three outcomes:
+
+    valid        integrity holds AND the signer is a key you pinned
+    unverified   self-consistent, but the origin is unproven
+    invalid      something failed — not the record it claims to be
+
+THE REFERENCE, AND WHY A FOURTH COPY OF canonical() IS SAFE
+
+packages/verify/index.js defines the format; this is a port, and where the two
+disagree the reference is right. The canonicalisation below is duplicated from
+runback-sdk rather than imported, because importing it would reintroduce the
+dependency this package exists to avoid.
+
+Duplication is how three implementations silently drifted apart once already
+(exponent padding, HTML escaping, non-BMP key order — each changing the digest).
+What makes a fourth copy safe is that every copy is now held to one generated
+fixture, packages/verify/testdata/jcs-vectors.json, by a conformance suite in
+its own language. A copy that drifts fails its tests.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import re
+from typing import Any, Optional, Sequence, Union
+
+def sha256(s: str) -> str:
+    return hashlib.sha256(s.encode("utf-8")).hexdigest()
+
+
+def _js_number(x: float) -> str:
+    """ECMAScript Number::toString — what JSON.stringify emits, and what RFC 8785
+    is defined against.
+
+    Python's json module is NOT a drop-in here. Two differences, both of which
+    changed the digest:
+
+      json.dumps(1e-7)  -> "1e-07"   JSON.stringify(1e-7)  -> "1e-7"
+      json.dumps(1e16)  -> "1e+16"   JSON.stringify(1e16)  -> "10000000000000000"
+
+    Python pads the exponent to two digits and switches to scientific notation
+    at 1e16; ECMAScript strips the pad and switches at 1e21. A record carrying
+    either value hashed differently in Python than in JS, so the Python side
+    would report TAMPERED on a record the reference verifier calls VALID.
+    """
+    if x != x or x in (float("inf"), float("-inf")):
+        return "null"  # JSON.stringify(NaN) === JSON.stringify(Infinity) === "null"
+    if x == 0:
+        return "0"  # also covers -0.0; ECMAScript prints negative zero as "0"
+    if x < 0:
+        return "-" + _js_number(-x)
+    if x == int(x) and x < 1e21:
+        return str(int(x))
+
+    # Shortest round-trip digits, renormalised to value == 0.<digits> x 10**n,
+    # which is the form the ECMAScript spec's cases are written against.
+    r = repr(float(x))
+    mant, _, e = r.partition("e")
+    exp = int(e) if e else 0
+    ip, _, fp = mant.partition(".")
+    ip_sig = ip.lstrip("0")
+    digits = (ip + fp).lstrip("0")
+    n = (len(ip_sig) + exp) if ip_sig else (exp - (len(fp) - len(fp.lstrip("0"))))
+    digits = digits.rstrip("0") or "0"
+    k = len(digits)
+
+    if k <= n <= 21:
+        return digits + "0" * (n - k)
+    if 0 < n <= 21:
+        return digits[:n] + "." + digits[n:]
+    if -6 < n <= 0:
+        return "0." + "0" * (-n) + digits
+    sign = "+" if n - 1 >= 0 else "-"
+    head = digits if k == 1 else digits[0] + "." + digits[1:]
+    return head + "e" + sign + str(abs(n - 1))
+
+
+def _utf16_key(k: str) -> bytes:
+    """Sort key giving UTF-16 code-unit order, which is what RFC 8785 requires.
+
+    Python's `sorted()` orders strings by Unicode CODE POINT; RFC 8785 (and JS's
+    own Object.keys().sort()) order by UTF-16 CODE UNIT. They agree across the
+    BMP and disagree above it, because a non-BMP character encodes as a
+    surrogate pair in 0xD800-0xDFFF, which sorts BELOW ordinary characters in
+    0xE000-0xFFFF while its code point sorts above them.
+
+    Measured: {"\U0001F600": 1, "\uFFFD": 2} canonicalises with the emoji key
+    FIRST in JS and SECOND in Python. Same object, two digests, and an auditor
+    running the Python verifier would call a genuine record tampered.
+    """
+    return k.encode("utf-16-be", "surrogatepass")
+
+
+def canonical(v: Any) -> str:
+    if isinstance(v, bool):
+        # Before the int branch: bool is a subclass of int in Python, so
+        # `isinstance(True, int)` is True and True would serialise as "1".
+        return "true" if v else "false"
+    if isinstance(v, float):
+        return _js_number(v)
+    if v is None or not isinstance(v, (dict, list)):
+        return json.dumps(v, separators=(",", ":"), ensure_ascii=False)
+    if isinstance(v, list):
+        return "[" + ",".join(canonical(x) for x in v) + "]"
+    o: dict = v
+    parts = []
+    # Python has no distinct "undefined" — a key simply absent from the dict
+    # never appears in `o.keys()` to begin with, which already matches
+    # JSON.stringify's "omit undefined-valued keys" behavior with nothing
+    # extra to check for here.
+    for k in sorted(o.keys(), key=_utf16_key):
+        parts.append(json.dumps(k, ensure_ascii=False) + ":" + canonical(o[k]))
+    return "{" + ",".join(parts) + "}"
+
+
+def chain_step(prev: str, entry: dict) -> str:
+    """One step of the hash chain over an entry's defining content (not its own hash)."""
+    return sha256(prev + canonical({"kind": entry["kind"], "key": entry["key"], "output": entry["output"]}))
+
+
+def _project_input(input_value: Any, projection: Optional[dict]) -> Any:
+    if not projection:
+        return input_value
+    keep = projection.get("keep")
+    drop = projection.get("drop")
+    if not keep and not drop:
+        return input_value
+    if not isinstance(input_value, (dict, list)):
+        return input_value
+    work = json.loads(json.dumps(input_value))  # deep clone, matching the TS jsonClone
+    if keep and isinstance(work, dict):
+        keep_top = {k.split(".")[0] for k in keep}
+        for k in list(work.keys()):
+            if k not in keep_top:
+                del work[k]
+    if drop:
+        for p in drop:
+            _drop_path(work, p.split("."))
+    return work
+
+
+def _drop_path(node: Any, segs: list[str]) -> None:
+    if node is None or not segs or not isinstance(node, (dict, list)):
+        return
+    if isinstance(node, list):
+        for el in node:
+            _drop_path(el, segs)
+        return
+    head, *rest = segs
+    if not rest:
+        node.pop(head, None)
+    elif head in node:
+        _drop_path(node[head], rest)
+
+
+def tool_key_p(name: str, input_value: Any, projection: Optional[dict] = None) -> str:
+    return sha256(f"tool:{name}:{canonical(_project_input(input_value, projection))}")
+
+
+def llm_key_p(model_id: str, request: Any, projection: Optional[dict] = None) -> str:
+    return sha256(f"llm:{model_id}:{canonical(_project_input(request, projection))}")
+
+
+def oracle_entry_of(event: dict) -> Optional[dict]:
+    """
+    Map a trace event (dict, matching the wire schema) to the entry it
+    contributes to the deterministic chain, or None if it isn't a
+    nondeterminism boundary (run/reasoning envelopes) — the exact same rule
+    packages/replay/src/cassette.ts's oracleEntryOf enforces, so a digest
+    computed here and one computed server-side from the same stored events
+    are identical by construction.
+    """
+    t = event.get("type")
+    if t == "llm":
+        error = event.get("error")
+        return {
+            "kind": "llm",
+            "key": llm_key_p(event["model"]["model_id"], event["request"], event.get("key_projection")),
+            "output": {"error": error} if error else event.get("response"),
+        }
+    if t == "tool":
+        error = event.get("error")
+        return {
+            "kind": "tool",
+            "key": tool_key_p(event["tool_name"], event.get("input"), event.get("key_projection")),
+            "output": {"error": error} if error else event.get("output"),
+        }
+    if t == "env":
+        return {"kind": event["kind"], "key": event["key"], "output": event.get("output")}
+    return None
+
+
+__all__ = [
+    "verify",
+    "verify_json",
+    "compute_event_chain",
+    "compute_cassette_digest",
+    "RUNBACK_AUDIT_PUBKEYS_PEM",
+    "KNOWN_SCHEMAS",
+]
+
+KNOWN_SCHEMAS = {"runback.audit/v2", "runback.cassette/v1"}
+
+# Runback's published production signing keys, mirroring
+# packages/verify/index.js. Kept as a list so a rotated-out key can stay
+# accepted for the lifetime of records it signed.
+RUNBACK_AUDIT_PUBKEYS_PEM: list[str] = [
+    "-----BEGIN PUBLIC KEY-----\n"
+    "MCowBQYDK2VwAyEAGb9ECWmEzf6FQbrBZ9w7lshQhqowtrbLDFw4rXAxZuE=\n"
+    "-----END PUBLIC KEY-----\n",
+]
+RUNBACK_AUDIT_REVOKED_PUBKEYS_PEM: list[str] = []
+
+
+# ── Ed25519 verification, RFC 8032, pure Python ──────────────────────────────
+# Reference implementation arithmetic. Not constant-time — irrelevant here,
+# because verification uses only public values: a signature, a public key and a
+# message an attacker already holds. There is no secret to leak by timing.
+
+_P = 2**255 - 19
+_L = 2**252 + 27742317777372353535851937790883648493
+_D = -121665 * pow(121666, _P - 2, _P) % _P
+_I = pow(2, (_P - 1) // 4, _P)
+
+
+def _x_recover(y: int) -> int:
+    xx = (y * y - 1) * pow(_D * y * y + 1, _P - 2, _P)
+    x = pow(xx, (_P + 3) // 8, _P)
+    if (x * x - xx) % _P != 0:
+        x = (x * _I) % _P
+    if x % 2 != 0:
+        x = _P - x
+    return x
+
+
+_BY = 4 * pow(5, _P - 2, _P) % _P
+_BX = _x_recover(_BY)
+_B = (_BX % _P, _BY % _P, 1, _BX * _BY % _P)
+
+
+def _point_add(p: tuple, q: tuple) -> tuple:
+    a = (p[1] - p[0]) * (q[1] - q[0]) % _P
+    b = (p[1] + p[0]) * (q[1] + q[0]) % _P
+    c = 2 * p[3] * q[3] * _D % _P
+    d = 2 * p[2] * q[2] % _P
+    e, f, g, h = b - a, d - c, d + c, b + a
+    return (e * f % _P, g * h % _P, f * g % _P, e * h % _P)
+
+
+def _scalar_mult(p: tuple, e: int) -> tuple:
+    q = (0, 1, 1, 0)  # neutral element
+    while e > 0:
+        if e & 1:
+            q = _point_add(q, p)
+        p = _point_add(p, p)
+        e >>= 1
+    return q
+
+
+def _point_equal(p: tuple, q: tuple) -> bool:
+    if (p[0] * q[2] - q[0] * p[2]) % _P != 0:
+        return False
+    return (p[1] * q[2] - q[1] * p[2]) % _P == 0
+
+
+def _point_decompress(s: bytes) -> Optional[tuple]:
+    if len(s) != 32:
+        return None
+    y = int.from_bytes(s, "little")
+    sign = y >> 255
+    y &= (1 << 255) - 1
+    if y >= _P:
+        return None
+    x = _x_recover(y)
+    if x == 0 and sign:
+        return None
+    if x & 1 != sign:
+        x = _P - x
+    return (x, y, 1, x * y % _P)
+
+
+def ed25519_verify(public_key: bytes, message: bytes, signature: bytes) -> bool:
+    """RFC 8032 Ed25519 verification. Returns False rather than raising."""
+    if len(signature) != 64 or len(public_key) != 32:
+        return False
+    a = _point_decompress(public_key)
+    if a is None:
+        return False
+    r = _point_decompress(signature[:32])
+    if r is None:
+        return False
+    s = int.from_bytes(signature[32:], "little")
+    if s >= _L:
+        return False
+    h = int.from_bytes(
+        hashlib.sha512(signature[:32] + public_key + message).digest(), "little"
+    ) % _L
+    sb = _scalar_mult(_B, s)
+    check = _point_add(r, _scalar_mult(a, h))
+    return _point_equal(sb, check)
+
+
+# ── SPKI PEM parsing ─────────────────────────────────────────────────────────
+
+
+def _spki_der(pem: str) -> Optional[bytes]:
+    """Raw 32-byte Ed25519 public key from an SPKI PEM.
+
+    An Ed25519 SPKI DER is a fixed 44 bytes whose final 32 are the key, so the
+    prefix is checked rather than parsed: a real ASN.1 parser here would be more
+    code and more attack surface for one fixed shape.
+    """
+    body = re.sub(r"-----(BEGIN|END)[^-]*-----|\s", "", pem or "")
+    try:
+        der = base64.b64decode(body, validate=True)
+    except Exception:
+        return None
+    if len(der) != 44:
+        return None
+    # 302a300506032b6570032100 — SEQUENCE, AlgorithmIdentifier id-Ed25519, BIT STRING
+    if der[:12] != bytes.fromhex("302a300506032b6570032100"):
+        return None
+    return der[12:]
+
+
+# ── The chain and the cassette digest ────────────────────────────────────────
+
+
+def compute_event_chain(events: Sequence[dict]) -> dict:
+    """h_0 = ""; h_i = SHA-256(h_{i-1} + canonical(event_i without _hash))."""
+    prev = ""
+    hashes = []
+    for e in events:
+        # Skip _hash without copying the event. Copying is not cosmetic here:
+        # dict(e) is fine in Python, but the JS reference had to serialise in
+        # place because Object.assign drops an own "__proto__" key, and the two
+        # implementations must hash the same bytes for the same input.
+        body = {k: v for k, v in e.items() if k != "_hash"}
+        h = sha256(prev + canonical(body))
+        hashes.append(h)
+        prev = h
+    return {"hashes": hashes, "digest": prev or sha256("")}
+
+
+def compute_cassette_digest(events: Sequence[dict]) -> dict:
+    ordered = sorted(events, key=lambda e: e.get("seq") or 0)
+    prev = ""
+    count = 0
+    for e in ordered:
+        entry = oracle_entry_of(e)
+        if not entry:
+            continue
+        prev = chain_step(prev, entry)
+        count += 1
+    return {"digest": prev or sha256(""), "entry_count": count}
+
+
+# ── Consistency: the unsigned convenience fields must match the signed events ─
+
+
+def _check_consistency(record: dict) -> dict:
+    """Bind the record's summary to the events the signature actually covers.
+
+    The signed material is the event chain plus the cassette digest. It does NOT
+    cover manifest.run_id or the top-level `run` summary — so on a genuinely
+    signed record those can be rewritten and every hash still verifies. The
+    reference implementation demonstrated it: a real signed record with
+    run.status flipped error -> completed and a fabricated approval passed.
+
+    An auditor reads the summary, not the raw event stream, so a record that
+    misrepresents its own outcome is not valid however intact its chain.
+    """
+    events = record.get("events") or []
+    reasons: list[str] = []
+
+    run_ids = {e.get("run_id") for e in events if isinstance(e, dict) and e.get("run_id")}
+    manifest_run_id = (record.get("manifest") or {}).get("run_id")
+    if manifest_run_id and run_ids and manifest_run_id not in run_ids:
+        reasons.append(
+            f"manifest.run_id ({manifest_run_id}) is not the run_id in the signed events"
+        )
+
+    end = next(
+        (e for e in events if isinstance(e, dict) and e.get("type") == "run" and e.get("phase") == "end"),
+        None,
+    )
+    run = record.get("run")
+    if isinstance(run, dict) and end:
+        if "status" in run and run["status"] != end.get("status"):
+            reasons.append(
+                f"run.status ({run['status']}) contradicts the sealed run-end event ({end.get('status')})"
+            )
+        if "output" in run and run["output"] != end.get("output"):
+            reasons.append("run.output does not match the sealed run-end event")
+        if "error" in run and run["error"] != end.get("error"):
+            reasons.append("run.error does not match the sealed run-end event")
+
+    return {"ok": not reasons, "reasons": reasons}
+
+
+# ── Public API ───────────────────────────────────────────────────────────────
+
+PemList = Union[str, Sequence[str], None]
+
+
+def verify(
+    record: dict,
+    signing_key: Optional[str] = None,
+    *,
+    expected_public_key: PemList = "__default__",
+    revoked_public_keys: Optional[Sequence[str]] = None,
+) -> dict:
+    """Verify a parsed cassette record. Mirrors packages/verify/index.js verify()."""
+    if not isinstance(record, dict) or not isinstance(record.get("manifest"), dict) \
+            or not isinstance(record.get("events"), list):
+        raise TypeError("Not a runback.cassette record — missing manifest or events array.")
+
+    manifest = record["manifest"]
+    events = record["events"]
+
+    chain = compute_event_chain(events)
+    cassette = compute_cassette_digest(events)
+
+    chain_ok = all(
+        h == (events[i].get("_hash") if isinstance(events[i], dict) else None)
+        for i, h in enumerate(chain["hashes"])
+    )
+    digest_ok = chain["digest"] == manifest.get("content_digest")
+    cassette_ok = cassette["digest"] == (manifest.get("replay") or {}).get("cassette_digest")
+    schema_ok = record.get("$schema") in KNOWN_SCHEMAS
+
+    signature = "unsigned"
+    signature_alg = None
+    sig = manifest.get("signature") or {}
+    if sig.get("value"):
+        # Must match web/lib/audit.ts exactly: the signature covers both the
+        # event chain and the replay digest, so a record cannot be re-pointed at
+        # a different cassette without breaking it.
+        payload = f"{manifest.get('content_digest')}:{(manifest.get('replay') or {}).get('cassette_digest')}"
+
+        if sig.get("alg") == "Ed25519":
+            signature_alg = "Ed25519"
+            raw_pinned = (
+                RUNBACK_AUDIT_PUBKEYS_PEM if expected_public_key == "__default__" else expected_public_key
+            )
+            if raw_pinned is None:
+                pinned: list[str] = []
+            elif isinstance(raw_pinned, str):
+                pinned = [raw_pinned]
+            else:
+                pinned = list(raw_pinned)
+            revoked = list(
+                RUNBACK_AUDIT_REVOKED_PUBKEYS_PEM if revoked_public_keys is None else revoked_public_keys
+            )
+
+            embedded = sig.get("pubkey")
+            if not embedded:
+                signature = "no-key"
+            else:
+                key = _spki_der(embedded)
+                try:
+                    raw_sig = bytes.fromhex(str(sig["value"]))
+                except ValueError:
+                    raw_sig = b""
+                if key is None or not ed25519_verify(key, payload.encode("utf-8"), raw_sig):
+                    signature = "invalid"
+                else:
+                    # Compare normalised DER, not PEM text: whitespace and line
+                    # wrapping differ between exporters and must not change the
+                    # verdict.
+                    def matches(lst: Sequence[str]) -> bool:
+                        return any(_spki_der(p) == key for p in lst)
+
+                    if matches(revoked):
+                        # A sound signature from a known-compromised key proves
+                        # nothing about who produced the record — checked before
+                        # the unpinned case so passing expected_public_key=None
+                        # cannot launder a revoked signer into "valid-unpinned".
+                        signature = "revoked"
+                    elif not pinned:
+                        signature = "valid-unpinned"
+                    elif matches(pinned):
+                        signature = "valid"
+                    else:
+                        signature = "valid-unpinned"
+        elif sig.get("alg") in ("HMAC-SHA256", "hmac-sha256"):
+            signature_alg = "HMAC-SHA256"
+            if not signing_key:
+                # Symmetric: only someone already holding the secret can check
+                # it, so a third party gets "no-key" by construction.
+                signature = "no-key"
+            else:
+                import hmac
+
+                expect = hmac.new(
+                    signing_key.encode("utf-8"), payload.encode("utf-8"), hashlib.sha256
+                ).hexdigest()
+                signature = "valid" if hmac.compare_digest(expect, str(sig["value"])) else "invalid"
+
+    consistency = _check_consistency(record)
+    integrity = chain_ok and digest_ok and cassette_ok and schema_ok and consistency["ok"]
+    valid = integrity and signature == "valid"
+    verdict = "invalid" if (not integrity or signature == "invalid") else ("valid" if valid else "unverified")
+
+    signed_run_ids = [e.get("run_id") for e in events if isinstance(e, dict) and e.get("run_id")]
+
+    return {
+        "valid": valid,
+        "verdict": verdict,
+        "integrity": integrity,
+        "checks": {
+            "schema": schema_ok,
+            "chain": chain_ok,
+            "digest": digest_ok,
+            "cassette": cassette_ok,
+            "consistent": consistency["ok"],
+            "signature": signature,
+            "signature_alg": signature_alg,
+        },
+        "consistency_failures": consistency["reasons"],
+        "meta": {
+            "schema": record.get("$schema"),
+            # From the SIGNED events, not the unsigned manifest, so the
+            # displayed identity is one the signature actually covers.
+            "run_id": (signed_run_ids[0] if signed_run_ids else manifest.get("run_id")),
+            "event_count": len(events),
+            "generated_at": manifest.get("generated_at"),
+            "spec_url": manifest.get("spec_url") or "https://runback.dev/spec",
+        },
+    }
+
+
+def verify_json(raw: str, signing_key: Optional[str] = None, **kwargs) -> dict:
+    """Verify a cassette from its raw JSON text."""
+    return verify(json.loads(raw), signing_key, **kwargs)
+
+
+def _main(argv: Sequence[str]) -> int:
+    import sys
+
+    if not argv:
+        print("usage: python3 -m runback.verify <record.json> [--json]", file=sys.stderr)
+        return 2
+    path = argv[0]
+    as_json = "--json" in argv
+    # An auditor running this on a file that is missing, unreadable or not JSON
+    # should be told so in one line. A Python traceback reads as "the tool is
+    # 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()
+    except OSError as exc:
+        print(f"cannot read {path}: {exc.strerror}", file=sys.stderr)
+        return 2
+    try:
+        result = verify_json(raw)
+    except json.JSONDecodeError as exc:
+        print(f"{path} is not valid JSON (line {exc.lineno}, column {exc.colno}).", file=sys.stderr)
+        return 2
+    except TypeError as exc:
+        print(f"{path}: {exc}", file=sys.stderr)
+        return 2
+    if as_json:
+        print(json.dumps(result, indent=2))
+    else:
+        c = result["checks"]
+        print(f"{path}: {result['verdict'].upper()}")
+        print(f"  schema     {'ok' if c['schema'] else 'FAILED'}")
+        print(f"  chain      {'ok' if c['chain'] else 'FAILED'}")
+        print(f"  digest     {'ok' if c['digest'] else 'FAILED'}")
+        print(f"  cassette   {'ok' if c['cassette'] else 'FAILED'}")
+        print(f"  consistent {'ok' if c['consistent'] else 'FAILED'}")
+        print(f"  signature  {c['signature']}" + (f" ({c['signature_alg']})" if c["signature_alg"] else ""))
+        for r in result["consistency_failures"]:
+            print(f"    ! {r}")
+        if result["verdict"] == "unverified":
+            print("\n  Self-consistent, but its origin is unproven. Anyone can author a")
+            print("  record that satisfies the public chain algorithm; only a signature")
+            print("  from a key you pinned out of band shows who produced this one.")
+    # 0 valid, 1 invalid, 2 unverified — so CI can tell the three apart.
+    return {"valid": 0, "invalid": 1, "unverified": 2}[result["verdict"]]
+
+
+def _console() -> int:
+    """Console-script entry point declared in pyproject.toml."""
+    import sys
+
+    return _main(sys.argv[1:])
+
+
+if __name__ == "__main__":
+    import sys
+
+    raise SystemExit(_main(sys.argv[1:]))

runback_verify-2.1.0/runback_verify/__main__.py

@@ -0,0 +1,9 @@
+"""`python3 -m runback_verify record.json` — the same entry point as the
+console script, for an auditor who would rather not put a wheel's bin/ on PATH.
+"""
+
+import sys
+
+from . import _main
+
+raise SystemExit(_main(sys.argv[1:]))

runback_verify-2.1.0/tests/test_conformance.py

@@ -0,0 +1,164 @@
+"""
+The standalone package must agree with the reference, and with the SDK's copy.
+
+runback_verify duplicates canonicalisation from runback-sdk rather than
+importing it, because importing it would reintroduce the requests/python-ulid
+dependency this package exists to avoid.
+
+Duplication is exactly how three implementations silently drifted apart once
+already — exponent padding, HTML escaping, non-BMP key ordering, each changing
+the digest and each invisible because every implementation was tested only
+against itself. So this suite pins the standalone copy to the SAME generated
+fixture the JS, SDK-Python and Go suites use, and additionally asserts it agrees
+with the SDK copy character for character. A copy that drifts fails here.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+_HERE = Path(__file__).resolve().parent
+_REPO = _HERE.parents[2]
+_FIXTURE = _REPO / "packages" / "verify" / "testdata" / "jcs-vectors.json"
+_RECORDS = _REPO / "packages" / "verify" / "testdata" / "records"
+
+sys.path.insert(0, str(_HERE.parent))
+
+from runback_verify import (  # noqa: E402
+    canonical,
+    compute_event_chain,
+    ed25519_verify,
+    verify,
+    verify_json,
+)
+
+
+def _vectors():
+    return json.loads(_FIXTURE.read_text(encoding="utf-8"))["vectors"]
+
+
+def _cases():
+    return json.loads((_RECORDS / "expected.json").read_text(encoding="utf-8"))["cases"]
+
+
+@pytest.mark.parametrize("vec", _vectors(), ids=lambda v: v["name"])
+def test_canonical_matches_reference(vec):
+    got = canonical(vec["value"])
+    assert got == vec["canonical"], (
+        f"\n  vector:   {vec['name']}\n  expected: {vec['canonical']}\n  got:      {got}\n\n"
+        "This package and packages/verify/index.js now disagree about the bytes that\n"
+        "get hashed, so one will call a genuine record TAMPERED. The reference is\n"
+        "authoritative: fix this port, not the fixture."
+    )
+
+
+def test_canonical_agrees_with_the_sdk_copy():
+    """The two Python copies must be identical in behaviour, not just both 'correct'.
+
+    They are separate files by necessity. This is the check that keeps them one
+    implementation in practice.
+    """
+    sdk = _REPO / "packages" / "sdk-python"
+    probe = (
+        "import json,sys;"
+        f"sys.path.insert(0, {str(sdk)!r});"
+        "from runback.cassette import canonical;"
+        f"vs = json.load(open({str(_FIXTURE)!r}))['vectors'];"
+        "print(json.dumps([canonical(v['value']) for v in vs]))"
+    )
+    out = subprocess.run([sys.executable, "-c", probe], capture_output=True, text=True)
+    assert out.returncode == 0, f"could not run the SDK copy: {out.stderr}"
+    sdk_out = json.loads(out.stdout)
+    mine = [canonical(v["value"]) for v in _vectors()]
+    assert mine == sdk_out, "the standalone copy and the SDK copy have drifted apart"
+
+
+@pytest.mark.parametrize("name", sorted(_cases().keys()))
+def test_verdict_matches_reference(name):
+    exp = _cases()[name]
+    record = json.loads((_RECORDS / f"{name}.json").read_text(encoding="utf-8"))
+    got = verify(record, expected_public_key=exp["opts"]["expectedPublicKey"])
+    assert got["verdict"] == exp["verdict"], (
+        f"{name}: expected {exp['verdict']}, got {got['verdict']} — checks {got['checks']}"
+    )
+    assert got["valid"] == exp["valid"]
+    for key, want in exp["checks"].items():
+        assert got["checks"][key] == want, f"{name}: checks.{key}"
+
+
+def test_forged_summary_is_rejected_despite_a_sound_signature():
+    record = json.loads((_RECORDS / "forged-summary.json").read_text(encoding="utf-8"))
+    got = verify(record, expected_public_key=None)
+    assert got["checks"]["signature"] in ("valid", "valid-unpinned"), (
+        "the fixture must carry a SOUND signature or this passes for the wrong reason"
+    )
+    assert got["checks"]["chain"] is True
+    assert got["verdict"] == "invalid"
+    assert got["consistency_failures"]
+
+
+def test_ed25519_is_not_vacuous():
+    """A verifier that returns True unconditionally would pass most of the suite."""
+    record = json.loads((_RECORDS / "signed-genuine.json").read_text(encoding="utf-8"))
+    from runback_verify import _spki_der
+
+    m = record["manifest"]
+    key = _spki_der(m["signature"]["pubkey"])
+    payload = f"{m['content_digest']}:{m['replay']['cassette_digest']}".encode("utf-8")
+    sig = bytes.fromhex(m["signature"]["value"])
+
+    assert ed25519_verify(key, payload, sig) is True
+    assert ed25519_verify(key, payload + b"x", sig) is False
+    assert ed25519_verify(key, payload, bytes(64)) is False
+
+
+def test_chain_recomputes_published_hashes():
+    record = json.loads((_RECORDS / "signed-genuine.json").read_text(encoding="utf-8"))
+    chain = compute_event_chain(record["events"])
+    assert chain["digest"] == record["manifest"]["content_digest"]
+
+
+def test_verify_json_accepts_raw_text():
+    raw = (_RECORDS / "signed-genuine.json").read_text(encoding="utf-8")
+    assert verify_json(raw, expected_public_key=None)["integrity"] is True
+
+
+def test_the_package_imports_nothing_third_party():
+    """The whole reason this package is separate from runback-sdk.
+
+    Measured as a DIFFERENCE against a baseline interpreter, not as an absolute
+    module list. The first version compared sys.modules against
+    sys.stdlib_module_names and failed on `sitecustomize` — a startup hook the
+    interpreter injects before any user code runs, which this package neither
+    imports nor can prevent. That check was measuring the environment rather
+    than the import, which is the same mistake as a guard that passes because
+    it looked at the wrong thing.
+    """
+
+    def modules(import_line: str) -> set:
+        probe = (
+            "import sys;"
+            f"sys.path.insert(0, {str(_HERE.parent)!r});"
+            f"{import_line}"
+            "print(','.join(sorted(sys.modules)))"
+        )
+        out = subprocess.run([sys.executable, "-c", probe], capture_output=True, text=True)
+        assert out.returncode == 0, out.stderr
+        return set(out.stdout.strip().split(","))
+
+    baseline = modules("")
+    with_pkg = modules("import runback_verify;")
+    added = {m.split(".")[0] for m in (with_pkg - baseline)}
+    added.discard("runback_verify")
+
+    stdlib = set(sys.stdlib_module_names)
+    third_party = sorted(m for m in added if m not in stdlib and not m.startswith("_"))
+    assert third_party == [], (
+        f"importing runback_verify pulled in non-stdlib modules: {third_party}. "
+        "This package is published on the promise that it needs nothing installed."
+    )